This is originally written by Matt Welsh and updated by many people.

     See guide.txt or guide.ps for formatted output.

-->

<article>

<title>LinuxDoc-Tools User's Guide

<author>

  <name>written by Matt Welsh as the LinuxDoc-SGML User's Guide.</name>

  <and>

    <name>Updated by Greg Hankins, and rewritten by Eric S. Raymond

          for SGML-Tools.</name>

  <and>

    <name>Updated and renamed by Taketoshi Sano, for LinuxDoc-Tools</name>

</author>

<date>$Date: 2002/03/18 13:39:10 $ ($Revision: 1.2 $)

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

</abstract>

<toc>

<sect>Introduction

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 

that you can use as a model for your own documents.

The ``LinuxDoc'' means the name of a specific SGML DTD here.

<sect1>What's the DTD ?

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 

You may know the HTML has their own DTD.

Don't be confusing.  SGML is 

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

 (<ref id="sgml" name="How LinuxDoc-Tools Works">).

<sect1>History of the LinuxDoc

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, 

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.

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 <url url="http://sgmltools-lite.sourceforge.net/">.

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.

<sect>Installation

<sect1>Where to get the source archive

You can get the source archive of the linuxdoc-tools from:

<itemize>

<item><url url="http://www.debian.org/˜sano/linuxdoc-tools/">

</itemize>

The name of the archive may be 

These have the equivalent contents. You can use anyone.

<sect1>What LinuxDoc-Tools Needs

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.

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.

<enum>

<item>

You can get this from <url url="ftp://prep.ai.mit.edu/pub/gnu">.

There is a Linux binary

version at 

name="ftp://sunsite.unc.edu/pub/Linux/utils/text"> as well.  You

will need 

You can find the version of your <tt/groff/ from <tt>groff -v < /dev/null</tt>.

<item>TeX and LaTeX.  This is available more or less everywhere; you should

