<chapt id="structure">

  <heading>Overall structure</heading>

  <p>
    The first line of the document should be
<example>
&lt!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN"&gt
</example>
    or
<example>
&lt!doctype debiandoc system&gt
</example>
    to indicate that the document is a Debiandoc-SGML file.
  </p>

  <p>
    The document should start with the <tt>&lt;book&gt;</tt> tag and
    end with <tt>&lt;/book&gt;</tt>.  This may optionally be enclosed
    between <tt>&lt;debiandoc&gt;</tt> tag and  
    <tt>&lt;/debiandoc&gt;</tt>.
  </p>

  <p>
    This should be followed by the <tt>&lt;title&gt;</tt>, one or more
    <tt>&lt;author&gt;</tt>s or <tt>&lt;translator&gt;</tt>s 
    (each consisting of a
    <tt>&lt;name&gt;</tt> and an optional<tt>&lt;email&gt;</tt>), and
    optionally a <tt>&lt;version&gt;</tt>.  Each of these is a piece
    of marked-up inline text - see <ref id="inline">.  The
    <tt>&lt;version&gt;</tt> may also contain a <tt>&lt;date&gt;</tt>
    which stands for the date at the time the document is formatted.
  </p>

  <p>
    Then may come an <tt>&lt;abstract&gt;</tt>, a
    <tt>&lt;copyright&gt;</tt> notice, and a <tt>&lt;toc&gt;</tt>
    marker.
  </p>

  <p>
    The <tt>&lt;abstract&gt;</tt> contains a single paragraph.
  </p>

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

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

  <p>
    Following these parts comes the body of the document - one or more
    chapters <tt>&lt;chapt&gt;</tt>, optionally followed by one or
    more appendices <tt>&lt;appendix&gt;</tt>.
  </p>

  <p>
    It is not necessary to mark the end of the <tt>&lt;title&gt;</tt>,
    <tt>&lt;author&gt;</tt>, <tt>&lt;version&gt;</tt>,
    <tt>&lt;abstract&gt;</tt> and <tt>&lt;copyright&gt;</tt> elements
    - they are implicitly ended by the start of the next element.
  </p>
  
  <p>
  Here is an example of simple Debiandoc SGML file.
  <example>
&lt;!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN" [

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

]&gt;

&lt;debiandoc&gt;

&lt;book&gt;

&lt;title&gt;Book Title Here&lt;/title&gt;
&lt;author&gt;
 &lt;name&gt;Osamu Aoki&lt;/name&gt;
 &lt;email&gt;debian@aokiconsulting.com&lt;/email&gt;
&lt;/author&gt;

&lt;version&gt;Version 1.00&lt;/version&gt;

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

&lt;copyright&gt;
  &lt;copyrightsummary&gt;
    Copyright &copy; 2006 by Osamu Aoki &lt;email&gt;debian@aokiconsulting.com&lt;/&gt;
  &lt;/copyrightsummary&gt;
  &lt;p&gt;
  &lt;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."&gt;
&lt;/copyright&gt;

&lt;toc sect1&gt;  &lt;!-- list section to sect1 in table of content--&gt;

&lt;chapt id="chapter-one"&gt;&lt;heading&gt;Chapter title&lt;/heading&gt;

&lt;!-- This is comment.  Heading tags above can be skipped --&gt;

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

&lt;sect1 id="ch-1-sect1-1"&gt;Sect-1-level title
&lt;p&gt;
...contents

&lt;sect2 id="ch-1-sect2-1"&gt;Sect-2-level title
&lt;p&gt;
...contents

&lt;/sect2&gt;
&lt;/sect1&gt;
&lt;/sect&gt;

&lt;/book&gt;

&lt;/debiandoc&gt;


  </example>

</chapt>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:("../debiandoc-sgml.en.sgml" "book" "chapt")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
