Re: How to make "Debian Reference" as scalable SGML

[Osamu Aoki <debian@aokiconsulting.com>]

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         +