<!DOCTYPE linuxdoc 
         PUBLIC "-//LinuxDoc//DTD LinuxDoc 97//EN" >
<!-- ================================================= -->
<!--

    $Id: guide.sgml,v 1.1 1997/07/09 13:18:49 cg Exp $
     
    This is the Linuxdoc SGML User's Guide file.
    This is guide.sgml, distributed with SGML-Tools.
    It was originally written for authors of Linux
    HOWTO's.

    $Log: guide.sgml,v $
    Revision 1.1  1997/07/09 13:18:49  cg
    * Added contrib/bk, with a lot of work-in-progress from Bernd. (CdG)


    Comments: This is the SGML-Tools User's Guide,
    originally by Matt Welsh. Updated by many people.
    See guide.txt or guide.ps for formatted output.

    Modified by Greg Hankins, 29 November 1996, for
    the first SGML Tools release v0.99.0.
    Modified by BK, May 1997, for strict DTD.
    Removed newline usage.

                                                       -->
<!-- ================================================= -->



<article>

<title>SGML-Tools User's Guide
<author>by Matt Welsh.  Updated by Greg Hankins.
<date>v0.99.10, 12 May 1997

<abstract>
This document is a user's guide to the SGML-Tools formatting system,
a SGML-based system which allows you to produce a variety of
output 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 SGML-Tools version 0.99.0.
</abstract>

<toc>

<sect>Introduction
<p>
This is a user's guide to the SGML-Tools document processing system.  SGML-Tools 
provides 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.

SGML-Tools is based heavily on the QWERTZ DTD by Tom Gordon,
<tt/thomas.gordon@gmd.de/.

<sect1>About This Document
<p>
This document is written using the linuxdoc DTD, which comes with SGML-Tools.  
It contains more or less everything you need to know to write SGML documents 
with this DTD.  See <tt/example.sgml/ for an example of an SGML document that 
you can use as a model for your own documents.

<sect1>Why SGML?
<p>
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 <em/structure/ 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 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 <em/emphasized text/.  Unlike LaTeX, however,
these elements are not in any way intrinsic to SGML itself.  The
linuxdoc 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 DTD is like LaTeX.

Don't be confused by this analogy.  SGML is <em/not/ a text-formatting system.
There is no ``SGML formatter'' per se.  SGML source is <em/only/ 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.

<sect1>How It Works
<p>
Here's how processing a document with SGML-Tools 
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 DTD for our purposes.  
The DTD simply sets up the structure of the document.  A small portion of
it looks like this:
<tscreen><verb>
<!element article - -
    (titlepag, header?, 
     toc?, lof?, lot?, p*, sect*, 
     (appendix, sect+)?, biblio?) +(footnote)>
</verb></tscreen>
This part sets up the overall structure for an ``article'', which is like
a ``documentstyle'' within LaTeX.  The article consists of a titlepage
(<tt/titlepag/), an optional header (<tt/header/), an optional table of 
contents (<tt/toc/), optional lists of figures (<tt/lof/) and tables
(<tt/lot/), any number of paragraphs (<tt/p/), any number of top-level
sections (<tt/sect/), optional appendices (<tt/appendix/), an optional
bibliography (<tt/biblio/) and footnotes (<tt/footnote/).  

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 
<tt/titlepag/, <tt/header/, <tt/sect/, 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 <em/do/ need to be familiar with
the document <em/structure/ 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 SGML documents in detail later.

The next step is to write a document using the structure defined by the
DTD.  Again, the linuxdoc 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 <em/parsed/ along with the DTD by the SGML <em/parser/.
I'm using the <tt/sgmls/ parser by James Clark, <tt/jjc@jclark.com/, who
also happens to be the author of <tt/groff/.  We're in good hands.
The parser (<tt/sgmls/) 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 <tt/sgmlsasp/, the next part of the
process.  

<tt/sgmlsasp/ is responsible for converting the output of <tt/sgmls/ to
another format (such as LaTeX).  It does this using <em/replacement files/,
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:
<tscreen><verb>
<itemize>    +    "\\begin&lcub;itemize&rcub;   +
&etago;itemize>   +    "\\end&lcub;itemize&rcub;    +
</verb></tscreen>
Which says that whenever you begin an <tt/itemize/ element in the 
SGML source, it should be replaced with 
<tscreen><verb>
\begin&lcub;itemize&rcub;
</verb></tscreen>
in the LaTeX source.  (As I said, elements in the 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 <tt/sgmlsasp/ 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.

<sect>Installation
<p>
Get <tt/sgml-tools-0.99.9.tar.gz/ from one of the following ftp sites:
<itemize>
<item><tt><htmlurl url="ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-0.99.0.tar.gz"
name="ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-0.99.0.tar.gz"></tt>
</itemize>

You can also get uptodate information from the 
<tt><url url="http://www.informatik.tu-muenchen.de/~schwarz/linuxdoc-sgml/"
name="SGML-Tools WWW Page"></tt>.

<p>
The file <tt/sgml-tools-0.99.0.tar.gz/ 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.  
<enum>
<item><tt/groff/.  You <em/need/ version 1.08 or greater.  You can get this from 
<tt><htmlurl url="ftp://prep.ai.mit.edu/pub/gnu" 
name="ftp://prep.ai.mit.edu/pub/gnu"></tt>.  There is a Linux 
binary version on 
<tt><htmlurl url="ftp://sunsite.unc.edu/pub/Linux/utils/text"
name="ftp://sunsite.unc.edu/pub/Linux/utils/text"></tt>
as well.  You will need <tt/groff/ to produce plain text from your SGML documents.
<tt/nroff/ will <em/not/ work!

<item>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 <tt/sunsite.unc.edu/).  Of course, you only need TeX/LaTeX
if you want to format your SGML documents with LaTeX.  So, installing TeX/LaTeX
is optional.

<item><tt/flex/.  <tt/lex/ will probably not work.  You can get this from
<tt><htmlurl url="ftp://prep.ai.mit.edu/pub/gnu" 
name="ftp://prep.ai.mit.edu/pub/gnu"></tt>.

<item><tt/gawk/ and the GNU info tools, for formatting and viewing 
info files.  These are also available on 
<tt><htmlurl url="ftp://prep.ai.mit.edu/pub/gnu"
name="ftp://prep.ai.mit.edu/pub/gnu"></tt>, or on 
<tt><htmlurl url="ftp://sunsite.unc.edu/pub/Linux/utils/text"
name="ftp://sunsite.unc.edu/pub/Linux/utils/text"></tt> 
(for <tt/gawk/) and
<tt><htmlurl url="ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers"
name="ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers"></tt> 
(for GNU info tools).  <tt/awk/ will not work.

<item>LyX (a quasi-WYSIWYG interface to LaTeX, with SGML layouts), is
available on 
<tt><htmlurl url="ftp://ftp.via.ecp.fr"
name="ftp://ftp.via.ecp.fr"></tt>.
</enum>

<sect1>Installing The Software
<p>
The steps needed to install and configure the SGML-Tools are:

<enum>
<item>First, unpack the tar file <tt/sgml-tools-0.99.0.tar.gz/ somewhere.  
This will create the directory <tt/sgml-tools-0.99.0/.  It doesn't matter 
where you unpack this file; just don't move things around within the 
<tt/sgml-tools-0.99.0/ directory.

<item>Read the <tt/INSTALL/ file - it has detailed installation instructions.

If all went well, you should be ready to use the system.
</enum>

<sect1>Formatting SGML Documents
<p>
Let's say you have the SGML document <tt/foo.sgml/, 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.

<sect2>Creating Plain Text Output
<p>
If you want to produce plain text, use the command:
<tscreen><verb>
% sgml2txt foo.sgml 
</verb></tscreen>

<p>
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.

<p>
You can also create groff source for man pages, which can be formatted with
<tt/groff -man/.  To do this, do the following:
<tscreen><verb>
% sgml2txt -man foo.sgml 
</verb></tscreen>

<sect2>Creating LaTeX, DVI or PostScript Output
<p>
To create a LaTeX documents from the SGML source file, simply run:
<tscreen><verb>
% sgml2latex foo.sgml 
</verb></tscreen>

<p>
If you want to produce PostScript output (via <tt/dvips/), use the 
<tt/-p/ option:
<tscreen><verb>
% sgml2latex -p foo.sgml 
</verb></tscreen>

<p>
Or, you can produce a DVI file using the <tt>-d</tt> switch, as so:
<tscreen><verb>
% sgml2latex -d foo.sgml 
</verb></tscreen>

<sect2>Creating HTML Output
<p>
If you want to produce HTML output, do this:
<tscreen><verb>
% sgml2html -img foo.sgml 
</verb></tscreen>
<p>
This will produce <tt>foo.html</tt>, as well as <tt>foo-1.html</tt>,
<tt/foo-2.html/, and so on---one file for each section of the document.
Run your WWW browser on <tt>foo.html</tt>, 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 
<tt>&dollar;SGMLTOOLSLIB/icons</tt>.  These will also need to be copied to the 
final location of the HTML documents.  <tt/&dollar;SGMLTOOLSLIB/ is defined 
at the beginning of the SGML conversion scripts.

<p>
If you use <tt/sgml2html/ without the <tt/-img/ 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 
<tt>&dollar;SGMLTOOLSLIB/rep/html/&lt;filename&gt;</tt>, and substituting your 
own words for different languages.  The file has the following format:
<tscreen><verb>
	PrevPage:  newvalue
    NextPage:  newvalue
	TOC:     newvalue
</verb></tscreen>
See <tt/deutsch/ for an example.

<sect2>Creating GNU Info Output
<p>
If you want to format your file for the GNU info browser, just run the
following command:
<tscreen><verb>
% sgml2info foo.sgml 
</verb></tscreen>

<sect2>Creating LyX Output
<p>
For LyX output, use the the command:
<tscreen><verb>
% sgml2lyx foo.sgml 
</verb></tscreen>

<sect2>Creating RTF Output
<p>
If you want to produce RTF output, run the command:
<tscreen><verb>
% sgml2rtf foo.sgml 
</verb></tscreen>
<p>
This will produce <tt>foo.rtf</tt>, as well as <tt>foo-1.rtf</tt>,
<tt/foo-2.rtf/, and so on---one file for each section of the document.

<sect2>Checking SGML Syntax
<p>
If you just want to capture your errors from the SGML conversion,
use the <tt/sgmlcheck/ script.  For example.
<tscreen><verb>
% sgmlcheck foo.sgml 
</verb></tscreen>

<sect1>ISO 8859-1 Character Set
<p>
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 <tt/-l/ flag, for example:
<tscreen><verb>
% sgml2txt -l foo.sgml 
</verb></tscreen>
You also can use ISO 8859-1 characters in the SGML source, they will 
automatically be translated to the proper escape codes for the corresponding 
output format.

<sect>Writing Documents With SGML-Tools
<p>
For the most part, writing documents using the SGML-Tools 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 <tt/example.sgml/ 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 <tt/example.sgml/ so you have a real live case to
refer to.

<sect1>Basic Concepts
<p>
Looking at the source of the example document, you'll notice right off
that there are a number of ``tags'' marked within angle brackets
(<tt>&lt;</tt> and <tt/&gt;</tt>).  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 <tt>&bsol;item</tt> or 
<tt>&bsol;section{...}</tt>.

As a simple example, to produce <bf>this boldfaced text</bf>, I typed
<tscreen><verb>
As a simple example, to produce <bf>this boldfaced text&etago;bf>, ...
</verb></tscreen>
in the source.  <tt>&lt;bf></tt> begins the region of bold text, and
<tt>&etago;bf></tt> ends it.  Alternately, you can use the abbreviated form
<tscreen><verb>
As a simple example, to produce <bf/this boldfaced text/, ...
</verb></tscreen>
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 <tt>&lt;sect></tt> 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 (<tt/example.sgml/).

