How to get started with Docbook in Red Hat Linux 7.0

For the DocBook dazed and confused

By Phil Jones (pjls16812 at blueyonder.co.uk) with contributions by Richard Poole (richard at ruthie.org).
May 2001

Index

Intro
Setup
Testing
It didn't work!
Links

Intro

You are in a maze of twisty little DocBooks, all alike.

This pretty much summarises my experience of trying to get started writing in DocBook. A lot of the documentation to do with DocBook on the web is written in DocBook and the various DocBook web pages link to each other. Pretty soon I got rather lost.

This document is a getting started beginner guide to DocBook specifically for those using Red Hat Linux 7.0. Unlike other DocBook documents it is refreshingly written in plain old HTML. It is also meant for those that want to use the RPM package management system as much as possible. The version of DocBook supplied with Red Hat Linux 7.0 is DocBook 3.1.

The document covers making an SGML source file and viewing it in HTML, PDF, Postscript and RTF document formats.

What this article doesn't do

This article is only about getting started. I am a DocBook newbie. Please don't ask me about advanced stuff because I really wouldn't have any idea. Apparently DocBook can be done in XML as well as SGML but I don't know about that at all.

Setup

The standard Red Hat 7.0 workstation install has enough to get started. The RPMs required are in the Applications/Publishing and Applications/Text categories. Here is a list. This may not be a complete list, there may be other RPMs required I don't know about.

The magic

docbook. The document type definition. Makes the computer understand the tags in your SGML source file.
stylesheets. The stylesheets convert the DocBook formatting in your source file into a presentation formatted DVI, HTML, PDF, Postscript or RTF output file. The stylesheet takes care of spacing, layout and so on. For example, look at this file:
```
/usr/lib/sgml/stylesheets/nwalsh-modular/html/dbtitle.dsl
```
The file converts DocBook section headings into hypertext <H1> <H2> <H3> <H4> <H5> tags as appropriate. If you wanted to change the appearance of the headings in the hypertext output, you would edit this file.
This package also contains the magical scripts which we will use later. They are db2dvi, db2html, db2pdf, db2ps and db2rtf.

The machinery

openjade. The processor. Your source SGML goes in; a TeX document comes out; the TeX document becomes the format you want.
tetex. The TeX typesetting system.
tetex-fonts. Fonts needed by TeX.
tetex-xdvi. Viewer for device-independent (.dvi) files produced by TeX.
ghostscript. Viewer for Postscript and PDF files.
ghostscript-fonts. Fonts needed by Ghostscript.
sgml-common. Defines special characters such as Greek letters, maths symbols, and box and line drawing.
jadetex. Contains macros for processing Jade TeX output files as LaTeX files.

Please remember this list may not be complete.

Testing

Create a file called 'myfile.sgml'. Enter this text, which is borrowed from the DocBook Install mini howto. This text is slightly modified to suit DocBook version 3.1, whereas the mini howto is for DocBook 4.1.

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

<article lang="en">
<artheader>
	<title>This is a Test</title>

	<author>
		<firstname>John</firstname>
		<surname>Doe</surname>
		<othername role="mi">L</othername>
		<affiliation>
			<address>
			<email>j.doe@jdoe dot com</email>
			</address>
		</affiliation>
	</author>

	<revhistory>
		<revision>
		<revnumber>v1.0</revnumber>
		<date>2000-12-30</date>
		<authorinitials>jld</authorinitials>
		</revision>
	</revhistory>

	<abstract>
	<para>
	This is a test DocBook document.
	</para>
	</abstract>

</artheader>

<sect1 id="test1">
<title>Test 1</title>
<para>
Test section 1.
</para>
	<sect2>
	<title>Test 1.1</title>
	<para>
	Test section 1.1
	</para>
	</sect2>

	<sect2>
	<title>Test 1.2</title>
	<para>
	<screen>
		-- Test section 1.2
		openjade -t sgml -d $DSLFILE test.sgml
	</screen>
	</para>
	</sect2>

</sect1>

<sect1 id="test2">
<title>Test 2</title>
<para>
Test section 2.
</para>

	<sect2>
	<title>Test 2.1</title>
	<para>
	Test section 2.1
	</para>
	</sect2>

	<sect2>
	<title>Test 2.2</title>
	<para>
	Test section 2.2
	</para>
	</sect2>

</sect1>
</article>

Save changes to myfile.sgml.
Enter this command to generate DVI format output:
```
db2dvi myfile.sgml
```
You should see some progress information. This will produce DVI output in TeX format. View the output file with this command:
```
xdvi myfile.dvi
```
You should see something like this:
Next, try this for HTML output:
```
db2html myfile.sgml
```
This will make a folder called 'myfile' with HTML files in it. Here is the output viewed with Netscape:
Here is the command for PDF output:
```
db2pdf myfile.sgml
```
To view the output use this command:
```
ghostview myfile.pdf
```
The Postscript output command is:
```
db2ps myfile.sgml
```
This will produce DVI output in PostScript document text format.
The command for RTF output is:
```
db2rtf myfile.sgml
```
This will produce Rich Text Format output which can be viewed in any word processor. This is what it looks like in AbiWord.

It didn't work!

Sorry, I can't help.