# Building Information Libraries

This chapter discusses how to use `dtdocbook2infolib` subcommands to validate and build your SGML documents into an Information Manager-browsable library and how to update style sheet information in a bookcase.

You use the `dtdocbook2infolib validate` command to validate your SGML book documents and your bookcase specification. Validation is useful during preparation for the build.

You use the `dtdocbook2infolib build` command, which also performs SGML validation, to build a new information library, add a bookcase to an existing information library, and update an existing library.

Once you have built an information library, you can use the `dtdocbook2infolib update` command to update the style sheet information associated with the library. These procedures are covered in:

- Validating Your SGML Documents

- Building, Adding, and Replacing Bookcases in a Library

- Updating Style Sheets in Built Bookcases

See the `dtdocbook2infolib(1)` man page for command syntax and additional examples of these commands.

## Before You Build a New Library

Before you build a new Information Manager information library you need to:

- Specify the method to be used to map external entity references to your system files. You can either:

  - Set the appropriate environment variables for handling external entity references, or

  - Specify the appropriate catalog file using the `-m` option with the `dtdocbook2infolib build` command.

- Check to make sure that you have all of the required SGML-conforming documents, including DTD(s), hypertext TOCs, and style sheet(s) for every book in the bookcase. You can validate your SGML documents using the `dtdocbook2infolib validate` command as described in Running dtdocbook2infolib validate.

- Understand the options that `dtdocbook2infolib build` provides, as described in Building, Adding, and Replacing Bookcases in a Library.

## Setting Environment Variables

Depending on whether you are using the SGML Open Technical Resolution 9401:1994 recommendation for resolving external entity references, you need to set one or both of the following environment variables, or use the `-m` option with the `dtdocbook2infolib` command:

`SGML_CATALOG_FILES`

- Set this environment variable if you follow the SGML Open Technical Resolution 9401:1994 recommendation related to external entity management. The value of this environment variable specifies the location of the file `catalog` or `CATALOG` (you can use either upper-case or lower-case letters) that lists SGML entity declarations and file mapping identifiers.

  If you don't set this environment variable, you can use the `-m` option with the appropriate `dtdocbook2infolib` command to map public identifiers and entity names to system files. See the `catalog(5)` man page for more information.

`SGML_PATH`

- Set this environment variable to map external entity references to system files.

  See the `dtdocbook2infolib(5)` man page for more information.

For related information, see:

- SGML Open Technical Resolution 9401:1994

## Validating Your SGML Documents

Before building an information library, you should validate your SGML documents to ensure that they conform to the appropriate DTD.

You can use the `dtdocbook2infolib validate`
command to perform SGML validation on bookcase specifications, on individual documents, or any other SGML conforming document. During the validation process `dtdocbook2infolib validate`:

- Checks the input document's DTD to verify that it conforms to SGML.

- Verifies that the SGML markup in the input document is consistent with the markup language defined in the document's DTD.

If any documents are found to be invalid, error messages are issued by the `dtdocbook2infolib validate` program. All errors in files used to build an information library must be corrected before the data can be built.

### Running dtdocbook2infolib validate

The basic command line for the following example, which performs validation on a single-bookcase information library, is:

    dtdocbook2infolib validate ch03.sgm ch04.sgm ch05.sgm

where

`ch03.sgm ch04.sgm ch05.sgm`

specifies the SGML documents that are to be validated. The `dtdocbook2infolib validate` command can be run against any valid SGML conforming document.

Error messages are returned if a document is invalid. Here is an example of the type of errors returned against an example file `ch05.sgm`, which contains missing or invalid entity declarations.

    %:  dtdocbook2infolib validate

    nsgmls:ch05.sgm:12:1:E: cannot open "hal.gml" (No such file or directory)
    nsgmls:ch05.sgm:20:1:E: general entity "tab" not defined and no default entity
    ..............................
    ..............................
    ..............................
    dtdocbook2infolib: command failed: nsgmls -sg /usr/dt/infolib/C/SGML/dtinfo.decl ch05.sgm
    ch05.sgm

## Building, Adding, and Replacing Bookcases in a Library

This section describes how you use the `dtdocbook2infolib build` command to build a bookcase into a new information library, add a bookcase to an existing information library, and update the information database in an existing library.

### Build Considerations

You can build information libraries of all sizes, containing any number of books and bookcases. You can have (but are not limited to) information libraries containing:

- A single bookcase consisting of one or more books

- Multiple bookcases, each consisting of one or more books.

When designing an information library, you should give thought to its presentation in the Information Manager and to its reception by readers, many of whom may not be experienced users of on-line documentation.

Information structure and information search capability are among the most important factors in the design of an on-line information library. Readers must be able to easily discern the structure of a book or set of books in a bookcase. In addition, they must be able to find the information they want quickly, through the use of clear hypertext links and through efficient search mechanisms.

#### Library Configuration

The Information Manager has very powerful search capabilities. However, the configuration of your on-line information library affects the efficiency of the search process.

In general, the fewer bookcases you have in an information library, and the fewer books contained in each bookcase, the faster the build process will proceed. This type of information library structure can also be quickly and easily updated.

Unfortunately, as the number of bookcases grows, this type of library structure becomes inefficient in terms of the browser's ability to search its contents for information.

On the other hand, an information library that contains a smaller number of bookcases, each of which contains a relatively large number of books, will take much longer to build and to subsequently update. But search times for this type of library structure will be significantly shorter.

#### Build Space

Before you build an information library, you must ensure that sufficient space is available in the appropriate locations for the build process to succeed.

Upon build completion, an information library takes up about the same amount of space as the source from which it was built. However, during the build process itself, up to three times as much additional space will be required for temporary file storage. This additional space must be allocated as temporary build space, which is automatically removed upon completion of the build. The default location for temporary build space is `/usr/tmp`.

If you find that the disk space available in `/usr/tmp` is less than three times the size of the original document source, you should use the `-T` option with the `dtdocbook2infolib build` command to specify a different location for the temporary build files, or set the `TMPDIR` environment variable.

The current version of the Information Manager has no concurrent-use locking mechanisms to prevent users from attempting to simultaneously build or modify the same information library. Take precautions to ensure that no other `dtdocbook2infolib` or Information Manager processes are accessing the information library when you run the `dtdocbook2infolib build` command. Concurrent use of the `dtdocbook2infolib` commands may cause an Information Manager failure.

## Information Library Organization

When you build an information library, your browser-readable files are organized in the structure depicted in the figure Build Directory Structure.

### Build Directory Structure

The build directory structure shows:

`BC``.dbd`

- This file is the document database for the bookcase `BC`. It contains all compiled text, graphics, and table data.

`BC``.dbi`

- This file contains the index data for bookcase `BC`.

`BC``.sch`

- This file describes the structure of the database.

`dtsearch` directory

- This directory contains all the files related to the full-text search engine.

`bookcase.map`

- This file organizes the bookcases within the library. You use the `dtdocbook2infolib admin` command to modify this file.

`LIB``.oli`

- The string used for `LIB` gives the library its file name.

## Building a New Library

Here is an example of the basic `dtdocbook2infolib build` command line for building a new information library:

    dtdocbook2infolib build -T /k1/local/daver/ -l InfoLib1 DCE.bc INFOMGR.bc PROG.bc

where

`-T` `/k1/local/daver`

- Specifies the directory in which temporary files generated during the build process will be placed.

`-l` `InfoLib1`

- Specifies the name of the directory containing the information library. After the build, `InfoLib1` will contain the three bookcases specified in the command line arguments that follow.

`DCE.bc INFOMGR.bc PROG.bc`

- Specify the file names of your bookcase specification files. Each bookcase specification contains the names of one or more books to be built. You can include as many bookcase specification file names on the command line as you wish.

`dtdocbook2infolib build` converts the documents specified in each of the bookcase specifications into browser-readable format and places them in the newly created information library directory `InfoLib1`.