<sect1>Special Characters
<p>
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: <tt>&lt;foo></tt>.  In order to get the left angle bracket, you
must use the <tt>&amp;lt;</tt> element, which is a ``macro'' that expands
to the actual left-bracket character.  Therefore, in the source, I typed
<tscreen><verb>
angle brackets around it, as so: <tt>&ero;lt;foo>&etago;tt>.
</verb></tscreen>
Generally, something beginning with an ampersand is a special macro.  For
example, there's <tt/&amp;percnt;/ to produce &percnt;, 
<tt/&amp;verbar;/ to produce &verbar;, 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:
<itemize>
<item>Use <tt>&amp;amp;</tt> for the ampersand (&amp;), 
<item>Use <tt>&amp;lt;</tt> for a left bracket (&lt;),
<item>Use <tt>&amp;gt;</tt> for a right bracket (&gt),
<item>Use <tt>&amp;etago;</tt> for a left bracket with a slash 
(<tt>&etago;</tt>)
<item>Use <tt>&amp;dollar;</tt> for a dollar sign (&dollar;),
<item>Use <tt>&amp;num;</tt> for a hash (&num;),
<item>Use <tt>&amp;percnt;</tt> for a percent (&percnt;),
<item>Use <tt>&amp;tilde;</tt> for a tilde (&tilde;),
<item>Use <tt>``</tt> and <tt>''</tt> for quotes, or use
   <tt>&amp;dquot</tt> for &dquot;.
</itemize>
<p>
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 <tt>&dollar;SGMLTOOLSLIB/rep/latex/general</tt> would be a 
good place to start.  <tt/&dollar;SGMLTOOLSLIB/ is defined at the beginning 
of the SGML conversion scripts.

<sect1>Verbatim and Code Environments
<p>
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 
<tt>verb</tt> element is used for this; it looks like the following:
<tscreen><verb>
<verb>
 Some literal text to include as example output.
&etago;verb>
</verb></tscreen>
The <tt>verb</tt> environment doesn't allow you to use <em/everything/
within it literally.  Specifically, you must do the following within
<tt/verb/ environments.
<itemize>
<item>Use <tt>&amp;ero;</tt> to get an ampersand, 
<item>Use <tt>&amp;etago;</tt> to get <tt>&etago;</tt>,
<item>Don't use <tt>&bsol;end{verbatim}</tt> within a <tt>verb</tt>
environment, as this is what LaTeX uses to end the <tt>verbatim</tt> 
environment.  (In the future, it should be possible to hide the underlying
text formatter entirely, but the parser doesn't support this feature yet.) 
</itemize>
The <tt>code</tt> environment is much just like the <tt/verb/ environment,
except that horizontal rules are added to the surrounding text, as so:
<code>
Here is an example code environment.
</code>

You should use the <tt/tscreen/ environment around any <tt/verb/ environments,
as so:
<tscreen><verb>
<tscreen><verb>
Here is some example text.  
&etago;verb>&etago;tscreen>
</verb></tscreen>
<tt/tscreen/ is an environment that simply indents the text and sets the 
sets the default font to <tt/tt/.  This makes examples look much nicer, both
in the LaTeX and plain text versions.  You can use <tt/tscreen/
without <tt/verb/, however, if you use any special characters in your 
example you'll need to use both of them.  <tt/tscreen/ does nothing to 
special characters.  See <tt/example.sgml/ for examples.

The <tt/quote/ environment is like <tt/tscreen/, except that it does
not set the default font to <tt/tt/.  So, you can use <tt/quote/ for
non-computer-interaction quotes, as in:
<tscreen><verb>
<quote>
Here is some text to be indented, as in a quote.
&etago;quote>
</verb></tscreen>
which will generate:
<quote>
Here is some text to be indented, as in a quote.
</quote>

<sect1>Overall Document Structure
<p>
Before we get too in-depth with details, I'm going to describe the
overall structure of a document as defined by the DTD.
Look at <tt/example.sgml/ for a good example of how a document is set up.

<sect2>The Preamble
<p>
In the document ``preamble'' you set up things such as the title
information and document style: 
<tscreen><verb>
<!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.
&etago;abstract>

<toc>
</verb></tscreen>

The elements should go more or less in this order.  The first line tells
the SGML parser to use the linuxdoc DTD.  The <tt>&lt;article></tt>
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 SGML-Tools).

The <tt/title/, <tt/author/, and <tt/date/ tags should be obvious; in the
<tt>date</tt> tag include the version number and last modification time of
the document.

The <tt/abstract/ tag sets up the text to be printed at the top of the
document, <em/before/ the table of contents.  If you're not going to
include a table of contents (the <tt/toc/ tag), you probably don't
need an <tt/abstract/.

