#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
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{
\end_inset
sgml
\begin_inset LatexDel }{
\end_inset
How LinuxDoc-Tools Works
\begin_inset LatexDel }
\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 LatexDel \url{
\end_inset
http://sgmltools-lite.sourceforge.net/
\begin_inset LatexDel }{
\end_inset
\begin_inset LatexDel }
\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 LatexDel \url{
\end_inset
http://www.debian.org/~sano/linuxdoc-tools/
\begin_inset LatexDel }{
\end_inset
\begin_inset LatexDel }
\end_inset
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 LatexDel \url{
\end_inset
ftp://prep.ai.mit.edu/pub/gnu
\begin_inset LatexDel }{
\end_inset
\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. 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 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 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 
\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 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

\protected_separator

\protected_separator
(½)
\protected_separator

\layout Standard

vertical 1/2 fraction 
\layout Description

&frac12
\protected_separator
(½)
\protected_separator

\layout Standard

typeset 1/2 fraction 
\layout Description

&frac14
\protected_separator
(¼)
\protected_separator

\layout Standard

typeset 1/4 fraction 
\layout Description

&frac34
\protected_separator
(¾)
\protected_separator

\layout Standard

typeset 3/4 fraction 
\layout Description

&frac18
\protected_separator
(1/8)
\protected_separator

\layout Standard

typeset 1/8 fraction 
\layout Description

&frac38
\protected_separator
(3/8)
\protected_separator

\layout Standard

typeset 3/8 fraction 
\layout Description

&frac58
\protected_separator
(5/8)
\protected_separator

\layout Standard

typeset 5/8 fraction 
\layout Description

&frac78
\protected_separator
(7/8)
\protected_separator

\layout Standard

typeset 7/8 fraction 
\layout Description

&sup1
\protected_separator

\protected_separator

\protected_separator
(¹)
\protected_separator

\layout Standard

superscript 1 
\layout Description

&sup2
\protected_separator

\protected_separator

\protected_separator
(²)
\protected_separator

\layout Standard

superscript 2 
\layout Description

&sup3
\protected_separator

\protected_separator

\protected_separator
(³)
\protected_separator

\layout Standard

superscript 3 
\layout Description

&plus
\protected_separator

\protected_separator

\protected_separator
(+)
\protected_separator

\layout Standard

plus sign 
\layout Description

&plusmn
\protected_separator
(±)
\protected_separator

\layout Standard

plus-or-minus sign 
\layout Description

&lt
\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator
(<)
\protected_separator

\layout Standard

less-than sign 
\layout Description

&equals
\protected_separator
(=)
\protected_separator

\layout Standard

equals sign 
\layout Description

&gt
\protected_separator

\protected_separator

\protected_separator

\protected_separator

\protected_separator
(>)
\protected_separator

\layout Standard

greater-than sign 
\layout Description

&divide
\protected_separator
(/)
\protected_separator

\layout Standard

division sign 
\layout Description

&times
\protected_separator

\protected_separator
(×)
\protected_separator

\layout Standard

multiplication sign 
\layout Description

&curren
\protected_separator
(¤)
\protected_separator

\layout Standard

currency symbol 
\layout Description

&pound
\protected_separator

\protected_separator
(£)
\protected_separator

\layout Standard

symbol for ``pounds'' 
\layout Description

&dollar
\protected_separator
($)
\protected_separator

\layout Standard

dollar sign 
\layout Description

&cent
\protected_separator

\protected_separator

\protected_separator
(¢)
\protected_separator

\layout Standard

cent sign 
\layout Description

&yen
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(¥)
\protected_separator

\layout Standard

yen sign 
\layout Description

&num
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(#)
\protected_separator

\layout Standard

number or hash sign 
\layout Description

&percnt
\protected_separator
(%)
\protected_separator

\layout Standard

percent sign 
\layout Description

&amp
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(&)
\protected_separator

\layout Standard

ampersand 
\layout Description

&ast
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(*)
\protected_separator

\layout Standard

asterisk 
\layout Description

&commat
\protected_separator
(@)
\protected_separator

\layout Standard

commercial-at sign 
\layout Description

&lsqb
\protected_separator

\protected_separator

\protected_separator
([)
\protected_separator

\layout Standard

left square bracket 
\layout Description

&bsol
\protected_separator

\protected_separator

\protected_separator
(\backslash
\protected_separator
)
\protected_separator

\layout Standard

backslash 
\layout Description

&rsqb
\protected_separator

\protected_separator

\protected_separator
(])
\protected_separator

\layout Standard

right square bracket 
\layout Description

&lcub
\protected_separator

\protected_separator

\protected_separator
({)
\protected_separator

\layout Standard

left curly brace 
\layout Description

&horbar
\protected_separator
(-)
\protected_separator

\layout Standard

horizontal bar 
\layout Description

&verbar
\protected_separator
(|)
\protected_separator

\layout Standard

vertical bar 
\layout Description

&rcub
\protected_separator

\protected_separator

\protected_separator
(})
\protected_separator

\layout Standard

right curly brace 
\layout Description

&micro
\protected_separator

\protected_separator
(µ)
\protected_separator

\layout Standard

greek mu (micro prefix) 
\layout Description

&ohm
\protected_separator

\protected_separator

\protected_separator

\protected_separator
({ohm})
\protected_separator

\layout Standard

greek capital omega (Ohm sign) 
\layout Description

&deg
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(°)
\protected_separator

\layout Standard

small superscript circle sign (degree sign) 
\layout Description

&ordm
\protected_separator

\protected_separator

\protected_separator
({ordm})
\protected_separator

\layout Standard

masculine ordinal 
\layout Description

&ordf
\protected_separator

\protected_separator

\protected_separator
({ordf})
\protected_separator

\layout Standard

feminine ordinal 
\layout Description

&sect
\protected_separator

\protected_separator

\protected_separator
(§)
\protected_separator

\layout Standard

section sign 
\layout Description

&para
\protected_separator

\protected_separator

\protected_separator
(¶)
\protected_separator

\layout Standard

paragraph sign 
\layout Description

&middot
\protected_separator
(·)
\protected_separator

\layout Standard

centered dot 
\layout Description

&larr
\protected_separator

\protected_separator

\protected_separator
(<-)
\protected_separator

\layout Standard

left arrow 
\layout Description

&rarr
\protected_separator

\protected_separator

\protected_separator
(->)
\protected_separator

\layout Standard

right arrow 
\layout Description

&uarr
\protected_separator

\protected_separator

\protected_separator
({uarr})
\protected_separator

\layout Standard

up arrow 
\layout Description

&darr
\protected_separator

\protected_separator

\protected_separator
({darr})
\protected_separator

\layout Standard

down arrow 
\layout Description

&copy
\protected_separator

\protected_separator

\protected_separator
(©)
\protected_separator

\layout Standard

copyright 
\layout Description

&reg
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(®)
\protected_separator

\layout Standard

r-in-circle marl 
\layout Description

&trade
\protected_separator

\protected_separator
((TM))
\protected_separator

\layout Standard

trademark sign 
\layout Description

&brvbar
\protected_separator
(¦)
\protected_separator

\layout Standard

broken vertical bar 
\layout Description

&not
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(¬)
\protected_separator

\layout Standard

logical-negation sign 
\layout Description

&sung
\protected_separator

\protected_separator

\protected_separator
({sung})
\protected_separator

\layout Standard

sung-note sign 
\layout Description

&excl
\protected_separator

\protected_separator

\protected_separator
(!)
\protected_separator

\layout Standard

exclamation point 
\layout Description

&iexcl
\protected_separator

\protected_separator
(¡)
\protected_separator

\layout Standard

inverted exclamation point 
\layout Description

&quot
\protected_separator

\protected_separator

\protected_separator
(")
\protected_separator

\layout Standard

double quote 
\layout Description

&apos
\protected_separator

\protected_separator

\protected_separator
(')
\protected_separator

\layout Standard

apostrophe (single quote) 
\layout Description

&lpar
\protected_separator

\protected_separator

\protected_separator
(()
\protected_separator

\layout Standard

left parenthesis 
\layout Description

&rpar
\protected_separator

\protected_separator

\protected_separator
())
\protected_separator

\layout Standard

right parenthesis 
\layout Description

&comma
\protected_separator

\protected_separator
(,)
\protected_separator

\layout Standard

comma 
\layout Description

&lowbar
\protected_separator
(_)
\protected_separator

\layout Standard

under-bar 
\layout Description

&hyphen
\protected_separator
(-)
\protected_separator

\layout Standard

hyphen 
\layout Description

&period
\protected_separator
(.)
\protected_separator

\layout Standard

period 
\layout Description

&sol
\protected_separator

\protected_separator

\protected_separator

\protected_separator
(/)
\protected_separator

\layout Standard

solidus 
\layout Description

&colon
\protected_separator

\protected_separator
(:)
\protected_separator

\layout Standard

colon 
\layout Description

&semi
\protected_separator

\protected_separator

\protected_separator
(;)
\protected_separator

\layout Standard

semicolon 
\layout Description

&quest
\protected_separator

\protected_separator
(?)
\protected_separator

\layout Standard

question mark 
\layout Description

&iquest
\protected_separator
(¿)
\protected_separator

\layout Standard

interrobang 
\layout Description

&laquo
\protected_separator

\protected_separator
(«)
\protected_separator

\layout Standard

left guillemot 
\layout Description

&raquo
\protected_separator

\protected_separator
(»)
\protected_separator

\layout Standard

right guillemot 
\layout Description

&lsquo
\protected_separator

\protected_separator
(`)
\protected_separator

\layout Standard

left single quote 
\layout Description

&rsquo
\protected_separator

\protected_separator
(')
\protected_separator

\layout Standard

right single quote 
\layout Description

&ldquo
\protected_separator

\protected_separator
(")
\protected_separator

\layout Standard

left double quote 
\layout Description

&rdquo
\protected_separator

\protected_separator
(")
\protected_separator

\layout Standard

right double quote 
\layout Description

&nbsp
\protected_separator

\protected_separator

\protected_separator
( )
\protected_separator

\layout Standard

non-breaking space 
\layout Description

&shy
\protected_separator

\protected_separator

\protected_separator

\protected_separator
()
\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: 
\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 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:  
\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 LinuxDoc-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
LinuxDoc-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 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{
\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

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 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: 
\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

\layout Standard

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

Gnus.
\protected_separator

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

Some
\protected_separator
<#if
\protected_separator
output=latex2e
\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 ``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  
\begin_deeper
\layout Verbatim

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
latex
\protected_separator
-D
\protected_separator
version=drlinux
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\end_deeper
\layout Standard

or 
\begin_deeper
\layout Verbatim

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
latex
\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
linuxdoc
\protected_separator
-B
\protected_separator
html
\protected_separator
-D
\protected_separator
version=drlinux
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\end_deeper
\layout Standard

nor 
\begin_deeper
\layout Verbatim

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
latex
\protected_separator
-D
\protected_separator
private=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="latex2e|html"
\protected_separator
version=drlinux>conditional</#if>
\protected_separator
text.
\protected_separator

\protected_separator

\end_deeper
\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 Standard

\begin_deeper
\layout Verbatim

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
check
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

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

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
txt
\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
linuxdoc
\protected_separator
-B
\protected_separator
txt
\protected_separator
--man
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Subsection

Creating LaTeX, DVI, PostScript or PDF Output 
\layout Standard

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

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
latex
\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 -o
\family default '' option: 
\begin_deeper
\layout Verbatim

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
latex
\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
linuxdoc
\protected_separator
-B
\protected_separator
latex
\protected_separator
--output=dvi
\protected_separator
foo.sgml
\protected_separator

\protected_separator

\protected_separator

\end_deeper
\layout Standard

Also, you can produce a PDF file: 
\begin_deeper
\layout Verbatim

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
latex
\protected_separator
--output=pdf
\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
linuxdoc
\protected_separator
-B
\protected_separator
html
\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 ``
\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: 
\begin_deeper
\layout Verbatim

%
\protected_separator
linuxdoc
\protected_separator
-B
\protected_separator
info
\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
linuxdoc
\protected_separator
-B
\protected_separator
lyx
\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
linuxdoc
\protected_separator
-B
\protected_separator
rtf
\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
linuxdoc
\protected_separator
-B
\protected_separator
txt
\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 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 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 . 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: 
\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, 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 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
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
