[ 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