Re: How to make "Debian Reference" as scalable SGML
On Mon, Feb 11, 2002 at 08:59:35PM -0800, Osamu Aoki wrote:
> ### Roadmap to the next stage for "Debian reference" ###
... More thinking on how to separate content from structure
I am thinking to structure the "Debian reference" document so that the
content of each <chapt>, <sect> or <sect1> section is written in a
separate small file. There is always chance to make <sect> to be
<sect1> or <sect> to become <chapt> during reorganization. That should
not affect each document. Creating this modular structure should make
maintenance easier.
It will be a lot of work to impliment it. But maintenance shall be
easier afterward. What do you think?
==== Detail plan ====
Main SGML contains only structure, for example as follows:
<!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN"
[
<!-- textual data entities -->
<!entity % date system "date.ent"> %date;
<!entity % default system "default.ent"> %default;
<!entity % dynamic system "dynamic.ent"> %dynamic;
]
>
<!-- CVS revision of this document "$Revision: 1.3 $" -->
<debiandoc>
<book id="quick-reference">
<title>&book-title;</title>
<author>
<name>Osamu Aoki</name>
<email>debian@aokiconsulting.com</email>
</author>
<author>
<name>Qref team (Appendix B)</name>
</author>
<version> &version;, &date;</version>
<abstract>
&file-abstract;
</abstract>
<copyright>
&file-copyright;
</copyright>
<toc sect1>
<chapt id="html-name-of-chapt-1"><heading>&header-example;</heading>
&file-example;
<sect id="sect-1"><heading>&header-sect-1;</heading>
&file-sect-1;
<sect1 id="sect-11"><heading>&header-sect1-11;</heading>
&file-sect1-11;
</sect1>
<sect1 id="sect-12"><heading>&header-sect1-12;</heading>
&file-sect1-12;
</sect1>
</sect>
<sect id="sect-2"><heading>&header-sect-1;</heading>
&file-sect-1;
<sect1 id="sect-21"><heading>&header-sect1-21;</heading>
&file-sect1-21;
</sect1>
<sect1 id="sect-22"><heading>&header-sect1-22;</heading>
&file-sect1-22;
</sect1>
</sect>
</chapt>
</book>
</debiandoc>
Then each files in "en" directory contains a comment line at first line which
define content of <heading>...</heading>.
This starting line is, for example:
<!--####"Section 2 title text here"####-->
"Makefile" script will extract this comment dynamically and create SGML
tags and write them to "dynamic.ent".
dynamic.ent::
: > $@ # clear the file
@echo "<!entity language \"$(TLANG)\">" >> $@
@echo "<!entity % lang-$(TLANG) \"INCLUDE\">" >> $@
@for filesgml in $(basename $(notdir $(wildcard $(TLANG)/*.sgml))) ; do
\
echo "<!entity file-$${filesgml} system \"$(TLANG)/$${filesgml}.sgml\">" >> $@ ; \
head -n1 $(TLANG)/$${filesgml}.sgml | \
sed -e "s/--####/entity header-$${filesgml} /" -e "s/####--//" >> $@ ; \
done
Here TLANG should contain target language such as "en". Also, this
removes needs to current 'sed "s/@@@@/$(TLANG)/"' hack.
Osamu
--
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Osamu Aoki <debian@aokiconsulting.com> @ Cupertino, CA USA +
Reply to: