#This file was created by LinuxDoc-SGML
#(conversion : Frank Pavageau and Jose' Matos)
\lyxformat 2.15
\textclass article
\language default
\inputencoding default
\fontscheme default
\graphics default
\paperfontsize default
\spacing single
\papersize Default
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language default
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default
\layout Title
\added_space_top vfill \added_space_bottom vfill
LinuxDoc-Tools User's Guide 
\layout Author
written by Matt Welsh as the LinuxDoc-SGML User's Guide. and Updated by Greg Hankins, and rewritten by Eric S. Raymond for SGML-Tools. and Updated and renamed by Taketoshi Sano, for LinuxDoc-Tools
\layout Date
$Date: 2002/03/18 13:39:10 $ ($Revision: 1.2 $) 
\layout Abstract
 This document is a user's guide to the LinuxDoc-Tools formatting system, a SGML-based system which allows you to produce a variety of output formats. You can create plain text output (ASCII, ISO-8859-1, and EUC-JP), DVI, PostScript, PDF, HTML, GNU info, LyX, and RTF output from a single document source file. LinuxDoc-Tools is a new branch from SGML-Tools 1.0.9, and an descendant of the original LinuxDoc-SGML. 
\layout Standard
\begin_inset LatexCommand \tableofcontents
\end_inset
\layout Section
Introduction 
\layout Standard
This document is the user's guide to the LinuxDoc-Tools document 
processing system. LinuxDoc-Tools is a suite of programs to help 
you write source documents that can be rendered as plain text, 
hypertext, or LaTeX files. It contains what you need to know to 
set up LinuxDoc-Tools and write documents using it. 
See 
\family typewriter
example.sgml
\family default
 for an example of an LinuxDoc DTD SGML document 
