Tornado Reference : Tornado Utilities

htmlBook

NAME

htmlBook - html Book Index generator

SYNOPSIS

htmlBook [-h] [-nonav] [-noupdate] [-skip dirName] [dirList]

DESCRIPTION

This tool generates the hierarchy of HTML indexes for the HTML manuals within a directory tree. The top-level index is called books.html.

htmlBook reads all linkage files generated by refgen, by htmlLink, or inserted manually, extracts all the book and chapter/section names, then creates the proper indexes.

Each book has a single entry in the top-level index, which points to a book-level index. If the book was not created by refgen, then it is possible to have this link point directly to the book's table of contents. If the book was created by refgen, then there will be a book index, which will have chapter/section entries pointing to chapter/section indexes. These chapter/section indexes then point to the specific entries in the reference manual.

OPTIONS

-h

Display a simple description of htmlBook.

-nonav

Do not create the alphabetic navigation bar at the top of the chapter/section index.

-noupdate

Do not generate new LIB.SUB and RTN.SUB files, just uses any existing ones.

-skip dirName

Do not process the subdirectory dirName. Create no links to or from it. If several directories are to be skipped, then the -skip option must be repeated for each of the directories to be skiped.

NON-REFERENCE DOCUMENTS

In order to generate index links to HTML documents not generated by refgen, a LIB (linkage) file must be associated with the new document (in the same directory as the html index for the document). This file allows htmlBook to generate the appropriate index entries.

This LIB file should contain a single linkage entry. A linkage entry consists of a Tcl list with eight elements ( enclosed in curly braces) defined as follows:

Entry

This field normally represents the name of library. If you are creating a LIB file for an externally generated HTML document, this entry should be the name of the document. This field would normally appear in the chapter/section index, and if the Category field (see below) were not empty, the category name (between square brackets) would be appended to the entry name. For an externally generated HTML document, however, the Chapter Name field (see below) should be empty, and then this name will only be used internally. The Link field (see below) will then be used for the top-level book index.

Short Description

This is a short description of the entry that will appear in the chapter/section index, if present.

Pattern

This field is used only by htmlLink to specify what pattern should be replaced with the text in the Link field (next field) in all HTML files.

Link

This specifies the HTML text to be inserted, after the path is corrected, as the link for the entry. For an external document, this is usually a link to the table of contents of the book. The path in this link should be relative to the LIB file, and should begin with a ./ so that it can be corrected for the actual location of the indexes.

Book Name

For a reference entry, this field specifies the book the library entry belongs to (for example, Tornado Reference or BSP Reference). This field would appear in the top-level index. For an external document, this field is only used internally.

Chapter/Section Name

This field specifies the chapter or section that the entry belongs in. In combination with the Book Name field, this allows two levels of indexes (for example, VxWorks Reference Manual->ANSI Libraries). If there is no chapter name, the Link field will be used (after the path is corrected) in the top-level index.

Category

This field makes it possible to distinguish help entries that have the same name, but belong to different libraries (for example, wtxToolAttach for C, Java or Tcl APIs).

File

This is used by htmlLink to generate the RTN.SUB and LIB.SUB files. The relative path of the LIB file containing this entry is stored in this field. If this field is empty, the LIB file is in the local directory.

EXAMPLE

If the LIB file contains the following line (all on one line) :

{HTMLWorks} {HTMLWorks user's guide} {<b>HTMLWorks</b>} 
{<b><a href="./guide.html">HTMLWorks</a></b>} {Tornado Optional Products}
{HTMLWorks} {} {}

Then the top-level HTML index (book.html) will contain a link named Tornado Optional Products to a book HTML index, and this book index will contain a link to a section named HTMLWorks. If other LIB files have entries with Tornado Optional Products as their book name, the corresponding section names will be listed along with HTMLWorks.

The HTMLWorks section index will then have links for all the LIB file entries that give Tornado Optional Products as their book name, and HTMLWorks as their section name.

To make a direct link from the top-level index and the table of contents of an externally generated HTML document, just provide a LIB file with an ampty chapter name field. The following example will create a Tornado user's guide entry in the top-level (book.html) index, and the link will go directly to path/tug/TUG.html, where :

path

is the directory the LIB file is in,

tug

comes from the Path field, and

TUG.html

is extracted from the Link field

{Tornado user's guide} {The Tornado user's guide}
{<b>Tornado User's Guide</b>}
{<b><a href="./TUG.html">Tornado User's Guide</a></b>}
{Tornado user's guide} {} {} {tug}

Note that the above entry must be on a single line.

FILES

updateDocTime

This is an empty file that fixes the last doc update time. Such a file is generated in each directory in dirList.

books.html

The top-level HTML index, containing all books that htmlBook found. All other index file names are drived from the book or chapter/section names by replacing any non-alphanumeric characters with an underscore.

RETURNS

N/A

ERRORS

N/A

FILES

WIND_BASE/docs/book.html

SEE ALSO

htmlBook, refgen, windHelpLib, htmlLink