Get going
Here is a brutal sequence of steps that will get you started writing DocBook documents.
If you actually want to understand what is going on, you might want to read the chapter called Concepts first and then come back to this chapter.
This chapter will not tell you how to get the tools installed — it is assumed that your system administrator has done that for you. If she or he has not done so, there is an appendix that gives instructions to get DocBook editing and processing tools. There are sections for the section called UNIX in the appendix called Obtaining and installing DocBook tools (with free tools), the section called Win32 in the appendix called Obtaining and installing DocBook tools (with free tools) and the section called FrameMaker+SGML in the appendix called Obtaining and installing DocBook tools.
Hello, world
Here's a simple DocBook document to get going. I will show you how to write this document using explicit element tags, but if you are using an authoring tool that provides a high level interface, just choose the same tags using that interface.
Example 1. Bare bones DocBook document — the source
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
]>
<book>
<bookinfo>
<date>1997-10-11</date>
<title>My first booklet</title>
<subtitle>it even has a subtitle</subtitle>
</bookinfo>
<toc></toc>
<!-- We are done with the preliminaries, now we can start with
the body of the document -->
<chapter>
<title>My first chapter</title>
<para>Here's a paragraph of text because it is stylistically
poor to start a section right after the chapter title.</para>
<sect1>
<title>A section in that first chapter</title>
<para>All I need is a single paragraph of text to make the
section valid.</para>
</sect1>
</chapter>
<appendix>
<title>Remaining details</title>
<para>Although this booklet is quite complete, here I will
mention some details I never got to.</para>
<sect1>
<title>Use of the word dude</title>
<para>Here's an example of how to say
<emphasis>dude</emphasis>: DUDE.</para>
</sect1>
</appendix>
</book>
|
Brief explanation
This example, and the others in this chapter, are meant to get you used to SGML/DocBook markup, but a minimal explanation should be given here.
The first line, with the <!doctype book stuff, is boiler plate. You can ignore it except to note that it says book, and the document then begins with the <book> tag. These must agree.
The special words wrapped with < and > symbols are called tags, and they are used to delimit elements. Elements are structural parts of the the document, like chapters, titles, paragraphs and so forth.
Another feature of interest in this brief document is the fact that the <chapter> and <sect1> have to be followed by a <title> element.
Process and view it
You might be curious to see how your SGML document will be rendered in both a hardcopy–oriented typesetting output, and in online hypertext output.
I will outline the steps you should carry out on UNIX to generate postscript and HTML output using the program jade and the DSSSL stylesheets we use at Cygnus. Assuming your file is called myfile.sgml, you can type the following steps:
Use jade with the transformation DSSSL to convert DocBook to HTML.
$ jade -d /usr/lib/sgml/stylesheets/dbtohtml.dsl -t sgml myfile.sgml > myfile.html
The free tools also provide a utility shell script db2html which does the same. So you can just run:
$ db2html myfile.sgml
Use jade with the real DSSSL to convert DocBook to TeX.
$ jade -d /usr/lib/sgml/stylesheets/docbook.dsl -t tex myfile.sgml > myfile.tex
Use TeX with the jadetex macros to process myfile.tex.
$ jadetex myfile.tex
Use dvips to generate a postscript file from myfile.dvi.
$ dvips myfile.dvi
The steps to create the postscript file can be replaced by:
$ db2ps myfile.sgml
You can now view the HTML file with your favourite browser, and you can print the postscript file, or view it with ghostscript, or its front end gv.