Assuming the names of the three bookcases (as specified by each bookcase's BOOKCASENAME element) are `DCE`, `INFOMGR`, and `PROG`, respectively, the `InfoLib1` directory now contains the bookcase directories `DCE`, `INFOMGR`, and `PROG`. Each bookcase, in turn, contains the document databases (books) specified by its BOOK element(s).

The figure Creating a New Library depicts the newly built `InfoLib1` library.

### Creating a New Library

## Adding a Bookcase to an Existing Library

In addition to creating a new Information Manager information library, you can also use `dtdocbook2infolib build` to add a bookcase that has not yet been built to an existing information library. In the example below, assume the argument `-l` `InfoLib1` is the name of an existing information library rather than the name of a new information library.

    dtdocbook2infolib build -l InfoLib1 ORA.bc

where

`-l` `InfoLib1`

- is the name of the directory that contains the existing information library.

`ORA.bc`

- is the file name of the bookcase specification file whose contents you are adding to the `InfoLib1` information library. You can include as many bookcase specification names on the command line as you wish.

`dtdocbook2infolib build` converts the book documents in the bookcase specification file `ORA.bc` into browser-readable format and adds them to the existing information library directory `InfoLib1`.

Assuming the name of the added bookcase (as specified by its BOOKCASENAME element) is `ORA`, the `InfoLib1` directory now contains the bookcase directories `DCE`, `INFOMGR`, `PROG`, and `ORA`.

The figure Adding a Bookcase to an Existing Library depicts the revised `InfoLib1` library.

Added bookcases are appended to the existing list of bookcases in the Information Manager Book List. The `dtdocbook2infolib admin` command can be used to rearrange the list after it is built. See the `dtdocbook2infolib(1)` man page.

### Adding a Bookcase to an Existing Library

## Replacing a Bookcase in an Existing Library

In addition to creating information libraries and adding bookcases to existing libraries, you can also replace specified bookcases in a library with the `dtdocbook2infolib build` command. In the example below, the `dtdocbook2infolib build` process is used to rebuild the bookcases `INFOMGR` and `PROG` and to overwrite the existing bookcases of the same name in the `InfoLib1` information library.

    dtdocbook2infolib build -l InfoLib1 INFOMGR.bc PROG.bc

where

`-l` `InfoLib1`

- is the name of the directory that contains the existing information library.

`INFOMGR.bc PROG.bc`

- are the file names of the bookcase specification files whose contents you are rebuilding in order to update the information library `InfoLib1`. You can include as many bookcase specification file names on the command line as you wish.

`dtdocbook2infolib build` rebuilds the books in the bookcase specification files `INFOMGR.bc` and `PROG.bc` and places them in the existing information library directory `InfoLib1`.

The newly built bookcases, whose bookcase names are `INFOMGR` and `PROG` (as specified in the their respective BOOKCASENAME elements), overwrite the existing bookcases that have the same names.

The figure Replacing Bookcases in an Existing Library depicts the revised `InfoLib1` library.

### Replacing Bookcases in an Existing Library

## Updating Style Sheets in Built Bookcases

In Information Manager, you can change the formatting instructions for existing bookcases without rebuilding those databases. This capability gives you great flexibility in the way you handle books whose formatting characteristics must change to meet differing audience or industry requirements.

You use the `dtdocbook2infolib update` command to reformat the books in existing information libraries by updating the style sheet information that controls their formatting.

With `dtdocbook2infolib update` you can revise a style sheet and quickly see the results of your changes, or you can replace one style sheet with another and quickly reformat associated documents.

When you run `dtdocbook2infolib update`, only the documents or document sections affected by the style sheet changes are reformatted.

Before you run `dtdocbook2infolib update` to reformat documents in an information library:

- Ensure that any changes you have made to the style sheet are valid. The `dtdocbook2infolib update` command validates the style sheet file during the update process.

- Set the appropriate environment variables for handling external entity references or specify the appropriate catalog file using the `-m` option when you run `dtdocbook2infolib update`.

Do not run the Information Manager or execute an `dtdocbook2infolib admin` process while updating a style sheet.

### Running dtdocbook2infolib update

The basic command line for the following example, which reformats the documents and/or document sections that use the specified style sheet, is:

    dtdocbook2infolib update -l InfoLib1 -b INFOMGR style1.sty

where

`-l` `InfoLib1`

- Is the name of the directory that contains the existing information library.

`-b` `INFOMGR`

- Is the name of the bookcase (as specified in the its BOOKCASENAME element) that includes the sections that will be reformatted by the specified style sheet.

`style1.sty`

- Is the file name of the style sheet that will be applied during the `dtdocbook2infolib update` process. The style sheet you use must conform to `StyleSheet.dtd` as discussed in Understanding Information Manager Style Sheets.

After running `dtdocbook2infolib update` process you can open the information library using the Information Manager Book List window to see the effect of your changes.

For related information, see:

- the `dtdocbook2infolib(1)` man page

- Creating a Bookcase Specification

- Using Style Sheets

- Understanding Information Manager Style Sheets