Introduction to DocBook
- 0
- Add a Comment
- No Related Post
Introduction to DocBook,
Part I
I’ve had a request to cover DocBook, and I figured that you
PENGUINS are the kinds of folks who could easily contribute to the
Linux Documentation Project.
Since DocBook is the format they use, covering it sounds like a
pretty good idea. So, here we go.
DocBook is both an XML and SGML DTD, but I’m only going to focus
on the XML version. With that caveat, it’s safe to say that the
XML DTD is basically a document markup standard written using the
XML ruleset and format. This is a popular and well-supported
format, used in many open source projects within and outside the
Linux realm.
The first thing you’ll need to do is install your Linux
distribution’s DocBook package. Most of them come with one these
days, including Red Hat, which in fact has five different
“docbook” packages with the various components and utilities.
Expect to have to add other items as well for dependencies. I had
to add the Perl SGML module and “jadetex.”
There are a ton of available tutorials and pages devoted to
DocBook. See the Resources section of the LDP Author
Guide for a useful list.
I’m going to walk you through a simple example as an introduction,
and if there’s interest, we can go into this with a more in-depth
look. As with all HTML, XML, and SGML, you start by opening a text
file in your favorite text editor (unless you have a favorite XML
markup tool). I’ll name my file “myfirstdocbook.”
If you’re unfamiliar with XML, think of shell scripts for a
moment. The first line in the document tells Linux what program to
run the remaining document content with. In this case, the first
line is your document declaration, or the line that tells the
DocBook parser what it’s dealing with:
<?xml version="1.0" standalone="no"?>
Next, you need to choose a Document Type Declaration, or DTD. This
tells the parser what DTD it needs to use, obviously the DocBook
one in this case. The current version (as of this writing) of
DocBook is 4.2. According to the DocBook 4.2 DTD:
<!-- This is the driver file for V4.2 of the DocBook DTD.
Please use the following formal public identifier to identify it:
"-//OASIS//DTD DocBook XML V4.2//EN"
For example, if your document's top-level element is Book, and
you are using DocBook directly, use the FPI in the DOCTYPE
declaration:
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[...]>
So, our file now contains:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
Next we have to define the element root, which means what type of document we’re writing
within this particular DTD’s definitions. To make sure I’m using
the latest and greatest, I now check out the information pool
module (referenced in the main DTD) for this version of DocBook,
which has:
pubwork (article
|book
|chapter
|part
|refentry
|section
|journal
|series
|set
|manuscript) #IMPLIED
So, we can choose from article, book,
chapter, part, referentry, section, journal, series, set, or manuscript. Let’s do an article. It’s nice and short. So now we have:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
</article>
This should start to look a little familiar now. In an HTML file,
we start and end with <html>, right? HTML is a subset of SGML just as XML
</html>
is. So now all of the document has to be within these <article> tags.
Articles have their own special format to follow, of course. They
have subsections and other exciting things. Taking a look in the
hierarchy module (as referenced in the DTD and subsequent
modules), I find (some lines edited out for brevity, marked with a
…):
<!-- Article .............................................................. --
...
<!-- An Article is a chapter-level, stand-alone document that is often,
but need not be, collected into a Book. -->
...
<!-- Class: Indicates the type of a particular article;
all articles have the same structure and general purpose.
No default. -->
<!-- ParentBook: ID of the enclosing Book -->
...
<!ATTLIST article
class (journalarticle
|productsheet
|whitepaper
|techreport
|specification
|faq) #IMPLIED
So, which of these classes will our article fall into? I suppose the closest is the journalarticle, so that’s what I’ll
go with here. This makes our document:
<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article class="journalarticle">
</article>
The <article> tag might
start to remind you of the <background> tag in HTML, where you can have
lists of settings in the format setting="value".
… To Be Continued…