4.10. Tools & Hints
The process of producing output and generating indexes is repetitive and error prone. To make things easier, some scripts are included here to facilitate this work. Customize and use them at will.
4.10.1. Compiling the sources
The compiles-sgml script is a set of grouped commands. As parameters, use the SGML file and the output format you want.
The script included below supports the following formats: XML, HTML, TeX, RTF, PS, DVI and mirrored PS, ideal for the creation of photolithographs.
The generation of the indices is made automatically by the script collateindex.pl[1], which should be installed in your system.
Besides the commands below, which generate the outputs in different formats, there are other tools from Cygnus™ for making the direct conversion. The tools can be obtained from Cygnus.
The list below is available here.
Here is also available a version of collateindex.pl.
Example 4-8. Script compiles-sgml
#!/bin/bash
#
# Compile DocBook documents into several output formats.
#
# Godoy.
# 19991230 - Initial release.
# 20000117 - Placed the options using "case" and parameters passed
# via command line. The pages on the Zope are already updated.
# --- Removed to public version (/home/ldp).
# 20000120 - Placed the call to use the books.dtd.
# 20000126 - Placed the commands for the index generation.
#
# If the jade is already installed, disconsider the line bellow.
JADE=/usr/bin/jade
# If the jade package is already installed, disconsider the line bellow.
# JADE=/usr/bin/openjade
DOCUMENT=$1
shift 1
TYPE=$1
. ~/.bash_profile
. ~/.bashrc
case $TYPE in
html)
rm -f *.htm
rm -f *.html
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o index.sgml HTML.index
$JADE -t sgml -i html -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#html $DOCUMENT.sgml
;;
rtf)
rm -f $DOCUMENT.rtf
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
$JADE -t rtf -V rtf-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/books.dsl#print $DOCUMENT.sgml
;;
xml)
rm -f $DOCUMENT.xml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o index.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
$JADE -t sgml -i xml -d /home/ldp/SGML/style/xsl/docbook/html/docbook.xsl $DOCUMENT.sgml
;;
tex)
rm -f $DOCUMENT.tex
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
;;
dvi)
rm -f $DOCUMENT.tex
rm -f $DOCUMENT.dvi
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
jadetex $DOCUMENT.tex
;;
mirror)
rm -f $DOCUMENT.tex
rm -f $DOCUMENT.dvi
rm -f $DOCUMENT.mirror.ps
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
jadetex $DOCUMENT.tex
dvips -h /home/ldp/estilos/skel/mirr.hd -O 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.mirror.ps
;;
ps)
rm -f $DOCUMENT.tex
rm -f $DOCUMENT.dvi
rm -f $DOCUMENT.ps
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -N -o indice.sgml
jade -t sgml -V html-index -d /home/ldp/SGML/style/dsssl/docbook/html/docbook.dsl $DOCUMENT.sgml
perl /home/ldp/SGML/style/dsssl/docbook/bin/collateindex.pl -o indice.sgml HTML.index
$JADE -t tex -V tex-backend -d /home/ldp/SGML/style/dsssl/docbook/print/docbook.dsl -d /home/ldp/SGML/conectiva/livros.dsl#print $DOCUMENT.sgml
jadetex $DOCUMENT.tex
dvips -The 1.5cm,3cm -f $DOCUMENT.dvi -o $DOCUMENT.ps
;;
*)
echo "How to use: $0 file {html|tex|rtf|xml|ps|dvi|mirror}"
exit 1
esac
exit 0
|
A similar script can be modified by creating a Makefile and optimizing some functions.
4.10.2. Inserting a summary on the initial articles page
A feature that might be valuable in some cases is the insertion of the summary on the initial page of an article. DocBook articles do not include it as a standard feature.
To enable this, it is necessary to modify the stylesheet file.
The example below describes the process, and its use is shown in Example 4-8.
Example 4-9. Stylesheet to insert summaries in articles
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!entity html-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
<!entity print-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
]>
<style-sheet>
<style-specification use="html">
<style-specification-body>
; Includes a summary at the beginning of an item.
(define %generate-article-toc% #t)
</style-specification-body>
</style-specification>
<style-specification use="print">
<style-specification-body>
; Includes a summary at the beginning of an item.
(define %generate-article-toc% #t)
</style-specification-body>
</style-specification>
<external-specification id="html" document="html-docbook">
<external-specification id="print" document="print-docbook">
</style-sheet>
|
4.10.3. Inserting indexes automatically
Although DocBook has markups for the composition of them, indexes are not generated automatically. The collateindex.pl command allows indexes to be generated automatically.
The way to use this script is described bellow and a practical example can be seen previously in this document (see Example 4-8).
-
Process the document with jade using the style to HTML with the option -V html-index.
-
Generate the index.sgml file with collateindex.pl.
For the above example to work, it's necessary to define an external entity by calling the file index.sgml.
Example 4-10. Configuring an external entity to include the index
<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!-- Insertion of the index -->
<!entity index SYSTEM "index.sgml">
]>
|
See also Section 4.5 for information on how to insert necessary information on the text.
 |
Remember that if you're trying to get Tables of Contents or Indexes on PS or PDF output you'll need to run jadetex or pdfjadetex at least three times. This is required by TeX but not by DocBook or related applications. |
4.10.4. Making notes on the text while it is being written
An important feature while writing a text is the ability to check whether or not it will be presented in the final draft. It's common to have several parts of the text marked as draft, especially when updating an already existing document.
DocBook allows the insertions of specific parts of text in several places of the document based on the context. Sometimes for an upgrading we need to see how the document looks like or just have sketches of a new session or chapter, but we don't want this sketch to appear in the final draft.
With the use of parameter entities, you can include or eliminate these drafts by altering only one line at the beginning of a document.
Example 4-11. Use of parameter entities
<!entity % review "INCLUDE">
...
<![%review;[
<para>This paragraph will be included on the draft when the entity
"review" is defined with the value "INCLUDE". </para>
]]>
|
The entity review might have several texts defined, as in Example 4-11. When the changes to the text are considered final, you need only to remove parts of the text between the 3rd. and 6th. lines.
To keep the draft definitions and hide the text in the final draft, just alter the specification of the entity from INCLUDE to IGNORE.
4.10.5. Re-using parts of documents
An important feature of external entities is re-using text and documents.
This makes it possible to create files with text that are used several times (e.g. licenses and company policies) or simply include files in the appropriate place.
An example and application of this was used previously in Example 4-10. Another example is the DocBook code of this HOWTO.