Now 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
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> <article lang="en"> <articleinfo> <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> </articleinfo> <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> |
DocBook: The Definitive Reference. http://www.docbook.org/tdg/html/docbook.html
Figure 2. Generating HTML output using docbook.dsl
bash$ ls -l total 4 -rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml bash$ echo $SGML_SHARE /usr/local/share/sgml bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/docbook.dsl test.sgml openjade:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported [snip - DTDDECL catalog entries are not supported, repeats] openjade:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported bash$ ls -l total 12 -rw-r--r-- 1 reaster users 1885 Dec 31 17:34 t1.htm -rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml -rw-r--r-- 1 reaster users 1544 Dec 31 17:34 x27.htm bash$ |
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.
Figure 3. Generating HTML output using ldp.dsl
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/ldp.dsl#html test.sgml bash$ ls -l total 16 -rw-r--r-- 1 reaster users 2006 Dec 31 18:00 index.html -rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml -rw-r--r-- 1 reaster users 1677 Dec 31 18:00 test1.html -rw-r--r-- 1 reaster users 1598 Dec 31 18:00 test2.html bash$ |
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 DSSSL's Core Programming Language, as mentioned in Section 2.4.
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 |
Figure 4. Running jadetex to generate a Device Independent (dvi) file.
-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 bash$ jadetex test.tex This is TeX, Version 3.14159 (Web2C 7.3.1) (test.tex JadeTeX 1999/06/29: 2.7 (/usr/share/texmf/tex/latex/psnfss/t1ptm.fd) (/usr/share/texmf/tex/jadetex/isoents.tex) Elements will be labelled Jade begin document sequence at 19 No file test.aux. (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd) (/usr/share/texmf/tex/latex/base/ts1cmr.fd) (/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd) (/usr/share/texmf/tex/latex/hyperref/nameref.sty) (/usr/share/texmf/tex/latex/psnfss/t1phv.fd) LaTeX Warning: Reference `TEST1' on page 1 undefined on input line 238. LaTeX Warning: Reference `20' on page 1 undefined on input line 262. LaTeX Warning: Reference `23' on page 1 undefined on input line 285. LaTeX Warning: Reference `TEST2' on page 1 undefined on input line 316. LaTeX Warning: Reference `30' on page 1 undefined on input line 340. LaTeX Warning: Reference `33' on page 1 undefined on input line 363. [1.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) LaTeX Warning: There were undefined references. ) Output written on test.dvi (3 pages, 34984 bytes). Transcript written on test.log. bash$ ls -l total 80 -rw-r--r-- 1 reaster users 771 Dec 31 20:55 test.aux -rw-r--r-- 1 reaster users 34984 Dec 31 20:55 test.dvi -rw-r--r-- 1 reaster users 5072 Dec 31 20:55 test.log -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 bash$ jadetex test.tex This is TeX, Version 3.14159 (Web2C 7.3.1) (test.tex JadeTeX 1999/06/29: 2.7 (/usr/share/texmf/tex/latex/psnfss/t1ptm.fd) (/usr/share/texmf/tex/jadetex/isoents.tex) Elements will be labelled Jade begin document sequence at 19 (test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd) (/usr/share/texmf/tex/latex/base/ts1cmr.fd) (/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd) (/usr/share/texmf/tex/latex/hyperref/nameref.sty) (/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) ) Output written on test.dvi (3 pages, 34148 bytes). Transcript written on test.log. You have new mail in /var/spool/mail/reaster bash$ ls -l total 80 -rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux -rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi -rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log -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 bash$ |
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.
bash$ ls -l total 80 -rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux -rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi -rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log -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 bash$ dvips test.dvi This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com) ' TeX output 2000.12.31:2058' -> test.ps <texc.pro><8r.enc><texps.pro><special.pro><color.pro>. [1] [2] [3] bash$ ls -l total 116 -rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux -rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi -rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log -rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps -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 bash$ |
Figure 6. Running htmldoc to generate a Postscript (ps) file.
bash$ ls -l -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htmldoc.ps - bash$ ls -l -rw-r--r-- 1 reaster users 9050 Jan 1 00:44 test-htmldoc.ps -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$ |
Figure 7. Running pdfjadetex to generate a Portable Document Format (pdf) file.
bash$ ls -l -rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux -rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi -rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log -rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps -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 bash$ pdfjadetex test.tex This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1) (test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg] JadeTeX 1999/06/29: 2.7 (/usr/share/texmf/tex/latex/psnfss/t1ptm.fd) (/usr/share/texmf/tex/jadetex/isoents.tex) Elements will be labelled Jade begin document sequence at 19 (test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd) (/usr/share/texmf/tex/latex/base/ts1cmr.fd) (/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd) (/usr/share/texmf/tex/context/base/supp-pdf.tex (/usr/share/texmf/tex/context/base/supp-mis.tex loading : Context Support Macros / Missing ) loading : Context Support Macros / PDF ) (/usr/share/texmf/tex/latex/hyperref/nameref.sty) (/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )<8r.enc> Output written on test.pdf (3 pages, 9912 bytes). Transcript written on test.log. bash$ ls -l total 128 -rw-r--r-- 1 reaster users 753 Dec 31 21:13 test.aux -rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi -rw-r--r-- 1 reaster users 5075 Dec 31 21:13 test.log -rw-r--r-- 1 reaster users 9912 Dec 31 21:13 test.pdf -rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps -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 bash$ bash$ pdfjadetex test.tex [snip] bash$ pdfjadetex test.tex [snip] |
Figure 8. Running htmldoc to generate a Portable Document Format (pdf) file.
bash$ ls -l -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm bash$ ldp_print test-htmldoc.htm bash$ ls -l -rw-r--r-- 1 reaster users 9050 Jan 1 01:17 test-htmldoc.pdf -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml bash$ |
Repeating 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.
# Generates online and print versions of SGML source file. BASENAME=DocBook-Install # SGML source file. SGML_FILE=$(BASENAME).sgml # Stylesheets DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html # Generated files. HTML_FILE=index.html HTM_FILE=$(BASENAME).htm TEX_FILE=$(BASENAME).tex RTF_FILE=$(BASENAME).rtf PDF_FILE=$(BASENAME).pdf DVI_FILE=$(BASENAME).dvi PS_FILE=$(BASENAME).ps # Build rules. html: $(HTML_FILE) htm: $(HTM_FILE) tex: $(TEX_FILE) rtf: $(RTF_FILE) pdf: $(PDF_FILE) dvi: $(DVI_FILE) ps: $(PS_FILE) all: html htm tex rtf pdf dvi ps clean: rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot} rm -f *.html distclean: clean rm -f $(BASENAME).tgz package: rm -f $(BASENAME).tgz tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME) mv /tmp/$(BASENAME).tgz . dist: clean package distall: all package # Compile rules. $(HTML_FILE): $(SGML_FILE) openjade -t sgml -d $(DSL_HTML) $(SGML_FILE) $(HTM_FILE): $(SGML_FILE) openjade -t sgml -V nochunks -d $(DSL_HTML) \ $(SGML_FILE) > $(HTM_FILE) $(TEX_FILE): $(SGML_FILE) openjade -t tex -d $(DSL_PRINT) $(SGML_FILE) $(RTF_FILE): $(SGML_FILE) openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE) # [pdf]jadetex is run 3 times to resolve references. #$(PDF_FILE): $(TEX_FILE) # pdfjadetex $(TEX_FILE) # pdfjadetex $(TEX_FILE) # pdfjadetex $(TEX_FILE) # This *should* work, but htmldoc has bugs ... #$(PDF_FILE): $(SGML_FILE) # openjade -t sgml -V nochunks -d $(DSL_HTML) \ # $(SGML_FILE) | htmldoc -f $(PDF_FILE) - # Have to use ldp_print to work around htmldoc bugs # ldp_print can also do the ps file - see script $(PDF_FILE): $(HTM_FILE) ldp_print $(HTM_FILE) $(DVI_FILE): $(TEX_FILE) jadetex $(TEX_FILE) jadetex $(TEX_FILE) jadetex $(TEX_FILE) $(PS_FILE): $(DVI_FILE) dvips $(DVI_FILE) #$(PS_FILE): $(SGML_FILE) # openjade -t sgml -V nochunks -d $(DSL_HTML) \ # $(SGML_FILE) | htmldoc -f $(PS_FILE) - |
Usage is just like for most projects:
Figure 10. Invoking make to run Makefile
-- generate html (default) make -- generate just pdf make pdf -- generate all files make all -- delete all generated files make clean -- create tgz distribution -- with no generated files make dist -- create tgz distribution -- containing all generated files make distall |
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 perl5 module SGMLSpm. Then we installed docbook2X which provides the spec.pl files for transforming DocBook RefEntry documents into nroff (manpage) format with sgmlspl.
An example Docbook RefEntry document, for the foo command, is given below.
Figure 11. foo manpage, docbook refentry source (foo-ref.sgml)
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> <refentry> <refentryinfo> <date>2001-01-01</date> </refentryinfo> <refmeta> <refentrytitle> <application>foo</application> </refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo>foo 1.0</refmiscinfo> </refmeta> <refnamediv> <refname> <application>foo</application> </refname> <refpurpose> Does nothing useful. </refpurpose> </refnamediv> <refsynopsisdiv> <refsynopsisdivinfo> <date>2001-01-01</date> </refsynopsisdivinfo> <cmdsynopsis> <command>foo</command> <arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg> <arg><option>-d<replaceable class="parameter">n</replaceable></option></arg> <arg rep="repeat"><replaceable class="parameter">file</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> <refsect1> <refsect1info> <date>2001-01-01</date> </refsect1info> <title>DESCRIPTION</title> <para> <command>foo</command> does nothing useful. </para> </refsect1> <refsect1> <title>OPTIONS</title> <variablelist> <varlistentry> <term>-f <replaceable class="parameter">bar</replaceable></term> <listitem> <para> Takes <filename>bar</filename> as it's run control file. If this were a real program, there might be more to say here about what bar is and how it will be used. </para> </listitem> </varlistentry> <varlistentry> <term>-d<replaceable class="parameter">n</replaceable></term> <listitem> <para> Do something, where integer <replaceable class="parameter">n</replaceable> specifies how many times. </para> </listitem> </varlistentry> <varlistentry> <term><replaceable class="parameter">file...</replaceable></term> <listitem> <para> Processes the files in the order listed, sending all output to stdout. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>USAGE</title> <para> <command>foo</command> -f foo.conf -d2 foodata.foo </para> </refsect1> <refsect1> <title>CAVEATS</title> <para> Other programs named <command>foo</command> may exist and actually do something! </para> </refsect1> <refsect1> <title>BUGS</title> <para> None. Program does nothing. </para> </refsect1> <refsect1> <title>AUTHOR</title> <para> <author> <firstname>Foo</firstname> <othername role="mi">E</othername> <surname>Bar</surname> <contrib>Original author</contrib> </author> </para> </refsect1> </refentry> |
Figure 12. Generating a manpage with onsgmls, sgmlspl, and docbook2man-spec.pl
bash$ ls -l -rw-r--r-- 1 reaster users 2434 Jan 3 03:51 foo-ref.sgml bash$ onsgmls foo-ref.sgml | sgmlspl $SGML_SHARE/docbook2X/docbook2man-spec.pl onsgmls:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported bash$ ls -l -rw-r--r-- 1 reaster users 2434 Jan 3 03:51 foo-ref.sgml -rw-r--r-- 1 reaster users 1129 Jan 3 04:03 foo.1 -rw-r--r-- 1 reaster users 0 Jan 3 04:03 manpage.links -rw-r--r-- 1 reaster users 0 Jan 3 04:03 manpage.log -rw-r--r-- 1 reaster users 15 Jan 3 04:03 manpage.refs bash$ groff -mandoc -Tascii foo.1 FOO(1) FOO(1) NAME foo - Does nothing useful. SYNOPSIS foo [ -f bar ] [ -dn ] [ file... ] DESCRIPTION foo does nothing useful. OPTIONS -f bar Takes bar as its run control file. If this were a real program, there might be more to say here about what bar is and how it will be used. -dn Do something, where integer n specifies how many times. file... Processes the files in the order listed, sending all output to stdout. USAGE foo -f foo.conf -d2 foodata.foo CAVEATS Other programs named foo may exist and actually do some- thing! BUGS None. Program does nothing. AUTHOR Foo E Bar (Original author) [snip - several extra blank lines that man would not show] foo 1.0 2001-01-01 1 bash$ groff -mandoc -Tascii foo.1 | less bash$ less foo.1 |
The manpage, 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 manpage, 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 manpages system are 1 though 9. Each is for holding specific catagories of documentation.
Table 1. Manpage 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 |
Tip: The source file for a manpage, 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 manpage can be made into html and rtf, tex, pdf, dvi, and ps. This can really save a lot of conversion work!
Have fun!