  Linuxdoc-SGML User's Guide
  by Matt Welsh. Updated by Greg Hankins, ggrreegg..hhaannkkiinnss@@cccc..ggaatteecchh..eedduu
  v1.5, 8 March 1996

  This document is a user's guide to the Linuxdoc-SGML formatting sys-
  tem, a SGML-based system which allows you to produce a variety of out-
  put formats. You can create plain text output (ASCII and ISO-8859-1),
  DVI, PostScript, HTML, GNU info, LyX, and RTF output from a single
  SGML source file. This guide documents Linuxdoc-SGML version 1.5.
  ______________________________________________________________________

  Table of Contents:

  1.      Introduction

  1.1.    About This Document

  1.2.    Why SGML?

  1.3.    How It Works

  2.      Installation

  2.1.    Installing The Software

  2.2.    Formatting SGML Documents

  2.2.1.  Creating Plain Text Output

  2.2.2.  Creating LaTeX, DVI or PostScript Output

  2.2.3.  Creating HTML Output

  2.2.4.  Creating GNU Info Output

  2.2.5.  Creating LyX Output

  2.2.6.  Creating RTF Output

  2.2.7.  Checking SGML Syntax

  2.3.    ISO 8859-1 Character Set

  3.      Writing Documents With Linuxdoc-SGML

  3.1.    Basic Concepts

  3.2.    Special Characters

  3.3.    Verbatim and Code Environments

  3.4.    Overall Document Structure

  3.4.1.  The Preamble

  3.4.2.  Sectioning And Paragraphs

  3.4.3.  Ending The Document

  3.5.    Cross-References

  3.6.    Fonts

  3.7.    Lists

  3.8.    Further Information
  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  This is a user's guide to the Linuxdoc-SGML document processing
  system, for use with Linux documentation. Linuxdoc-SGML is a SGML DTD
  (Document Type Definition) and set of ``replacement files'' which
  convert the SGML to groff, LaTeX, HTML, GNU info, LyX, and RTF source.

  Linuxdoc-SGML is based heavily on the QWERTZ DTD by Tom Gordon,
  tthhoommaass..ggoorrddoonn@@ggmmdd..ddee. I have only made revisions to his DTD and
  replacement files for use with Linux documentation.

  Linuxdoc-SGML is not meant to be a general document-processing system.
  Although it can be used for documents of many types, I have tailored
  it for use by the Linux documenters in producing HOWTOs, FAQs, and
  (later) the Linux Documentation Project manuals. Therefore, I have
  tweaked features into and out of the system for this purpose. If you
  see a lack of generality in the system, that is the reason. However,
  there's nothing binding Linuxdoc-SGML to Linux documentation, but all
  documents produced by the system will look a certain way. If you want
  things to look differently I suggest that you use a more generalized
  system such as the plain QWERTZ DTD, in combination with the Linuxdoc-
  SGML tools.

  One of the goals of this system is to make documents easy to produce
  in numerous formats. Until now, most Linux documentation has been
  produced in plain text through manual editing. A system like groff can
  take care of the plain text formatting, but that still doesn't give
  you HTML (for use on the World Wide Web), LaTeX (for nicely printed
  documents), or other various output formats. Therefore, if there are
  features missing from this system that you would like, _p_l_e_a_s_e _l_e_t _m_e
  _k_n_o_w_! The idea is that we shouldn't have to use a lot of hackery to
  produce good-looking documentss in multiple formats.  The author
  should have to do as little as possible.

  11..11..  AAbboouutt TThhiiss DDooccuummeenntt

  This document is written using the Linuxdoc-SGML DTD. It contains more
  or less everything you need to know to write SGML documents with this
  DTD. See eexxaammppllee..ssggmmll for an example of an SGML document that you can
  use as a model for your own documents.

  11..22..  WWhhyy SSGGMMLL??

  I chose SGML for this system because SGML is made specifically for
  translation to other formats. SGML, which stands for Standard
  Generalized Markup Language, allows you to specify the _s_t_r_u_c_t_u_r_e of a
  document---that is, what kinds of things make up the document. You
  specify the structure of a document with a DTD (Document Type
  Definition). Linuxdoc-SGML is one DTD that specifies the structure for
  Linux HOWTOs and other documents. QWERTZ is another DTD; the SGML
  standard provides DTD's for books, articles, and other generic
  document types.

  The DTD specifies the names of ``elements'' within the document. An
  element is just a bit of structure---like a section, a subsection, a
  paragraph, or even something smaller like _e_m_p_h_a_s_i_z_e_d _t_e_x_t. Unlike
  LaTeX, however, these elements are not in any way intrinsic to SGML
  itself. The Linuxdoc-SGML DTD happens to define elements that look a
  lot like their LaTeX counterparts---you have sections, subsections,
  verbatim ``environments'', and so forth. However, using SGML you can
  define any kind of structure for the document that you like. In a way,
  SGML is like low-level TeX, while the Linuxdoc-SGML DTD is like LaTeX.

  Don't be confused by this analogy. SGML is _n_o_t a text-formatting
  system.  There is no ``SGML formatter'' per se. SGML source is _o_n_l_y
  converted to other formats for processing. Furthermore, SGML itself is
  used only to specify the document structure. There are no text-
  formatting facilities or ``macros'' intrinsic to SGML itself. All of
  those things are defined within the DTD. You can't use SGML without a
  DTD---a DTD defines what SGML does.

  11..33..  HHooww IItt WWoorrkkss

  Here's how processing a document with SGML and the Linuxdoc-SGML DTD
  works. First, you need a DTD. I'm using the QWERTZ DTD which was
  produced, originally, by a group of people who needed a LaTeX-like
  DTD. I've modified the QWERTZ DTD to produce the Linuxdoc-SGML DTD for
  our purposes.  The DTD simply sets up the structure of the document. A
  small portion of it looks like this:

       <!element article - -
               (titlepag, header?,
                toc?, lof?, lot?, p*, sect*,
                (appendix, sect+)?, biblio?) +(footnote)>

  This part sets up the overall structure for an ``article'', which is
  like a ``documentstyle'' within LaTeX. The article consists of a
  titlepage (ttiittlleeppaagg), an optional header (hheeaaddeerr), an optional table
  of contents (ttoocc), optional lists of figures (llooff) and tables (lloott),
  any number of paragraphs (pp), any number of top-level sections (sseecctt),
  optional appendices (aappppeennddiixx), an optional bibliography (bbiibblliioo) and
  footnotes (ffoooottnnoottee).

  As you can see, the DTD doesn't say anything about how the document
  should be formatted or what it should look like. It just defines what
  parts make up the document. Elsewhere in the DTD the structure of the
  ttiittlleeppaagg, hheeaaddeerr, sseecctt, and other elements are defined.

  You don't need to know anything about the syntax of the DTD in order
  to write documents. I'm just presenting it so you know what it looks
  like and what it does. You _d_o need to be familiar with the document
  _s_t_r_u_c_t_u_r_e that the DTD defines. If not, you might violate the
  structure when attempting to write a document, and be very confused
  about the resulting error messages. We'll describe the structure of
  Linuxdoc-SGML documents in detail later.

  The next step is to write a document using the structure defined by
  the DTD. Again, the Linuxdoc-SGML DTD makes documents look a lot like
  LaTeX---it's very easy to follow. In SGML jargon a single document
  written using a particular DTD is known as an ``instance'' of that
  DTD.

  In order to translate the SGML source into another format (such as
  LaTeX or groff) for processing, the SGML source (the document that you
  wrote) is _p_a_r_s_e_d along with the DTD by (you guessed it) the SGML
  _p_a_r_s_e_r.  I'm using the ssggmmllss parser by James Clark, jjjjcc@@jjccllaarrkk..ccoomm,
  who also happens to be the author of ggrrooffff. We're in good hands.  The
  parser (ssggmmllss) simply picks through your document and verifies that it
  follows the structure set forth by the DTD. It also spits out a more
  explicit form of your document, with all ``macros'' and elements
  expanded, which is understood by ssggmmllssaasspp, the next part of the
  process.
  ssggmmllssaasspp is responsible for converting the output of ssggmmllss to another
  format (such as LaTeX). It does this using _r_e_p_l_a_c_e_m_e_n_t _f_i_l_e_s, which
  describe how to convert elements in the original SGML document into
  corresponding source in the ``target'' format (such as LaTeX or
  groff).

  For example, part of the replacement file for LaTeX looks like:

       <itemize>       +       "\\begin{itemize}      +
       </itemize>      +       "\\end{itemize}        +

  Which says that whenever you begin an iitteemmiizzee element in the SGML
  source, it should be replaced with

       \begin{itemize}

  in the LaTeX source. (As I said, elements in the Linuxdoc-SGML DTD are
  very similar to their LaTeX counterparts).

  So, to convert the SGML to another format, all you have to do is write
  a new replacement file for that format that gives the appropriate
  analogies to the SGML elements in that new format. In practice, it's
  not that simple---for example, if you're trying to convert to a format
  that isn't structured at all like your DTD, you're going to have
  trouble. In any case, it's much easier to do than writing individual
  parsers and translators for many kinds of output formats; SGML
  provides a generalized system for converting one source to many
  formats.

  Once ssggmmllssaasspp has completed its work, you have LaTeX source which
  corresponds to your original SGML document, which you can format using
  LaTeX as you normally would. Later in this document I'll give examples
  and show the commands used to do the translation and formatting. You
  can do this all on one command line.

  But first, I should describe how to install and configure the
  software.

  22..  IInnssttaallllaattiioonn

  Get lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz from one of the following ftp sites:

  +o  ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt//lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz

  +o  ffttpp::////ttssxx--1111..mmiitt..eedduu//ppuubb//lliinnuuxx//ddooccss//lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz

  +o  ffttpp::////ffttpp..cccc..ggaatteecchh..eedduu//ppuubb//ppeeooppllee//ggrreegghh//lliinnuuxxddoocc--ssggmmll//lliinnuuxxddoocc--
     ssggmmll--11..55..ttaarr..ggzz

  Uptodate patches to version 1.5 can be found at
  ffttpp::////ffttpp..cccc..ggaatteecchh..eedduu//ppuubb//ppeeooppllee//ggrreegghh//lliinnuuxxddoocc--ssggmmll.

  You can also get uptodate information from the LLiinnuuxxddoocc--SSGGMMLL WWWWWW PPaaggee
  <<hhttttpp::////wwwwww..iinnffoorrmmaattiikk..ttuu--mmuueenncchheenn..ddee//~~sscchhwwaarrzz//lliinnuuxxddoocc--ssggmmll//>.

  The file lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz contains everything that you need to
  write SGML documents and convert them to groff, LaTeX, HTML, GNU info,
  LyX, and RTF. In addition to this package, you will need the following
  tools - these are not required by the SGML system, but I suggest that
  you get them in order to format your documents and verify that they
  look all right before distributing them.

  1. ggrrooffff. You _n_e_e_d version 1.08 or 1.09. Apparently some of the
     margin-handling in ggrrooffff is in a state of flux from version to
     version; they both work, but you get slightly different results
     (particularly, with 1.09 the left margin isn't indented two
     characters as it is in 1.08. There is a way around it, but it looks
     terrible on 1.08).  Versions previous to 1.08 _w_i_l_l _n_o_t _w_o_r_k. You
     can get this from ffttpp::////pprreepp..aaii..mmiitt..eedduu//ppuubb//ggnnuu. There is a Linux
     binary version on ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt as
     well.  You will need ggrrooffff to produce plain text from your SGML
     documents.  nnrrooffff will _n_o_t work!

  2. TeX and LaTeX. This is available more or less everywhere; you
     should have no problem getting it and installing it (there is a
     Linux binary distribution on ssuunnssiittee..uunncc..eedduu). Of course, you only
     need TeX/LaTeX if you want to format your SGML documents with
     LaTeX. So, installing TeX/LaTeX is optional.

  3. If you want to view the generated HTML, I suggest getting NCSA
     Mosaic 2.6 or later, available on
     ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//ssyysstteemm//NNeettwwoorrkk//iinnffoo--ssyysstteemmss.

  4. ggaawwkk and the GNU info tools, for formatting and viewing info files.
     These are also available on ffttpp::////pprreepp..aaii..mmiitt..eedduu//ppuubb//ggnnuu, or on
     ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt (for ggaawwkk) and
     ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//ssyysstteemm//MMaannuuaall--ppaaggeerrss (for GNU info
     tools).  aawwkk will not work without hacking.

  5. LyX (a quasi-WYSIWYG interface to LaTeX, with SGML layouts), is
     available on ffttpp::////ffttpp..vviiaa..eeccpp..ffrr.

  22..11..  IInnssttaalllliinngg TThhee SSooffttwwaarree

  The steps needed to install and configure the lliinnuuxxddoocc--ssggmmll stuff are
  as follows:

  1. First, unpack the tar file lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz somewhere.
     This will create the directory lliinnuuxxddoocc--ssggmmll--11..55.  It doesn't
     matter where you unpack this file; just don't move things around
     within the lliinnuuxxddoocc--ssggmmll--11..55 directory.

  2. Read the IINNSSTTAALLLL file - it has detailed installation instructions.

     If all went well, you should be ready to use the system.

  22..22..  FFoorrmmaattttiinngg SSGGMMLL DDooccuummeennttss

  Let's say you have the SGML document ffoooo..ssggmmll, which you want to
  format.  Here is a general overview of formatting the document for
  different output.  For a complete list of options, consult the man
  pages.

  22..22..11..  CCrreeaattiinngg PPllaaiinn TTeexxtt OOuuttppuutt

  If you want to produce plain text, use the command:

  % sgml2txt foo.sgml

  Note that I have tailored the groff conversion for plain text output.
  That is, I've removed page headers, page numbers, changed the margins,
  and so on. With some hacking you can produce PostScript and DVI from
  the groff output, but I suggest that you use LaTeX for that instead.

  You can also create groff source for man pages, which can be formatted
  with ggrrooffff --mmaann. To do this, do the following:

       % sgml2txt -man foo.sgml

  22..22..22..  CCrreeaattiinngg LLaaTTeeXX,, DDVVII oorr PPoossttSSccrriipptt OOuuttppuutt

  To create a LaTeX documents from the SGML source file, simply run:

       % sgml2latex foo.sgml

  If you want to produce PostScript output (via ddvviippss), use the --pp
  option:

       % sgml2latex -p foo.sgml

  Or, you can produce a DVI file using the --dd switch, as so:

       % sgml2latex -d foo.sgml

  22..22..33..  CCrreeaattiinngg HHTTMMLL OOuuttppuutt

  If you want to produce HTML output, do this:

       % sgml2html -img foo.sgml

  This will produce ffoooo..hhttmmll, as well as ffoooo--11..hhttmmll, ffoooo--22..hhttmmll, and so
  on---one file for each section of the document.  Run your WWW browser
  on ffoooo..hhttmmll, which is the top level file.  Also make sure that all of
  the HTML files corresponding to your document are in one directory, as
  they reference each other with local URLs.  The icons referenced in
  the HTML output are located in $$LLIINNUUXXDDOOCCLLIIBB//iiccoonnss. These will also
  need to be copied to the final location of the HTML documents.
  $$LLIINNUUXXDDOOCCLLIIBB is defined at the beginning of the SGML conversion
  scripts.

  If you use ssggmmll22hhttmmll without the --iimmgg flag, HTML documents will have
  the labels ``Previous'', ``Next'', and ``Table of Contents'' for
  navigation. You can override these defaults by creating a file in
  $$LLIINNUUXXDDOOCCLLIIBB//rreepp//hhttmmll//<<ffiilleennaammee>>, and substituting your own words for
  different languages. The file has the following format:

               PrevPage:    newvalue
               NextPage:    newvalue
               TOC:         newvalue

  See ddeeuuttsscchh for an example.

  22..22..44..  CCrreeaattiinngg GGNNUU IInnffoo OOuuttppuutt

  If you want to format your file for the GNU info browser, just run the
  following command:

       % sgml2info foo.sgml

  22..22..55..  CCrreeaattiinngg LLyyXX OOuuttppuutt

  For LyX output, use the the command:

       % sgml2lyx foo.sgml

  22..22..66..  CCrreeaattiinngg RRTTFF OOuuttppuutt

  If you want to produce RTF output, run the command:

       % sgml2rtf foo.sgml

  This will produce ffoooo..rrttff, as well as ffoooo--11..rrttff, ffoooo--22..rrttff, and so
  on---one file for each section of the document.

  22..22..77..  CChheecckkiinngg SSGGMMLL SSyynnttaaxx

  If you just want to capture your errors from the SGML conversion, use
  the ssggmmllcchheecckk script.  For example.

  % sgmlcheck foo.sgml

  22..33..  IISSOO 88885599--11 CChhaarraacctteerr SSeett

  The ISO 8859-1 (latin1) character set may be used for international
  characters in plain text, LaTeX, HTML, LyX, and RTF output (GNU info
  support for ISO 8859-1 may be possible in the future).  To use this
  feature, give the formatting scripts the --ll flag, for example:

       % sgml2txt -l foo.sgml

  You also can use ISO 8859-1 characters in the SGML source, they will
  automatically be translated to the proper escape codes for the corre-
  sponding output format.

  33..  WWrriittiinngg DDooccuummeennttss WWiitthh LLiinnuuxxddoocc--SSGGMMLL

  For the most part, writing documents using the Linuxdoc-SGML DTD is
  very simple, and somewhat like LaTeX. However, there are some caveats
  to watch out for. In this section I'll give an introduction on writing
  SGML documents.  See the file eexxaammppllee..ssggmmll for a SGML example document
  (and tutorial) which you can use as a model when writing your own
  documents. Here I'm just going to discuss the various features of
  SGML, but the source is not very readable as an example. Instead,
  print out the source (as well as the formatted output) for
  eexxaammppllee..ssggmmll so you have a real live case to refer to.

  33..11..  BBaassiicc CCoonncceeppttss

  Looking at the source of the example document, you'll notice right off
  that there are a number of ``tags'' marked within angle brackets (<<
  and >>). A tag simply specifies the beginning or end of an element,
  where an element is something like a section, a paragraph, a phrase of
  italicized text, an item in a list, and so on. Using a tag is like
  using a LaTeX command such as \\iitteemm or \\sseeccttiioonn{{......}}.

  As a simple example, to produce tthhiiss bboollddffaacceedd tteexxtt, I typed

       As a simple example, to produce <bf>this boldfaced text</bf>, ...

  in the source. <<bbff>> begins the region of bold text, and <<//bbff>> ends it.
  Alternately, you can use the abbreviated form

       As a simple example, to produce <bf/this boldfaced text/, ...

  which encloses the bold text within slashes. (Of course, you'll need
  to use the long form if the enclosed text contains slashes, such as
  the case with Unix filenames).
  There are other things to watch out with respect to special characters
  (that's why you'll notice all of these bizarre-looking ampersand
  expressions if you look at the source; I'll talk about those shortly).

  In some cases, the end-tag for a particular element is optional. For
  example, to begin a section, you use the <<sseecctt>> tag, however, the end-
  tag for the section (which could appear at the end of the section body
  itself, not just after the name of the section!)  is optional and
  implied when you start another section of the same depth.  In general
  you needn't worry about these details; just follow the model used in
  the tutorial (eexxaammppllee..ssggmmll).

  33..22..  SSppeecciiaall CChhaarraacctteerrss

  Obviously, the angle brackets are themselves special characters in the
  SGML source. There are others to watch out for. For example, let's say
  that you wanted to type an expression with angle brackets around it,
  as so: <<ffoooo>>. In order to get the left angle bracket, you must use the
  &&lltt;; element, which is a ``macro'' that expands to the actual left-
  bracket character. Therefore, in the source, I typed

       angle brackets around it, as so: <tt>&lt;foo></tt>.

  Generally, something beginning with an ampersand is a special macro.
  For example, there's &&ppeerrccnntt;; to produce %, &&vveerrbbaarr;; to produce |, and
  so on. For all ``special characters'' there exist these ampersanded-
  entities to represent them.

  Usually, you don't need to use the ampersand macro to get a special
  character, however, in some cases it is necessary. The most commonly
  used are:

  +o  Use &&aammpp;; for the ampersand (&),

  +o  Use &&lltt;; for a left bracket (<),

  +o  Use &&ggtt;; for a right bracket (>),

  +o  Use &&eettaaggoo;; for a left bracket with a slash (<<//)

  +o  Use &&ddoollllaarr;; for a dollar sign ($),

  +o  Use &&nnuumm;; for a hash (#),

  +o  Use &&ppeerrccnntt;; for a percent (%),

  +o  Use &&ttiillddee;; for a tilde (~),

  +o  Use ```` and '''' for quotes, or use &&ddqquuoott for ".

  For a complete list of special characters, look at one of the
  replacement files.  Usually LaTeX complains the most about special
  characters, so paging through $$LLIINNUUXXDDOOCCLLIIBB//rreepp//llaatteexx//ggeenneerraall would be
  a good place to start.  $$LLIINNUUXXDDOOCCLLIIBB is defined at the beginning of
  the SGML conversion scripts.

  33..33..  VVeerrbbaattiimm aanndd CCooddee EEnnvviirroonnmmeennttss

  While we're on the subject of special characters, I might as well
  mention the verbatim ``environment'' used for including literal text
  in the output (with spaces and indentation preserved, and so on). The
  vveerrbb element is used for this; it looks like the following:

       <verb>
         Some literal text to include as example output.
       </verb>

  The vveerrbb environment doesn't allow you to use _e_v_e_r_y_t_h_i_n_g within it
  literally. Specifically, you must do the following within vveerrbb envi-
  ronments.

  +o  Use &&eerroo;; to get an ampersand,

  +o  Use &&eettaaggoo;; to get <<//,

  +o  Don't use \\eenndd{{vveerrbbaattiimm}} within a vveerrbb environment, as this is what
     LaTeX uses to end the vveerrbbaattiimm environment. (In the future, it
     should be possible to hide the underlying text formatter entirely,
     but the parser doesn't support this feature yet.)

     The ccooddee environment is much just like the vveerrbb environment, except
     that horizontal rules are added to the surrounding text, as so:

     ___________________________________________________________________
     Here is an example code environment.
     ___________________________________________________________________

  You should use the ttssccrreeeenn environment around any vveerrbb environments,
  as so:

       <tscreen><verb>
       Here is some example text.
       </verb></tscreen>

  ttssccrreeeenn is an environment that simply indents the text and sets the
  sets the default font to tttt. This makes examples look much nicer, both
  in the LaTeX and plain text versions. You can use ttssccrreeeenn without
  vveerrbb, however, if you use any special characters in your example
  you'll need to use both of them. ttssccrreeeenn does nothing to special char-
  acters. See eexxaammppllee..ssggmmll for examples.

  The qquuoottee environment is like ttssccrreeeenn, except that it does not set the
  default font to tttt. So, you can use qquuoottee for non-computer-interaction
  quotes, as in:

       <quote>
       Here is some text to be indented, as in a quote.
       </quote>

  which will generate:

  Here is some text to be indented, as in a quote.

  33..44..  OOvveerraallll DDooccuummeenntt SSttrruuccttuurree

  Before we get too in-depth with details, I'm going to describe the
  overall structure of a document as defined by the Linuxdoc-SGML DTD.
  Look at eexxaammppllee..ssggmmll for a good example of how a document is set up.

  33..44..11..  TThhee PPrreeaammbbllee

  In the document ``preamble'' you set up things such as the title
  information and document style. For a Linux HOWTO document this should
  look like:

       <!doctype linuxdoc system>

       <article>

       <title>Linux Foo HOWTO
       <author>Norbert Ebersol, <tt/norb@baz.com/
       <date>v1.0, 9 March 1994
       <abstract>
       This document describes how to use the <tt/foo/ tools to frobnicate
       bar libraries, using the <tt/xyzzy/ relinker.
       </abstract>

       <toc>

  The elements should go more or less in this order. The first line
  tells the SGML parser to use the Linuxdoc-SGML DTD. The <<aarrttiiccllee>> tag
  forces the document to use the ``article'' document style. (The
  original QWERTZ DTD defines ``report'' and ``book'' as well; I haven't
  tweaked these for use with Linuxdoc-SGML).

  The ttiittllee, aauutthhoorr, and ddaattee tags should be obvious; in the ddaattee tag
  include the version number and last modification time of the document.

  The aabbssttrraacctt tag sets up the text to be printed at the top of the
  document, _b_e_f_o_r_e the table of contents. If you're not going to include
  a table of contents (the ttoocc tag), you probably don't need an
  aabbssttrraacctt. I suggest that all Linux HOWTOs use this same format for the
  preamble, so that the title, abstract, and table of contents are all
  there and look the same.

  33..44..22..  SSeeccttiioonniinngg AAnndd PPaarraaggrraapphhss

  After the preamble, you're ready to dive into the document. The
  following sectioning commands are available:

  +o  sseecctt: For top-level sections (i.e. 1, 2, and so on.)

  +o  sseecctt11: For second-level subsections (i.e. 1.1, 1.2, and so on.)

  +o  sseecctt22: For third-level subsubsections.

  +o  sseecctt33: For fourth-level subsubsubsections.

  +o  sseecctt44: For fifth-level subsubsubsubsections.

     These are roughly equivalent to their LaTeX counterparts sseeccttiioonn,
     ssuubbsseeccttiioonn, and so on.

  After the sseecctt (or sseecctt11, sseecctt22, etc.) tag comes the name of the
  section. For example, at the top of this document, after the preamble,
  comes the tag:

       <sect>Introduction

  And at the beginning of this section (Sectioning and paragraphs),
  there is the tag:

       <sect2>Sectioning And Paragraphs

  After the section tag, you begin the body of the section. However, you
  must start the body with a <<pp>> tag, as so:

       <sect>Introduction
       <p>
       This is a user's guide to the Linuxdoc-SGML document processing...

  This is to tell the parser that you're done with the section title and
  are ready to begin the body. Thereafter, new paragraphs are started
  with a blank line (just as you would do in TeX). For example,

       Here is the end of the first paragraph.

       And we start a new paragraph here.

  There is no reason to use <<pp>> tags at the beginning of every para-
  graph; only at the beginning of the first paragraph after a sectioning
  command.

  33..44..33..  EEnnddiinngg TThhee DDooccuummeenntt

  At the end of the document, you must use the tag:

       </article>

  to tell the parser that you're done with the aarrttiiccllee element (which
  embodies the entire document).

  33..55..  CCrroossss--RReeffeerreenncceess

  Now we're going to move onto other features of the system.  Cross-
  references are easy. For example, if you want to make a cross-
  reference to a certain section, you need to label that section as so:

       <sect1>Introduction<label id="sec-intro">

  You can then refer to that section somewhere in the text using the
  expression:

       See section <ref id="sec-intro" name="Introduction"> for an introduction.

  This will replace the rreeff tag with the section number labeled as sseecc--
  iinnttrroo. The nnaammee argument to rreeff is necessary for groff and HTML trans-
  lations. The groff macro set used by Linuxdoc-SGML does not currently
  support cross-references, and it's often nice to refer to a section by
  name instead of number.

  For example, this section is ``Cross-References''.

  There is also a uurrll element for Universal Resource Locators, or URLs,
  used on the World Wide Web. This element should be used to refer to
  other documents, files available for FTP, and so forth. For example,

       You can get the Linux HOWTO documents from
       <url url="http://sunsite.unc.edu/mdw/HOWTO/"
            name="The Linux HOWTO INDEX">.

  The uurrll argument specifies the actual URL itself. A link to the URL in
  question will be automatically added to the HTML document.  The
  optional nnaammee argument specifies the text that should be anchored to
  the URL (for HTML conversion) or named as the description of the URL
  (for LaTeX and groff). If no nnaammee argument is given, the URL itself
  will be used.

  For example, you can get the Linuxdoc-SGML package from
  ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt//lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz.

  A useful variant of this is hhttmmlluurrll, which suppresses rendering of the
  URL part in every context except HTML.  What this is useful for is
  things like a person's email addresses; you can write

       <htmlurl url="mailto:esr@snark.thyrsus.com"
                  name="esr@snark.thyrsus.com">

  and get ``esr@snark.thyrsus.com'' in text output rather than the
  duplicative ``esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>''
  but still have a proper URL in HTML documents.

  33..66..  FFoonnttss

  Essentially, the same fonts supported by LaTeX are supported by
  Linuxdoc-SGML. Note, however, that the conversion to plain text
  (through ggrrooffff) does away with the font information.  So, you should
  use fonts as much as possible, for the benefit of the conversion to
  LaTeX.  But don't depend on the fonts to get a point across in the
  plain text version.

  In particular, the tttt tag described above can be used to get constant-
  width ``typewriter'' font which should be used for all e-mail
  addresses, machine names, filenames, and so on.  Example:

       Here is some <tt>typewriter text</tt> to be included in the document.

  Equivalently:

       Here is some <tt/typewriter text/ to be included in the document.

  Remember that you can only use this abbreviated form if the enclosed
  text doesn't contain slashes.

  Other fonts can be achieved with bbff for bboollddffaaccee and eemm for _i_t_a_l_i_c_s.
  Several other fonts are supported as well, but I don't suggest you use
  them, because we'll be converting these documents to other formats
  such as HTML which may not support them.  Boldface, typewriter, and
  italics should be all that you need.

  33..77..  LLiissttss

  There are various kinds of supported lists. They are:

  +o  iitteemmiizzee for bulleted lists such as this one.

  +o  eennuumm for numbered lists.

  +o  ddeessccrriipp for ``descriptive'' lists.

     Each item in an iitteemmiizzee or eennuumm list must be marked with an iitteemm
     tag. Items in a ddeessccrriipp are marked with ttaagg.  For example,

       <itemize>
       <item>Here is an item.
       <item>Here is a second item.
       </itemize>

  Looks like this:

  +o  Here is an item.

  +o  Here is a second item.

     Or, for an eennuumm,
       <enum>
       <item>Here is the first item.
       <item>Here is the second item.
       </enum>

  You get the idea. Lists can be nested as well; see the example docu-
  ment for details.

  A ddeessccrriipp list is slightly different, and slightly ugly, but you might
  want to use it for some situations:

       <descrip>
       <tag/Gnats./ Annoying little bugs that fly into your cooling fan.
       <tag/Gnus./ Annoying little bugs that run on your CPU.
       </descrip>

  ends up looking like:

     GGnnaattss..
        Annoying little bugs that fly into your cooling fan.

     GGnnuuss..
        Annoying little bugs that run on your CPU.

  33..88..  FFuurrtthheerr IInnffoorrmmaattiioonn

  +o  The QWERTZ User's Guide is available from
     ffttpp::////ffttpp..ccss..ccoorrnneellll..eedduu//ppuubb//mmddww//SSGGMMLL.  QWERTZ (and hence,
     Linuxdoc-SGML) supports many features such as mathematical
     formulae, tables, figures, and so forth. I don't recommend using
     most of these features in the Linux HOWTOs because they won't
     render well in plain text. If you'd like to write general
     documentation in SGML, I suggest using the original QWERTZ DTD
     instead of the hacked-up Linuxdoc-SGML DTD, which I've modified for
     use particularly by the Linux HOWTOs and other such documentation.

  +o  Tom Gordon's original QWERTZ tools can be found at
     ffttpp::////ffttpp..ggmmdd..ddee//GGMMDD//ssggmmll.

  +o  More information on SGML can be found at the following WWW pages:

     1. SSGGMMLL aanndd tthhee WWeebb <<hhttttpp::////wwwwww..ww33..oorrgg//hhyyppeerrtteexxtt//WWWWWW//MMaarrkkUUpp//SSGGMMLL//>

     2. SSGGMMLL WWeebb PPaaggee <<hhttttpp::////wwwwww..ssiill..oorrgg//ssggmmll//ssggmmll..hhttmmll>

  +o  James Clark's ssggmmllss parser, and it's successor nnssggmmllss and other
     tools can be found at ffttpp::////ffttpp..jjccllaarrkk..ccoomm and at JJaammeess CCllaarrkk''ss WWWWWW
     PPaaggee <<hhttttpp::////wwwwww..jjccllaarrkk..ccoomm>.

  +o  You can join the Linuxdoc-SGML mailing list by sending mail to
     mmaajjoorrddoommoo@@vviiaa..eeccpp..ffrr with ssuubbssccrriibbee lliinnuuxxddoocc--ssggmmll in the message
     body.  The list address is lliinnuuxxddoocc--ssggmmll@@vviiaa..eeccpp..ffrr.

  +o  More information on LLyyXX can be found at the LLyyXX WWWWWW PPaaggee
     <<hhttttpp::////wwssiisseerrvv..iinnffoorrmmaattiikk..uunnii--ttuueebbiinnggeenn..ddee//~~eettttrriicchh//>.  LLyyXX is a
     high-level word processor frontend to LaTeX. Quasi-WYSIWYG
     interface, many LaTeX styles and layouts automatically generated.
     Speeds up learning LaTeX and makes complicated layouts easy and
     intuitive.

