/usr/share/doc/linuxdoc-tools/html/guide-3.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.72">
 <TITLE>LinuxDoc-Tools User's Guide: Writing Documents With LinuxDoc-Tools</TITLE>
 <LINK HREF="guide-4.html" REL=next>
 <LINK HREF="guide-2.html" REL=previous>
 <LINK HREF="guide.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="guide-4.html"><IMG SRC="next.png" ALT="Next"></A>
<A HREF="guide-2.html"><IMG SRC="prev.png" ALT="Previous"></A>
<A HREF="guide.html#toc3"><IMG SRC="toc.png" ALT="Contents"></A>
<HR>
<H2><A NAME="s3">3.</A> <A HREF="guide.html#toc3">Writing Documents With LinuxDoc-Tools</A></H2>

<P>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 <CODE>example.sgml</CODE> 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
<CODE>example.sgml</CODE> so you have a real live case to refer to.</P>

<H2><A NAME="ss3.1">3.1</A> <A HREF="guide.html#toc3.1">Basic Concepts</A>
</H2>

<P>Looking at the source of the example document, you'll notice right off
that there are a number of ``tags'' marked within angle brackets
(<CODE>&lt;</CODE> and <CODE>&gt;</CODE>).  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 <CODE>\item</CODE> or 
<CODE>\section{...}</CODE>.</P>
<P>As a simple example, to produce <B>this boldfaced text</B>, you would type
<BLOCKQUOTE><CODE>
<PRE>
As a simple example, to produce &lt;bf>this boldfaced text&lt;/bf>, ...
</PRE>
</CODE></BLOCKQUOTE>

in the source.  <CODE>&lt;bf></CODE> begins the region of bold text, and
<CODE>&lt;/bf></CODE> ends it.  Alternately, you can use the abbreviated form
<BLOCKQUOTE><CODE>
<PRE>
As a simple example, to produce &lt;bf/this boldfaced text/, ...
</PRE>
</CODE></BLOCKQUOTE>

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).  </P>
<P>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).</P>
<P>In some cases, the end-tag for a particular element is optional.  For
example, to begin a section, you use the <CODE>&lt;sect></CODE> 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 (<CODE>example.sgml</CODE>).</P>

<H2><A NAME="ss3.2">3.2</A> <A HREF="guide.html#toc3.2">Special Characters</A>
</H2>

<P>Obviously, the angle brackets are themselves special characters in the
SGML source.  There are others to watch out for.  For example, let's say 
that you wanted to type an expression with angle brackets around it,
as so: <CODE>&lt;foo&gt;</CODE>.  In order to get the left angle bracket, you
must use the <CODE>&amp;lt;</CODE> element, which is a ``macro'' that expands
to the actual left-bracket character.  Therefore, in the source, I typed
<BLOCKQUOTE><CODE>
<PRE>
angle brackets around it, as so: &lt;tt>&amp;lt;foo&amp;gt;&lt;/tt>.
</PRE>
</CODE></BLOCKQUOTE>

