[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ A ] [ B ] [ next ]

# DebianDoc-SGML Manual
Chapter 3 - Overall structure

The first line of the document should be

         <!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN">

or

         <!doctype debiandoc system>

to indicate that the document is a Debiandoc-SGML file.

The document should start with the `<book>` tag and end with `</book>`. This may optionally be enclosed between `<debiandoc>` tag and `</debiandoc>`.

This should be followed by the `<title>`, one or more `<author>`s or `<translator>`s (each consisting of a `<name>` and an optional`<email>`), and optionally a `<version>`. Each of these is a piece of marked-up inline text - see Marked-up inline text and character style markup, Chapter 5. The `<version>` may also contain a `<date>` which stands for the date at the time the document is formatted.

Then may come an `<abstract>`, a `<copyright>` notice, and a `<toc>` marker.

The `<abstract>` contains a single paragraph.

The `<copyright>` notice contains one or more copyright summaries marked with `<copyrightsummary>` and `</copyrightsummary>` followed by one or more paragraphs, the first of which must be indicated by a `<p>` tag to distinguish it from the summaries.

The `<toc>` marker specifies that a table of contents is to be produced. The `<toc>` doesn't contain anything in the SGML source - its contents are generated by the processing systems. The `<toc>` can have an attribute saying how detailed it should be; for example, `<toc sect1>` says that subsections should be included, whereas `<toc chapt>` says that only chapters and appendices should be included. The values allowed are `chapt`, `sect`, `sect1` and `sect2`.

Following these parts comes the body of the document - one or more chapters `<chapt>`, optionally followed by one or more appendices `<appendix>`.

It is not necessary to mark the end of the `<title>`, `<author>`, `<version>`, `<abstract>` and `<copyright>` elements - they are implicitly ended by the start of the next element.

Here is an example of simple Debiandoc SGML file.

         <!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN" [

         <-- Next line is an example to include external definition -->
         <!ENTITY % default  SYSTEM "default.ent">  %default;
         <-- Next line is an example of common definition -->
         <!ENTITY common-definition "Foo Bar" >

         ]>

         <debiandoc>

         <book>

         <title>Book Title Here</title>
         <author>
          <name>Osamu Aoki</name>
          <email>debian@aokiconsulting.com</email>
         </author>

         <version>Version 1.00</version>

         <abstract>
         This provides a simple skeleton example of a debiandoc-sgml document.
         You cannot place "p" or "ref" tags in here.
         </abstract>

         <copyright>
           <copyrightsummary>
             Copyright © 2006 by Osamu Aoki <email>debian@aokiconsulting.com</>
           </copyrightsummary>
           <p>
           <url id="http://www.gnu.org/copyleft/gpl.html"
                 name="This document may used under the terms of the GNU General Public License version 2 or higher.">
         </copyright>

         <toc sect1>  <!-- list section to sect1 in table of content-->

         <chapt id="chapter-one"><heading>Chapter title</heading>

         <!-- This is comment.  Heading tags above can be skipped -->

         <p>
         ...
         <sect id="ch-1-sect-1">Section title here
         <p>
         ...contents. "&common-definition;" becomes "Foo Bar".

         <sect1 id="ch-1-sect1-1">Sect-1-level title
         <p>
         ...contents

         <sect2 id="ch-1-sect2-1">Sect-2-level title
         <p>
         ...contents

         </sect2>
         </sect1>
         </sect>

         </book>

         </debiandoc>

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ A ] [ B ] [ next ]

DebianDoc-SGML Manual