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, 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.