Generally, anything beginning with an ampersand is a special
character.  For example, there's <CODE>&amp;percnt;</CODE> to produce
%, <CODE>&amp;verbar;</CODE> 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:
<UL>
<LI>Use <CODE>&amp;amp;</CODE> for the ampersand (&amp;), </LI>
<LI>Use <CODE>&amp;lt;</CODE> for a left bracket (&lt;),</LI>
<LI>Use <CODE>&amp;gt;</CODE> for a right bracket (&gt;),</LI>
<LI>Use <CODE>&amp;etago;</CODE> for a left bracket with a slash 
(<CODE>&lt;/</CODE>)</LI>
<LI>Use <CODE>&amp;dollar;</CODE> for a dollar sign ($),</LI>
<LI>Use <CODE>&amp;num;</CODE> for a hash (#),</LI>
<LI>Use <CODE>&amp;percnt;</CODE> for a percent (%),</LI>
<LI>Use <CODE>&amp;tilde;</CODE> for a tilde (~),</LI>
<LI>Use <CODE>``</CODE> and <CODE>''</CODE> for quotes, or use
<CODE>&amp;dquot;</CODE> for &#34;.</LI>
<LI>Use <CODE>&amp;shy;</CODE> for a soft hyphen (that is, an indication
that this is a good place to break a word for horizontal justification).  </LI>
</UL>
</P>
<P>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.</P>
<P>
<DL>
<DT><B>&amp;half   (1/2)</B><DD>
<P>vertical 1/2 fraction</P>
<DT><B>&amp;frac12 (1/2)</B><DD>
<P>typeset 1/2 fraction</P>
<DT><B>&amp;frac14 (1/4)</B><DD>
<P>typeset 1/4 fraction</P>
<DT><B>&amp;frac34 (3/4)</B><DD>
<P>typeset 3/4 fraction</P>
<DT><B>&amp;frac18 (1/8)</B><DD>
<P>typeset 1/8 fraction</P>
<DT><B>&amp;frac38 (3/8)</B><DD>
<P>typeset 3/8 fraction</P>
<DT><B>&amp;frac58 (5/8)</B><DD>
<P>typeset 5/8 fraction</P>
<DT><B>&amp;frac78 (7/8)</B><DD>
<P>typeset 7/8 fraction</P>
<DT><B>&amp;sup1   (^1)</B><DD>
<P>superscript 1</P>
<DT><B>&amp;sup2   (^2)</B><DD>
<P>superscript 2</P>
<DT><B>&amp;sup3   (^3)</B><DD>
<P>superscript 3</P>
<DT><B>&amp;plus   (+)</B><DD>
<P>plus sign</P>
<DT><B>&amp;plusmn (&plusmn;)</B><DD>
<P>plus-or-minus sign</P>
<DT><B>&amp;lt     (&lt;)</B><DD>
<P>less-than sign</P>
<DT><B>&amp;equals (=)</B><DD>
<P>equals sign</P>
<DT><B>&amp;gt     (&gt;)</B><DD>
<P>greater-than sign</P>
<DT><B>&amp;divide (&divide;)</B><DD>
<P>division sign</P>
<DT><B>&amp;times  (&times;)</B><DD>
<P>multiplication sign</P>
<DT><B>&amp;curren (&curren;)</B><DD>
<P>currency symbol</P>
<DT><B>&amp;pound  (£)</B><DD>
<P>symbol for ``pounds''</P>
<DT><B>&amp;dollar ($)</B><DD>
<P>dollar sign</P>
<DT><B>&amp;cent   (&cent;)</B><DD>
<P>cent sign</P>
<DT><B>&amp;yen    (&yen;)</B><DD>
<P>yen sign</P>
<DT><B>&amp;num    (#)</B><DD>
<P>number or hash sign</P>
<DT><B>&amp;percnt (%)</B><DD>
<P>percent sign</P>
<DT><B>&amp;amp    (&amp;)</B><DD>
<P>ampersand</P>
<DT><B>&amp;ast    (*)</B><DD>
<P>asterisk</P>
<DT><B>&amp;commat (@)</B><DD>
<P>commercial-at sign</P>
<DT><B>&amp;lsqb   ([)</B><DD>
<P>left square bracket</P>
<DT><B>&amp;bsol   (\)</B><DD>
<P>backslash</P>
<DT><B>&amp;rsqb   (])</B><DD>
<P>right square bracket</P>
<DT><B>&amp;lcub   ({)</B><DD>
<P>left curly brace</P>
<DT><B>&amp;horbar (&horbar;)</B><DD>
<P>horizontal bar</P>
<DT><B>&amp;verbar (|)</B><DD>
<P>vertical bar</P>
<DT><B>&amp;rcub   (})</B><DD>
<P>right curly brace</P>
<DT><B>&amp;micro  (&micro;)</B><DD>
<P>greek mu (micro prefix)</P>
<DT><B>&amp;ohm    (&ohm;)</B><DD>
<P>greek capital omega (Ohm sign)</P>
<DT><B>&amp;deg    (&deg;)</B><DD>
<P>small superscript circle sign (degree sign)</P>
<DT><B>&amp;ordm   (&ordm;)</B><DD>
<P>masculine ordinal</P>
<DT><B>&amp;ordf   (&ordf;)</B><DD>
<P>feminine ordinal</P>
<DT><B>&amp;sect   (&sect;)</B><DD>
<P>section sign</P>
<DT><B>&amp;para   (&para;)</B><DD>
<P>paragraph sign</P>
<DT><B>&amp;middot (&middot;)</B><DD>
<P>centered dot</P>
<DT><B>&amp;larr   (&lt;-)</B><DD>
<P>left arrow</P>
<DT><B>&amp;rarr   (-&gt;)</B><DD>
<P>right arrow</P>
<DT><B>&amp;uarr   (-^)</B><DD>
<P>up arrow</P>
<DT><B>&amp;darr   (-v)</B><DD>
<P>down arrow</P>
<DT><B>&amp;copy   (&copy;)</B><DD>
<P>copyright</P>
<DT><B>&amp;reg    (&reg;)</B><DD>
<P>r-in-circle marl</P>
<DT><B>&amp;trade  ((TM))</B><DD>
<P>trademark sign</P>
<DT><B>&amp;brvbar (&brvbar;)</B><DD>
<P>broken vertical bar</P>
<DT><B>&amp;not    (&not;)</B><DD>
<P>logical-negation sign</P>
<DT><B>&amp;sung   (&sung;)</B><DD>
<P>sung-note sign</P>
<DT><B>&amp;excl   (!)</B><DD>
<P>exclamation point</P>
<DT><B>&amp;iexcl  (&iexcl;)</B><DD>
<P>inverted exclamation point</P>
<DT><B>&amp;quot   (&#34;)</B><DD>
<P>double quote</P>
<DT><B>&amp;apos   (')</B><DD>
<P>apostrophe (single quote)</P>
<DT><B>&amp;lpar   (()</B><DD>
<P>left parenthesis</P>
<DT><B>&amp;rpar   ())</B><DD>
<P>right parenthesis</P>
<DT><B>&amp;comma  (,)</B><DD>
<P>comma</P>
<DT><B>&amp;lowbar (_)</B><DD>
<P>under-bar</P>
<DT><B>&amp;hyphen (-)</B><DD>
<P>hyphen</P>
<DT><B>&amp;period (.)</B><DD>
<P>period</P>
<DT><B>&amp;sol    (/)</B><DD>
<P>solidus</P>
<DT><B>&amp;colon  (:)</B><DD>
<P>colon</P>
<DT><B>&amp;semi   (;)</B><DD>
<P>semicolon</P>
<DT><B>&amp;quest  (?)</B><DD>
<P>question mark</P>
<DT><B>&amp;iquest (&iquest;)</B><DD>
<P>interrobang</P>
<DT><B>&amp;laquo  (&laquo;)</B><DD>
<P>left guillemot</P>
<DT><B>&amp;raquo  (&raquo;)</B><DD>
<P>right guillemot</P>
<DT><B>&amp;lsquo  (&lsquo;)</B><DD>
<P>left single quote</P>
<DT><B>&amp;rsquo  (&rsquo;)</B><DD>
<P>right single quote</P>
<DT><B>&amp;ldquo  (&ldquo;)</B><DD>
<P>left double quote</P>
<DT><B>&amp;rdquo  (&rdquo;)</B><DD>
<P>right double quote</P>
<DT><B>&amp;nbsp   (&nbsp;)</B><DD>
<P>non-breaking space</P>
<DT><B>&amp;shy    (&shy;)</B><DD>
<P>soft hyphen</P>
</DL>
</P>

<H2><A NAME="ss3.3">3.3</A> <A HREF="guide.html#toc3.3">Verbatim and Code Environments</A>
</H2>

<P>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 
<CODE>verb</CODE> element is used for this; it looks like the following:
<BLOCKQUOTE><CODE>
<PRE>
&lt;verb>
 Some literal text to include as example output.
&lt;/verb>
</PRE>
</CODE></BLOCKQUOTE>

The <CODE>verb</CODE> environment doesn't allow you to use <EM>everything</EM>
within it literally.  Specifically, you must do the following within
<CODE>verb</CODE> environments.
<UL>
<LI>Use <CODE>&amp;ero;</CODE> to get an ampersand, </LI>
<LI>Use <CODE>&amp;etago;</CODE> to get <CODE>&lt;/</CODE>,</LI>
<LI>Don't use <CODE>\end{verbatim}</CODE> within a <CODE>verb</CODE>
environment, as this is what LaTeX uses to end the <CODE>verbatim</CODE> 
environment.  (In the future, it should be possible to hide the underlying
text formatter entirely, but the parser doesn't support this feature yet.) </LI>
</UL>

The <CODE>code</CODE> environment is much just like the <CODE>verb</CODE> environment,
except that horizontal rules are added to the surrounding text, as so:
<HR>
<PRE>
Here is an example code environment.
</PRE>
<HR>
</P>
<P>You should use the <CODE>tscreen</CODE> environment around any <CODE>verb</CODE> environments,
as so:
<BLOCKQUOTE><CODE>
<PRE>
&lt;tscreen>&lt;verb>
Here is some example text.  
&lt;/verb>&lt;/tscreen>
</PRE>
</CODE></BLOCKQUOTE>

<CODE>tscreen</CODE> is an environment that simply indents the text and sets the 
sets the default font to <CODE>tt</CODE>.  This makes examples look much nicer, both
in the LaTeX and plain text versions.  You can use <CODE>tscreen</CODE>
without <CODE>verb</CODE>, however, if you use any special characters in your 
example you'll need to use both of them.  <CODE>tscreen</CODE> does nothing to 
special characters.  See <CODE>example.sgml</CODE> for examples.</P>
<P>The <CODE>quote</CODE> environment is like <CODE>tscreen</CODE>, except that it does
not set the default font to <CODE>tt</CODE>.  So, you can use <CODE>quote</CODE> for
non-computer-interaction quotes, as in:
<BLOCKQUOTE><CODE>
<PRE>
&lt;quote>
Here is some text to be indented, as in a quote.
&lt;/quote>
</PRE>
</CODE></BLOCKQUOTE>

which will generate:
<BLOCKQUOTE>
Here is some text to be indented, as in a quote.
</BLOCKQUOTE>
</P>

<H2><A NAME="ss3.4">3.4</A> <A HREF="guide.html#toc3.4">Overall Document Structure</A>
</H2>

<P>Before we get too in-depth with details, we're going to describe the
overall structure of an LinuxDoc-Tools document.  Look at
<CODE>example.sgml</CODE> for a good example of how a document is set up.</P>

<H3>The Preamble</H3>

<P>In the document ``preamble'' you set up things such as the title
information and document style: 
<BLOCKQUOTE><CODE>
<PRE>
&lt;!doctype linuxdoc system>

&lt;article>

&lt;title>Linux Foo HOWTO
&lt;author>Norbert Ebersol, &lt;tt/norb@baz.com/
&lt;date>v1.0, 9 March 1994
&lt;abstract>
This document describes how to use the &lt;tt/foo/ tools to frobnicate
bar libraries, using the &lt;tt/xyzzy/ relinker.
&lt;/abstract>

&lt;toc>
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>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 
<A HREF="guide-6.html#sgml">How LinuxDoc-Tools Works</A>; for
now just treat it as a bit of necessary magic.  The
<CODE>&lt;article></CODE> tag forces the document to use the ``article''
document style.</P>
<P>The <CODE>title</CODE>, <CODE>author</CODE>, and <CODE>date</CODE> tags should be obvious; in the
<CODE>date</CODE> tag include the version number and last modification time of
the document.</P>
<P>The <CODE>abstract</CODE> tag sets up the text to be printed at the top of the
document, <EM>before</EM> the table of contents.  If you're not going to
include a table of contents (the <CODE>toc</CODE> tag), you probably don't
need an <CODE>abstract</CODE>.</P>

<H3>Sectioning And Paragraphs</H3>

<P>After the preamble, you're ready to dive into the document.  The following
sectioning commands are available:
<UL>
<LI><CODE>sect</CODE>: For top-level sections (i.e.  1, 2, and so on.) </LI>
<LI><CODE>sect1</CODE>: For second-level subsections (i.e.  1.1, 1.2, and so on.)</LI>
<LI><CODE>sect2</CODE>: For third-level subsubsections.</LI>
<LI><CODE>sect3</CODE>: For fourth-level subsubsubsections.</LI>
<LI><CODE>sect4</CODE>: For fifth-level subsubsubsubsections.</LI>
</UL>

These are roughly equivalent to their LaTeX counterparts <CODE>section</CODE>,
<CODE>subsection</CODE>, and so on.</P>
<P>After the <CODE>sect</CODE> (or <CODE>sect1</CODE>, <CODE>sect2</CODE>, etc.) tag comes the
name of the section.  For example, at the top of this document, after
the preamble, comes the tag:
<BLOCKQUOTE><CODE>
<PRE>
&lt;sect>Introduction
</PRE>
</CODE></BLOCKQUOTE>

And at the beginning of this section (Sectioning and paragraphs), there
is the tag:
<BLOCKQUOTE><CODE>
<PRE>
&lt;sect2>Sectioning And Paragraphs
</PRE>
</CODE></BLOCKQUOTE>

After the section tag, you begin the body of the section.  However, you
must start the body with a <CODE>&lt;p></CODE> tag, as so:
<BLOCKQUOTE><CODE>
<PRE>
&lt;sect>Introduction
&lt;p>
This is a user's guide to the LinuxDoc-Tools document processing...
</PRE>
</CODE></BLOCKQUOTE>

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,
<BLOCKQUOTE><CODE>
<PRE>
Here is the end of the first paragraph.

And we start a new paragraph here.
</PRE>
</CODE></BLOCKQUOTE>

There is no reason to use <CODE>&lt;p></CODE> tags at the beginning of
every paragraph; only at the beginning of the first paragraph after
a sectioning command.</P>

<H3>Ending The Document</H3>

<P>At the end of the document, you must use the tag:
<BLOCKQUOTE><CODE>
<PRE>
&lt;/article>
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>to tell the parser that you're done with the <CODE>article</CODE> element (which
embodies the entire document).  </P>
<H2><A NAME="cross-ref"></A> <A NAME="ss3.5">3.5</A> <A HREF="guide.html#toc3.5">Internal Cross-References</A>
</H2>

<P>Now we're going to move onto other features of the system.  
Cross-references are easy.  For example, if you want to make a
cross-reference to a certain section, you need to label that section
as so:
<BLOCKQUOTE><CODE>
<PRE>
&lt;sect1>Introduction&lt;label id="sec-intro">
</PRE>
</CODE></BLOCKQUOTE>

You can then refer to that section somewhere in the text using the
expression:
<BLOCKQUOTE><CODE>
<PRE>
See section &lt;ref id="sec-intro" name="Introduction"> for an introduction.
</PRE>
</CODE></BLOCKQUOTE>

This will replace the <CODE>ref</CODE> tag with the section number labeled
as <CODE>sec-intro</CODE>.  The <CODE>name</CODE> argument to <CODE>ref</CODE> 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.  </P>
<P>For example, this section is 
<A HREF="#cross-ref">Cross-References</A>.</P>
<P>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.</P>

<H2><A NAME="ss3.6">3.6</A> <A HREF="guide.html#toc3.6">Web References</A>
</H2>

<P>There is also a <CODE>url</CODE> 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,
<BLOCKQUOTE><CODE>
<PRE>
You can get the Linux HOWTO documents from 
&lt;url url="http://sunsite.unc.edu/mdw/HOWTO/" 
   name="The Linux HOWTO INDEX">.
</PRE>
</CODE></BLOCKQUOTE>

The <CODE>url</CODE> argument specifies the actual URL itself.  A link to the
URL in question will be automatically added to the HTML document.
The optional <CODE>name</CODE> 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 <CODE>name</CODE> argument is given, the
URL itself will be used.</P>
<P>A useful variant of this is <CODE>htmlurl</CODE>, 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
<BLOCKQUOTE><CODE>
<PRE>
&lt;htmlurl url="mailto:esr@snark.thyrsus.com"
      name="esr@snark.thyrsus.com">
</PRE>
</CODE></BLOCKQUOTE>

and get ``esr@snark.thyrsus.com'' in text output rather than the
duplicative ``esr@snark.thyrsus.com &lt;mailto:esr@snark.thyrsus.com&gt;''
but still have a proper URL in HTML documents.</P>

<H2><A NAME="ss3.7">3.7</A> <A HREF="guide.html#toc3.7">Fonts</A>
</H2>

<P>Essentially, the same fonts supported by LaTeX are supported
by LinuxDoc-Tools.  Note, however, that the conversion to 
plain text (through <CODE>groff</CODE>) 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.  </P>
<P>In particular, the <CODE>tt</CODE> 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:
<BLOCKQUOTE><CODE>
<PRE>
Here is some &lt;tt>typewriter text&lt;/tt> to be included in the document.
</PRE>
</CODE></BLOCKQUOTE>

Equivalently:
<BLOCKQUOTE><CODE>
<PRE>
Here is some &lt;tt/typewriter text/ to be included in the document.
</PRE>
</CODE></BLOCKQUOTE>

Remember that you can only use this abbreviated form if the enclosed
text doesn't contain slashes.</P>
<P>Other fonts can be achieved with <CODE>bf</CODE> for <B>boldface</B> and <CODE>em</CODE> 
for <EM>italics</EM>.  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.</P>

<H2><A NAME="ss3.8">3.8</A> <A HREF="guide.html#toc3.8">Lists</A>
</H2>

<P>There are various kinds of supported lists.  They are:
<UL>
<LI><CODE>itemize</CODE> for bulleted lists such as this one.</LI>
<LI><CODE>enum</CODE> for numbered lists.</LI>
<LI><CODE>descrip</CODE> for ``descriptive'' lists.  </LI>
</UL>

Each item in an <CODE>itemize</CODE> or <CODE>enum</CODE> list must be marked
with an <CODE>item</CODE> tag.  Items in a <CODE>descrip</CODE> are marked with <CODE>tag</CODE>.
For example,
<BLOCKQUOTE><CODE>
<PRE>
&lt;itemize>
&lt;item>Here is an item.
&lt;item>Here is a second item.
&lt;/itemize>
</PRE>
</CODE></BLOCKQUOTE>

Looks like this:
<UL>
<LI>Here is an item.</LI>
<LI>Here is a second item.</LI>
</UL>

Or, for an <CODE>enum</CODE>,
<BLOCKQUOTE><CODE>
<PRE>
&lt;enum>
&lt;item>Here is the first item.
&lt;item>Here is the second item.
&lt;/enum>
</PRE>
</CODE></BLOCKQUOTE>

You get the idea.  Lists can be nested as well; see the example document
for details.</P>
<P>A <CODE>descrip</CODE> list is slightly different, and slightly ugly, but
you might want to use it for some situations:
<BLOCKQUOTE><CODE>
<PRE>
&lt;descrip>
&lt;tag/Gnats./ Annoying little bugs that fly into your cooling fan.
&lt;tag/Gnus./ Annoying little bugs that run on your CPU.
&lt;/descrip>
</PRE>
</CODE></BLOCKQUOTE>

ends up looking like:
<DL>
<DT><B>Gnats.</B><DD>
<P>Annoying little bugs that fly into your cooling fan.</P>
<DT><B>Gnus.</B><DD>
<P>Annoying little bugs that run on your CPU.</P>
</DL>
</P>

<H2><A NAME="ss3.9">3.9</A> <A HREF="guide.html#toc3.9">Conditionalization</A>
</H2>

<P>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 &lt;#if&gt; and &lt;#unless&gt;
bracketing tags.</P>
<P>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:
<BLOCKQUOTE><CODE>
<PRE>
Some &lt;#if output=latex2e version=drlinux&gt;conditional&lt;/#if&gt; text.
</PRE>
</CODE></BLOCKQUOTE>

Everything from this &lt;#if&gt; tag to the following &lt;/#if&gt; 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.</P>
<P>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, ``<CODE>linuxdoc -B latex</CODE>'' 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 
<BLOCKQUOTE><CODE>
<PRE>
% linuxdoc -B latex -D version=drlinux foo.sgml
</PRE>
</CODE></BLOCKQUOTE>

or
<BLOCKQUOTE><CODE>
<PRE>
% linuxdoc -B latex foo.sgml
</PRE>
</CODE></BLOCKQUOTE>

would include the ``conditional'' part, but neither
<BLOCKQUOTE><CODE>
<PRE>
% linuxdoc -B html -D version=drlinux foo.sgml
</PRE>
</CODE></BLOCKQUOTE>

nor
<BLOCKQUOTE><CODE>
<PRE>
% linuxdoc -B latex -D private=book foo.sgml
</PRE>
</CODE></BLOCKQUOTE>

would do so.</P>
<P>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:
<BLOCKQUOTE><CODE>
<PRE>
Some &lt;#if output="latex2e|html" version=drlinux&gt;conditional&lt;/#if&gt; text.
</PRE>
</CODE></BLOCKQUOTE>

and formatting with either ``-B latex'' or ``-B html'' will include the
``conditional'' text (but formatting with, say, ``-B txt'' will not).</P>
<P>The &lt;#unless&gt; tag is the exact inverse of &lt;#if&gt;; it
includes when &lt;#if&gt;; would exclude, and vice-versa.</P>
<P>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.  </P>
<P>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 ``<CODE>linuxdoc -B check</CODE>''.</P>
<P>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 &lt;if&gt; or &lt;unless&gt; within a
&lt;verb&gt; environment, or any other kind of bracket that changes
SGML's normal processing of whitespace.</P>
<P>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.</P>

<H2><A NAME="ss3.10">3.10</A> <A HREF="guide.html#toc3.10">Index generation</A>
</H2>

<P>To support automated generation of indexes for book publication of
SGML masters, LinuxDoc-Tools supports the &lt;idx&gt; and &lt;cdx&gt;
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.</P>
<P>The two tags behave identically, except that &lt;idx&gt; sets the
entry in a normal font and &lt;cdx&gt; in a constant-width one.</P>
<P>If you want to add an index entry that shouldn't appear in the text
itself, use the &lt;nidx&gt; and &lt;ncdx&gt; tags.</P>

<H2><A NAME="ss3.11">3.11</A> <A HREF="guide.html#toc3.11">Controlling justification</A>
</H2>

<P>In order to get proper justification and filling of paragraphs in
typeset output, LinuxDoc-Tools includes the &amp;shy; entity.  This
becomes an optional or `soft' hyphen in back ends like latex2e
for which this is neaningful.</P>
<P>The bracketing tag &lt;file&gt; can be used to surround filenames in
running text.  It effectively inserts soft hyphens after each slash in
the filename.</P>
<P>One of the advantages of using the &lt;url&gt; and &lt;htmlurl&gt;
tags is that they do likewise for long URLs.</P>

<HR>
<A HREF="guide-4.html"><IMG SRC="next.png" ALT="Next"></A>
<A HREF="guide-2.html"><IMG SRC="prev.png" ALT="Previous"></A>
<A HREF="guide.html#toc3"><IMG SRC="toc.png" ALT="Contents"></A>
</BODY>
</HTML>
linuxdoc-tools 0.9.72-4build1 / usr / share / doc / linuxdoc-tools / html / guide-3.html
