Next Previous Contents

6. How LinuxDoc-Tools Works

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.

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

In SGML jargon, a markup language specification is called a ``DTD'' (Document Type Definition). A DTD allows you to specify the structure 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.

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.

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.

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, thomas.gordon@gmd.de.

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.

6.2 How SGML Works

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

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.

Don't be confused by this analogy. SGML is not a text-formatting system. There is no ``SGML formatter'' per se. SGML source is only 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.

6.3 What Happens When LinuxDoc-Tools Processes A Document

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:

<!element article - -
    (titlepag, header?, 
     toc?, lof?, lot?, p*, sect*, 
     (appendix, sect+)?, biblio?) +(footnote)>

This part sets up the overall structure for an ``article'', which is like a ``documentstyle'' within LaTeX. The article consists of a titlepage (titlepag), an optional header (header), an optional table of contents (toc), optional lists of figures (lof) and tables (lot), any number of paragraphs (p), any number of top-level sections (sect), optional appendices (appendix), an optional bibliography (biblio) and footnotes (footnote).

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 titlepag, header, sect, and other elements are defined.

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 do need to be familiar with the document structure 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.

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.

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 parsed along with the DTD by the SGML parser. LinuxDoc-Tools uses the onsgmls parser in OpenJade, or nsgmls parser in Jade. The former is the successor of the latter. sgmls parser was written by James Clark, jjc@jclark.com, who also happens to be the author of groff. We're in good hands. The parser (onsgmls or nsgmls) 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 sgmlsasp, the next part of the process.

sgmlsasp is responsible for converting the output of sgmls to another format (such as LaTeX). It does this using replacement files, which describe how to convert elements in the original SGML document into corresponding source in the ``target'' format (such as LaTeX or groff).

For example, part of the replacement file for LaTeX looks like: 

<itemize>    +    "\\begin{itemize}   +
</itemize>   +    "\\end{itemize}    +
Which says that whenever you begin an itemize element in the SGML source, it should be replaced with 
\begin{itemize}
in the LaTeX source. (As I said, elements in the DTD are very similar to their LaTeX counterparts).

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.

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

6.4 Further Information

Next Previous Contents