have no problem getting it and installing it (there is a Linux binary

distribution on 

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.

<item>

<tt>

name="ftp://prep.ai.mit.edu/pub/gnu"></tt>.

<item>

info files.  These are also available on 

<tt>

name="ftp://prep.ai.mit.edu/pub/gnu"></tt>, or on 

<tt>

name="ftp://sunsite.unc.edu/pub/Linux/utils/text"></tt> 

(for 

<tt>

name="ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers"></tt> 

(for GNU info tools).  

<item>LyX (a quasi-WYSIWYG interface to LaTeX, with SGML layouts), is

available on 

<htmlurl url="ftp://ftp.via.ecp.fr" name="ftp://ftp.via.ecp.fr">.

</enum>

<sect1>Installing The Software

The steps needed to install and configure the LinuxDoc-Tools are:

<enum>

<item>First, unpack the tar file of the source archive somewhere.

This will create the directory 

It doesn't matter where you unpack this file; just don't move things 

around within the extracted source tree.

<item>Read the 

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

immediately once you have done so.

</enum>

<sect>Writing Documents With LinuxDoc-Tools

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 

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

<sect1>Basic Concepts

Looking at the source of the example document, you'll notice right off

that there are a number of ``tags'' marked within angle brackets

(<tt><</tt> and <tt/></tt>).  A tag simply specifies the beginning or end

of an element, where an element is something like a section, a paragraph,

a phrase of italicized text, an item in a list, and so on.  Using a tag

is like using an HTML tag, or a LaTeX command such as <tt>\item</tt> or 

<tt>\section{...}</tt>.

As a simple example, to produce <bf>this boldfaced text</bf>, you would type

<tscreen><verb>

As a simple example, to produce <bf>this boldfaced text&etag;;bf>, ...

</verb></tscreen>

in the source.  <tt><bf></tt> begins the region of bold text, and

<tt>&etag;;bf></tt> ends it.  Alternately, you can use the abbreviated form

<tscreen><verb>

As a simple example, to produce 

</verb></tscreen>

which encloses the bold text within slashes.  (Of course, you'll need to

use the long form if the enclosed text contains slashes, such as the

case with Unix filenames).  

There are other things to watch out with respect to special characters 

(that's why you'll notice all of these bizarre-looking ampersand 

expressions if you look at the source; I'll talk about those shortly).

In some cases, the end-tag for a particular element is optional.  For

example, to begin a section, you use the <tt><sect></tt> tag, 

however, the end-tag for the section (which could appear at the end of

the section body itself, not just after the name of the section!) 

is optional and implied when you start another section of the same depth.

In general you needn't worry about these details; just follow the model

used in the tutorial (

<sect1>Special Characters

Obviously, the angle brackets are themselves special characters in the

SGML source.  There are others to watch out for.  For example, let's say 

that you wanted to type an expression with angle brackets around it,

as so: <tt><foo></tt>.  In order to get the left angle bracket, you

must use the <tt>&lt;</tt> element, which is a ``macro'' that expands

to the actual left-bracket character.  Therefore, in the source, I typed

<tscreen><verb>

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

</verb></tscreen>

Generally, anything beginning with an ampersand is a special

character.  For example, there's 

%, 

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:

<itemize>

<item>Use <tt>&amp;</tt> for the ampersand (&), 

<item>Use <tt>&lt;</tt> for a left bracket (<),

<item>Use <tt>&gt;</tt> for a right bracket (&gt),

<item>Use <tt>&etago;</tt> for a left bracket with a slash 

(<tt>&etag;;</tt>)

<item>Use <tt>&dollar;</tt> for a dollar sign ($),

<item>Use <tt>&num;</tt> for a hash (#),

<item>Use <tt>&percnt;</tt> for a percent (%),

<item>Use <tt>&tilde;</tt> for a tilde (˜),

<item>Use <tt>``</tt> and <tt>''</tt> for quotes, or use

   <tt>&dquot;</tt> for &dquot;.

<item>Use <tt>&shy;</tt> for a soft hyphen (that is, an indication

   that this is a good place to break a word for horizontal justification).  

</itemize>

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.

<descrip>

<tag>&half   (½)</tag>vertical 1/2 fraction

<tag>&frac12 (½)</tag>typeset 1/2 fraction

<tag>&frac14 (¼)</tag>typeset 1/4 fraction

<tag>&frac34 (¾)</tag>typeset 3/4 fraction

<tag>&frac18 (⅛)</tag>typeset 1/8 fraction

<tag>&frac38 (⅜)</tag>typeset 3/8 fraction

<tag>&frac58 (⅝)</tag>typeset 5/8 fraction

<tag>&frac78 (⅞)</tag>typeset 7/8 fraction

<tag>&sup1   (¹)</tag>superscript 1

<tag>&sup2   (²)</tag>superscript 2

<tag>&sup3   (³)</tag>superscript 3

<tag>&plus   (+)</tag>plus sign

<tag>&plusmn (±)</tag>plus-or-minus sign

<tag>&lt     (<)</tag>less-than sign

<tag>&equals (=)</tag>equals sign

<tag>&gt     (>)</tag>greater-than sign

<tag>&divide (÷)</tag>division sign

<tag>&times  (×)</tag>multiplication sign

<tag>&curren (¤)</tag>currency symbol

<tag>&pound  (£)</tag>symbol for ``pounds''

<tag>&dollar ($)</tag>dollar sign

<tag>&cent   (¢)</tag>cent sign

<tag>&yen    (¥)</tag>yen sign

<tag>&num    (#)</tag>number or hash sign

<tag>&percnt (%)</tag>percent sign

<tag>&amp    (&)</tag>ampersand

<tag>&ast    (*)</tag>asterisk

<tag>&commat (@)</tag>commercial-at sign

<tag>&lsqb   ([)</tag>left square bracket

<tag>&bsol   (\)</tag>backslash

<tag>&rsqb   (])</tag>right square bracket

<tag>&lcub   ({)</tag>left curly brace

<tag>&horbar (―)</tag>horizontal bar

<tag>&verbar (|)</tag>vertical bar

<tag>&rcub   (})</tag>right curly brace

<tag>&micro  (µ)</tag>greek mu (micro prefix)

<tag>&ohm    (Ω)</tag>greek capital omega (Ohm sign)

<tag>&deg    (°)</tag>small superscript circle sign (degree sign)

<tag>&ordm   (º)</tag>masculine ordinal

<tag>&ordf   (ª)</tag>feminine ordinal

<tag>&sect   (§)</tag>section sign

<tag>&para   (¶)</tag>paragraph sign

<tag>&middot (·)</tag>centered dot

<tag>&larr   (←)</tag>left arrow

<tag>&rarr   (→)</tag>right arrow

<tag>&uarr   (↑)</tag>up arrow

<tag>&darr   (↓)</tag>down arrow

<tag>&copy   (©)</tag>copyright

<tag>&reg    (®)</tag>r-in-circle marl

<tag>&trade  (™)</tag>trademark sign

<tag>&brvbar (¦)</tag>broken vertical bar

<tag>&not    (¬)</tag>logical-negation sign

<tag>&sung   (♪)</tag>sung-note sign

<tag>&excl   (!)</tag>exclamation point

<tag>&iexcl  (¡)</tag>inverted exclamation point

<tag>&quot   (")</tag>double quote

<tag>&apos   (')</tag>apostrophe (single quote)

<tag>&lpar   (()</tag>left parenthesis

<tag>&rpar   ())</tag>right parenthesis

<tag>&comma  (,)</tag>comma

<tag>&lowbar (_)</tag>under-bar

<tag>&hyphen (‐)</tag>hyphen

<tag>&period (.)</tag>period

<tag>&sol    (/)</tag>solidus

<tag>&colon  (:)</tag>colon

<tag>&semi   (;)</tag>semicolon

<tag>&quest  (?)</tag>question mark

<tag>&iquest (¿)</tag>interrobang

<tag>&laquo  («)</tag>left guillemot

<tag>&raquo  (»)</tag>right guillemot

<tag>&lsquo  (‘)</tag>left single quote

<tag>&rsquo  (’)</tag>right single quote

<tag>&ldquo  (“)</tag>left double quote

<tag>&rdquo  (”)</tag>right double quote

<tag>&nbsp   ( )</tag>non-breaking space

<tag>&shy    (­)</tag>soft hyphen

</descrip>

<sect1>Verbatim and Code Environments

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 

<tt>verb</tt> element is used for this; it looks like the following:

<tscreen><verb>

<verb>

 Some literal text to include as example output.

&etag;;verb>

</verb></tscreen>

The <tt>verb</tt> environment doesn't allow you to use 

within it literally.  Specifically, you must do the following within

<itemize>

<item>Use <tt>&ero;</tt> to get an ampersand, 

<item>Use <tt>&etago;</tt> to get <tt>&etag;;</tt>,

<item>Don't use <tt>\end{verbatim}</tt> within a <tt>verb</tt>

environment, as this is what LaTeX uses to end the <tt>verbatim</tt> 

environment.  (In the future, it should be possible to hide the underlying

text formatter entirely, but the parser doesn't support this feature yet.) 

</itemize>

The <tt>code</tt> environment is much just like the 

except that horizontal rules are added to the surrounding text, as so:

Here is an example code environment.

You should use the 

as so:

<tscreen><verb>

<tscreen><verb>

Here is some example text.  

&etag;;verb>&etag;;tscreen>

</verb></tscreen>

sets the default font to 

in the LaTeX and plain text versions.  You can use 

without 

example you'll need to use both of them.  

special characters.  See 

The 

not set the default font to 

non-computer-interaction quotes, as in:

<tscreen><verb>

<quote>

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

&etag;;quote>

</verb></tscreen>

which will generate:

<quote>

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

</quote>

<sect1>Overall Document Structure

Before we get too in-depth with details, we're going to describe the

overall structure of an LinuxDoc-Tools document.  Look at

<sect2>The Preamble

In the document ``preamble'' you set up things such as the title

information and document style: 

<tscreen><verb>

<article>

<title>Linux Foo HOWTO

<author>Norbert Ebersol, 

<date>v1.0, 9 March 1994

<abstract>

This document describes how to use the 

bar libraries, using the 

&etag;;abstract>

<toc>

</verb></tscreen>

The elements should go more or less in this order.  The first line

tells the SGML parser to use the linuxdoc DTD.  We'll explain that in

the later section on <ref id="sgml" name="How LinuxDoc-Tools Works">; for

now just treat it as a bit of necessary magic.  The

<tt><article></tt> tag forces the document to use the ``article''

document style.

The 

<tt>date</tt> tag include the version number and last modification time of

the document.

The 

document, 

include a table of contents (the 

need an 

<sect2>Sectioning And Paragraphs

After the preamble, you're ready to dive into the document.  The following

sectioning commands are available:

<itemize>

<item>

<item>

<item>

<item>

<item>

</itemize>

These are roughly equivalent to their LaTeX counterparts 

After the 

name of the section.  For example, at the top of this document, after

the preamble, comes the tag:

<tscreen><verb>

<sect>Introduction

</verb></tscreen>

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

is the tag:

<tscreen><verb>

<sect2>Sectioning And Paragraphs

</verb></tscreen>

After the section tag, you begin the body of the section.  However, you

must start the body with a <tt><p></tt> tag, as so:

<tscreen><verb>

<sect>Introduction

This is a user's guide to the LinuxDoc-Tools document processing...

</verb></tscreen>

This is to tell the parser that you're done with the section title

and are ready to begin the body.  Thereafter, new paragraphs are started

with a blank line (just as you would do in TeX).  For example,

<tscreen><verb>

Here is the end of the first paragraph.

And we start a new paragraph here.

</verb></tscreen>

There is no reason to use <tt><p></tt> tags at the beginning of

every paragraph; only at the beginning of the first paragraph after

a sectioning command.

<sect2>Ending The Document

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

<tscreen><verb>

&etag;;article>

</verb></tscreen>

to tell the parser that you're done with the 

embodies the entire document).  

</sect2>

<sect1>Internal Cross-References<label id="cross-ref">

Now we're going to move onto other features of the system.  

Cross-references are easy.  For example, if you want to make a

cross-reference to a certain section, you need to label that section

as so:

<tscreen><verb>

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

</verb></tscreen>

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

expression:

<tscreen><verb>

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

</verb></tscreen>

This will replace the 

as 

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.  

For example, this section is <ref id="cross-ref" name="Cross-References">.

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.

<sect1>Web References

There is also a 

URLs, used on the World Wide Web.  This element should be used to refer

to other documents, files available for FTP, and so forth.  For

example,

<tscreen><verb>

You can get the Linux HOWTO documents from 

   name="The Linux HOWTO INDEX">.

</verb></tscreen>

The 

URL in question will be automatically added to the HTML document.

The optional 

the URL (for HTML conversion) or named as the description of the

URL (for LaTeX and groff).  If no 

URL itself will be used.

A useful variant of this is 

the URL part in every context except HTML.  What this is useful for

is things like a person's email addresses; you can write

<tscreen><verb>

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

</verb></tscreen>

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.

<sect1>Fonts

Essentially, the same fonts supported by LaTeX are supported

by LinuxDoc-Tools.  Note, however, that the conversion to 

plain text (through 

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.  

In particular, the 

get constant-width ``typewriter'' font which should be used for

all e-mail addresses, machine names, filenames, and so on.  

Example:

<tscreen><verb>

Here is some <tt>typewriter text&etag;;tt> to be included in the document.

</verb></tscreen>

Equivalently:

<tscreen><verb>

Here is some 

</verb></tscreen>

Remember that you can only use this abbreviated form if the enclosed

text doesn't contain slashes.

Other fonts can be achieved with 

for 

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.

<sect1>Lists

There are various kinds of supported lists.  They are:

<itemize>

<item>

<item>

<item>

</itemize>

Each item in an 

with an 

For example,

<tscreen><verb>

<itemize>

<item>Here is an item.

<item>Here is a second item.

&etag;;itemize>

</verb></tscreen>

Looks like this:

<itemize>

<item>Here is an item.

<item>Here is a second item.

</itemize>

Or, for an 

<tscreen><verb>

<enum>

<item>Here is the first item.

<item>Here is the second item.

&etag;;enum>

</verb></tscreen>

You get the idea.  Lists can be nested as well; see the example document

for details.

A 

you might want to use it for some situations:

<tscreen><verb>

<descrip>

&etag;;descrip>

</verb></tscreen>

ends up looking like:

<descrip>

</descrip>

<sect1>Conditionalization

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.

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:

<tscreen><verb>

Some <#if output=latex2e version=drlinux>conditional</#if> text.

</verb></tscreen>

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.

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, ``<tt>linuxdoc -B latex</tt>'' 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 

<tscreen><verb>

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

</verb></tscreen>

or

<tscreen><verb>

% linuxdoc -B latex foo.sgml

</verb></tscreen>

would include the ``conditional'' part, but neither

<tscreen><verb>

% linuxdoc -B html -D version=drlinux foo.sgml

</verb></tscreen>

nor

<tscreen><verb>

% linuxdoc -B latex -D private=book foo.sgml

</verb></tscreen>

would do so.

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:

<tscreen><verb>

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

</verb></tscreen>

and formatting with either ``-B latex'' or ``-B html'' will include the

``conditional'' text (but formatting with, say, ``-B txt'' will not).

The <#unless> tag is the exact inverse of <#if>; it

includes when <#if>; would exclude, and vice-versa.

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.  

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 ``<tt>linuxdoc -B check</tt>''.

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.

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.

<sect1>Index generation

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.

The two tags behave identically, except that <idx> sets the

entry in a normal font and <cdx> in a constant-width one.

If you want to add an index entry that shouldn't appear in the text

itself, use the <nidx> and <ncdx> tags.

<sect1>Controlling justification

In order to get proper justification and filling of paragraphs in

typeset output, LinuxDoc-Tools includes the ­ entity.  This

becomes an optional or `soft' hyphen in back ends like latex2e

for which this is neaningful.

The bracketing tag <file> can be used to surround filenames in

running text.  It effectively inserts soft hyphens after each slash in

the filename.

One of the advantages of using the <url> and <htmlurl>

tags is that they do likewise for long URLs.

<sect>Formatting SGML Documents

Let's say you have the SGML document 

Here is a general overview of formatting the document for different output.

For a complete list of options, consult the man pages.

<sect1>Checking SGML Syntax

If you just want to capture your errors from the SGML conversion,

use the ``<tt>linuxdoc -B check</tt>''.  For example.

<tscreen><verb>

% linuxdoc -B check foo.sgml 

</verb></tscreen>

If you see no output from this check run other than the

``Processing...'' message, that's good.  It means there were no errors.

<sect1>Creating Plain Text Output

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

<tscreen><verb>

% linuxdoc -B txt foo.sgml 

</verb></tscreen>

You can also create groff source for man pages, which can be formatted with

<tscreen><verb>

% linuxdoc -B txt --man foo.sgml 

</verb></tscreen>

<sect1>Creating LaTeX, DVI, PostScript or PDF Output 

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

<tscreen><verb>

% linuxdoc -B latex foo.sgml 

</verb></tscreen>

If you want to produce PostScript output (via 

``<tt>-o</tt>'' option:

<tscreen><verb>

% linuxdoc -B latex --output=ps foo.sgml 

</verb></tscreen>

Or you can produce a DVI file:

<tscreen><verb>

% linuxdoc -B latex --output=dvi foo.sgml 

</verb></tscreen>

Also, you can produce a PDF file:

<tscreen><verb>

% linuxdoc -B latex --output=pdf foo.sgml 

</verb></tscreen>

<sect1>Creating HTML Output

If you want to produce HTML output, do this:

<tscreen><verb>

% linuxdoc -B html --imagebuttons foo.sgml 

</verb></tscreen>

This will produce <tt>foo.html</tt>, as well as <tt>foo-1.html</tt>,

document.  Run your WWW browser on <tt>foo.html</tt>, 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.

The ``<tt>--imagebuttons</tt>'' 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.

If you use ``<tt>linuxdoc -B html</tt>'' without the ``<tt>-img</tt>''

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 ``<tt>--language</tt>'' option, however, the labels will be given

in that language.

<sect1>Creating GNU Info Output

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

following command:

<tscreen><verb>

% linuxdoc -B info foo.sgml 

</verb></tscreen>

<sect1>Creating LyX Output

For LyX output, use the the command:

<tscreen><verb>

% linuxdoc -B lyx foo.sgml 

</verb></tscreen>

<sect1>Creating RTF Output

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

<tscreen><verb>

% linuxdoc -B rtf foo.sgml 

</verb></tscreen>

This will produce <tt>foo.rtf</tt>, as well as <tt>foo-1.rtf</tt>,

<sect>Internationalization Support

The ISO 8859-1 (latin1) character set may be used for international characters 

in plain text, LaTeX, HTML, LyX, and RTF output (GNU info support for 

ISO 8859-1 may be possible in the future).  To use this feature, give the

formatting scripts the ``<tt>--charset=latin</tt>'' flag, for example:

<tscreen><verb>

% linuxdoc -B txt --charset=latin foo.sgml 

</verb></tscreen>

You also can use ISO 8859-1 characters in the SGML source, they will 

automatically be translated to the proper escape codes for the corresponding 

output format.

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.

<sect>How LinuxDoc-Tools Works<label id="sgml">

Technically, the tags and conventions we've explored in previous

sections of this use's guide are what is called a markup

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

<sect1>Overview of SGML

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