#This file was created by LinuxDoc-SGML
#(conversion : Frank Pavageau and Jose' Matos)
\lyxformat 2.15
\textclass linuxdoc
\language default
\inputencoding default
\fontscheme default
\papersize Default
\paperfontsize default
\spacing single
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language default
\quotes_times 2
\paperorientation portrait
\papercolumns 1
\papersides 1
\paperpagestyle default
\layout Title

\added_space_top vfill \added_space_bottom vfill
SGML-Tools User's Guide 
\layout Author

by Matt Welsh.  Updated by Greg Hankins, rewritten by Eric S. Raymond. 
\layout Date

1.0 ($Revision: 1.4 $), 10 November 1997 
\layout 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 document source file.  This guide describes SGML-Tools version 1.0. 
\layout Standard

\begin_inset LatexCommand \tableofcontents
\end_inset
\layout Section

Introduction 
\layout Standard

SGML-Tools is a suite of programs to help you write source documents 
that can be rendered as plain text, hypertext, or high-quality typeset 
markup suitable for printing books.  
\layout Standard

This document is the user's guide to the SGML-Tools document processing system. 
It contains more or less everything you need to know to set up 
SGML-Tools and write documents using it.  See 
\family typewriter example.sgml
\family default  for 
an example of an SGML document that you can use as a model for your 
own documents. 
\layout Section

Installation 
\layout Standard

You can get 
\family typewriter sgml-tools-1.0.x.tar.gz
\family default  from: 
\layout Itemize
\begin_inset LatexDel \htmlurl{
\end_inset
http://pobox.com/~cg/sgmltools
\begin_inset LatexDel }{
\end_inset
http://pobox.com/~cg/sgmltools
\begin_inset LatexDel }
\end_inset
\layout Subsection

What SGML-Tools Needs 
\layout Standard

The file 
\family typewriter sgml-tools-1.0.x.tar.gz
\family default  contains everything that you 
need to write SGML documents and convert them to groff, LaTeX, 
PostScript, HTML, GNU info, LyX, and RTF.  In addition to this 
package, you will need some additional tools for generating formatted 
output. 
\layout Enumerate
\family typewriter groff
\family default .  You 
\shape italic need
\shape default  version 1.08 or greater.  You can get 
this from \begin_inset LatexDel \htmlurl{
\end_inset
ftp://prep.ai.mit.edu/pub/gnu
\begin_inset LatexDel }{
\end_inset
ftp://prep.ai.mit.edu/pub/gnu
\begin_inset LatexDel }
\end_inset
.  There is a Linux binary 
version at \begin_inset LatexDel \htmlurl{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/utils/text
\begin_inset LatexDel }{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/utils/text
\begin_inset LatexDel }
\end_inset
 as well.  You 
will need 
\family typewriter groff
\family default  to produce plain text from your SGML documents. 
\family typewriter nroff
\family default  will 
\shape italic not
\shape default  work! 
You can find the version of your 
\family typewriter groff
\family default  from 
\family typewriter groff -v < /dev/null
\family default . 
\layout Enumerate
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 
\family typewriter sunsite.unc.edu
\family default ).  Of course, you only need TeX/LaTeX 
if you want to format your SGML documents with LaTeX.  So, installing TeX/LaTeX 
is optional. 
\layout Enumerate
\family typewriter flex
\family default .  
\family typewriter lex
\family default  will probably not work.  You can get flex from 
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://prep.ai.mit.edu/pub/gnu
\begin_inset LatexDel }{
\end_inset
ftp://prep.ai.mit.edu/pub/gnu
\begin_inset LatexDel }
\end_inset
\family default . 
\layout Enumerate
\family typewriter gawk
\family default  and the GNU info tools, for formatting and viewing  
info files.  These are also available on  
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://prep.ai.mit.edu/pub/gnu
\begin_inset LatexDel }{
\end_inset
ftp://prep.ai.mit.edu/pub/gnu
\begin_inset LatexDel }
\end_inset
\family default , or on  
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/utils/text
\begin_inset LatexDel }{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/utils/text
\begin_inset LatexDel }
\end_inset
\family default   
(for 
\family typewriter gawk
\family default ) and 
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers
\begin_inset LatexDel }{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers
\begin_inset LatexDel }
\end_inset
\family default   
(for GNU info tools).  
\family typewriter awk
\family default  will not work. 
\layout Enumerate
LyX (a quasi-WYSIWYG interface to LaTeX, with SGML layouts), is 
available on  
\begin_inset LatexDel \htmlurl{
\end_inset
ftp://ftp.via.ecp.fr
\begin_inset LatexDel }{
\end_inset
ftp://ftp.via.ecp.fr
\begin_inset LatexDel }
\end_inset
. 
\layout Subsection

Installing The Software 
\layout Standard

The steps needed to install and configure the SGML-Tools are: 
\layout Enumerate
First, unpack the tar file 
\family typewriter sgml-tools-1.0.x.tar.gz
\family default  somewhere.   
This will create the directory 
\family typewriter sgml-tools-1.0.x
\family default .  It doesn't matter  
where you unpack this file; just don't move things around within the  
\family typewriter sgml-tools-1.0.x
\family default  directory. 
\layout Enumerate
Read the 
\family typewriter INSTALL
\family default  file - it has detailed installation instructions. 
Follow them.  If all went well, you should be ready to use the system 
immediately once you have done so. 
\layout Section

Writing Documents With SGML-Tools 
\layout Standard

For the most part, writing documents using SGML-Tools is very 
simple, and rather like writing HTML.  However, there are some caveats to 
watch out for.  In this section we'll give an introduction on writing 
SGML documents.  See the file 
\family typewriter example.sgml
\family default  for a SGML example 
document (and tutorial) which you can use as a model when writing your 
own documents.  Here we're just going to discuss the various features 
of SGML-Tools, but the source is not very readable as an example.  Instead, 
print out the source (as well as the formatted output) for 
\family typewriter example.sgml
\family default  so you have a real live case to refer to. 
\layout Subsection

Basic Concepts 
\layout Standard

Looking at the source of the example document, you'll notice right off 
that there are a number of ``tags'' marked within angle brackets 
(
\family typewriter <
\family default  and 
\family typewriter >
\family default ).  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 an HTML tag, or a LaTeX command such as 
\family typewriter 
\backslash
 item
\family default  or  
\family typewriter 
\backslash
 section{...}
