# Markup

## Markup: A General Overview

A markup language is a system for marking or tagging a document to define the structure of the document. You may add tags to your document to define which parts of your document are paragraphs, titles, sections, glossary items (the list goes on!). There are many markup languages in use today. XHTML and HTML will be familiar to those who author web documents. The LDP uses a markup language known as DocBook. Each of these markup languages uses its own controlled vocabulary to describe documents. For example: in XHTML a paragraph would be marked up with the tagset <p></p> while in DocBook a paragraph would be marked up with `para` `para`. The tagsets are defined in a quasi dictionary known as a Document Type Definition (DTD).

Markup languages also follow a set of rules on how a document can be assembled. The rules are either SGML (Standard Generalized Markup Language) or XML (eXtensible Markup Language). These rules are essentially the grammar of a document's markup. SGML and XML are very similiar. XML is a sub-set of SGML, but XML requires more precise use of the tags when marking up a document. The LDP accepts both SGML and XML documents, but prefers XML.

There are three components to an XML/SGML document which is read by a person.

- ### Content

  As a TLDP author it is good to remember that this is the most important piece. Many authors will write the content first and add their markup later. Content may include both plain text and graphics. This is the only part that is required of LDP authors!

- ### Markup

  To describe the structure of a document a controlled vocabulary is added on top of the content. It is used to distinguish different kinds of content: paragraphs, lists, tables, warnings (and so on). The markup must also conform to either SGML or XML rules. If you are not comfortable adding markup to your document, a TLDP volunteer will do it for you.

- ### Transformation

  Finally the document is transformed from DocBook to PDF, HTML, PostScript for display in digital or paper form. This transformation is controlled through the Document Style Semantics and Specification Language (DSSSL). The DSSSL tells the program doing the transformation how to convert the raw markup into something that a human can read. The LDP uses a series of scripts to automate these transformations. You are not required to transform your own documents.

### Content, markup and transformations

Steve Champeon does a great job of explaining how content, markup languages, and transformations all fit together in his article The Secret Life of Markup. Although he is writing from an HTML perspective, the ideas are relevant and there is an example of DocBook markup.

## DocBook: What it is and why we use it

According to the official DocBook web site,

> DocBook.org

> DocBook is a general purpose XML and SGML document type particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

### For the impatient

In the next sections we will be explaining about the theoretical side of DocBook, its origins, development, advantages and disadvantages. If you just want the practical side, check out these sections for an overview of HOWTO DocBook: , , and from this guide.

### For the beginner

We wish to stress again the fact that any open document format will be accepted. If you feel more comfortable with plain text, OpenOffice or HTML, that is fine with us. If you do not look forward to learning DocBook, LDP volunteerd will convert your document to DocBook XML. To us, the most important task for our authors is the actual writing, not the formatting, keep that in mind!

From the point of submission onwards, however, you will have to maintain your document in this XML format, but that's a piece of cake. Promised.

Although there are other DTDs used to write documentation, there are a few reasons not to use them.

- DocBook is the most popular DTD, being used by more than a dozen major open source projects from GNOME to Python to FreeBSD.

- The tools for DocBook are more developed than others. DocBook support is included in most Linux distributions, allowing you to send raw files to be processed at the receiver's end.

- And finally, DocBook has an extensive set of tags (over 300 in all) which is very useful when you are trying to describe the content of a document. Fortunately for new authors the majority of them do not need to be used for simple documentation.

Still not convinced? Eric Raymond has written a DocBook Demystification HOWTO which may help.

Convinced, but still not comfortable with the thought of working with DocBook? Give David Lawyer's Howtos-with-LinuxDoc-mini-HOWTO a try.

## XML and SGML: Why we use XML

DocBook comes in a couple of different flavors--including both XML and SGML formats. This means that you may use either the SGML grammar/rules when adding markup, or you may use the XML grammar/rules. Either way you may only use one set of rules throughout your document, and you must define which one you are using at the top of your document.

The LDP prefers the XML flavor of DocBook. There are a number of reasons for this including the following:

1. Libraries for handling XML files are developing at a rapid pace. These utilities may make it easier for new authoring tools to become available.

2. Many popular word processing programs are now creating XML output. While it may not be DocBook XML, this does make it easier for application writers to either add DocBook XML support, or provide some method of translating between their format and DocBook XML.

3. Everyone else is doing it. While this might not be a real reason, it allows the LDP to keep up-to-date with similar projects. Tools, procedures, and issues can be worked out in a common framework.

Still not convinced? Fortunately the LDP does accept a number of other file formats for input. The list of accepted markup languages can be found in

## Markup Languages Accepted by TLDP

&ldp-markup;