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"
<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>
<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:
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.
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
Sccood high-level suction in this article Piev
Sample Doc Book Honnc
Figure 11-8: Chunked HTML Version of DocBook.
Was this article helpful?
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.