B.6. Formatting Documents

B.6.1. 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 style sheet file.

<!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>

B.6.2. 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 from the source DocBook for inclusion into the finished/transformed document.

1. Process the document with jade using the style to HTML with the option -V html-index.

   bash$ jade -t sgml \ -d html/docbook.dsl -V html-index document.sgml

2. Generate the index.sgml file with collateindex.pl.

   bash$ perl collateindex.pl \ -o index.sgml HTML.index

For the above example to work, it is necessary to define an external entity by calling the file index.sgml.

<!DOCTYPE article PUBLIC "-//OASIS//DTD
DocBook V3.1//EN" [

<!-- Insertion of the index --> <!entity index SYSTEM
"index.sgml"> ]>
	

See also Section D.4 for information on how to insert necessary information on the text.

	Odd behavior generating indexes for print versions
	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.