\family default . 
\layout Standard

As a simple example, to produce 
\series bold this boldfaced text
\series default , you would type 
\begin_deeper
\layout Verbatim

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

\protected_separator

\end_deeper
\layout Standard

in the source.  
\family typewriter <bf>
\family default  begins the region of bold text, and 
\family typewriter </bf>
\family default  ends it.  Alternately, you can use the abbreviated form 
\begin_deeper
\layout Verbatim

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

\protected_separator

\end_deeper
\layout Standard

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).   
\layout Standard

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). 
\layout Standard

In some cases, the end-tag for a particular element is optional.  For 
example, to begin a section, you use the 
\family typewriter <sect>
\family default  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 (
\family typewriter example.sgml
\family default ). 
\layout Subsection

Special Characters 
\layout Standard

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: 
\family typewriter <foo>
\family default .  In order to get the left angle bracket, you 
must use the 
\family typewriter &lt;
\family default  element, which is a ``macro'' that expands 
to the actual left-bracket character.  Therefore, in the source, I typed 
\begin_deeper
\layout Verbatim

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

\protected_separator

\end_deeper
\layout Standard

Generally, anything beginning with an ampersand is a special 
character.  For example, there's 
\family typewriter &percnt;
\family default  to produce 
%, 
\family typewriter &verbar;
\family default  to produce |, and so on.  For every 
special character that might otherwise confuse SGML-Tools if typed by 
itself, there is an ampersand "entity" to represent it.  The most 
commonly used are: 
\layout Itemize
Use 
\family typewriter &amp;
\family default  for the ampersand (&),  
\layout Itemize
Use 
\family typewriter &lt;
\family default  for a left bracket (<), 
\layout Itemize
Use 
\family typewriter &gt;
\family default  for a right bracket (>), 
\layout Itemize
Use 
\family typewriter &etago;
\family default  for a left bracket with a slash  
(
\family typewriter </
\family default ) 
\layout Itemize
Use 
\family typewriter &dollar;
\family default  for a dollar sign ($), 
\layout Itemize
Use 
\family typewriter &num;
\family default  for a hash (#), 
\layout Itemize
Use 
\family typewriter &percnt;
\family default  for a percent (%), 
\layout Itemize
Use 
\family typewriter &tilde;
\family default  for a tilde (), 
\layout Itemize
Use 
\family typewriter ``
\family default  and 
\family typewriter ''
\family default  for quotes, or use 
\family typewriter &dquot;
\family default  for ". 
\layout Itemize
Use 
\family typewriter &shy;
\family default  for a soft hyphen (that is, an indication 
that this is a good place to break a word for horizontal justification).   
\layout Standard

Here is a complete list of the entities recognized by 1.0.x.  Note 
that not all back-ends will be able to make anything useful from every 
entity -- if you see parantheses with nothing between them in the 
list, it means that the back-end that generated what you're looking at 
has no replacement for the entity.  The ``common'' ones listed above 
are pretty reliable. 
\layout Description

&half
\protected_separator

\protected_separator

\protected_separator
(½)
\protected_separator

 vertical 1/2 fraction 
\layout Description

&frac12
\protected_separator
(½)
\protected_separator

 typeset 1/2 fraction 
\layout Description

&frac14
\protected_separator
(¼)
\protected_separator

 typeset 1/4 fraction 
\layout Description

&frac34
\protected_separator
(¾)
\protected_separator

 typeset 3/4 fraction 
\layout Description

&frac18
\protected_separator
(1/8)
\protected_separator

 typeset 1/8 fraction 
\layout Description

&frac38
\protected_separator
(3/8)
\protected_separator

 typeset 3/8 fraction 
\layout Description

&frac58
\protected_separator
(5/8)
\protected_separator

 typeset 5/8 fraction 
\layout Description

&frac78
\protected_separator
(7/8)
\protected_separator

 typeset 7/8 fraction 
\layout Description

&sup1
\protected_separator

\protected_separator

\protected_separator
(¹)
\protected_separator

 superscript 1 
\layout Description

&sup2
\protected_separator

\protected_separator

\protected_separator
(²)
\protected_separator

 superscript 2 
\layout Description

&sup3
\protected_separator

\protected_separator

\protected_separator
(³)
\protected_separator

 superscript 3 
\layout Description

&plus
\protected_separator

\protected_separator

\protected_separator
(+)
\protected_separator

 plus sign 
\layout Description

&plusmn
\protected_separator
(±)
\protected_separator

 plus-or-minus sign 
\layout Description

&lt
\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator
(<)
\protected_separator

 less-than sign 
\layout Description

&equals
\protected_separator
(=)
\protected_separator

 equals sign 
\layout Description

&gt
\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator
(>)
\protected_separator

 greater-than sign 
\layout Description

&divide
\protected_separator
(/)
\protected_separator

 division sign 
\layout Description

&times
\protected_separator

\protected_separator
(×)
\protected_separator

 multiplication sign 
\layout Description

&curren
\protected_separator
(¤)
\protected_separator

 currency symbol 
\layout Description

&pound
\protected_separator

\protected_separator
(£)
\protected_separator

 symbol for ``pounds'' 
\layout Description

&dollar
\protected_separator
($)
\protected_separator

 dollar sign 
\layout Description

&cent
\protected_separator

\protected_separator

\protected_separator
(¢)
\protected_separator

 cent sign 
\layout Description

&yen
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(¥)
\protected_separator

 yen sign 
\layout Description

&num
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(#)
\protected_separator

 number or hash sign 
\layout Description

&percnt
\protected_separator
(%)
\protected_separator

 percent sign 
\layout Description

&amp
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(&)
\protected_separator

 ampersand 
\layout Description

&ast
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(*)
\protected_separator

 asterisk 
\layout Description

&commat
\protected_separator
(@)
\protected_separator

 commercial-at sign 
\layout Description

&lsqb
\protected_separator

\protected_separator

\protected_separator
([)
\protected_separator

 left square bracket 
\layout Description

&bsol
\protected_separator

\protected_separator

\protected_separator
(\backslash
\protected_separator
)
\protected_separator

 backslash 
\layout Description

&rsqb
\protected_separator

\protected_separator

\protected_separator
(])
\protected_separator

 right square bracket 
\layout Description

&lcub
\protected_separator

\protected_separator

\protected_separator
({)
\protected_separator

 left curly brace 
\layout Description

&horbar
\protected_separator
(-)
\protected_separator

 horizontal bar 
\layout Description

&verbar
\protected_separator
(|)
\protected_separator

 vertical bar 
\layout Description

&rcub
\protected_separator

\protected_separator

\protected_separator
(})
\protected_separator

 right curly brace 
\layout Description

&micro
\protected_separator

\protected_separator
(µ)
\protected_separator

 greek mu (micro prefix) 
\layout Description

&ohm
\protected_separator

\protected_separator

\protected_separator

\protected_separator
({ohm})
\protected_separator

 greek capital omega (Ohm sign) 
\layout Description

&deg
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(°)
\protected_separator

 small superscript circle sign (degree sign) 
\layout Description

&ordm
\protected_separator

\protected_separator

\protected_separator
({ordm})
\protected_separator

 masculine ordinal 
\layout Description

&ordf
\protected_separator

\protected_separator

\protected_separator
({ordf})
\protected_separator

 feminine ordinal 
\layout Description

&sect
\protected_separator

\protected_separator

\protected_separator
(§)
\protected_separator

 section sign 
\layout Description

&para
\protected_separator

\protected_separator

\protected_separator
(¶)
\protected_separator

 paragraph sign 
\layout Description

&middot
\protected_separator
(·)
\protected_separator

 centered dot 
\layout Description

&larr
\protected_separator

\protected_separator

\protected_separator
(<-)
\protected_separator

 left arrow 
\layout Description

&rarr
\protected_separator

\protected_separator

\protected_separator
(->)
\protected_separator

 right arrow 
\layout Description

&uarr
\protected_separator

\protected_separator

\protected_separator
({uarr})
\protected_separator

 up arrow 
\layout Description

&darr
\protected_separator

\protected_separator

\protected_separator
({darr})
\protected_separator

 down arrow 
\layout Description

&copy
\protected_separator

\protected_separator

\protected_separator
(©)
\protected_separator

 copyright 
\layout Description

&reg
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(®)
\protected_separator

 r-in-circle marl 
\layout Description

&trade
\protected_separator

\protected_separator
((TM))
\protected_separator

 trademark sign 
\layout Description

&brvbar
\protected_separator
(¦)
\protected_separator

 broken vertical bar 
\layout Description

&not
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(¬)
\protected_separator

 logical-negation sign 
\layout Description

&sung
\protected_separator

\protected_separator

\protected_separator
({sung})
\protected_separator

 sung-note sign 
\layout Description

&excl
\protected_separator

\protected_separator

\protected_separator
(!)
\protected_separator

 exclamation point 
\layout Description

&iexcl
\protected_separator

\protected_separator
(¡)
\protected_separator

 inverted exclamation point 
\layout Description

&quot
\protected_separator

\protected_separator

\protected_separator
(")
\protected_separator

 double quote 
\layout Description

&apos
\protected_separator

\protected_separator

\protected_separator
(')
\protected_separator

 apostrophe (single quote) 
\layout Description

&lpar
\protected_separator

\protected_separator

\protected_separator
(()
\protected_separator

 left parenthesis 
\layout Description

&rpar
\protected_separator

\protected_separator

\protected_separator
())
\protected_separator

 right parenthesis 
\layout Description

&comma
\protected_separator

\protected_separator
(,)
\protected_separator

 comma 
\layout Description

&lowbar
\protected_separator
(_)
\protected_separator

 under-bar 
\layout Description

&hyphen
\protected_separator
(-)
\protected_separator

 hyphen 
\layout Description

&period
\protected_separator
(.)
\protected_separator

 period 
\layout Description

&sol
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(/)
\protected_separator

 solidus 
\layout Description

&colon
\protected_separator

\protected_separator
(:)
\protected_separator

 colon 
\layout Description

&semi
\protected_separator

\protected_separator

\protected_separator
(;)
\protected_separator

 semicolon 
\layout Description

&quest
\protected_separator

\protected_separator
(?)
\protected_separator

 question mark 
\layout Description

&iquest
\protected_separator
(¿)
\protected_separator

 interrobang 
\layout Description

&laquo
\protected_separator

\protected_separator
(«)
\protected_separator

 left guillemot 
\layout Description

&raquo
\protected_separator

\protected_separator
(»)
\protected_separator

 right guillemot 
\layout Description

&lsquo
\protected_separator

\protected_separator
(`)
\protected_separator

 left single quote 
\layout Description

&rsquo
\protected_separator

\protected_separator
(')
\protected_separator

 right single quote 
\layout Description

&ldquo
\protected_separator

\protected_separator
(")
\protected_separator

 left double quote 
\layout Description

&rdquo
\protected_separator

\protected_separator
(")
\protected_separator

 right double quote 
\layout Description

&nbsp
\protected_separator

\protected_separator

\protected_separator
( )
\protected_separator

 non-breaking space 
\layout Description

&shy
\protected_separator

\protected_separator

\protected_separator

\protected_separator
()
\protected_separator

 soft hyphen 
\layout Subsection

Verbatim and Code Environments 
\layout Standard

While we're on the subject of special characters, we might as well mention 
the verbatim ``environment'' used for including literal text in the output 
(with spaces and indentation preserved, and so on).  The  
\family typewriter verb
\family default  element is used for this; it looks like the following: 
\begin_deeper
\layout Verbatim

<verb>
\protected_separator

\protected_separator
\newline

\protected_separator
Some
\protected_separator
literal
\protected_separator
text
\protected_separator
to
\protected_separator
include
\protected_separator
as
\protected_separator
example
\protected_separator
output.
\protected_separator

\newline
</verb>
\protected_separator


\end_deeper
\layout Standard

The 
\family typewriter verb
\family default  environment doesn't allow you to use 
\shape italic everything
\shape default  
within it literally.  Specifically, you must do the following within 
\family typewriter verb
\family default  environments. 
\layout Itemize
Use 
\family typewriter &ero;
\family default  to get an ampersand,  
\layout Itemize
Use 
\family typewriter &etago;
\family default  to get 
\family typewriter </
\family default , 
\layout Itemize
Don't use 
\family typewriter 
\backslash
 end{verbatim}
\family default  within a 
\family typewriter verb
\family default  
environment, as this is what LaTeX uses to end the 
\family typewriter verbatim
\family default   
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 
\family typewriter code
\family default  environment is much just like the 
\family typewriter verb
\family default  environment, 
except that horizontal rules are added to the surrounding text, as so: 
\layout Code

Here is an example code environment.  
\layout Standard

You should use the 
\family typewriter tscreen
\family default  environment around any 
\family typewriter verb
\family default  environments, 
as so: 
\begin_deeper
\layout Verbatim

<tscreen><verb>
\protected_separator

\protected_separator
\newline
Here
\protected_separator
is
\protected_separator
some
\protected_separator
example
\protected_separator
text.
\protected_separator

\protected_separator

\protected_separator

\newline
</verb></tscreen>
\protected_separator


\end_deeper
\layout Standard

\family typewriter tscreen
\family default  is an environment that simply indents the text and sets the  
sets the default font to 
\family typewriter tt
\family default .  This makes examples look much nicer, both 
in the LaTeX and plain text versions.  You can use 
\family typewriter tscreen
\family default  
without 
\family typewriter verb
\family default , however, if you use any special characters in your  
example you'll need to use both of them.  
\family typewriter tscreen
\family default  does nothing to  
special characters.  See 
\family typewriter example.sgml
\family default  for examples. 
\layout Standard

The 
\family typewriter quote
\family default  environment is like 
\family typewriter tscreen
\family default , except that it does 
not set the default font to 
\family typewriter tt
\family default .  So, you can use 
\family typewriter quote
\family default  for 
non-computer-interaction quotes, as in: 
\begin_deeper
\layout Verbatim

<quote>
\protected_separator

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

\newline
</quote>
\protected_separator


\end_deeper
\layout Standard

which will generate: 
\layout Quote

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

Overall Document Structure 
\layout Standard

Before we get too in-depth with details, we're going to describe the 
overall structure of an SGML-tools document.  Look at 
\family typewriter example.sgml
\family default  for a good example of how a document is set up. 
\layout Subsubsection

The Preamble 
\layout Standard

In the document ``preamble'' you set up things such as the title 
information and document style:  
\begin_deeper
\layout Verbatim

<!doctype
\protected_separator
linuxdoc
\protected_separator
system>
\protected_separator

\protected_separator
\newline

\protected_separator

\newline
<article>
\protected_separator

\newline

\protected_separator

\newline
<title>Linux
\protected_separator
Foo
\protected_separator
HOWTO
\protected_separator

\newline
<author>Norbert
\protected_separator
Ebersol,
\protected_separator
<tt/norb@baz.com/
\protected_separator

\newline
<date>v1.0,
\protected_separator
9
\protected_separator
March
\protected_separator
1994
\protected_separator

\newline
<abstract>
\protected_separator

\newline
This
\protected_separator
document
\protected_separator
describes
\protected_separator
how
\protected_separator
to
\protected_separator
use
\protected_separator
the
\protected_separator
<tt/foo/
\protected_separator
tools
\protected_separator
to
\protected_separator
frobnicate
\protected_separator

\newline
bar
\protected_separator
libraries,
\protected_separator
using
\protected_separator
the
\protected_separator
<tt/xyzzy/
\protected_separator
relinker.
\protected_separator

\newline
</abstract>
\protected_separator

\newline

\protected_separator

\newline
<toc>
\protected_separator


\end_deeper
\layout Standard

The elements should go more or less in this order.  The first line 
tells the SGML parser to use the linuxdoc DTD.  We'll explain that in 
the later section on 
\begin_inset LatexCommand \ref{
\end_inset
sgml
\begin_inset LatexDel }{
\end_inset
How SGML-Tools Works
\begin_inset LatexDel }
\end_inset
; for 
now just treat it as a bit of necessary magic.  The 
\family typewriter <article>
\family default  tag forces the document to use the ``article'' 
document style. 
\layout Standard

The 
\family typewriter title
\family default , 
\family typewriter author
\family default , and 
\family typewriter date
\family default  tags should be obvious; in the 
\family typewriter date
\family default  tag include the version number and last modification time of 
the document. 
\layout Standard

The 
\family typewriter abstract
\family default  tag sets up the text to be printed at the top of the 
document, 
\shape italic before
\shape default  the table of contents.  If you're not going to 
include a table of contents (the 
\family typewriter toc
\family default  tag), you probably don't 
need an 
\family typewriter abstract
\family default . 
\layout Subsubsection

Sectioning And Paragraphs 
\layout Standard

After the preamble, you're ready to dive into the document.  The following 
sectioning commands are available: 
\layout Itemize
\family typewriter sect
\family default : For top-level sections (i.e.  1, 2, and so on.)  
\layout Itemize
\family typewriter sect1
\family default : For second-level subsections (i.e.  1.1, 1.2, and so on.) 
\layout Itemize
\family typewriter sect2
\family default : For third-level subsubsections. 
\layout Itemize
\family typewriter sect3
\family default : For fourth-level subsubsubsections. 
\layout Itemize
\family typewriter sect4
\family default : For fifth-level subsubsubsubsections. 
These are roughly equivalent to their LaTeX counterparts 
\family typewriter section
\family default , 
\family typewriter subsection
\family default , and so on. 
\layout Standard

After the 
\family typewriter sect
\family default  (or 
\family typewriter sect1
\family default , 
\family typewriter sect2
\family default , etc.) tag comes the 
name of the section.  For example, at the top of this document, after 
the preamble, comes the tag: 
\begin_deeper
\layout Verbatim

<sect>Introduction
\protected_separator

\protected_separator

\end_deeper
\layout Standard

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

<sect2>Sectioning
\protected_separator
And
\protected_separator
Paragraphs
\protected_separator

\protected_separator

\end_deeper
\layout Standard

After the section tag, you begin the body of the section.  However, you 
must start the body with a 
\family typewriter <p>
\family default  tag, as so: 
\begin_deeper
\layout Verbatim

<sect>Introduction
\protected_separator

\protected_separator
\newline
<p>
\protected_separator

\newline
This
\protected_separator
is
\protected_separator
a
\protected_separator
user's
\protected_separator
guide
\protected_separator
to
\protected_separator
the
\protected_separator
SGML-Tools
\protected_separator
document
\protected_separator
processing...
\protected_separator


\end_deeper
\layout Standard

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, 
\begin_deeper
\layout Verbatim

Here
\protected_separator
is
\protected_separator
the
\protected_separator
end
\protected_separator
of
\protected_separator
the
\protected_separator
first
\protected_separator
paragraph.
\protected_separator

\protected_separator
\newline

\protected_separator

\newline
And
\protected_separator
we
\protected_separator
start
\protected_separator
a
\protected_separator
new
\protected_separator
paragraph
\protected_separator
here.
\protected_separator


\end_deeper
\layout Standard

There is no reason to use 
\family typewriter <p>
\family default  tags at the beginning of 
every paragraph; only at the beginning of the first paragraph after 
a sectioning command. 
\layout Subsubsection

Ending The Document 
\layout Standard

At the end of the document, you must use the tag: 
\begin_deeper
\layout Verbatim

</article>
\protected_separator

\protected_separator

\end_deeper
\layout Standard

to tell the parser that you're done with the 
\family typewriter article
\family default  element (which 
embodies the entire document).   
\layout Subsection

Internal Cross-References
\begin_inset LatexCommand \label{cross-ref}
\end_inset 
\layout Standard

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: 
\begin_deeper
\layout Verbatim

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

\protected_separator

\end_deeper
\layout Standard

You can then refer to that section somewhere in the text using the 
expression: 
\begin_deeper
\layout Verbatim

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

\protected_separator

\end_deeper
\layout Standard

This will replace the 
\family typewriter ref
\family default  tag with the section number labeled 
as 
\family typewriter sec-intro
\family default .  The 
\family typewriter name
\family default  argument to 
\family typewriter ref
\family default  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.   
\layout Standard

For example, this section is 
\begin_inset LatexCommand \ref{
\end_inset
cross-ref
\begin_inset LatexDel }{
\end_inset
Cross-References
\begin_inset LatexDel }
\end_inset
. 
\layout Standard

Some back-ends may get upset about special characters in reference labels. 
In particular, latex2e chokes on underscores (though the latex back end 
used in older versions of this package didn't).  Hyphens are safe. 
\layout Subsection

Web References 
\layout Standard

There is also a 
\family typewriter url
\family default  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, 
\begin_deeper
\layout Verbatim

You
\protected_separator
can
\protected_separator
get
\protected_separator
the
\protected_separator
Linux
\protected_separator
HOWTO
\protected_separator
documents
\protected_separator
from
\protected_separator

\protected_separator

\protected_separator
\newline
<url
\protected_separator
url="http://sunsite.unc.edu/mdw/HOWTO/"
\protected_separator

\protected_separator

\newline

\protected_separator

\protected_separator

\protected_separator
name="The
\protected_separator
Linux
\protected_separator
HOWTO
\protected_separator
INDEX">.
\protected_separator


\end_deeper
\layout Standard

The 
\family typewriter url
\family default  argument specifies the actual URL itself.  A link to the 
URL in question will be automatically added to the HTML document. 
The optional 
\family typewriter name
\family default  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 
\family typewriter name
\family default  argument is given, the 
URL itself will be used. 
\layout Standard

For example, you can get the SGML-Tools package from 
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-1.0.x.tar.gz
\begin_inset LatexDel }{
\end_inset
ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-1.0.x.tar.gz
\begin_inset LatexDel }
\end_inset
\family default . 
\layout Standard

A useful variant of this is 
\family typewriter htmlurl
\family default , 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 
\begin_deeper
\layout Verbatim

<htmlurl
\protected_separator
url="mailto:esr@snark.thyrsus.com"
\protected_separator

\protected_separator
\newline

\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator
name="esr@snark.thyrsus.com">
\protected_separator


\end_deeper
\layout Standard

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. 
\layout Subsection

Fonts 
\layout Standard

Essentially, the same fonts supported by LaTeX are supported 
by SGML-Tools.  Note, however, that the conversion to  
plain text (through 
\family typewriter groff
\family default ) does away with the font  
information.  So, you should use fonts  
as 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.   
\layout Standard

In particular, the 
\family typewriter tt
\family default  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: 
\begin_deeper
\layout Verbatim

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

\protected_separator

\end_deeper
\layout Standard

Equivalently: 
\begin_deeper
\layout Verbatim

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

\protected_separator

\end_deeper
\layout Standard

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

Other fonts can be achieved with 
\family typewriter bf
\family default  for 
\series bold boldface
\series default  and 
\family typewriter em
\family default   
for 
\shape italic italics
\shape default .  Several other fonts are supported as well, but 
we 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. 
\layout Subsection

Lists 
\layout Standard

There are various kinds of supported lists.  They are: 
\layout Itemize
\family typewriter itemize
\family default  for bulleted lists such as this one. 
\layout Itemize
\family typewriter enum
\family default  for numbered lists. 
\layout Itemize
\family typewriter descrip
\family default  for ``descriptive'' lists.   
Each item in an 
\family typewriter itemize
\family default  or 
\family typewriter enum
\family default  list must be marked 
with an 
\family typewriter item
\family default  tag.  Items in a 
\family typewriter descrip
\family default  are marked with 
\family typewriter tag
\family default . 
For example, 
\begin_deeper
\layout Verbatim

<itemize>
\protected_separator

\protected_separator
\newline
<item>Here
\protected_separator
is
\protected_separator
an
\protected_separator
item.
\protected_separator

\newline
<item>Here
\protected_separator
is
\protected_separator
a
\protected_separator
second
\protected_separator
item.
\protected_separator

\newline
</itemize>
\protected_separator


\end_deeper
\layout Standard

Looks like this: 
\layout Itemize
Here is an item. 
\layout Itemize
Here is a second item. 
Or, for an 
\family typewriter enum
\family default , 
\begin_deeper
\layout Verbatim

<enum>
\protected_separator

\protected_separator
\newline
<item>Here
\protected_separator
is
\protected_separator
the
\protected_separator
first
\protected_separator
item.
\protected_separator

\newline
<item>Here
\protected_separator
is
\protected_separator
the
\protected_separator
second
\protected_separator
item.
\protected_separator

\newline
</enum>
\protected_separator


\end_deeper
\layout Standard

You get the idea.  Lists can be nested as well; see the example document 
for details. 
\layout Standard

A 
\family typewriter descrip
\family default  list is slightly different, and slightly ugly, but 
you might want to use it for some situations: 
\begin_deeper
\layout Verbatim

<descrip>
\protected_separator

\protected_separator
\newline
<tag/Gnats./
\protected_separator
Annoying
\protected_separator
little
\protected_separator
bugs
\protected_separator
that
\protected_separator
fly
\protected_separator
into
\protected_separator
your
\protected_separator
cooling
\protected_separator
fan.
\protected_separator

\newline
<tag/Gnus./
\protected_separator
Annoying
\protected_separator
little
\protected_separator
bugs
\protected_separator
that
\protected_separator
run
\protected_separator
on
\protected_separator
your
\protected_separator
CPU.
\protected_separator

\newline
</descrip>
\protected_separator


\end_deeper
\layout Standard

ends up looking like: 
\layout Description

Gnats.
\protected_separator

 Annoying little bugs that fly into your cooling fan. 
\layout Description

Gnus.
\protected_separator

 Annoying little bugs that run on your CPU. 
\layout Subsection

Conditionalization 
\layout Standard

The overall goal of SGML-tools is to be able to produce from one set 
of masters output that is semantically equivalent on all back ends. 
Nevertheless, it is sometimes useful to be able to produce a document 
in slightly different variants depending on back end and version.   
SGML-tools supports this through the <#if> and <#unless> 
bracketing tags. 
\layout Standard

These tags allow you to selectively include and uninclude portions of 
an SGML master in your output, depending on filter options set by your 
driver.  Each tag may include a set of attribute/value pairs.  The 
most common are ``output'' and ``version'' (though you are not 
restricted to these) so a typical example might look like this: 
\begin_deeper
\layout Verbatim

Some
\protected_separator
<#if
\protected_separator
output=latex
\protected_separator
version=drlinux>conditional</#if>
\protected_separator
text.
\protected_separator

\protected_separator

\end_deeper
\layout Standard

Everything from this <#if> tag to the following </#if> would 
be considered conditional, and would not be included in the document 
if either the filter option ``output'' were set to something that 
doesn't match ``latex'' or the filter option ``version'' were set to 
something that doesn't match ``drlinux''.  The double negative is 
deliberate; if no ``output'' or ``version'' filter options are set, 
the conditional text will be included. 
\layout Standard

Filter options are set in one of two ways.  Your format driver sets 
the ``output'' option to the name of the back end it uses; thus, in 
particular, sgml2latex sets ``output=latex2e'',  Or you may set an 
attribute-value pair with the -D option of your format driver.  Thus, 
if the above tag were part of a file a file named ``foo.sgml'', then 
formatting with either  
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2latex
\protected_separator
-Dversion-drlinux
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\end_deeper
\layout Standard

or 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2latex
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\end_deeper
\layout Standard

would include the ``conditional'' part, but neither 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2html
\protected_separator
-Dversion-drlinux
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\end_deeper
\layout Standard

nor 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2latex
\protected_separator
-Dprivate-book
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\end_deeper
\layout Standard

would do so. 
\layout Standard

So that you can have conditionals depending on one or more of several 
values matching, values support a simple alternation syntax using 
``|''.  Thus you could write: 
\begin_deeper
\layout Verbatim

Some
\protected_separator
<#if
\protected_separator
output="latex|html"
\protected_separator
version=drlinux>conditional</#if>
\protected_separator
text.
\protected_separator

\protected_separator

\end_deeper
\layout Standard

and formatting with either sgml2latex or sgml2html will include the 
``conditional'' text (but formatting with, say, sgml2txt will not). 
\layout Standard

The <#unless> tag is the exact inverse of <#if>; it 
includes when <#if>; would exclude, and vice-versa. 
\layout Standard

Note that these tags are implemented by a preprocessor which runs 
before the SGML parser ever sees the document.  Thus they are 
completely independent of the document structure, are not in the DTD, 
and usage errors won't be caught by the parser.  You can seriously 
confuse yourself by conditionalizing sections that contain unbalanced 
bracketing tags.   
\layout Standard

The preprocessor implementation also means that standalone SGML 
parsers will choke on SGML-tools documents that contain conditionals. 
However, you can validity-check them with the 
\family typewriter sgmlcheck
\family default  tool. 
\layout Standard

Also note that in order not to mess up the source line numbers in 
parser error messages, the preprocessor doesn't actually throw 
away everything when it omits a conditionalized section.  It still 
passes through any newlines.  This leads to behavior that may  
suprise you if you use <if> or <unless> within a 
<verb> environment, or any other kind of bracket that changes 
SGML's normal processing of whitespace. 
\layout Standard

These tags are called ``#if'' and ``#unless'' (rather than ``if'' and 
``unless'') to remind you that they are implemented by a preprocessor 
and you need to be a bit careful about how you use them. 
\layout Subsection

Index generation 
\layout Standard

To support automated generation of indexes for book publication of 
SGML masters, SGML-tools supports the <idx> and <cdx> 
tags.  These are bracketing tags which cause the text between them to 
be saved as an index entry, pointing to the page number on which it 
occurs in the formatted document.  They are ignored by all backends 
except LaTeX, which uses them to build a .ind file suitable for 
processing by the TeX utility makeindex. 
\layout Standard

The two tags behave identically, except that <idx> sets the 
entry in a normal font and <cdx> in a constant-width one. 
\layout Standard

If you want to add an index entry that shouldn't appear in the text 
itself, use the <nidx> and <ncdx> tags. 
\layout Subsection

Controlling justification 
\layout Standard

In order to get proper justification and filling of paragraphs in 
typeset output, SGML-tools includes the &shy; entity.  This 
becomes an optional or `soft' hyphen in back ends like latex2e 
for which this is neaningful. 
\layout Standard

The bracketing tag <file> can be used to surround filenames in 
running text.  It effectively inserts soft hyphens after each slash in 
the filename. 
\layout Standard

One of the advantages of using the <url> and <htmlurl> 
tags is that they do likewise for long URLs. 
\layout Section

Formatting SGML Documents 
\layout Standard

Let's say you have the SGML document 
\family typewriter foo.sgml
\family default , 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. 
\layout Subsection

Checking SGML Syntax 
\layout Standard

If you just want to capture your errors from the SGML conversion, 
use the 
\family typewriter sgmlcheck
\family default  script.  For example. 
\layout Standard

\begin_deeper
\layout Verbatim

%
\protected_separator
sgmlcheck
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

If you see no output from an sgmlcheck run other than the 
``Processing...'' message, that's good.  It means there were no errors. 
\layout Subsection

Creating Plain Text Output 
\layout Standard

If you want to produce plain text, use the command: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2txt
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

You can also create groff source for man pages, which can be formatted with 
\family typewriter groff -man
\family default .  To do this, do the following: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2txt
\protected_separator
--man
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Subsection

Creating LaTeX, DVI or PostScript Output 
\layout Standard

To create a LaTeX documents from the SGML source file, simply run: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2latex
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

If you want to produce PostScript output (via 
\family typewriter dvips
\family default ), use the  
\family typewriter -p
\family default  option: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2latex
\protected_separator
--output=ps
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

Or you can produce a DVI file: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2latex
\protected_separator
--output=dvi
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Subsection

Creating HTML Output 
\layout Standard

If you want to produce HTML output, do this: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2html
\protected_separator
--imagebuttons
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

This will produce 
\family typewriter foo.html
\family default , as well as 
\family typewriter foo-1.html
\family default , 
\family typewriter foo-2.html
\family default , and so on -- one file for each section of the 
document.  Run your WWW browser on 
\family typewriter foo.html
\family default , which is the top 
level file.  You must make sure that all of the HTML files generated 
from your document are all installed in the directory, as they 
reference each other with local URLs. 
\layout Standard

The --imagebuttons option tells sgml2html to use graphic arrows as  
navigation buttons.  The names of these icons are "next.gif", 
"prev.gif", and "toc.gif", and the SGML-tools system supplies  
appropriate GIFs in its library directory. 
\layout Standard

If you use 
\family typewriter sgml2html
\family default  without the 
\family typewriter -img
\family default  flag, HTML documents 
will by default have the English labels ``Previous'', ``Next'', and 
``Table of Contents'' for navigation.  If you specify one of the 
accepted language codes in a --language option, however, the labels 
will be given in that language. 
\layout Subsection

Creating GNU Info Output 
\layout Standard

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

%
\protected_separator
sgml2info
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Subsection

Creating LyX Output 
\layout Standard

For LyX output, use the the command: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2lyx
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Subsection

Creating RTF Output 
\layout Standard

If you want to produce RTF output, run the command: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2rtf
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

This will produce 
\family typewriter foo.rtf
\family default , as well as 
\family typewriter foo-1.rtf
\family default , 
\family typewriter foo-2.rtf
\family default , and so on---one file for each section of the document. 
\layout Section

Internationalization Support 
\layout Standard

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 
\family typewriter --charset=latin
\family default  flag, for example: 
\begin_deeper
\layout Verbatim

%
\protected_separator
sgml2txt
\protected_separator
--charset=latin
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

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. 
\layout Section

How SGML-Tools Works
\begin_inset LatexCommand \label{sgml}
\end_inset 
\layout Standard

Technically, the tags and conventions we've explored in previous 
sections of this use's guide are what is called a 
\shape italic markup 
language
\shape default  -- a way to embed formatting information in a document 
so that programs can do useful things with it.  HTML, Tex, and Unix 
manual-page macros are well-known examples of markup languages. 
\layout Subsection

Overview of SGML 
\layout Standard

SGML-tools is so called because it uses a way of describing markup 
languages called SGML (Standard Generalized Markup Language).  SGML 
itself doesn't describe a markup language; rather, it's a language for 
writing specifications for markup languages.  The reason SGML is 
useful is that an SGML markup specification for a language can be used 
to generate programs that "know" that language with much less effort 
(and a much lower bugginess rate!) than if they had to be coded by hand. 
\layout Standard

In SGML jargon, a markup language specification is called a ``DTD'' 
(Document Type Definition).  A DTD allows you to specify the 
\shape italic structure
\shape default  of a kind of document---that is, what parts, in what 
order, make up a document of that kind.  Given a DTD, an SGML parser 
can check a document for correctness.  An SGML-parser/DTD combination 
can also make it easy to write programs that translate that structure 
into another markup language -- and this is exactly how SGML-tools 
actually works. 
\layout Standard

SGML-Tools provides a SGML DTD called ``linuxdoc'' and a set of 
``replacement files'' which convert the linuxdoc documents to groff, 
LaTeX, HTML, GNU info, LyX, and RTF source.  This is why the example document 
has a magic cookie at thtop of it that says "linuxdoc system"; that is 
how one tells an SGML parser what DTD to use. 
\layout Standard

Actually, SGML-tools provides a couple of closely related DTDs.  But 
the ones other than linuxdoc are still experimental, and you probably 
do not want to try working with them unless you are an SGML-tools guru. 
\layout Standard

If you are an SGML guru, you may find it interesting to know that the  
SGML-Tools DTDs are based heavily on the QWERTZ DTD by Tom Gordon, 
\family typewriter thomas.gordon@gmd.de
\family default . 
\layout Standard

If you are not an SGML guru, you may not know that HTML (the markup 
language used on the World Wide Web) is itself sefined by a DTD. 
\layout Subsection

How SGML Works 
\layout Standard

An SGML DTD like linuxdoc specifies the names of ``elements'' within a 
document type.  An element is just a bit of structure---like a 
section, a subsection, a paragraph, or even something smaller like 
\shape italic emphasized text
\shape default . 
\layout Standard

Unlike in 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. 
\layout Standard

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

What Happens When SGML-Tools Processes A Document 
\layout Standard

Here's how processing a document with SGML-Tools works.  First, you 
need a DTD, which sets up the structure of the document.  A small 
portion of the normal (linuxdoc) DTD looks like this: 
\layout Standard

\begin_deeper
\layout Verbatim

<!element
\protected_separator
article
\protected_separator
-
\protected_separator
-
\protected_separator

\protected_separator
\newline

\protected_separator

\protected_separator

\protected_separator

\protected_separator
(titlepag,
\protected_separator
header?,
\protected_separator

\protected_separator

\newline

\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator
toc?,
\protected_separator
lof?,
\protected_separator
lot?,
\protected_separator
p*,
\protected_separator
sect*,
\protected_separator

\protected_separator

\newline

\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator
(appendix,
\protected_separator
sect+)?,
\protected_separator
biblio?)
\protected_separator
+(footnote)>
\protected_separator


\end_deeper
\layout Standard

This part sets up the overall structure for an ``article'', which is like 
a ``documentstyle'' within LaTeX.  The article consists of a titlepage 
(
\family typewriter titlepag
\family default ), an optional header (
\family typewriter header
\family default ), an optional table of  
contents (
\family typewriter toc
\family default ), optional lists of figures (
\family typewriter lof
\family default ) and tables 
(
\family typewriter lot
\family default ), any number of paragraphs (
\family typewriter p
\family default ), any number of top-level 
sections (
\family typewriter sect
\family default ), optional appendices (
\family typewriter appendix
\family default ), an optional 
bibliography (
\family typewriter biblio
\family default ) and footnotes (
\family typewriter footnote
\family default ).   
\layout Standard

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  
\family typewriter titlepag
\family default , 
\family typewriter header
\family default , 
\family typewriter sect
\family default , and other elements are defined.   
\layout Standard

You don't need to know anything about the syntax of the DTD in order 
to write documents.  We're just presenting it here so you know what it 
looks like and what it does.  You 
\shape italic do
\shape default  need to be familiar with the 
document 
\shape italic structure
\shape default  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. 
\layout Standard

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 or HTML -- 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. 
\layout Standard

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 
\shape italic parsed
\shape default  along with the DTD by the SGML 
\shape italic parser
\shape default . 
SGML-Tools uses the 
\family typewriter nsgmls
\family default  parser by James Clark, 
\family typewriter jjc@jclark.com
\family default , who 
also happens to be the author of 
\family typewriter groff
\family default .  We're in good hands. 
The parser (
\family typewriter sgmls
\family default ) 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 
\family typewriter sgmlsasp
\family default , the next part of the 
process.   
\layout Standard

\family typewriter sgmlsasp
\family default  is responsible for converting the output of 
\family typewriter sgmls
\family default  to 
another format (such as LaTeX).  It does this using 
\shape italic replacement files
\shape default , 
which describe how to convert elements in the original SGML document into 
corresponding source in the ``target'' format (such as LaTeX or groff).   
\layout Standard

For example, part of the replacement file for LaTeX looks like: 
\begin_deeper
\layout Verbatim

<itemize>
\protected_separator

\protected_separator

\protected_separator

\protected_separator
+
\protected_separator

\protected_separator

\protected_separator

\protected_separator
"\backslash
\protected_separator
\backslash
\protected_separator
begin{itemize}
\protected_separator

\protected_separator

\protected_separator
+
\protected_separator

\protected_separator
\newline
</itemize>
\protected_separator

\protected_separator

\protected_separator
+
\protected_separator

\protected_separator

\protected_separator

\protected_separator
"
\protected_separator
\backslash
\protected_separator

\protected_separator
\backslash
\protected_separator
end{itemize}
\protected_separator

\protected_separator

\protected_separator

\protected_separator
+
\protected_separator


\end_deeper
\layout Standard

Which says that whenever you begin an 
\family typewriter itemize
\family default  element in the  
SGML source, it should be replaced with  
\begin_deeper
\layout Verbatim

\backslash
\protected_separator
begin{itemize}
\protected_separator

\protected_separator

\end_deeper
\layout Standard

in the LaTeX source.  (As I said, elements in the DTD 
are very similar to their LaTeX counterparts).   
\layout Standard

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. 
\layout Standard

Once 
\family typewriter sgmlsasp
\family default  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. 
\layout Subsection

Further Information 
\layout Itemize
The QWERTZ User's Guide is available from  
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://ftp.cs.cornell.edu/pub/mdw/SGML
\begin_inset LatexDel }{
\end_inset
ftp://ftp.cs.cornell.edu/pub/mdw/SGML
\begin_inset LatexDel }
\end_inset
\family default . 
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.   
\layout Itemize
Tom Gordon's original QWERTZ tools can be found at  
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://ftp.gmd.de/GMD/sgml
\begin_inset LatexDel }{
\end_inset
ftp://ftp.gmd.de/GMD/sgml
\begin_inset LatexDel }
\end_inset
\family default . 
\layout Itemize
More information on SGML can be found at the following WWW  
pages:  

\begin_deeper
\layout Enumerate
\family typewriter \begin_inset LatexDel \url{
\end_inset
http://www.w3.org/hypertext/WWW/MarkUp/SGML/
\begin_inset LatexDel }{
\end_inset
SGML and the Web
\begin_inset LatexDel }
\end_inset
\family default  
\layout Enumerate
\family typewriter \begin_inset LatexDel \url{
\end_inset
http://www.sil.org/sgml/sgml.html
\begin_inset LatexDel }{
\end_inset
SGML Web Page
\begin_inset LatexDel }
\end_inset
\family default  
\layout Enumerate
\family typewriter \begin_inset LatexDel \url{
\end_inset
http://www.yahoo.com/Computers_and_Internet/Software/Data_Formats/SGML
\begin_inset LatexDel }{
\end_inset
Yahoo's SGML Page
\begin_inset LatexDel }
\end_inset
\family default  

\end_deeper
\layout Itemize
James Clark's 
\family typewriter sgmls
\family default  parser, and it's successor 
\family typewriter nsgmls
\family default  
and other tools can be found at 
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://ftp.jclark.com
\begin_inset LatexDel }{
\end_inset
ftp://ftp.jclark.com
\begin_inset LatexDel }
\end_inset
\family default  and at 
\family typewriter \begin_inset LatexDel \url{
\end_inset
http://www.jclark.com
\begin_inset LatexDel }{
\end_inset
James Clark's WWW Page
\begin_inset LatexDel }
\end_inset
\family default . 
\layout Itemize
The emacs psgml package can be found at 
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
ftp://ftp.lysator.liu.se/pub/sgml
\begin_inset LatexDel }{
\end_inset
ftp://ftp.lysator.liu.se/pub/sgml
\begin_inset LatexDel }
\end_inset
\family default .  This package 
provides a lot of SGML functionality. 
\layout Itemize
You can join the SGML-Tools mailing list by sending mail to 
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
mailto:majordomo@via.ecp.fr
\begin_inset LatexDel }{
\end_inset
majordomo@via.ecp.fr
\begin_inset LatexDel }
\end_inset
\family default  with 
\family typewriter subscribe sgml-tools
\family default  in  
the message body.  The list address is  
\family typewriter \begin_inset LatexDel \htmlurl{
\end_inset
mailto:sgml-tools@via.ecp.fr
\begin_inset LatexDel }{
\end_inset
sgml-tools@via.ecp.fr
\begin_inset LatexDel }
\end_inset
\family default . 
\layout Itemize
More information on 
\family typewriter LyX
\family default  can be found at the 
\family typewriter \begin_inset LatexDel \url{
\end_inset
http://wsiserv.informatik.uni-tuebingen.de/~ettrich/
\begin_inset LatexDel }{
\end_inset
LyX WWW Page
\begin_inset LatexDel }
\end_inset
\family default .  
\family typewriter LyX
\family default  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. 
\the_end
