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.
The script compiles-sgml is a set of grouped commands. As parameters the name of the document should be passed SGML and the output format expected.
The script version included below supports the 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 fromCygnus™ making the direct conversion. Such tools can be obtained in here.
The list below is available here.
Here is also available a version of collateindex.pl.
Example 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 |
Obviously such script can be modified forming a Makefile, optimizing some functions.
A feature that might be interesting in some cases is the insertion of a summary on the initial page of an article. The DocBook articles does not include it as a standard feature.
To enable this it's necessary to make a modification on the stylesheet file used.
The example below describes the process and it's use is shown in Example 8.
Example 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> |
Although DocBook has markups for the composition of indexes, these are not generated automatically. The tool collateindex.pl allows the 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 8).
Process the document with jade using the style to HTML with the option -V html-index.
Generate the document index.sgml with collateindex.pl.
For the above example to work, it's necessary to define an external entity by calling the file index.sgml.
Example 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 7 for information on how to insert necessary information on the text.
Note: Remember that if you're trying to get Table of Contents or Indexes on PS or PDF output you'll need to run jadetex or pdfjadetex at least three times. This is a TeX requirement and not a DocBook or related application one.
An interesting feature while writing a text is to be able to check if such text will be presentable or not on the final draft. It's common to have several parts of the text marked as drafts, especially when we're updating an already existent document.
DocBook allows along with an entity of parameters to include or not the insertions of specific parts of text in several places on 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 on the final draft.
With the use of parameter entities we can include or eliminate these drafts altering only one line at the beginning of a document.
Example 11. Use of parameter entities
<!entity % review "INCLUDE"> ... <![%review;[ <para>This paragrph 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 11. When the changes on the text are considered final, it's necessary just to remove parts of the text relative to the 3rd. and 6th. lines.
To keep the draft definitions and don't show the text on the final draft, just alter de specification of the entity from INCLUDE to IGNORE.
An important characteristic about the external entities is about the re-using issue of text and documents.
With those characteristics it's possible to create files with text used several times (e.g. licenses and company policies) and simply include those files in the appropriate place.
An example and application of this characteistic was found previously in Example 10. Another example is the SGML code of this HOWTO.
[1] |
More information about indexes are available at the page about index of Norman Walsh. |