Writing documentation with DocBook-XML 4.2 |  |
Writing documentation with DocBook-XML 4.2 | |
DocBook is a document type derived from an ISO standard called XML (eXtensible Markup Language). (HTML, used to write World Wide Web pages, is also a markup language, and XML is similar in syntax.) All XML document types use the idea of tags to structure a document.
A tag always starts with < and ends with >. Most tags are used in pairs. The start tag has the form
<tag-name options> |
and the end tag has the form
</tag-name> |
where the tag-name is some name that describes what the tag does. Some tags may also have options that change the way the tag works; some tags have no options.
For example, major sections of a document are always enclosed between <sect1> and </sect1> tags.
Some tags are called “empty” because they are used by themselves, not in pairs. Empty tags must have a forward slash (/) after the tag name. For example, the <colspec/> gives information on a table column (See Section 10). There is no such thing as a </colspec> ending tag.
Here is the basic workflow for the creation and maintenance of a document using DocBook.
Use a validating XML editor or other editor to add the content of your document to the XML file.
Follow the directions given in comments in the skeleton file. You will need to fill in the document's overall title, information on who you (the author) are, and so on.
Once the model is filled in, add the title of the first section where indicated, and begin writing the body of the document. The writing process mainly proceeds by:
Adding XML tags that describe the structure of the document.
Placing the content of the document inside these tags.
To render it into Web form as a group of HTML files, use:
make f.html |
To translate your document into one of the final forms, use the make utility, which is driven by the Makefile you prepared above in setting up your directory for DocBook.
To render into print form using PDF (Adobe Page Description Format) file, use the Unix command:
make f.pdf |
To render into print form using Adobe PostScript, use the Unix command:
make f.ps |
Or just type a make command by itself with no arguments to build all three.