<sect2>Sectioning And Paragraphs
<p>
After the preamble, you're ready to dive into the document.  The following
sectioning commands are available:
<itemize>
<item><tt/sect/: For top-level sections (i.e.  1, 2, and so on.) 
<item><tt/sect1/: For second-level subsections (i.e.  1.1, 1.2, and so on.)
<item><tt/sect2/: For third-level subsubsections.
<item><tt/sect3/: For fourth-level subsubsubsections.
<item><tt/sect4/: For fifth-level subsubsubsubsections.
</itemize>
These are roughly equivalent to their LaTeX counterparts <tt/section/,
<tt/subsection/, and so on.

After the <tt/sect/ (or <tt/sect1/, <tt/sect2/, etc.) tag comes the
name of the section.  For example, at the top of this document, after
the preamble, comes the tag:
<tscreen><verb>
<sect>Introduction
</verb></tscreen>
And at the beginning of this section (Sectioning and paragraphs), there
is the tag:
<tscreen><verb>
<sect2>Sectioning And Paragraphs
</verb></tscreen>
After the section tag, you begin the body of the section.  However, you
must start the body with a <tt>&lt;p></tt> tag, as so:
<tscreen><verb>
<sect>Introduction
<p>
This is a user's guide to the SGML-Tools document processing...
</verb></tscreen>
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,
<tscreen><verb>
Here is the end of the first paragraph.

And we start a new paragraph here.
</verb></tscreen>
There is no reason to use <tt>&lt;p></tt> tags at the beginning of
every paragraph; only at the beginning of the first paragraph after
a sectioning command.

<sect2>Ending The Document
<p>
At the end of the document, you must use the tag:
<tscreen><verb>
&etago;article>
</verb></tscreen>

to tell the parser that you're done with the <tt/article/ element (which
embodies the entire document).  
</sect2>

<sect1>Cross-References<label id="cross-ref">
<p>
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:
<tscreen><verb>
<sect1>Introduction<label id="sec-intro">
</verb></tscreen>
You can then refer to that section somewhere in the text using the
expression:
<tscreen><verb>
See section <ref id="sec-intro" name="Introduction"> for an introduction.
</verb></tscreen>
This will replace the <tt/ref/ tag with the section number labeled
as <tt/sec-intro/.  The <tt/name/ argument to <tt/ref/ is necessary for
groff and HTML translations.  The groff macro set used by SGML-Tools 
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 <ref id="cross-ref" name="Cross-References">.

There is also a <tt/url/ 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,
<tscreen><verb>
You can get the Linux HOWTO documents from 
<url url="http://sunsite.unc.edu/mdw/HOWTO/" 
   name="The Linux HOWTO INDEX">.
</verb></tscreen>
The <tt/url/ argument specifies the actual URL itself.  A link to the
URL in question will be automatically added to the HTML document.
The optional <tt/name/ 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 <tt/name/ argument is given, the
URL itself will be used.

For example, you can get the SGML-Tools package from
<tt><htmlurl 
url="ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-0.99.0.tar.gz"
name="ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-0.99.0.tar.gz"></tt>.

A useful variant of this is <tt/htmlurl/, 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
<tscreen><verb>
<htmlurl url="mailto:esr@snark.thyrsus.com"
      name="esr@snark.thyrsus.com">
</verb></tscreen>
and get ``esr@snark.thyrsus.com'' in text output rather than the
duplicative ``esr@snark.thyrsus.com &lt;mailto:esr@snark.thyrsus.com&gt;''
but still have a proper URL in HTML documents.

<sect1>Fonts
<p>
Essentially, the same fonts supported by LaTeX are supported
by SGML-Tools.  Note, however, that the conversion to 
plain text (through <tt/groff/) 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 <tt/tt/ 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:
<tscreen><verb>
Here is some <tt>typewriter text&etago;tt> to be included in the document.
</verb></tscreen>
Equivalently:
<tscreen><verb>
Here is some <tt/typewriter text/ to be included in the document.
</verb></tscreen>
Remember that you can only use this abbreviated form if the enclosed
text doesn't contain slashes.

Other fonts can be achieved with <tt/bf/ for <bf/boldface/ and <tt/em/ 
for <em/italics/.  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.

