7.1.11. Index

Before you can process your document, you must make sure that index.sgml exists. This is a chicken and egg problem, but it can be solved with the collateindex.pl command:

perl collateindex.pl -N -o index.sgml 

or, as in lyxtox:

$PERL $COLLATEINDEX -N -o index.sgml

The -N option creates a new index; -o indentifies the name of the output file. This name must be the same as the name you specified in the preample (see Section 4.6). The collateindex.pl script is part of the docbook-dsssl-stylesheets package (see Section 3.2). There are a multitude of options to collateindex.pl; see the reference page for more information.

Creating an index is a multi-step, two-pass process (see Automatic Indexing with the DocBook DSSSL Stylesheets):

• In order to create an index, you must first generate the raw index data. This is done with the HTML stylesheet (even if you want print output). That's why in lyxtox we use the same copy of HTML.index which was created with the “no-chunks” HTML stylesheet

  $PERL $COLLATEINDEX -p -g -o index.sgml HTML.index

• After you created the HTML.index file, you can generate your final document as usual using whichever stylesheet is appropriate. The generated document will contain the index:

  • Using sgmltools, as in older versions of lyxtox:

    • For one big HTML file:

      $SGMLTOOLS -b onehtml -s $HTML_NOCHUNKS_DSL -j "-i output.print.png" $1.sgml

      (notice the nochunks option we pass to openjade through sgmltools)

    • For many HTML files (one per chapter/section):

      $SGMLTOOLS -b html -s $HTML_DSL -j "-i output.print.png" $1.sgml

    • and for PDF:

      $SGMLTOOLS -b pdf -s sgmltools-pdf -j "-i output.print.pdf" $1.sgml

  • And using openjade and pdfjadetex as in newer versions:

    • For one big HTML file:

      ${OPENJADE} -t sgml -d $HTML_NOCHUNKS_DSL -i output.print.png -V nochunks $1.sgml > $1.html

    • For many HTML files (one per chapter/section):

      $OPENJADE -t sgml -d $HTML_CHUNKS_DSL -i output.print.png $1.sgml

    • and for PDF:

      ${PDFJADETEX} $1.tex

Tip

Whether an index has to be created or not, can be controlled by setting html-index to "#t" in the stylesheets (see Section 4.2 and Section 7.1.5) as follows (original code is in dbparam.dsl, but it is better not to touch it): (define html-index ;; REFENTRY html-index ;; PURP HTML indexing? ;; DESC ;; Turns on HTML indexing. If true, then index data will be written ;; to the file defined by 'html-index-filename'. This data can be ;; collated and turned into a DocBook index with bin/collateindex.pl. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY #t) Default is false ("#f"). I preferred to let the default untouched and insert the external entity "index" at the end of the document using runsed and sedscr, see Section 7.1.4.1. If you decide to set html-index you will have to comment this in sedscr.

Tip

You can change the name of the file to which index data will be written by setting html-index-filename in the stylesheets (see Section 4.2 and Section 7.1.5) as follows (original code is in dbparam.dsl, but it is better not to touch it): (define html-index-filename ;; REFENTRY html-index-filename ;; PURP Name of HTML index file ;; DESC ;; The name of the file to which index data will be written if ;; 'html-index' is not '#f'. ;; /DESC ;; AUTHOR N/A ;; /REFENTRY "HTML.index") Default is HTML.index. I preferred to let the default untouched. If you decide to set html-index-filename, you will have to adapt lyxtox to reflect the name change.