Book metadata file

The book metadata file supplies information at the topic or book level. The information in this file provides the topic or book title, and determines whether and how the table of contents is processed. It is named with a .book filename suffix, typically topicID.book, and resides in the topic directory with the HTML files.

The syntax for the book file is (optional fields are marked with square brackets):

   topicID:
      Title = topic or book title
      TOCType = fixed | alpha | chapter
      TOCFilename = filename.html
      [Version = arbitrary version number ]
      [PrefaceURL = URL for right frame intro ]

The fields in the book metadata file are:

topicID:

The directory name for the topic or book that also serves as the unique ID for that topic or book.

Title

The title of the topic or book that is displayed in topic or book lists and in search results.

TOCType

A code which indicates how the table of contents should be generated:

alpha

list <TITLE> elements alphabetically

chapter

generate table of contents from chapter files only

fixed

``canned'' table of contents file, so do not regenerate

See ``Processing topic tables of contents''.

TOCFilename

The filename of the table of contents to be used in references to this book.

Version

If more than one .book file is supplied in a directory, the tools use the one with the latest version. The version strings support multiple levels of point releases, and letter modifiers after each.

PrefaceURL

The URL of a topic introductory HTML node. If present, the topic title in the CONTENTS.html file is a hot spot that displays this URL in the right frame.

Processing topic tables of contents

The ODSSI tools enable a table of contents to be updated in the field during a documentation update. There are several styles of contents, each handled differently during updates:

fixed

The table of contents file that ships with the documentation is fixed. It cannot be updated in the field; it can only be replaced in an update. Examples include a structured hierarchical table of contents, or one with section numbering.

alpha

The table of contents is an alphabetical listing of the <TITLE> elements. This is appropriate for man page sections, and certain alphabetical reference material. When the collection of files changes, a new alphabetical listing can be generated.

chapter

The table of contents lists a sequence of chapters. Each of these is a link to its own more detailed chapter table of contents. Because a chapter table of contents can include a nested hierarchy of sections, the tools do not try to update them. An update must include a replacement chapter table of contents where needed. However, chapters can be added, changed, or deleted in the topic's table of contents. The nodes metadata file indicates which files are chapter tables of contents and what sequence they should appear in. For this to work, chapters should not be numbered.

Here is a sample book metadata file:

   AdminNet:
      Title = Administering Networks
      TOCType = chapter
      TOCFilename = CONTENTS.html
      Version = 5.0.3