Previous Next Contents

3. Writing Documents With Linuxdoc-SGML

For the most part, writing documents using the Linuxdoc-SGML DTD is very simple, and somewhat like LaTeX. However, there are some caveats to watch out for. In this section I'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 I'm just going to discuss the various features of SGML, 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 there are a number of ``tags'' marked within angle brackets (< and >). 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 a LaTeX command such as \item or \section{...}.

As a simple example, to produce this boldfaced text, I typed

As a simple example, to produce <bf>this boldfaced text</bf>, ...
in the source. <bf> begins the region of bold text, and </bf> ends it. Alternately, you can use the abbreviated form
As a simple example, to produce <bf/this boldfaced text/, ...
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 <sect> 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 (example.sgml).

3.2 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: <foo>. In order to get the left angle bracket, you must use the &lt; element, which is a ``macro'' that expands to the actual left-bracket character. Therefore, in the source, I typed

angle brackets around it, as so: <tt>&lt;foo></tt>.
Generally, something beginning with an ampersand is a special macro. For example, there's &percnt; to produce %, &verbar; to produce |, and so on. For all ``special characters'' there exist these ampersanded-entities to represent them.

Usually, you don't need to use the ampersand macro to get a special character, however, in some cases it is necessary. The most commonly used are:

For a complete list of special characters, look at one of the replacement files. Usually LaTeX complains the most about special characters, so paging through $LINUXDOCLIB/rep/latex/general would be a good place to start. $LINUXDOCLIB is defined at the beginning of the SGML conversion scripts.

3.3 Verbatim and Code Environments

While we're on the subject of special characters, I might as well mention the verbatim ``environment'' used for including literal text in the output (with spaces and indentation preserved, and so on). The verb element is used for this; it looks like the following:

<verb>
  Some literal text to include as example output.
</verb>
The verb environment doesn't allow you to use everything within it literally. Specifically, you must do the following within verb environments. The code environment is much just like the verb environment, except that horizontal rules are added to the surrounding text, as so:
Here is an example code environment.

You should use the tscreen environment around any verb environments, as so:

<tscreen><verb>
Here is some example text. 
</verb></tscreen>
tscreen is an environment that simply indents the text and sets the sets the default font to tt. This makes examples look much nicer, both in the LaTeX and plain text versions. You can use tscreen without verb, however, if you use any special characters in your example you'll need to use both of them. tscreen does nothing to special characters. See example.sgml for examples.

The quote environment is like tscreen, except that it does not set the default font to tt. So, you can use quote for non-computer-interaction quotes, as in:

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

3.4 Overall Document Structure

Before we get too in-depth with details, I'm going to describe the overall structure of a document as defined by the Linuxdoc-SGML DTD. Look at example.sgml for a good example of how a document is set up.

The Preamble

In the document ``preamble'' you set up things such as the title information and document style. For a Linux HOWTO document this should look like:

<!doctype linuxdoc system>

<article>

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

<toc>

The elements should go more or less in this order. The first line tells the SGML parser to use the Linuxdoc-SGML DTD. The <article> tag forces the document to use the ``article'' document style. (The original QWERTZ DTD defines ``report'' and ``book'' as well; I haven't tweaked these for use with Linuxdoc-SGML).

The title, author, and date tags should be obvious; in the date tag include the version number and last modification time of the document.

The abstract tag sets up the text to be printed at the top of the document, before the table of contents. If you're not going to include a table of contents (the toc tag), you probably don't need an abstract. I suggest that all Linux HOWTOs use this same format for the preamble, so that the title, abstract, and table of contents are all there and look the same.

Sectioning And Paragraphs

After the preamble, you're ready to dive into the document. The following sectioning commands are available:

These are roughly equivalent to their LaTeX counterparts section, subsection, and so on.

After the sect (or sect1, sect2, etc.) tag comes the name of the section. For example, at the top of this document, after the preamble, comes the tag:

<sect>Introduction
And at the beginning of this section (Sectioning and paragraphs), there is the tag:
<sect2>Sectioning And Paragraphs
After the section tag, you begin the body of the section. However, you must start the body with a <p> tag, as so:
<sect>Introduction
<p>
This is a user's guide to the Linuxdoc-SGML document processing...
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,
Here is the end of the first paragraph.

And we start a new paragraph here.
There is no reason to use <p> tags at the beginning of every paragraph; only at the beginning of the first paragraph after a sectioning command.

Ending The Document

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

</article>

to tell the parser that you're done with the article element (which embodies the entire document).

3.5 Cross-References

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:

<sect1>Introduction<label id="sec-intro">
You can then refer to that section somewhere in the text using the expression:
See section <ref id="sec-intro" name="Introduction"> for an introduction.
This will replace the ref tag with the section number labeled as sec-intro. The name argument to ref is necessary for groff and HTML translations. The groff macro set used by Linuxdoc-SGML 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 Cross-References.

There is also a url 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,

You can get the Linux HOWTO documents from 
<url url="http://sunsite.unc.edu/mdw/HOWTO/" 
     name="The Linux HOWTO INDEX">.
The url argument specifies the actual URL itself. A link to the URL in question will be automatically added to the HTML document. The optional name 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 name argument is given, the URL itself will be used.

For example, you can get the Linuxdoc-SGML package from
ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz.

A useful variant of this is htmlurl, 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

<htmlurl url="mailto:esr@snark.thyrsus.com"
           name="esr@snark.thyrsus.com">
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.

3.6 Fonts

Essentially, the same fonts supported by LaTeX are supported by Linuxdoc-SGML. Note, however, that the conversion to plain text (through groff) does away with the font information. So, you should use fonts as much as possible, 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 tt 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:

Here is some <tt>typewriter text</tt> to be included in the document.
Equivalently:
Here is some <tt/typewriter text/ to be included in the document.
Remember that you can only use this abbreviated form if the enclosed text doesn't contain slashes.

Other fonts can be achieved with bf for boldface and em for italics. Several other fonts are supported as well, but I 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.

3.7 Lists

There are various kinds of supported lists. They are:

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: 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.8 Further Information


Previous Next Contents