Trying Out a Sample Doc Book

The best way to understand DocBook is to simply try out a sample file. You can see how the same DocBook file can be used to generate different output formats.

Use a text editor and prepare the file sample.xml with the following lines in it:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"




<title>Sample DocBook</title>


<para>This is a sample DocBook article that illustrates some simple DocBook XML tags. </para> <sect1>

<title>Section 1</title> <para>Paragraph 1 of section 1</para> <sect2>

<title>Section 1.1</title> <para>Paragraph 1 of section 1.1</para> <para>Paragraph 2 of section 1.1</para> </sect2> <sect2>

<title>Section 1.2</title> <para>Paragraph 1 of section 1.2</para> </sect2> </sect1> <sect1>

<title>Section 2</title>

<para>Second high-level section in this article </para> </sect1> </article>

After you save the sample.xml file, you can use the xmllint utility to check if all the XML tags in the file are correct. Type the following command to check the syntax of the sample.xml file:

xmllint --valid --noout sample.xml If everything is okay, the utility should print nothing.

Now, you can convert the sample.xml file into HTML and view it in a Web browser. To perform this task, type the following commands:

export DBS="/usr/share/sgml/docbook/xsl-stylesheets-1.68.1-1"

xsltproc -o sample.html $DBS/html/docbook.xsl sample.xml

The first command defines the DBS environment variable as the directory where the XSL stylesheets for DocBook are located in Fedora Linux. The second command runs xsltproc with appropriate options to convert the sample.xml file into sample.html.

Now, you can open the sample.html file in the Web browser and see how the document looks. Figure 11-7 shows the sample.html file in Firefox.

As Figure 11-7 shows, the DocBook is converted into a single HTML file with a table of contents at the beginning of the document. The table of contents includes links for each section and subsection.

Figure 11-7: Displaying an HTML Version of a Sample DocBook in a Web Browser.

You can also create a set of linked HTML files, one for each section. This is called chunked HTML because each section becomes a chunk. To create chunked HTML files from the sample.xml DocBook, type the following command (I assume that you still have the DBS environment variable defined, as shown earlier in this section):

xsltproc $DBS/html/chunk.xsl sample.xml

This generates an index.html file and separate HTML files for the other chunks (sections). Figure 11-8 shows the HTML chunk for section 2 of the sample DocBook.

The chunked HTML output is widely used for much open source documentation, so Figure 11-8 should look familiar to you. Note that each HTML chunk contains Next, Prev, and Up links to go from section to section and go back to the first page.

Section 2 - Mozilla Firefox

File Edit View Go Book marks Tools Help

^a ' 1 ■ <¿0 ^ ... fila:Whome/nala|H »Go |G,_

BRed Hal, Inc. ¡3 Red Haï Network CjSupjjon Dsiiop C]Prcitlucts DTralrang Scctiou 2


Section 2

Sccood high-level suction in this article Piev

Sample Doc Book Honnc


Figure 11-8: Chunked HTML Version of DocBook.

Was this article helpful?

0 0
Make Money Writing

Make Money Writing

This Report Will Show You How To Make Money By Providing Writing Services To Other Internet Marketers. Learn how to make money by writing the right way. Grab your copy of this report now and learn. Why writing is a great way to earn money. How to compete with cheap writers, even if you charge a lot more money.

Get My Free Ebook

Post a comment