Now that everything is installed, it's time to test it out
and see how to use openjade and the other tools.
For a guide to DocBook and a reference of DocBook elements, see:
The warnings about DTDDECL can be ignored. They might be a little annoying,
but these warnings are normal when using openjade. Other warnings and errors
should be looked at and often indicate syntax errors that you should fix.
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.
Using ldp.dsl, the output looks better:
An index file has been created that contains the article information.
A table of contents has been automatically generated.
Each <sect1> is in its own file.
Filenames are derived from ID attributes of the <sect1> elements.
The file extension has changed to html.
The <screen> elements are shaded.
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.
bash$ ls -l
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ openjade -t rtf -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ ls -l
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
|
The first time jadetex is run, warnings are printed. They can
be ignored. Running it a second time, they do not appear again.
If the ps file doesn't appear as expected, it may be due
to bugs in htmldoc. Look inside the ldp_print
script if you want to use it to make ps.
pdfjadetex must be run up to three times to resolve all
internal references for things such as TOC page numbers.
If enabled in the ldp_print script, this would generate a ps file
also.
Repeating the commands to generate the output files is tedious.
The make command works perfectly to automate the process.
Usage is just like for most projects:
Notice the commented compile rules for pdf and ps which
provide alternative means of generating those files.
During 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.
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 Section | Purpose |
---|
man1 | User programs | man2 | System calls | man3 | Library functions and subroutines | man4 | Devices | man5 | File formats | man6 | Games | man7 | Miscellaneous | man8 | System administration | man9 | Kernel internal variables and functions |
| The source file for a man page, like foo-ref.sgml,
can be processed into all the other formats just like any other
DocBook file. So using the same commands discussed earlier to generate
html and print output types, a man page can
be made into html and rtf, tex,
pdf, dvi, and ps.
This can really save a lot of conversion work!
|
Have fun !
|
|