## 3. 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 `example.sgml` 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 `example.sgml` so you have a real live case to refer to.

## 3.1 Basic Concepts

Looking at the source of the example document, you'll notice right off that may not support them. Boldface, typewriter, and italics should be all that you need.

## 3.2 Lists

There are various kinds of supported lists. They are:

- `itemize` for bulleted lists such as this one.
- `enum` for numbered lists.
- `descrip` for ``descriptive'' lists.

Each item in an `itemize` or `enum` list must be marked with an `item` tag. Items in a `descrip` are marked with `tag`. For example,

> `

>     <itemize>
>     <item>Here is an item.
>     <item>Here is a second item.
>     </itemize>

> `

Looks like this:

- Here is an item.
- Here is a second item.

Or, for an `enum`,

> `

>     <enum>
>     <item>Here is the first item.
>     <item>Here is the second item.
>     </enum>

> `

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

A `descrip` list is slightly different, and slightly ugly, but you might want to use it for some situations:

> `

>     <descrip>
>     <tag/Gnats./ Annoying little bugs that fly into your cooling fan.
>     <tag/Gnus./ Annoying little bugs that run on your CPU.
>     </descrip>

> `

ends up looking like:

Gnats.

  Annoying little bugs that fly into your cooling fan.

Gnus.

  Annoying little bugs that run on your CPU.

## 3.3 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:

> `

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

> `

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

> `

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

> `

or

> `

>     % linuxdoc -B latex foo.sgml

> `

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

> `

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

> `

nor

> `

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

> `

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:

> `

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

> `

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

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.

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

## 3.5 Controlling justification

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.

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.