4. Getting Started

Using the DocBook DTD to mark up your documentation doesn't require any special tools at all. An SGML file (usually having a .sgml or .sgm filename extension) is actually just a plaintext ASCII file that contains text interspersed with SGML "tags". I strongly recommend that you use your favourite text editor (vi, emacs, notepad, what have you) for doing DocBook markup. It's very important that the files are plaintext ASCII, so using a full-blown wordprocessing system is not only overkill, you might end up creating non-ASCII files. Use a text editor, it's still the best and simplest way.

A document that has been marked up with DocBook looks a lot like HTML in a lot of ways. For example, here's a very simple HTML page:

<html>
<head>
<title>My HTML Page</title>
</head>
<body bgcolor="#000000">
<h1>This is a heading</h1>
<p>
This is the first paragraph of the HTML page.
</p>
<p>
This is the second paragraph of the HTML page.
</p>
</body>
</html>

Markup tags are the things that begin and end with the "<" and ">" brackets. A markup "start" tag, which indicates the beginning of an "element" in the page just has the brackets, while an "end" tag, indicating the end of an element, begins with a "</" combination. Anything contained within a start and end tag of the same type is a complete "element" within the page.

So, what's an "element"? A document element is simply a section of the document that is defined by the tags which contain it. For example, the following is a complete HTML "H1" (heading level 1) element:

<h1>This is a Level 1 Heading</h1>

Elements can contain certain other elements, as defined by the DTD. For example, an HTML "body" element can contain headings, paragraphs, lists, and a wide variety of others. For example:

<body>
<h1>This is a Level 1 Heading</h1>
<p>
Here is a paragraph.
</p>
</body>

You will see that both the "h1" and "p" elements are contained by the "body" element.

The similarities between HTML and DocBook SGML pretty much end here, however. HTML is a markup language that is used primarily to define the formatting or appearance of the page when it is displayed in an HTML browser. HTML is also very informal in terms of how the tags fit together and how strict the tag structure must be.

DocBook SGML, however, is a markup language used to define the structure of a document, rather than its formatting. In DocBook there are no tags that you can use to make an element "bold" or "italic". Instead, you mark up the document by defining _what_ is in each element, rather than how each element should look. Here's a very simple DocBook example:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<article>

   <artheader>
      <title>This is the Article Title</title>
   </artheader>

   <sect1>
      <title>This is a Level 1 Section Title</title>
      <para>
      This is the first paragraph.
      </para>
      <para>
      This is the second paragraph.
      </para>
   </sect1>

</article>

As you can see, there is no formatting information in this document.

The "article" tags tell us that the document is an article. All other elements in the document are contained within this "root" element. The first pair of "title" tags indicate the article title, which is contained in the "artheader" (article header) element. The second set of "title" tags, contained by the "sect1" element, indicate the title of that section.

So, what's that "DOCTYPE" tag at the very beginning? That's the "document type declaration" which is how we define what type of SGML document this is and which DTD we're using for the markup. You don't have to understand the document type declaration, you just have to make sure that it's at the top of all the documents you markup using DocBook. You might have to change the word after "DOCTYPE", depending on what sort of document you're creating: the example is an "article", but you might want to create a "book", a "chapter", a "refentry", or something else.

In terms of the OSWG documentation set, the most common type of document is an "article". Articles include HOWTOs, mini-HOWTOs, magazine articles, papers, and such. An "article" is actually a general class of document that has a certain length and structural complexity. Unless you're doing a manual page ("man" page) or a proper book, chances are that your OSWG document will be an "article".