that you can use as a model for your own documents. 
The ``LinuxDoc'' means the name of a specific SGML DTD here. 
\layout Subsection
What's the DTD ? 
\layout Standard
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 
\shape italic
emphasized text
\shape default
. 
You may know the HTML has their own DTD.
\layout Standard
Don't be confusing. SGML is 
\shape italic
not
\shape default
 a text-formatting system. 
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. 
For more Detail, please refer the later section of this document 
(
\begin_inset LatexCommand \ref{sgml}
\end_inset
). 
\layout Subsection
History of the LinuxDoc 
\layout Standard
The LinuxDoc DTD is created by Matt Welsh as the core part of his 
Linuxdoc-SGML document processing system. This DTD is based heavily 
on the QWERTZ DTD by Tom Gordon, 
\family typewriter
thomas.gordon@gmd.de
\family default
. 
The target of the QWERTZ DTD is to provide the simple way to create 
LaTeX source for document publishing. Matt Welsh took and shaped it 
into Linuxdoc-SGML because he needed it to produce a lot of Linux 
Documentations. It can convert a single source of documentation into 
various output formats such as plain text, html, and PS. No work for 
synchronization between various output formatted documents are needed. 
\layout Standard
The Linuxdoc-SGML system had been maintained for years by Matt Welsh 
and many others, but it has some limitations. Then Cees de Groot came 
and created the new system using perl. The new system is called as 
``SGML-Tools''. The perl based version for LinuxDoc had been maintained 
for a year, then totally new system using the original python scripts 
and some stylesheets with the jade has been released. This system is 
called as ``SGML-Tools 2.0'' and it does not use the LinuxDoc DTD as 
the main DTD, but uses the new standard one, the DocBook DTD. 
Now ``SGML-Tools 2.0'' becomes ``SGMLtools-Lite'' and is distributed 
from 
\begin_inset LatexCommand \url[ ]{http://sgmltools-lite.sourceforge.net/}
\end_inset
. 
\layout Standard
Recently, the DocBook DTD is the standard DTD for the technical 
software documentation, and used by many project such as GNOME and 
KDE, as well as many professional authors and commercial publishers. 
But some people in the LDP, and users of the various LinuxDoc SGML 
documents, still needs the support of the tools for the LinuxDoc. 
This ``LinuxDoc-Tools'' is created for those people. If you need 
the tools for the LinuxDoc DTD, then you may wish to use this. But 
remember, the LinuxDoc DTD is not the standard way now even in the 
Linux world. If you can, try the DocBook DTD. It is the standard, 
and full-featured way of writing the documentations.
\layout Section
Installation 
\layout Subsection
Where to get the source archive 
\layout Standard
You can get the source archive of the linuxdoc-tools from: 
\layout Itemize
\begin_inset LatexCommand \url[ ]{http://www.debian.org/~sano/linuxdoc-tools/}
\end_inset
\layout Standard
The name of the archive may be 
\family typewriter
linuxdoc-tools_x.y.z.tar.gz
\family default
 or 
\family typewriter
linuxdoc-tools_x.y.z-rel.tar.gz
\family default
 or 
\family typewriter
linuxdoc-tools_x.y.z.orig.tar.gz
\family default
. 
These have the equivalent contents. You can use anyone. 
\layout Subsection
What LinuxDoc-Tools Needs 
\layout Standard
LinuxDoc-Tools depends on the usage of sgml parser from Jade or OpenJade 
(nsgmls or onsgmls). You have to install either of them to use this. 
\layout Standard
The source archive of the linuxdoc-tools contains the tools and data 
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 LatexCommand \url[ ]{ftp://prep.ai.mit.edu/pub/gnu}
\end_inset
. 
There is a Linux binary 
version at 
\begin_inset LatexCommand \htmlurl[ftp://sunsite.unc.edu/pub/Linux/utils/text]{ftp://sunsite.unc.edu/pub/Linux/utils/text}
\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. If you need PDF output, then you need pdfLaTeX also. 
\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 LatexCommand \htmlurl[ftp://prep.ai.mit.edu/pub/gnu]{ftp://prep.ai.mit.edu/pub/gnu}
\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 LatexCommand \htmlurl[ftp://prep.ai.mit.edu/pub/gnu]{ftp://prep.ai.mit.edu/pub/gnu}
\end_inset
\family default
, or on 
\family typewriter
\begin_inset LatexCommand \htmlurl[ftp://sunsite.unc.edu/pub/Linux/utils/text]{ftp://sunsite.unc.edu/pub/Linux/utils/text}
\end_inset
\family default
(for 
\family typewriter
gawk
\family default
) and 
\family typewriter
\begin_inset LatexCommand \htmlurl[ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers]{ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers}
\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 LatexCommand \htmlurl[ftp://ftp.via.ecp.fr]{ftp://ftp.via.ecp.fr}
\end_inset
. 
\layout Subsection
Installing The Software 
\layout Standard
The steps needed to install and configure the LinuxDoc-Tools are: 
\layout Enumerate
First, unpack the tar file of the source archive somewhere. 
This will create the directory 
\family typewriter
linuxdoc-tools-x.y.z
\family default
. 
It doesn't matter where you unpack this file; just don't move things 
around within the extracted source tree. 
\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 LinuxDoc-Tools 
\layout Standard
For the most part, writing documents using LinuxDoc-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 LinuxDoc-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 
\layout LyX-Code
As a simple example, to produce <bf>this boldfaced text</bf>, ... 
\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 
\layout LyX-Code
As a simple example, to produce <bf/this boldfaced text/, ... 
\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 
\layout LyX-Code
angle brackets around it, as so: <tt>&lt;foo&gt;</tt>. 
\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 LinuxDoc-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 0.1. 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
(½)
\layout Standard
vertical 1/2 fraction 
\layout Description
&frac12
\protected_separator
(½)
\layout Standard
typeset 1/2 fraction 
\layout Description
&frac14
\protected_separator
(¼)
\layout Standard
typeset 1/4 fraction 
\layout Description
&frac34
\protected_separator
(¾)
\layout Standard
typeset 3/4 fraction 
\layout Description
&frac18
\protected_separator
(1/8)
\layout Standard
typeset 1/8 fraction 
\layout Description
&frac38
\protected_separator
(3/8)
\layout Standard
typeset 3/8 fraction 
\layout Description
&frac58
\protected_separator
(5/8)
\layout Standard
typeset 5/8 fraction 
\layout Description
&frac78
\protected_separator
(7/8)
\layout Standard
typeset 7/8 fraction 
\layout Description
&sup1
\protected_separator
(¹)
\layout Standard
superscript 1 
\layout Description
&sup2
\protected_separator
(²)
\layout Standard
superscript 2 
\layout Description
&sup3
\protected_separator
(³)
\layout Standard
superscript 3 
\layout Description
&plus
\protected_separator
(+)
\layout Standard
plus sign 
\layout Description
&plusmn
\protected_separator
(±)
\layout Standard
plus-or-minus sign 
\layout Description
&lt
\protected_separator
(<)
\layout Standard
less-than sign 
\layout Description
&equals
\protected_separator
(=)
\layout Standard
equals sign 
\layout Description
&gt
\protected_separator
(>)
\layout Standard
greater-than sign 
\layout Description
&divide
\protected_separator
(/)
\layout Standard
division sign 
\layout Description
&times
\protected_separator
(×)
\layout Standard
multiplication sign 
\layout Description
&curren
\protected_separator
(¤)
\layout Standard
currency symbol 
\layout Description
&pound
\protected_separator
(£)
\layout Standard
symbol for ``pounds'' 
\layout Description
&dollar
\protected_separator
($)
\layout Standard
dollar sign 
\layout Description
&cent
\protected_separator
(¢)
\layout Standard
cent sign 
\layout Description
&yen
\protected_separator
(¥)
\layout Standard
yen sign 
\layout Description
&num
\protected_separator
(#)
\layout Standard
number or hash sign 
\layout Description
&percnt
\protected_separator
(%)
\layout Standard
percent sign 
\layout Description
&amp
\protected_separator
(&)
\layout Standard
ampersand 
\layout Description
&ast
\protected_separator
(*)
\layout Standard
asterisk 
\layout Description
&commat
\protected_separator
(@)
\layout Standard
commercial-at sign 
\layout Description
&lsqb
\protected_separator
([)
\layout Standard
left square bracket 
\layout Description
&bsol
\protected_separator
(
\protected_separator
\backslash
\protected_separator
)
\layout Standard
backslash 
\layout Description
&rsqb
\protected_separator
(])
\layout Standard
right square bracket 
\layout Description
&lcub
\protected_separator
({)
\layout Standard
left curly brace 
\layout Description
&horbar
\protected_separator
(-)
\layout Standard
horizontal bar 
\layout Description
&verbar
\protected_separator
(|)
\layout Standard
vertical bar 
\layout Description
&rcub
\protected_separator
(})
\layout Standard
right curly brace 
\layout Description
&micro
\protected_separator
(µ)
\layout Standard
greek mu (micro prefix) 
\layout Description
&ohm
\protected_separator
({ohm})
\layout Standard
greek capital omega (Ohm sign) 
\layout Description
&deg
\protected_separator
(°)
\layout Standard
small superscript circle sign (degree sign) 
\layout Description
&ordm
\protected_separator
({ordm})
\layout Standard
masculine ordinal 
\layout Description
&ordf
\protected_separator
({ordf})
\layout Standard
feminine ordinal 
\layout Description
&sect
\protected_separator
(§)
\layout Standard
section sign 
\layout Description
&para
\protected_separator
(¶)
\layout Standard
paragraph sign 
\layout Description
&middot
\protected_separator
(·)
\layout Standard
centered dot 
\layout Description
&larr
\protected_separator
(<-)
\layout Standard
left arrow 
\layout Description
&rarr
\protected_separator
(->)
\layout Standard
right arrow 
\layout Description
&uarr
\protected_separator
({uarr})
\layout Standard
up arrow 
\layout Description
&darr
\protected_separator
({darr})
\layout Standard
down arrow 
\layout Description
&copy
\protected_separator
(©)
\layout Standard
copyright 
\layout Description
&reg
\protected_separator
(®)
\layout Standard
r-in-circle marl 
\layout Description
&trade
\protected_separator
((TM))
\layout Standard
trademark sign 
\layout Description
&brvbar
\protected_separator
(¦)
\layout Standard
broken vertical bar 
\layout Description
&not
\protected_separator
(¬)
\layout Standard
logical-negation sign 
\layout Description
&sung
\protected_separator
({sung})
\layout Standard
sung-note sign 
\layout Description
&excl
\protected_separator
(!)
\layout Standard
exclamation point 
\layout Description
&iexcl
\protected_separator
(¡)
\layout Standard
inverted exclamation point 
\layout Description
&quot
\protected_separator
(")
\layout Standard
double quote 
\layout Description
&apos
\protected_separator
(')
\layout Standard
apostrophe (single quote) 
\layout Description
&lpar
\protected_separator
(()
\layout Standard
left parenthesis 
\layout Description
&rpar
\protected_separator
())
\layout Standard
right parenthesis 
\layout Description
&comma
\protected_separator
(,)
\layout Standard
comma 
\layout Description
&lowbar
\protected_separator
(_)
\layout Standard
under-bar 
\layout Description
&hyphen
\protected_separator
(-)
\layout Standard
hyphen 
\layout Description
&period
\protected_separator
(.)
\layout Standard
period 
\layout Description
&sol
\protected_separator
(/)
\layout Standard
solidus 
\layout Description
&colon
\protected_separator
(:)
\layout Standard
colon 
\layout Description
&semi
\protected_separator
(;)
\layout Standard
semicolon 
\layout Description
&quest
\protected_separator
(?)
\layout Standard
question mark 
\layout Description
&iquest
\protected_separator
(¿)
\layout Standard
interrobang 
\layout Description
&laquo
\protected_separator
(«)
\layout Standard
left guillemot 
\layout Description
&raquo
\protected_separator
(»)
\layout Standard
right guillemot 
\layout Description
&lsquo
\protected_separator
(`)
\layout Standard
left single quote 
\layout Description
&rsquo
\protected_separator
(')
\layout Standard
right single quote 
\layout Description
&ldquo
\protected_separator
(")
\layout Standard
left double quote 
\layout Description
&rdquo
\protected_separator
(")
\layout Standard
right double quote 
\layout Description
&nbsp
\protected_separator
( )
\layout Standard
non-breaking space 
\layout Description
&shy
\protected_separator
()
\layout Standard
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: 
\layout LyX-Code
<verb> 
\layout LyX-Code
 Some literal text to include as example output. 
\layout LyX-Code
</verb> 
\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.) 
\layout Standard
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: 
\layout LyX-Code
<tscreen><verb> 
\layout LyX-Code
Here is some example text.   
\layout LyX-Code
</verb></tscreen> 
\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: 
\layout LyX-Code
<quote> 
\layout LyX-Code
Here is some text to be indented, as in a quote. 
\layout LyX-Code
</quote> 
\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 LinuxDoc-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: 
\layout LyX-Code
<!doctype linuxdoc system> 
\layout LyX-Code
<article> 
\layout LyX-Code
<title>Linux Foo HOWTO 
\layout LyX-Code
<author>Norbert Ebersol, <tt/norb@baz.com/ 
\layout LyX-Code
<date>v1.0, 9 March 1994 
\layout LyX-Code
<abstract> 
\layout LyX-Code
This document describes how to use the <tt/foo/ tools to frobnicate 
\layout LyX-Code
bar libraries, using the <tt/xyzzy/ relinker. 
\layout LyX-Code
</abstract> 
\layout LyX-Code
<toc> 
\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{sgml}
\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. 
\layout Standard
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: 
\layout LyX-Code
<sect>Introduction 
\layout Standard
And at the beginning of this section (Sectioning and paragraphs), there 
is the tag: 
\layout LyX-Code
<sect2>Sectioning And Paragraphs 
\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: 
\layout LyX-Code
<sect>Introduction 
\layout LyX-Code
<p> 
\layout LyX-Code
This is a user's guide to the LinuxDoc-Tools document processing... 
\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, 
\layout LyX-Code
Here is the end of the first paragraph. 
\layout LyX-Code
And we start a new paragraph here. 
\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: 
\layout LyX-Code
</article> 
\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: 
\layout LyX-Code
<sect1>Introduction<label id="sec-intro"> 
\layout Standard
You can then refer to that section somewhere in the text using the 
expression: 
\layout LyX-Code
See section <ref id="sec-intro" name="Introduction"> for an introduction. 
\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 LinuxDoc-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{cross-ref}
\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, 
\layout LyX-Code
You can get the Linux HOWTO documents from  
\layout LyX-Code
<url url="http://sunsite.unc.edu/mdw/HOWTO/"  
\layout LyX-Code
   name="The Linux HOWTO INDEX">. 
\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
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 
\layout LyX-Code
<htmlurl url="mailto:esr@snark.thyrsus.com" 
\layout LyX-Code
      name="esr@snark.thyrsus.com"> 
\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 LinuxDoc-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: 
\layout LyX-Code
Here is some <tt>typewriter text</tt> to be included in the document. 
\layout Standard
Equivalently: 
\layout LyX-Code
Here is some <tt/typewriter text/ to be included in the document. 
\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. 
\layout Standard
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, 
\layout LyX-Code
<itemize> 
\layout LyX-Code
<item>Here is an item. 
\layout LyX-Code
<item>Here is a second item. 
\layout LyX-Code
</itemize> 
\layout Standard
Looks like this: 
\layout Itemize
Here is an item. 
\layout Itemize
Here is a second item. 
\layout Standard
Or, for an 
\family typewriter
enum
\family default
, 
\layout LyX-Code
<enum> 
\layout LyX-Code
<item>Here is the first item. 
\layout LyX-Code
<item>Here is the second item. 
\layout LyX-Code
</enum> 
\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: 
\layout LyX-Code
<descrip> 
\layout LyX-Code
<tag/Gnats./ Annoying little bugs that fly into your cooling fan. 
\layout LyX-Code
<tag/Gnus./ Annoying little bugs that run on your CPU. 
\layout LyX-Code
</descrip> 
\layout Standard
ends up looking like: 
\layout Description
Gnats.
\layout Standard
Annoying little bugs that fly into your cooling fan. 
\layout Description
Gnus.
\layout Standard
Annoying little bugs that run on your CPU. 
\layout Subsection
Conditionalization 
\layout Standard
The overall goal of LinuxDoc-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. 
LinuxDoc-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: 
\layout LyX-Code
Some <#if output=latex2e version=drlinux>conditional</#if> text. 
\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 ``latex2e'' 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, ``
\family typewriter
linuxdoc -B latex
\family default
'' 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 
\layout LyX-Code
% linuxdoc -B latex -D version=drlinux foo.sgml 
\layout Standard
or 
\layout LyX-Code
% linuxdoc -B latex foo.sgml 
\layout Standard
would include the ``conditional'' part, but neither 
\layout LyX-Code
% linuxdoc -B html -D version=drlinux foo.sgml 
\layout Standard
nor 
\layout LyX-Code
% linuxdoc -B latex -D private=book foo.sgml 
\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: 
\layout LyX-Code
Some <#if output="latex2e|html" version=drlinux>conditional</#if> text. 
\layout Standard
and formatting with either ``-B latex'' or ``-B html'' will include the 
``conditional'' text (but formatting with, say, ``-B txt'' 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 LinuxDoc-Tools documents that contain conditionals. 
However, you can validity-check them with ``
\family typewriter
linuxdoc -B check
\family default
''. 
\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, LinuxDoc-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, LinuxDoc-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
linuxdoc -B check
\family default
''. For example. 
\layout LyX-Code
% linuxdoc -B check foo.sgml  
\layout Standard
If you see no output from this check 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: 
\layout LyX-Code
% linuxdoc -B txt foo.sgml  
\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: 
\layout LyX-Code
% linuxdoc -B txt --man foo.sgml  
\layout Subsection
Creating LaTeX, DVI, PostScript or PDF Output 
\layout Standard
To create a LaTeX documents from the SGML source file, simply run: 
\layout LyX-Code
% linuxdoc -B latex foo.sgml  
\layout Standard
If you want to produce PostScript output (via 
\family typewriter
dvips
\family default
), use the 
``
\family typewriter
-o
\family default
'' option: 
\layout LyX-Code
% linuxdoc -B latex --output=ps foo.sgml  
\layout Standard
Or you can produce a DVI file: 
\layout LyX-Code
% linuxdoc -B latex --output=dvi foo.sgml  
\layout Standard
Also, you can produce a PDF file: 
\layout LyX-Code
% linuxdoc -B latex --output=pdf foo.sgml  
\layout Subsection
Creating HTML Output 
\layout Standard
If you want to produce HTML output, do this: 
\layout LyX-Code
% linuxdoc -B html --imagebuttons foo.sgml  
\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 ``
\family typewriter
--imagebuttons
\family default
'' option tells html backend driver 
to use graphic arrows as navigation buttons. The names of these 
icons are ``next.png'', ``prev.png'', and ``toc.png'', and 
the LinuxDoc-Tools system supplies appropriate PNGs in its library 
directory. 
\layout Standard
If you use ``
\family typewriter
linuxdoc -B html
\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 ``
\family typewriter
--language
\family default
'' 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: 
\layout LyX-Code
% linuxdoc -B info foo.sgml  
\layout Subsection
Creating LyX Output 
\layout Standard
For LyX output, use the the command: 
\layout LyX-Code
% linuxdoc -B lyx foo.sgml  
\layout Subsection
Creating RTF Output 
\layout Standard
If you want to produce RTF output, run the command: 
\layout LyX-Code
% linuxdoc -B rtf foo.sgml  
\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: 
\layout LyX-Code
% linuxdoc -B txt --charset=latin foo.sgml  
\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 Standard
Currently, EUC-JP (ujis) character set is partially supported. 
Source SGML file using this character set can be converted 
in plain text, HTML, and LaTeX. Other output formats are not 
tested fully. 
\layout Section
How LinuxDoc-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
LinuxDoc-Tools 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 LinuxDoc-Tools 
actually works. 
\layout Standard
LinuxDoc-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 the top of it that says ``linuxdoc system''; 
that is how one tells an SGML parser what DTD to use. 
\layout Standard
Actually, LinuxDoc-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 LinuxDoc-Tools guru. 
\layout Standard
If you are an SGML guru, you may find it interesting to know that the 
LinuxDoc-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 defined 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 LinuxDoc-Tools Processes A Document 
\layout Standard
Here's how processing a document with LinuxDoc-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 LyX-Code
<!element article - - 
\layout LyX-Code
    (titlepag, header?,  
\layout LyX-Code
     toc?, lof?, lot?, p*, sect*,  
\layout LyX-Code
     (appendix, sect+)?, biblio?) +(footnote)> 
\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
. LinuxDoc-Tools 
uses the 
\family typewriter
onsgmls
\family default
 parser in OpenJade, or 
\family typewriter
nsgmls
\family default
 parser in Jade. 
The former is the successor of the latter. 
\family typewriter
sgmls
\family default
 parser was written 
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
onsgmls
\family default
 or 
\family typewriter
nsgmls
\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: 
\layout LyX-Code
<itemize>    +    "\backslash \backslash begin{itemize}   + 
\layout LyX-Code
</itemize>   +    "\backslash \backslash end{itemize}    + 
\layout Standard
Which says that whenever you begin an 
\family typewriter
itemize
\family default
 element in the 
SGML source, it should be replaced with 
\layout LyX-Code
\backslash begin{itemize} 
\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 LatexCommand \htmlurl[ftp://ftp.cs.cornell.edu/pub/mdw/SGML]{ftp://ftp.cs.cornell.edu/pub/mdw/SGML}
\end_inset
\family default
. 
QWERTZ (and hence, LinuxDoc-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 LatexCommand \htmlurl[ftp://ftp.gmd.de/GMD/sgml]{ftp://ftp.gmd.de/GMD/sgml}
\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 LatexCommand \url[SGML and the Web]{http://www.w3.org/hypertext/WWW/MarkUp/SGML/}
\end_inset
\family default
\layout Enumerate
\family typewriter
\begin_inset LatexCommand \url[SGML Web Page]{http://www.sil.org/sgml/sgml.html}
\end_inset
\family default
\layout Enumerate
\family typewriter
\begin_inset LatexCommand \url[Yahoo's SGML Page]{http://www.yahoo.com/Computers_and_Internet/Software/Data_Formats/SGML}
\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 LatexCommand \htmlurl[ftp://ftp.jclark.com]{ftp://ftp.jclark.com}
\end_inset
\family default
 and at 
\family typewriter
\begin_inset LatexCommand \url[James Clark's WWW Page]{http://www.jclark.com}
\end_inset
\family default
. 
\layout Itemize
The emacs psgml package can be found at 
\family typewriter
\begin_inset LatexCommand \htmlurl[ftp://ftp.lysator.liu.se/pub/sgml]{ftp://ftp.lysator.liu.se/pub/sgml}
\end_inset
\family default
. This package 
provides a lot of SGML functionality. 
\layout Itemize
More information on 
\family typewriter
LyX
\family default
 can be found at the 
\family typewriter
\begin_inset LatexCommand \url[LyX WWW Page]{http://wsiserv.informatik.uni-tuebingen.de/~ettrich/}
\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. 
\layout Standard
\the_end
