trunk/sgml-howto/howto.db

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1//EN"
     "dtd/docbook-xml/docbookx.dtd"[

<!-- TODO: a <man> element with a link to -->
<!-- http://www.sources.org/cgi-bin/dwww?type=man&location=/usr/man/man1/sgml2latex.1.gz for the HTML output -->

<!-- TODO: externalize the following declarations in other -->
<!-- files. Warning: this will mean a validating XML parser to treat -->
<!-- the conditionals. First attemps with XML:/Checker are not -->
<!-- convincing. -->

<!-- Programs -->
<!ENTITY sgmltools2 '<link linkend="sgmltools2">SGMLtools, version 2</link>'>
<!ENTITY sgmltools1 '<link linkend="sgmltools1">sgml-tools, version 1</link>'>
<!ENTITY jade '<link linkend="jade">jade</link>'>
<!ENTITY jadetex '<link linkend="jadetex">jadetex</link>'>
<!ENTITY psgml '<application>Emacs</application>&apos; SGML mode, <link linkend="psgml">psgml</link>'>
<!ENTITY modular_ss '<link linkend="modularss">Modular DocBook Stylesheets</link>'>

<!-- Files -->
<!ENTITY print_ss
       '/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/docbook.dsl'>
<!ENTITY html_ss 
       '/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl'>
<!ENTITY xml_decl '<filename>/usr/lib/sgml/declaration/xml.decl</filename>'>

<!-- New elements -->

<!-- The contents of the debianpackage element is the official name -->
<!-- The name attribute holds the Debian name, if it's different -->
<!ELEMENT debianpackage (#PCDATA)>
<!ATTLIST debianpackage name CDATA #IMPLIED>
<!ATTLIST debianpackage refserver CDATA #IMPLIED>
<!ENTITY % local.title.char.mix
        "|debianpackage">

<!ELEMENT debiandoc (#PCDATA)>
<!ATTLIST debiandoc file CDATA #IMPLIED>
<!ATTLIST debiandoc text CDATA #IMPLIED>
<!ENTITY % local.para.char.mix
        "|debiandoc|debianpackage">

<!ELEMENT manpage (#PCDATA)>

<!-- New attributes -->
<!ENTITY % local.common.attrib 
      "debianversionequal CDATA #IMPLIED
       debianversionmin   CDATA #IMPLIED
       debianversionmax   CDATA #IMPLIED">


]>

<article>

  <artheader>
    <title>The Debian SGML/XML HOWTO</title>
    <author>
      <firstname>St&eacute;phane</firstname>
      <surname>Bortzmeyer</surname>
      <affiliation>
        <orgname>The Debian Project</orgname>
        <address><email>bortzmeyer@debian.org</email></address>
      </affiliation>   
    </author>
    <othercredit>
      <contrib>Spelling and grammar fixes</contrib>
      <firstname>Guy</firstname>
      <surname>Brand</surname>
      <affiliation>
        <address><email>guybrand@chimie.u-strasbg.fr</email></address>
      </affiliation>   
    </othercredit>
    <othercredit>
      <contrib>Spelling, grammar and style fixes</contrib>
      <firstname>John</firstname>
      <surname>van der Koijk</surname>
      <affiliation>
        <address><email>jvdkoijk@wirehub.nl</email></address>
      </affiliation>   
    </othercredit>
    <releaseinfo>$Id: howto.db,v 1.3 1999-10-13 15:35:03 bortz Exp $</releaseinfo>
    <copyright>
      <year>1999</year>
      <holder>St&eacute;phane Bortzmeyer</holder>
    </copyright>
    <legalnotice>
      <para>This text is distributed according to the <ulink url="http://www.gnu.org/copyleft/gpl.html">General
        Public License</ulink>.</para>
    </legalnotice>
  </artheader>

  <sect1>
    <title>Why this HOWTO? What's in it?</title>
    <para>This section explains why this HOWTO exist and which people
    it tries to help. It could be useful to read it first, before you
    lose time.</para>
    <sect2>
      <title>What is in the HOWTO</title>
      <para>This HOWTO contains <emphasis>practical</emphasis>
      information about the use of SGML and XML on a Debian operating
      system.</para>
      <para>The HOWTO is task-oriented: you will see what Debian packages you will need for
      various tasks, and how to use them. It is intended for hurried
      people, who do not like to read and understand everything before
      starting
        and who prefers "hands on" training. 
      </para>
      <para>We will cover SGML (and its subset XML), some DTD which I
      find important and the tools to write, format and display SGML,
      whether on the Web or in printing. The emphasis will be on SGML 
        as a way to write documentation, not as a general data
        interchange tool.</para>
    </sect2>
    <sect2>
      <title>What's not in the HOWTO</title>
      <para>You will not find anything about installing and setting up
      software, since we assume a Debian system, where everything is
      already packaged. We will use only Debian packages, as they are
      shipped with <phrase debianversionequal="2.2">Debian 2.2, nicknamed 'potato' (not yet ready when
      writing this)</phrase><phrase debianversionequal="2.1">Debian 2.1, nicknamed
      'slink'</phrase>.</para>
      <para>This is not a tutorial on SGML or XML. Refer to
      <xref linkend="references"/> for that type of information. 
        Instead, you will get just enough
      SGML to get you started
      right now.</para>
    </sect2>
    <sect2>
      <title>Meta-information about this HOWTO</title>
      <para>This HOWTO is itself written in DocBook (XML) on a Debian 
        system. The HOWTO can be retrieved from <ulink
      url="http://www.debian.org/~bortz/SGML-HOWTO/">my Web
      page</ulink>, including its <ulink
      url="http://www.debian.org/~bortz/SGML-HOWTO/howto.db">source code</ulink>.</para>
    </sect2>
    <sect2>
      <title>Why is this HOWTO specific to Debian?</title>
      <para>I said the purpose was to start quickly, remember? This
      means using actual filenames, actual commands and not wasting
        time compiling <application>jade</application>. And I hate to insert "Your mileage way
      vary" warnings everywhere. Therefore, I chose a specific
      operating
system and I used the best one, <ulink
      url="http://www.debian.org/">Debian</ulink>, which is also the
      only one with an integrated SGML environment... Even if it is not
      perfect, it works and, with this HOWTO, it even has a
      documentation.</para>
      <para>I added some pointers to <link linkend="otheros">other
          operating systems</link>.</para>
    </sect2>
  </sect1>

  <sect1>
    <title>What you really need to know about SGML</title>
    <para>I tried to keep this section short. However, I cannot
    explain anything without a small basis of concepts about SGML. So,
    let's go, before we switch to actual source code.</para>
    <sect2>
      <title>What is structured documentation?</title>
      <para>Structured documentation is built upon structured elements:
      chapters, sections, paragraphs, etcetera, where all elements
      are clearly labeled for
      what they are: references, program output, etc. No explicit information
      about how the document should be rendered is given;
      only about its structure (and content).
      When there are explicit rules for presentation, they are kept
      outside the SGML-document.</para>
      <para>This allows for automatic processing of the documents, without
      waiting for AI systems. It encourages authors to concentrate on
      structure, which conveys meaning. </para>
      <para>Thus, the question "How do I put a word in bold with
      SGML?" has little relevance. One <emphasis>could</emphasis> ask
      how to put emphasis on a certain stretch of text.</para>
    </sect2>
    <sect2>
      <title>What is SGML?</title>
      <para>Standard Generalized Markup Language is a standardized
        language intended to facilitate the authoring of
        structured documentation 
        <footnote><para>It has
      other uses, such as data interchange.</para></footnote>. More
      specifically, it is a meta-language. You never actually type
      SGML, but SGML is used to describe
      a document type specific structured language
      (this is called a DTD, a Document Type
      Definition), which defines how specific documants might be
      structured (written).</para>
      <para>Therefore, saying that a document is "in the SGML format"
      is technically correct, but deceptive. One could say that a
      document is in the DocBook format or the LinuxDoc format or the
      TEI format.</para>
    </sect2>

    <sect2>
      <title>What does SGML look like?</title>
      <para>SGML is a markup language. All SGML documents include
        text, mixed with <emphasis>tags</emphasis>, which delimits
      <emphasis>elements</emphasis><footnote><para>Depending on the DTD, the
      end-tag can be mandatory or not. In XML, end-tags are always mandatory.</para>
        </footnote>. SGML allows several syntaxes to be
      used, but we'll stick with the reference syntax, the most
      common, where tags are enclosed between angle brackets, &lt; and
      &gt;. Here is an example:</para>
        <programlisting role="docbook">
<![CDATA[
<article>

<title>The Foo software</title>

<para>
Foo is very fast. And its documentation can be read easily.
</para>
]]>
        </programlisting>
      <para>If it looks like HTML to you, it is because HTML is
       (theoretically) a DTD of SGML.</para>
      <para>Elements have a <emphasis>content</emphasis>. For
        instance, the content of the above <sgmltag>para</sgmltag>
        element is "Foo is very fast. 
        And its documentation can be read easily.".</para>
      <para>Elements can have <emphasis>attributes</emphasis> to
        indicate more information. For instance:</para>
        <programlisting role="docbook">
<![CDATA[
<example tested="true">
            *c++;
</example>
]]>
        </programlisting>
      <para>You can have also <emphasis>entities</emphasis> which
        allow you to parametrize some text. For instance, if you often
        refer to "the Best Operating System, Debian" and you want to
        avoid typing it each time or, worse, having to change every
        occurrence if you finally decide a more modest wording, you
        can declare an entity, let's call it "debian" and use it with
        the ampersand "&amp;debian;"<footnote><para>This is
        <emphasis>reference entities</emphasis>. SGML use other types
        of entities, which are not covered in this HOWTO.</para></footnote>.</para>
        <para> One element is special: the <emphasis>root
          element</emphasis> is the global element, which contains
        everything. In XML, the DOCTYPE line indicates which element
        is the root. Here is an example<phrase debianversionequal="2.2"> (It
          seems <emphasis>there is a bug</emphasis> in the SGML environment of Debian 2.2,
          which requires a full path name for the DTD below. If so,
          this is a bug and I will investigate it<comment>TODO: do
            it, a bug against psgml has been filled. Follow it.</comment>)</phrase>:</para>
      <programlisting role="docbook">
<![CDATA[
<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1//EN"
     "dtd/docbook-xml/docbookx.dtd"[
]]>
      </programlisting>
        <sect3><title>And the XML files?</title>
        <para>You'll learn <link linkend="xml">later about
        XML</link>. Let's just say that XML files begin first with a
        <emphasis>processing instruction</emphasis>, which starts with
        &lt;? and, in that case indicates it is a XML file, as well as
        some meta-information. Example:</para>
        <programlisting role="docbook">
<![CDATA[
        <?xml version="1.0" encoding="utf-8"?>
]]>
        </programlisting>
        <para>XML files must be <emphasis>well-formed</emphasis>,
        which means that tags must be balanced (no crossing of tags
        which is common in the HTML output of many Web editors) and
        can be <emphasis>valid</emphasis> which means conformant to
        their DTD.</para>
        <para>Start-tags must always have an end-tag in XML, but you
        can have <emphasis>empty elements</emphasis> where the
        start-tag and the end-tag merge in a tag written with a / at
        the end like:</para>
          <programlisting role="xml">
<![CDATA[
            <foobar/>
]]>
          </programlisting>
        </sect3>
    </sect2>

    <sect2>
      <title>What is a DTD?</title>
      <para>A Document Type Definition is the description (in SGML)
      of a specific language. You can write your own DTD (it is not
      very difficult, especially in XML) or you can use an
      already-existing DTD, which is convenient if you want to
      exchange documents with other people. Several such DTDs exist,
      typically for the purposes of a given group of people (astronoms, chemists, scholars in ancient literature...).</para>
      <para>The DTD lists the allowed elements and their
      relationships (for instance, it says a <sgmltag>chapter</sgmltag>
        must have at least one <sgmltag>section</sgmltag>).</para>
      <para>Typical DTDs that you may find useful:</para>
      <itemizedlist>
        <listitem>
          <para><ulink url="http://www.oasis-open.org/docbook/">DocBook</ulink> is mostly intended for
          writing technical documentation, especially about software.</para>
        </listitem>
        <listitem>
          <para><ulink url="http://www.linuxdoc.org/">LinuxDoc</ulink>
          is used by the Linux Documentation Project, for instance for
          the Linux
          HOWTOs. The LDP has decided to switch to DocBook, but the
          conversion has not been carried out.</para>
        </listitem>
        <listitem>
          <para><ulink url="http://www.debian.org/~elphick/ddp/manuals.html#doc">DebianDoc</ulink> is used in part by the
            <ulink url="http://www.debian.org/~elphick/ddp/">Debian Documentation Project</ulink>.</para>
        </listitem>
        <listitem>
          <para><ulink url="http://www.w3.org/MarkUp/">HTML</ulink> is
          in theory an SGML DTD but
          very few actual Web pages are compliant. So, most SGML tools
          will choke on a typical Web page.</para>
        </listitem>
      </itemizedlist>
      <para>At the beginning of a document, you will find a
      reference to the DTD to use (there are several ways to indicate
      such references; the following example is for LinuxDoc):</para>
        <programlisting role="linuxdoc">
<![CDATA[
<!doctype linuxdoc system>

<article>

<title>The Linux Kernel HOWTO
]]>
        </programlisting>
      <comment>TODO: Explain FPI, PUBLIC and SYSTEM, etc.</comment>
    </sect2>

    <sect2>
      <title>Which DTD to choose?</title>
      <para>Very often, you'll have no choice: the project you're a
      part of will have chosen already. Since standardization is of
      course very important in a big project, there is little chance
      you'll be able to change that. For instance, Linux Documentation
      Project uses LinuxDoc, <ulink
      url="http://www.freebsd.org/docproj/docproj.html">FreeBSD</ulink>,
      <ulink url="http://developer.gnome.org/arch/doc/tools.html">GNOME</ulink> or <ulink
      url="http://www.kde.org/documentation/index.html">KDE</ulink> use DocBook, etc.</para>
      <para>If you have the choice, I suggest to stay close to what
      similar projects are doing. If you write technical documentation
      for computer hardware or software, this probably means using
      DocBook.</para>
    </sect2>

    <sect2>
      <title>How do I write SGML?</title>
      <para>Since SGML is a markup language, you can use any editor,
        like <application>vi</application> or even
      <application>cat</application>.</para>
      <para>But it is often easier with an editor which helps you
      inserting tags, knowing, for example, which are valid. I recommend 
<application>Emacs</application> with its <link linkend="psgml">SGML mode</link>.</para>
    </sect2>

    <sect2 id="xml">
      <title>What is XML?</title>
      <para>XML (Extensible Markup Language ) is a subset of SGML, a 
        sort of SGML--. It
      was designed first for the World-Wide Web, but it is now used
      in unrelated areas.</para>
      <para>XML is much simpler than SGML, with less options, so a parser is
        lighter and faster.</para>
    </sect2>

    <sect2>
      <title>What is a stylesheet?</title>
      <para>In the markup world, you try to separate content from
      presentation. Content is expressed in the SGML document,
      following a given DTD. Presentation is expressed outside of the
      document, typically in a DTD-specific stylesheet, which is a description, in an
      appropriate language (<ulink
      url="http://www.jclark.com/dsssl/">DSSSL
        </ulink> - Document Style Semantics and
      Specification Language - is the most common<footnote><para>The
      XML world created a new language, <ulink
      url="http://www.w3.org/Style/XSL/">XSL</ulink>, which has few
      implementations at this moment<phrase debianversionmax="2.1">
      (and none before Debian 2.2)</phrase>.
      Despite what you may read in executive
      summaries, it is perfectly acceptable to use DSSSL to render XML
      files.</para></footnote>),
      of the layout rules for documents written for a certain DTD.</para>
      <para>For instance, it is the author of the stylesheet who will
      decide that titles should be rendered in bold, that URLs will be
      printed in red, etc.</para>
      <para>If you know the <ulink url="http://www.w3.org/Style/css/">
          CSS</ulink> (Cascading
      Style Sheets) language, do note that typical languages for SGML
      stylesheets are more complicated: they allow not only to specify
      the rendering of an element, but also the reordering of elements,
      computation of data from some elements, etc. DSSSL, for instance, is a
      full blown programming language (based on Scheme), enriched with stylesheet
      constructs.</para>
    </sect2>

  </sect1>

  <sect1>
    <title>Creating documentation with DocBook</title>
    <para>Here, we will see how to write and process documentation,
    using the DocBook DTD. We will use the XML version, often named
    DocBk, because
    I prefer XML<footnote><para>And also because future versions of
    DocBook will be <ulink url="http://www.oasis-open.org/docbook/meetings/min19990308.html">XML</ulink>.</para></footnote>, but most of what is written here apply to the SGML
    version as well.</para>
    <para debianversionmax="2.1">To use it on a Debian system prior to
    2.2 'potato', you'll need the
    <debianpackage>docbook-xml</debianpackage>. It installs fine on a
    'slink' system and does not break anything (it is just a DTD, it
    does not depend on specific libraries).</para>
    <sect2>
      <title>Writing DocBook</title>
      <para>You can skip this section if you just received a DocBook
      file and want to process it, rather than edit it.</para>
      <para>Like with any DTD, I recommend &psgml; to write DocBook. </para>
<para>First, choose a root element, preferably the simplest,
      <sgmltag>article</sgmltag>. Start with:</para>
        <programlisting role="docbook">
<![CDATA[
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1//EN"
     "dtd/docbook-xml/docbookx.dtd">
<article>
  <artheader>
    <title>My first XML document</title>
  </artheader>
  <section>
    <title>My first section</title>
    <para>My first paragraph.</para>
  </section>
</article>
]]>
        </programlisting>
<para>This is a complete DocBook document. You can <link linkend="nsgmls">
    validate it</link>.</para>
<para>Typical DocBook documents use book, chapter or article as the
 root element. Then, they include a header, where you find meta-information,
such as the title of the document. After this header, a DocBook
document is divided into sections, each with a title.
<comment>More details would be nice.</comment>
</para>
<para>To know the complete list of elements, see
        <debiandoc text="the set of DocBook texts">docbook-doc</debiandoc>, more specially 
        <debiandoc file="r2333.html" text="DocBook DTD Reference">docbook-doc</debiandoc>.</para>
    </sect2>

    <sect2>
      <title>Processing DocBook documents</title>
      <para>Remember, DocBook is not a program but a format. Asking
      "Does DocBook have a PDF output?" is meaningless. Software which
      uses DocBook may produce PDF. DocBook itself does nothing.</para>
      <para>There are several different solutions to produce printed
      paper, Web pages or manual pages from DocBook documents. You could
      program such a transformation yourself with tools like the Perl module
      XML::Parser or the Java module XP. Or you can use stylesheets,
      which you may or may not write yourself. If you decide not to
      write them, you can use
      the &modular_ss; with &jade;.</para>
      <para>Since we are using the XML version of DocBook, here is how to
      call &jade; to translate <filename>myfile.db</filename> to TeX:</para>
        <programlisting role="shell">
        jade -t tex \ 
                -d &print_ss; \
                &xml_decl; myfile.db
        </programlisting>
          <para>which will produce a TeX file using &jadetex; macros and
      needing the &jadetex; program to be processed:</para>
      <programlisting role="shell">
        jadetex myfile.tex
      </programlisting>
      <para>And to HTML:</para>
        <programlisting role="shell">
        jade -t sgml \ 
                -d &html_ss; \
                &xml_decl; myfile.db
        </programlisting>
        <para>Unfortunately, there is no easy way to create text-only
        output from a DocBook file, for instance for posting it on
        Usenet. The best available solution is to use the following
        kluge with 
        <application>lynx</application>:</para>
      <programlisting role="shell">
        jade -t sgml -V nochunks \
                 -d &html_ss; \
                 &xml_decl; myfile.db > dump.html
        lynx -force_html -dump dump.html > myfile.txt
      </programlisting>
        <sect3 debianversionmin="2.2"><title>Using SGMLtools</title>
        <para>You can also use &sgmltools2;. This may be
        simpler, since &sgmltools2; automates the tasks performed by
        jade, jadetex and lynx. But it does <emphasis>not</emphasis> work with the XML
        version of DocBook. To convert a file to HTML:</para>
            <programlisting role="shell">
          sgmltools --backend=ps howto.db
            </programlisting>
            <para>And to PostScript:</para>
            <programlisting role="shell">
          sgmltools --backend=ps howto.db
            </programlisting>
            <para>And to pure text:</para>
            <programlisting role="shell">
          sgmltools --backend=txt howto.db
            </programlisting>
          </sect3>
      <sect3><title>Automatize it with <application>make</application></title>
                <para>Since the manipulations needed to convert from
                DocBook to anything can be complicated, the use of
                <application>make</application> 
            is recommended. An example of a <filename>Makefile</filename> is:</para>
      <programlisting role="makefile">
<![CDATA[
MAX_TEX_RECURSION=4
XML_DECL=/usr/lib/sgml/declaration/xml.decl
HTML_SS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/docbook.dsl
PRINT_SS=/usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/docbook.dsl

all: myfile

myfile: myfile.ps myfile.txt myfile.html

myfile.tex: myfile.db 
        jade -t tex \
                -d $(PRINT_SS) \
                $(XML_DECL) $<

myfile.dvi: myfile.tex
        # Trick from Adam Di Carlo <adam@onshore.com> to recurse jadetex 
        # "just enough".
        -cp -pf prior.aux pprior.aux
        -cp -pf $(shell basename $< .tex).aux prior.aux
        jadetex $<
        if ! cmp $(shell basename $< .tex).aux prior.aux &&             \
           ! cmp $(shell basename $< .tex).aux pprior.aux &&            \
           expr $(MAKELEVEL) '<' $(MAX_TEX_RECURSION); then             \
                rm -f $@                                                ;\
                $(MAKE) $@                                              ;\
        fi
        rm -f prior.aux pprior.aux

myfile.ps: myfile.dvi
        dvips -f $< > $@

myfile.html: myfile.db html.dsl
        jade -t sgml \
                -d $(HTML_SS) \
                $(XML_DECL) $< 

myfile.txt: myfile.db
        jade -t sgml -V nochunks \
                -d $(HTML_SS) \
        $(XML_DECL) $< > dump.html
        lynx -force_html -dump dump.html > $@
        -rm -f dump.html

validate:
        nsgmls -s -wxml $(XML_DECL) myfile.db

clean: 
        rm -f *.html *.aux *.log *.dvi *.ps *.tex *.txt
]]>
      </programlisting>
        </sect3>
        <sect3 debianversionmin="2.2"><title>Misc</title>
        <comment>TODO: localization in various languages.</comment>
                <para>To convert DocBook to man pages or other formats, see <debianpackage name="docbook2X"
                refserver="http://shell.ipoline.com/~elmert/hacks/docbook2X/">docbook2man</debianpackage>
                and <debianpackage>docbook-to-man-ans</debianpackage>.
</para>
        </sect3>
      <sect3>
        <title>Customizing the Modular DocBook Stylesheets</title>
        <para>If you <link linkend="customdb">write a custom
        element</link>
        or if you want to change the default rendering of
        an element or if you simply want to customize the output a bit
        (such as changing the default font), you'll have to define a
        custom stylesheet. This does not imply retyping everything.
        DSSSL allows one stylesheet to "use" another. The stylesheet
          inherits all of the properties of the stylesheet that it is
          using, but local definitions take precedence over imported ones. 
          An example of a custom stylesheet is:</para>

        <programlisting role="dsssl">
<![CDATA[

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY docbook.dsl 
         PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
         CDATA DSSSL>
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

(define %body-font-family% 
  ;; The font family used in body text
  "Palatino")

</style-specification-body>
</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>
]]>
        </programlisting>
        <para>Your style instructions (here the changing of the font
        to Palatino) have to be written in DSSSL, whose syntax and
        many semantics come from the programming language Scheme,
        which is itself a Lisp dialect. You do not need to learn
        Scheme, the <phrase debianversionmax="2.1"><debiandoc text="documentation of the Modular Stylesheets" file="doc/custom.html">docbook-stylesheets</debiandoc></phrase><phrase debianversionmin="2.2"><debiandoc text="documentation of the Modular Stylesheets" file="custom.html">docbook-stylesheets-doc</debiandoc></phrase>
        contains examples for most purposes.</para>
<para>Since there are actually two stylesheets, one for printing and
        one for HTML, the above custom stylesheet works only for the
        first one. For the second, here is an exemple:</para>
        <programlisting role="dsssl">
<![CDATA[
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
]>
<style-sheet>

<style-specification id="html" use="docbook">
<style-specification-body> 

(define %generate-article-titlepage% #t)

</style-specification-body>
</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>
]]>
          </programlisting>
        <para>In both cases, you'll have to tell Jade to use your
        stylesheets, here <filename>myprint.dsl</filename>:</para>
        <programlisting role="shell">
        jade -t tex \ 
                -d myprint.dsl \
                &xml_decl; myfile.db
        </programlisting>

      </sect3>
      <sect3 id="customdb"><title>Customizing the DocBook DTD</title>
        <para>
          DocBook is intended to be customizable. There are many ways
          to do that<footnote><para>Including copying the DTD and
          editing it... But I was referring to `clean' ways of modifying the
          DTD, which will not create too many problems with
          future versions of DocBook.</para></footnote>,
          but be careful: customization may lead to problems
          when exchanging documents with others. See <debiandoc
          text="Customizer's Guide for the DocBook DTD" file="book68527.html">docbook-doc</debiandoc>.
        </para>
            <para>If you add new elements, you'll probably have to
            create a custom stylesheet as well.</para>
            <comment>
              Give examples of customization.
            </comment>
      </sect3>
    </sect2>
    
  </sect1>
  
  <sect1>
    <title>Creating documentation with LinuxDoc</title>
    <para>We will now go into writing and processing documentation
    using the LinuxDoc DTD.</para>
    <sect2>
      <title>Writing LinuxDoc</title>
      <para>You can skip this section if you just received a LinuxDoc
      file (for instance one of the Linux HOWTOs, such as you can find in the 
        <ulink
      url="http://metalab.unc.edu/pub/Linux/docs/HOWTO/other-formats/sgml/">
          LinuxDoc servers</ulink>).</para>
      <para>You may write LinuxDoc documents with &psgml;. Here is a
          sample example:</para>
      <programlisting role="linuxdoc">
<![CDATA[
<!doctype linuxdoc system>
<article>

<title>Quick SGML Example
<author>Matt Welsh, <tt>mdw@cs.cornell.edu</tt>
<date>v1.0, 28 March 1994
<abstract>
This document is a brief example using the Linuxdoc-SGML DTD.
</abstract>

<sect>Introduction

<p>
This is an SGML example file using the Linuxdoc-SGML DTD.

</article>
]]>
        </programlisting>
      <para>A more complete example of a LinuxDoc document is <debiandoc file="example.sgml.gz">sgml-tools</debiandoc>.</para>
      <para>To learn the list of legal elements, see <debiandoc
      file="html/guide.html.gz">sgml-tools</debiandoc><phrase
      debianversionmax="2.2"> (it is currently buggy: the HTML files
      are compressed, which may harm your browser) </phrase><comment>TODO Does it
      work? It seems HTML files are gzipped :-( Fill in a bug report</comment>or see <ulink
            url="http://www.sgmltools.org/guide/guide.html">Matt Welsh's guide</ulink>.</para>
      </sect2>
    <sect2>
      <title>Processing LinuxDoc</title>
      <para>You will use &sgmltools1;. To convert a
      LinuxDoc document to HTML:</para>
      <programlisting role="shell">
        sgml2html document.sgml
      </programlisting>
      <para>To ordinary text, for instance to post it on the News:</para>
       <programlisting role="shell">
        sgml2txt  document.sgml
      </programlisting>
      <para>And to PostScript, using LaTeX:</para>
            <programlisting role="shell">
        sgml2latex --output=ps document.sgml
      </programlisting>
      <comment>
        The extension has to be .sgml or sgml-tools will do unproper
        things.
      </comment >
      <para>You can have more information in <phrase
      debianversionmax="2.1">sgmltools(1)</phrase><phrase debianversionmin="2.2">sgmltools.v1(1)</phrase>.</para>
      <comment>TODO: localization un various languages.</comment>
      </sect2>

  </sect1>

  <sect1>
    <title>Creating documentation with DebianDoc</title>
    <para>Here, we will see how to write and process documentation,
    using the DebianDoc DTD.</para>
    <sect2><title>Writing DebianDoc documents</title>
      <para>Here is a sample DebianDoc document:</para>
      <programlisting role="debiandoc">
<![CDATA[
<!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN">

<debiandoc>
  <book>
    <titlepag>
      <title>FooBar</title>
      <author>
        <name>Bortzmeyer</name>
        <email>bortzmeyer@debian.org</email>
      </author>
    </titlepag>
    <chapt>
      <heading>Title</heading>
      <p>Content</p>
    </chapt>
  </book>
</debiandoc>
]]>
      </programlisting>
      <para>To know the list of legal tags, see <phrase
debianversionmax="2.1">
<debiandoc
file="debiandoc-sgml.html/index.html">debiandoc-sgml</debiandoc>
</phrase>
<phrase debianversionmin="2.2"><debiandoc
file="debiandoc-sgml.html/index.html">debiandoc-sgml-doc</debiandoc>
<comment>Bug #47300</comment></phrase>.</para>
    </sect2>
    <sect2><title>Processing DebianDoc documents</title>
      <para>
        To translate to PostScript:      
      </para>
      <programlisting role="shell">
         debiandoc2ps -1 myfile.dd
      </programlisting>
      <para>And to HTML:</para>
    <programlisting role="shell">
         debiandoc2html myfile.dd
      </programlisting>
      </sect2>
    
  </sect1>

  <sect1>
    <title>Tools</title>
    <para>This section is no longer oriented toward tasks, but toward
       software that you can use to write and process SGML.</para>
    <para debianversionmin="2.2"> The simplest way  to
    get all these tools is to install
    <debianpackage>task-sgml</debianpackage>.</para>
    <para debianversionmax="2.1"> To get all these tools, you'll have to
    install several packages. Here is the
    <application>apt</application> command which will do it for
    you<footnote><para>Providing that <application>apt</application>
    has been configured properly before.</para></footnote>:
        <programlisting role="shell">
          apt-get install docbook docbook-doc sp jade \
            docbook-stylesheets jadetex debiandoc-sgml \
            psgml 
        </programlisting>
      </para>
    <sect2 id="psgml">
      <title><debianpackage name="psgml" refserver="http://www.lysator.liu.se/projects/about_psgml.html">PSGML</debianpackage></title>
      <para>An excellent SGML mode for Emacs. Among its many features,
      it can:</para>
      <itemizedlist>
        <listitem><para>Show you what tags are valid at a given point,</para>
        </listitem>
        <listitem><para>Insert tags (begin and end, as well as
        mandatory tags in between) from a menu which shows only valid
        tags (this is tremendously useful when you start to use a new
        and complicated DTD),</para>
        </listitem>
        <listitem><para>Manipulate SGML elements, move
                according to elements, etc.</para>
        </listitem>
      </itemizedlist>
      <para>Its documentation is in <debiandoc
      file="psgml_toc.html">psgml</debiandoc>.</para>
      <para>
        Having some options set up in your <filename>~/.emacs</filename> will
        ease your use of psgml. Here are some examples:</para>
        <programlisting role="emacs-lisp">
<![CDATA[
          (autoload 'xml-mode "psgml" "Major mode to edit XML files." t )
          
          (setq
               auto-mode-alist (append '(
                           ;; DocBook-XML
                           ("\\.db" . xml-mode)
                           )
                         auto-mode-alist))

          (add-hook 'sgml-mode-hook 'turn-on-auto-fill)
          (setq sgml-custom-dtd '(
            ( "HTML 4.0 Strict"
              "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.0//EN\"
              \"dtd/html-4.0s.dtd\">" )
            ( "HTML 4.0 Blaireau"
              "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML Transitional 4.0//EN\"
              \"dtd/html-4.0-loose.dtd\">" )
            ( "DocBook 3.1 XML Article"
               "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>
               <!DOCTYPE article PUBLIC \"-//Norman Walsh//DTD DocBk XML V3.1//EN\"
               \"dtd/docbook-xml/docbookx.dtd\">" )
          ))
          (setq sgml-insert-missing-element-comment nil)
]]>
        </programlisting>
        <para>Among the most useful psgml commands:
        <itemizedlist>
          <listitem><para>C-c C-t :
<command>sgml-list-valid-tags</command>
reminds you
              (or teaches you) the DTD. Very convenient when you start
              playing with a monster like DocBook.</para>
          </listitem>
          <listitem><para><command>sgml-insert-element</command>. Again, a great
              way to learn a DTD</para>
          </listitem>
        </itemizedlist>
</para>
    </sect2>
    <sect2 id="nsgmls">
      <title><debianpackage name="sp" refserver="http://www.jclark.com/sp/nsgmls.htm">nsgmls</debianpackage></title>
      <para>An SGML tool, for instance for validating SGML documents. A
      typical use is to check the validity of a document:</para>
      <programlisting role="shell">
        nsgmls -s file.sgml
      </programlisting>
      <para>This will check whether or not the contents of the file
      <filename>file.sgml</filename> conform to the DTD indicated
      in the header of the file.</para>
      <para>If you write XML documents, two options of nsgmls are
         necessary:</para>
      <programlisting role="shell">
        nsgmls -s -wxml &xml_decl; file.sgml
      </programlisting>
        <para>There is a <debiandoc
        file="nsgmls.htm">sp</debiandoc>. nsgmls being a part of the
        sp package, the <debiandoc file="index.htm">sp</debiandoc> for sp may be useful
        too.</para>
    </sect2>
    <sect2 id="rxp" debianversionmin="2.2">
      <title><debianpackage>rxp</debianpackage></title>
      <para>A pure XML tool; can, for instance, be used to validate XML
      documents.</para>
      </sect2>
    <sect2 id="jade">
      <title><debianpackage
      refserver="http://www.jclark.com/jade/">jade</debianpackage></title>
      <comment>TODO: We should mention OpenJade! http://jade-cvs.avionitek.com/</comment>
      <para>jade is a DSSSL 
        processor. It takes an SGML file and a
      stylesheet, written in the DSSSL language, and produces output
      in the TeX (for which PostScript can be made), RTF or HTML
      formats.
      It has
      no backend for <application>groff</application> and therefore has trouble producing
      ASCII. The <application>TeX</application> backend produces &jadetex; files.</para>
      <para>The documentation is not really clear but it at leasts
      tell you the various options. See <debiandoc file="jade.htm">jade</debiandoc>.</para>
      <para>Typical uses:</para>
      <programlisting role="shell">
        jade -t backend-to-use -d stylesheet-name input-file
      </programlisting>
    </sect2>
    <sect2 id="jadetex">
        <title><debianpackage>jadetex</debianpackage></title>
                <comment>http://www.tug.org/applications/jadetex/"</comment>
      <para>A set of <application>TeX</application> macros to process
      the output of jade. Poorly documented and difficult to
      customize. Like with every TeX macros, several runs may be
      necessary, in particular to resolve references.</para>
    </sect2>
    <sect2 id="sgmltools2" debianversionmin="2.2">
      <title><debianpackage name="sgmltoolsv2" refserver="http://www.sgmltools.org/">SGMLtools</debianpackage></title>
      <para>The SGMLtools exist in two versions, 1 and 2. SGMLtools is
        the version 2.</para>
      <para>Unlike sgml-tools, version 1, which processes LinuxDoc
        documents, SGMLtools, version 2, treats DocBook
        documents. You can do everything it does with direct calls
        to &jade; but it may be simpler to use SGMLtools.</para>
    </sect2>
    <sect2 id="sgmltools1">
        <title><debianpackage name="sgml-tools"
        refserver="http://www.sgmltools.org/download-1.0.html">sgml-tools,
        version 1</debianpackage></title>
      <para>
          <footnote debianversionmin="2.2"><para>Did you notice the change in the
          capitalization?</para></footnote>
        This version is officially deprecated and should no
        longer, in theory, be used anymore. But, in practice, since
        the move of the Linux Documentation Project from LinuxDoc to
        the DocBook DTD never occured, you still need sgml-tools
        version 1.</para>
      </sect2>
    <sect2 id="modularss">
      <title><debianpackage name="docbook-stylesheets"
                            refserver="http://www.nwalsh.com/docbook/dsssl/index.html"> 
          Norman Walsh's "DocBook Modular Stylesheets"</debianpackage></title>
      <para>These are a set of DSSSL stylesheets (with a recent XSL version). You
can use them with any DSSSL tool, like &jade; to process DocBook documents.</para>
    </sect2>
  </sect1>

  <sect1 id="references">
    <title>References</title>
    <itemizedlist>
      <listitem>
        <para>SGML in general</para>
        <itemizedlist>
          <listitem>
            <para><ulink
                         url="http://www.oasis-open.org/cover/">Cover's
                page</ulink></para>
          </listitem>
          <listitem>
            <para><ulink
                         url="http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html">
                A Gentle Introduction to SGML</ulink> by the TEI people. Not very
              practical, IMHO. <comment>TODO: read it again, Sam.</comment>
            </para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>XML in general</para>
        <itemizedlist>
          <listitem>
            <para><ulink
            url="http://www.w3.org/XML/">Official XML</ulink></para>
          </listitem>
          <listitem>
            <para><ulink
            url="http://www.oasis-open.org/cover/xml.html">Cover's XML
            page</ulink></para>
          </listitem>
          <listitem>
            <para><ulink
            url="http://www.ucc.ie/xml/">XML FAQ</ulink></para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>DocBook</para>
        <itemizedlist>
          <listitem>
        <para><ulink url="http://www.oasis-open.org/docbook/">Official
        DocBook</ulink></para>
          </listitem>
          <listitem>
            <para><debiandoc file="index.html">docbook-doc</debiandoc></para>
          </listitem>
<listitem>
<para><ulink url="http://www.nwalsh.com/docbook/dsssl/">
Modular DocBook Stylesheets</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.freebsd.org/tutorials/docproj-primer/">
FreeBSD Documentation Project Primer</ulink> is a nice introduction to
SGML and
DocBook</para>
</listitem>
          <listitem>
            <para><ulink
                         url="http://www.nwalsh.com/docbook/simple/sdocbook/">
                Simplified DocBook</ulink>, a version of DocBook with
                         less elements to learn</para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>LinuxDoc</para>
        <itemizedlist>
          <listitem>
            <para><ulink
            url="http://www.sgmltools.org/guide/guide.html">Matt
            Welsh's SGML-Tools User's Guide</ulink></para>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem id="otheros">
        <para>Other operating systems: this section will list
        documents similar to this HOWTO (I mean
        <emphasis>practical</emphasis> documents) for operating systems
        other than Debian.</para>
        <itemizedlist>
          <listitem>
            <para><ulink
            url="http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html">Microsoft
            Windows NT</ulink></para>
          </listitem>
          <listitem>
            <para>RedHat users of DocBook should probably <ulink
            url="http://sourceware.cygnus.com/docbook-tools/">see the
            Cygnus tools</ulink>.</para>
            </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>
    <bibliography>
      <title>Interesting books</title>
      <biblioentry>
        <bookbiblio>
          <title>SGML CD</title>
          <author>
            <surname>DuCHARME</surname>
            <firstname>Bob</firstname>
          </author>
          <editor>
            <surname>Prentice-Hall</surname>
          </editor>
          <isbn>0-13-475740-8</isbn>
          <abstract>
            <para>A very good and practical book about the tools
            needed to write and process SGML on Unix and Windows
            NT. Does not cover XML.</para>
          </abstract>
        </bookbiblio>
        <bookbiblio>
           <title>DocBook: The Definitive Guide</title>
          <author>
            <surname>Walsh</surname>
            <firstname>Norman</firstname>
          </author>
          <author>
            <surname>Muellner</surname>
            <firstname>Leonard</firstname>
          </author>
          <editor>
            <surname>O'Reilly</surname>
          </editor>
          <isbn>1-56592-580-7</isbn>
          <abstract>
            <para>I didn't read it yet...</para>
          </abstract>
        </bookbiblio>
      </biblioentry>
    </bibliography>
  </sect1>
</article>