<sect1>Lists
<p>
There are various kinds of supported lists.  They are:
<itemize>
<item><tt/itemize/ for bulleted lists such as this one.
<item><tt/enum/ for numbered lists.
<item><tt/descrip/ for ``descriptive'' lists.  
</itemize>
Each item in an <tt/itemize/ or <tt/enum/ list must be marked
with an <tt/item/ tag.  Items in a <tt/descrip/ are marked with <tt/tag/.
For example,
<tscreen><verb>
<itemize>
<item>Here is an item.
<item>Here is a second item.
&etago;itemize>
</verb></tscreen>
Looks like this:
<itemize>
<item>Here is an item.
<item>Here is a second item.
</itemize>
Or, for an <tt/enum/,
<tscreen><verb>
<enum>
<item>Here is the first item.
<item>Here is the second item.
&etago;enum>
</verb></tscreen>
You get the idea.  Lists can be nested as well; see the example document
for details.

A <tt/descrip/ list is slightly different, and slightly ugly, but
you might want to use it for some situations:
<tscreen><verb>
<descrip>
<tag/Gnats./ Annoying little bugs that fly into your cooling fan.
<tag/Gnus./ Annoying little bugs that run on your CPU.
&etago;descrip>
</verb></tscreen>
ends up looking like:
<descrip>
<tag/Gnats./ Annoying little bugs that fly into your cooling fan.
<tag/Gnus./ Annoying little bugs that run on your CPU.
</descrip>

<sect1>Further Information
<p>
	<itemize>
	<item>The QWERTZ User's Guide is available from 
	<tt><htmlurl url="ftp://ftp.cs.cornell.edu/pub/mdw/SGML"
	name="ftp://ftp.cs.cornell.edu/pub/mdw/SGML"></tt>.
	QWERTZ (and hence, SGML-Tools) supports many features such as 
	mathematical formulae, tables, figures, and so forth.
	If you'd like to write general 
	documentation in SGML, I suggest using the original QWERTZ DTD instead 
	of the hacked-up linuxdoc DTD, which I've modified for use 
	particularly by the Linux HOWTOs and other such documentation.  

	<item>Tom Gordon's original QWERTZ tools can be found at 
	<tt><htmlurl url="ftp://ftp.gmd.de/GMD/sgml" 
	name="ftp://ftp.gmd.de/GMD/sgml"></tt>.

	<item>More information on SGML can be found at the following WWW 
	pages: 
	<enum>
	<item><tt><url url="http://www.w3.org/hypertext/WWW/MarkUp/SGML/"
	name="SGML and the Web"></tt>
	<item><tt><url url="http://www.sil.org/sgml/sgml.html"
	name="SGML Web Page"></tt>
	<item><tt><url url="http://www.yahoo.com/Computers&lowbar;and&lowbar;Internet/Software/Data&lowbar;Formats/SGML" name="Yahoo's SGML Page"></tt>
	</enum>

	<item>James Clark's <tt/sgmls/ parser, and it's successor <tt/nsgmls/
	and other tools can be found at
	<tt><htmlurl url="ftp://ftp.jclark.com" name="ftp://ftp.jclark.com">
	</tt> and at <tt><url url="http://www.jclark.com" 
	name="James Clark's WWW Page"></tt>.

	<item>The emacs psgml package can be found at
	<tt><htmlurl url="ftp://ftp.lysator.liu.se/pub/sgml" 
	name="ftp://ftp.lysator.liu.se/pub/sgml"></tt>.  This package
	provides a lot of SGML functionality.

	<item>You can join the SGML-Tools mailing list by sending mail to
	<tt><htmlurl url="mailto:majordomo@via.ecp.fr" 
	name="majordomo@via.ecp.fr"></tt> with <tt/subscribe linuxdoc-sgml/ in 
	the message body.  The list address is 
	<tt><htmlurl url="mailto:linuxdoc-sgml@via.ecp.fr" 
	name="linuxdoc-sgml@via.ecp.fr"></tt>.

	<item>More information on <tt/LyX/ can be found at the
	<tt><url url="http://wsiserv.informatik.uni-tuebingen.de/~ettrich/"
	name="LyX WWW Page"></tt>.  <tt/LyX/ 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.

	</itemize>
</article>
<!-- ================================================= -->
<!-- end of example.sgml                               -->
<!--
     Local Variables:
     mode: sgml
     End:                                              -->
<!-- ================================================= -->