
                       DDeebbiiaannddoocc--SSGGMMLL  mmaarrkkuupp  mmaannuuaall
                       --------------------------------------------------------
                   Ian Jackson <ijackson@gnu.ai.mit.edu>
                              14 August 1996

00..11  CCoonntteennttss

     1.        _S_G_M_L_ _m_a_r_k_u_p_ _a_n_d_ _m_e_t_a_c_h_a_r_a_c_t_e_r_s

     2.        _O_v_e_r_a_l_l_ _s_t_r_u_c_t_u_r_e

     3.        _C_h_a_p_t_e_r_s_,_ _s_e_c_t_i_o_n_s_ _a_n_d_ _p_a_r_a_g_r_a_p_h_s

     4.        _M_a_r_k_e_d_-_u_p_ _i_n_l_i_n_e_ _t_e_x_t_ _a_n_d_ _c_h_a_r_a_c_t_e_r_ _s_t_y_l_e_ _m_a_r_k_u_p
     4.1.      Character style
     4.2.      Cross-references
     4.3.      Footnotes

     5.        _L_i_s_t_s_ _a_n_d_ _e_x_a_m_p_l_e_s_ 
     5.1.      Lists
     5.2.      Examples

     0.2.      _C_o_p_y_r_i_g_h_t_ _N_o_t_i_c_e


-------------------------------------------------------------------------------


11..  SSGGMMLL  mmaarrkkuupp  aanndd  mmeettaacchhaarraacctteerrss

     As entered in a text editor SGML document consists of text
     interspersed with tags denoting the start and end of elements.

     Tags take the form <<_e_l_e_m_e_n_t>> to start the element _e_l_e_m_e_n_t and
     <<//_e_l_e_m_e_n_t>> to finish it.

     There are some shorthands you can use: <<_e_l_e_m_e_n_t//_c_o_n_t_e_n_t_s// specifies an
     element _e_l_e_m_e_n_t with contents _c_o_n_t_e_n_t_s - but the _c_o_n_t_e_n_t_s may not
     contain a slash //. <<//>> closes the innermost currently open element.

     Some types of element start tag can have attributes; these appear
     inside the closing angle bracket, and are separated from the element
     name by whitespace. The attributes allowed in a particular element's
     start tag are described along with the element.

     If you want to include SGML's markup characters (angle brackets << >>
     and ampersands &&) as text you must refer to them by name (this is
     called an entity reference in SGML-speak). &&_n_a_m_e;; produces the
     character whose name is _n_a_m_e. Some useful character names are: 
     lltt
          less than sign (left angle bracket) <<;
     ggtt
          greater than sign (right angle bracket) >>;
     aammpp
          ampersand &&;
     ccooppyy
          copyright symbol ;
     The full list of characters is borrowed from linuxdoc-sgml, in
     linuxdoc-sgml's rreepp//llaattiinn11//ggeenneerraall file.

     You can also use &&##_n_u_m_b_e_r;; to refer to the character whose number is
     _n_u_m_b_e_r (in ISO-LATIN-1). _n_u_m_b_e_r should be in decimal. 


-------------------------------------------------------------------------------


22..  OOvveerraallll  ssttrruuccttuurree

     The first line of the document should be 
          <!doctype debiandoc system>
     to indicate that the document is a Debiandoc-SGML file.

     The document should start with the <<bbooookk>> tag and end with <<//bbooookk>>.

     This should be followed by the <<ttiittllee>>, one or more <<aauutthhoorr>>-<<eemmaaiill>>
     pairs, and optionally a <<vveerrssiioonn>>. Each of these is a piece of
     marked-up inline text - see chapter 4, `Marked-up inline text and
     character style markup'. The <<vveerrssiioonn>> may also contain <<ddaattee>> which
     stands for the date at the time the document is formatted.

     Then may come an <<aabbssttrraacctt>> and a <<ccooppyyrriigghhtt>> notice and a <<ttoocc>>
     marker.

     The <<aabbssttrraacctt>> contains a single paragraph.

     The <<ccooppyyrriigghhtt>> notice contains a copyright summary (this is used, for
     example, at the bottom of every HTML page) followed by one or more
     paragraphs, the first of which must be indicated by a <<pp>> tag to
     distinguish it from the summary.

     The <<ttoocc>> marker specifies that a table of contents is to be produced.
     The <<ttoocc>> doesn't contain anything in the SGML source - its contents
     are generated by the processing systems. The <<ttoocc>> can have an
     attribute saying how detailed it should be; for example, <<ttoocc  sseecctt11>>
     says that subsections should be included, whereas <<ttoocc  cchhaapptt>> says
     that only chapters should be included. The values allowed are cchhaapptt,
     sseecctt, sseecctt11 and sseecctt22.

     Following these parts comes the body of the document - one or more
     chapters <<cchhaapptt>>.

     It is not necessary to mark the end of the <<ttiittllee>>, <<aauutthhoorr>>s,
     <<vveerrssiioonn>>, <<aabbssttrraacctt>> and <<ccooppyyrriigghhtt>> elements - they are implicitly
     ended by the start of the next element. 


-------------------------------------------------------------------------------


33..  CChhaapptteerrss,,  sseeccttiioonnss  aanndd  ppaarraaggrraapphhss

     Each chapter starts with a <<cchhaapptt>> tag, followed by the chapter's
     title. The title may contain marked-up inline text, but no
     cross-references (see chapter 4, `Marked-up inline text and character
     style markup').

     The body of the chapter is zero or more paragraphs, the first of which
     must be indicated by a <<pp;;>> tag to distinguish it from the title, and
     then zero or more sections.

     A section starts with <<sseecctt>>, and has a similar structure: title,
     optionally some paragraphs, and then optionally some subsections.

     Subsections are <<sseecctt11>>; there are also smaller divisions <<sseecctt22>>,
     <<sseecctt33>> and <<sseecctt44>>.

     Paragraphs are introduced by <<pp>>. Sometimes the start of paragraph tag
     can be omitted, but it is mandatory after <<cchhaapptt>>, <<sseecctt>> and so
     forth. It is never necessary to mark the end of a paragraph with <<//pp>>.

     Paragraphs can contain marked up inline text (see chapter 4,
     `Marked-up inline text and character style markup') and also lists and
     examples (chapter 5, `Lists and examples '). 


-------------------------------------------------------------------------------


44..  MMaarrkkeedd--uupp  iinnlliinnee  tteexxtt  aanndd  cchhaarraacctteerr  ssttyyllee  mmaarrkkuupp

     Ordinary text (called `inline text' in this document) may contain a
     elements for special formatting and cross-referencing. Inline text
     appears in chapter and section titles, in the copyright summary,
     inside paragraphs and in other similar places 


44..11..  CChhaarraacctteerr  ssttyyllee

     There are a number of elements for denoting special significance of
     certain pieces of text. For all of them the end of the special text
     must be marked up explicitly, by using an explicit end tag <<//_e_l_e_m_e_n_t>>,
     the abbreviated end tag for closing the innermost element <<//>> or the
     slash // which finishes the most abbreviated form of element markup
     (see chapter 1, `SGML markup and metacharacters'). 

     <<eemm>> - emphasis 
          Indicates that the contained text is more important or more
          significant than that surrounding it.

          Typically this will be represented by italics if available, or
          emboldened or underlined text, or in plain text formats with no
          character highlighting available by surrounding the text with
          asterisks like *this*. 

     <<vvaarr>> - metasyntactic variable
          Indicates that the contained