Copyright (C) 2000-2012 |
Whole document tree 4. Using DocBookNow that everything is installed, it's time to test it out and see how to use openjade and the other tools.
Figure 1. Example DocBook SGML file - test.sgml
DocBook: The Definitive Guide. http://www.docbook.org/tdg/en/ 4.1. Generating HTML4.1.1. docbook.dsl
Figure 2. Generating HTML output using docbook.dsl
Two htm files are generated, one for each <sect1>. The filenames are not very descriptive. Section one appears on the same page as the article information. These are the results of using the default stylesheet that comes with the Modular DocBook Stylesheets, docbook.dsl. Stylesheets can be customized to improve on these defaults. If you downloaded the Linux Documentation Project's ldp.dsl file and installed it as shown in Section 3.3, then you already have a customized style available. 4.1.2. ldp.dsl
Figure 3. Generating HTML output using ldp.dsl
Using ldp.dsl, the output looks better:
Note how the ldp.dsl file is written in the command line: it has "#html" appended. ldp.dsl contains two <STYLE-SPECIFICATION> elements, one with ID="html" and another with ID="print". This selects the html style from within ldp.dsl. The DocBook DSSSL contains support for converting DocBook files into html and print formats. In Section 3.3, we copied ldp.dsl into both the print and html directories. When generating html output, the html style should be selected like above. When generating other types of files, such as rtf and tex, they fall under the print style and so the print style should be selected from ldp.dsl. The alternative is to comment out or delete the print or html style in the copy of ldp.dsl in the respective directory. If a dsl file has more than one style-spec in it and none is selected like in the example above, then the first style encountered in the file is selected. For ldp.dsl, the print style-spec is first in the file, so it gets selected by default. So in the example above, without appending "#html" when specifying ldp.dsl as the dsssl stylesheet, the "print" style-spec would be selected and used when generating the html output. It will work, but is intended for when selecting the print/ldp.dsl and the formatting will be different. To learn more about how the stylesheet customization files are made, read the documentation for the Modular DocBook Stylesheets. Customization mainly involves setting boolean option parameters to toggle style features on and off. Completely new style logic can be programmed using the the DSSSL language. The openjade option "-t output_type" specifies the output type. The "-d dsssl_spec" option is the path to the dsssl stylesheet to use. In the example above, the output type specified is sgml, which is for SGML to SGML transformations. HTML, defined by the HTML Document Type Definition (DTD), is an SGML document type just as DocBook is, so "sgml" is the correct output_type option. The other two output types commonly used are "rtf" and "tex". The tex output_type will be used later as an intermediate format for the generation of pdf and ps formats. The dsssl_spec must specify a dsl file, not a directory. 4.2. Generating rtf and tex
4.3. Generating dvi and ps
Figure 4. Running jadetex to generate a Device Independent (dvi) file.
The first time jadetex is run, warnings are printed. They can be ignored. Running it a second time, they do not appear again.
Figure 5. Running dvips to generate a PostScript (ps) file.
Figure 6. Running htmldoc to generate a PostScript (ps) file.
4.4. Generating pdf
Figure 7. Running pdfjadetex to generate a Portable Document Format (pdf) file.
Figure 8. Running htmldoc to generate a Portable Document Format (pdf) file.
4.5. Using makeRepeating the commands to generate the output files is tedious. The make command works perfectly to automate the process.
Figure 9. Filename: Makefile - automates document generation.
Usage is just like for most projects: Figure 10. Invoking make to run Makefile
Notice the commented compile rules for pdf and ps which provide alternative means of generating those files. 4.6. Generating a man pageDuring the section on installing everything, we installed the perl version 5 module SGMLS.pm. Then we installed Docbook2X which provides the spec.pl files for transforming DocBook <refentry> documents into nroff (man page) format with sgmlspl. An example Docbook <refentry> document, for the foo command, is given below.
Figure 11. foo command man page, docbook <refentry> source (foo-ref.sgml)
Figure 12. Generating a man page with onsgmls, sgmlspl, and docbook2man-spec.pl
The man page, foo.1, is generated as a Section 1 page. The groff command is used to give a quick look at its formatted appearance. To install this man page, it belongs in any man/man1 directory, where the directory man/ is added to $MANPATH in the environment. The standard location is /usr/local/man/man1. The standard sections in the man pages system are 1 though 9. Each is for holding specific catagories of documentation. Table 1. Manual Pages Sections
Have fun ! |