# Preparing to Build

Tools in the Information System Toolkit process a number of different SGML files to build documents that are displayable in the Information Manager. This section discusses the files required to build documents with the Information Manager.

## Required Files

To build an Information Manager browsable book, you must supply the following:

- Book Source Document(s) — These SGML-conforming documents contain the text of the book and its SGML markup.

- Table of Contents File — Each Information Manager book requires a hypertext TOC that conforms to `dtinfoTOC.dtd(5)`. You can create the hypertext TOC with the `dtdocbook2infolib tocgen` command.

- Style Sheets — Style sheets govern the formatting of your books. In Information Manager, you can specify style sheet information for both the on-line and printed output of your books. Style sheets must conform to `dtinfoStyle.dtd(5)`.

- Bookcase Specification — The bookcase specification, which conforms to `dtinfoBook.dtd(5)`, contains or makes reference to all of the SGML entities required by the Information Manager during the build process. A bookcase specification can be used to build a single book or a complete Information Manager information library that contains many books.

  Creating a Bookcase Specification describes how you can create this document. An example is shown in Example Bookcase Specification.

## Book Source

At least one conforming SGML document is required for each book in your bookcase. A single SGML document may constitute a complete book or it may be only one of several documents that make up a complete book.

The SGML book source, whether it is one document or several, includes the text (content) of the book and its SGML markup. Through the use of entity references, the document source may also make reference to external text and non-text entities that reside in separate files or external system units.

Entity references cause the specified entities to be embedded at the reference point in the SGML document.

A document type definition (DTD) must be associated with the SGML document source. The DTD defines the structural relationships of elements such as titles, paragraphs, lists, tables, graphics, and so forth.

In most cases the DTD resides outside of the SGML document and is referenced by it, typically in a DOCTYPE declaration at the top of each SGML-conforming document. See the example DOCTYPE Declaration below.

The figure SGML Document Source illustrates the relationship between documents, including hypertext TOCs, and external entities, that can be used to produce an Information Manager book.

### SGML Document Source

An SGML declaration is required by the SGML parser. It specifies the character set and SGML delimiters that are valid for the document instance. `dtinfo.decl(5)` is the SGML declaration used by the Information Manager.

The Information Manager declaration `dtinfo.decl(5)` cannot be substituted or overridden. Therefore, your DTD's element declarations must contain the omitted tag minimization parameter (for example: `“-o” or “--”` ) because the Information Manager SGML declaration has OMITTAG set to YES. For more information, see Element Declaration, in International Standards Organization (ISO) 8879 .

The Information Manager's SGML declaration `dtinfo.decl` is supplied with the Information Manager and is referenced automatically when you invoke the `dtdocbook2infolib build`, `dtdocbook2infolib validate`, or `dtdocbook2infolib update` commands.

### Example DOCTYPE Declaration

    <!DOCTYPE Chapter PUBLIC
    “-//HaL and O'Reilly//DTD DocBook//EN”
    [
    <!ENTITY % ISOlist PUBLIC
     “-//Common Desktop Environment//ENTITIES ISO Catalog//EN”>
     %ISOlist;
     %ISOlat1;
     %ISOnum;
     %ISOpub;
     %ISOtech;
     <!ENTITY % halpubs SYSTEM “hal.gml” >
     %halpubs;
    ]>
    <CHAPTER ID=”CH-1015-3-1” LABEL=”3”><TITLE>Working in the
    X Environment</TITLE>
    <TITLEABBREV>Working in the X Environment</TITLEABBREV>
    <HIGHLIGHTS>
    <PARA>This chapter shows you how to begin working
    productively in the X environment. It describes how to:
    </PARA>
    …

See Related Documentation for a listing of books that describe how to create SGML-conforming documents.

## Table of Contents

Each book you build as part of an Information Manager information library is required to have a hypertext table of contents (TOC). Hypertext links connect the list of section titles in the TOC with the actual on-line sections to which those titles refer.

The TOC is displayed in the Information Manager as the initial entry point to a book. It establishes the default linear path of the book — the path that a reader would take if he or she were reading a hard copy version of the book. When a reader selects (clicks on) a section title in the TOC, the browser traverses the link and displays the on-line section in a reading window.

In the Information Manager, the TOC is also a powerful hypertext navigation tool with important features that help to orient the reader spatially within the on-line document. For example, using information supplied by the TOC, the Information Manager graphical map is able to display the relative locations of sections in the book. And, using the TOC, the Information Manager's Book List window's collapsible book list provides hierarchical information about the book's structure.

In order to set up the hypertext links required in the TOC, the Information Manager must be able to identify sections in your document source. This is done through the application of the Information Manager architectural forms to your book's DTD.

Before you can create a TOC for your book, you must apply Information Manager architectural forms to identify every element in your DTD that is to be referenced as a section in the TOC. This enables Information Manager's table of contents generator to extract the section's title and its unique section ID value. (See Table of Contents Architectural Forms .)

### Creating a Table of Contents

You use the `dtdocbook2infolib tocgen` command to create the TOCs for each of your books.

#### Running dtdocbook2infolib tocgen

Here's an example of using `dtdocbook2infolib tocgen` to generate a table of contents. Before running `dtdocbook2infolib tocgen`, ensure that the book’s source files:

- Contain a DTD or include a reference to a DTD to which the Information Manager architectural forms have been applied.

- Contain valid SGML markup based on the DTD.

The basic `dtdocbook2infolib tocgen` command line for this example is:

    dtdocbook2infolib tocgen -T /usr/pers -f TOC.file -id asg.toc -title “Acoustic Sound Generators” pref.sgm ch01.sgm ch02.sgm ch03.sgm appx.sgm

where

`-T` `/usr/pers`

- Specifies the directory in which temporary files are placed during the build process. The default is to use the environment variable `TMPDIR`. If variable `TMPDIR` is not set, `/usr/tmp` is used.

`-f` `TOC.file`

- Specifies the name of the file to which the output of the `dtdocbook2infolib tocgen` process is sent.

`-id` `asg.toc`

- Specifies the TOC identifier in the newly created TOC file. The alphanumeric string value of `-id`, in this case `asg.toc`, associates the table of contents file with the specific set of book source files for which the TOC was generated. You must use a value that is unique across bookcases in each library.

`-title` `“Acoustic Sound Generators”`

- Specifies the TOC title. The value of `-title`, in this case, `“Acoustic Sound Generators”`, becomes the title of the newly created TOC file.

  The TOC title identifies the table of contents of the book with which it is associated. This name appears as the title of the TOC node when viewed in the Information Manager reading window.

  If you don't use the `-title` flag to supply a name, you may open the TOC file after it is generated and replace the default string `$Title = “Table of Contents”` with the appropriate title.

`pref.sgm` `ch01.sgm` `ch02.sgm` `ch03.sgm` `appx.sgm`

- Specifies the names of the document entities from which the table of contents section title listing will be generated.

  The document entities should be entered on the command line in the order in which their contents should appear in the on-line book.

The `dtdocbook2infolib tocgen` program validates your document entities against their DTDs, verifying that the Information Manager architectural forms have been applied.

After successful validation, `dtdocbook2infolib tocgen` then extracts the list of section titles and section identifiers from the book source files and generates the TOC file.

If you later add or remove sections in any of the book source files, you must regenerate the TOC.

## Using Style Sheets

Style sheets control the formatted appearance of your books in Information Manager. You can use a single style sheet to specify both the on-line display characteristics of your books in the Information Manager as well as the printed output characteristics of your books when printed from the Information Manager.

You can also use a single style sheet to describe how to format multiple documents within a bookcase, or you can use multiple style sheets to process different document types within the same bookcase.

- The figure How Multiple Style Sheets are Used illustrates how books and sections within books can use different style sheets.

- Specifying Style Sheets at Different Levels explains how style sheets can be specified at the bookcase level, at the book level, and at the section level.

- Example Bookcase Using Multiple Style Sheets shows an example bookcase specification that uses four style sheets to provide formatting information for three books.

Once you have built an information database, you can use the `dtdocbook2infolib update`
command to reformat the sections using new style sheet information. See Updating Style Sheets in Built Bookcases.

For information about creating style sheets, see Creating a Style Sheet.

### How Multiple Style Sheets are Used

As shown in the illustration, the default style sheet `Style01` will be used to format all books in a bookcase unless a different style sheet is specified at the book level, or at the section level. When a style sheet other than the default style sheet is specified, it is valid only for formatting the specified book or the section for which it was defined. Processing then continues with the default style sheet unless a different style sheet is again specified.

### Defining Style Sheets

You must define a default style sheet for every bookcase in your Information Manager library (see Creating a Bookcase Specification.)

#### Specifying Style Sheets at Different Levels

Each style sheet must have a unique name, specified at the top of the style sheet document itself. All of the style sheets used in a bookcase can be defined using entity declarations at the top of the bookcase specification. Here is an example of entity declarations for a set of style sheets:

    [
     <!-- Style sheets -->
     <!ENTITY Style01 SYSTEM “InfoMgrRN/style01.sty” >
     <!ENTITY Style02 SYSTEM “Perl/perl.sty” >
     <!ENTITY PrefSty SYSTEM “Preface/pref.sty” >
     <!ENTITY IDXSty SYSTEM “Index/IDX.sty” >
     ...............
     ...............
     ...............
    ]

The declared style sheets are referenced from within the bookcase specification using entity references. Example Bookcase Using Multiple Style Sheets illustrates a complete bookcase specification with all entity declarations and style sheet entity references.

##### Specifying a Style Sheet at the Bookcase Level

The default style sheet is specified at the bookcase level. Entity references are made to any other style sheets that are defined for the bookcase.

The BOOKCASE element start tag begins the listing of the bookcase's contents, including the style sheets that will be used and the SGML document entities that will be processed.

The initial bookcase statement `<BOOKCASE StyleSheet=style01>` names `style01` as the default style sheet. After the BOOKCASENAME and BOOKCASEDESC elements are specified, entity references are made to all style sheet entities that will be used to format the bookcase's contents. For example:

    <BOOKCASE StyleSheet=Style01>
     <BOOKCASENAME>INFOMGR</>
     <BOOKCASEDESC>Info Manager Release Notes</>

     <!-- Include the style sheets. -->

     &Style01;
     &Style02;
     &PrefSty;
     &IDXSty;

The ampersand and semicolon in each of the entity references: `&Style01;`, `&Style02;`, `&PrefSty;`, and `&IDXSty;`are the open and close delimiters for entity references.

##### Specifying a Style Sheet at the Book Level

The default style sheet specified by the BOOKCASE element is used for each book in a bookcase unless a different style sheet is specified at the book level or at the section level.

The BOOK element start tag begins the listing of the book's contents, and refers to the style sheet that will be used (if it is different than the default style sheet). For example:

    </BOOK>

    <!-- Perl Manual -->
    <BOOK StyleSheet=Style02>

This statement specifies that `Style02` will be used to format the Perl Manual SGML source.

After the book's source files are processed, the next BOOK element start tag resets the style sheet to the default style sheet value specified by the initial BOOKCASE element start tag, unless another style sheet is specified.

##### Specifying a Style Sheet at the Section Level

Section-level style sheets are not specified inside the book element listing of the bookcase file. Instead, they are specified in a book's document type definition (DTD) using Information Manager architectural forms. The Information Manager architectural forms identify specific section-level elements in a book to which the formatting characteristics of a specified style sheet will apply.

For related information, see:

- Creating a Style Sheet

- Understanding Architectural Forms

### Example Bookcase Using Multiple Style Sheets

This is an example of a bookcase specification that defines three books and uses four style sheets. The style sheet entities `&PrefSty;` and `&IDXSty;` are referenced in the book DTD(s).

    <!DOCTYPE Bookcase PUBLIC
    “-//Common Desktop Environment//DTD DtInfo Bookcase Description//EN”
    [
     <!-- Style sheets -->
     <!ENTITY style01 SYSTEM “InfoMgrRN/style01.sty” >
     <!ENTITY style02 SYSTEM “Perl/perl.sty” >
     <!ENTITY PrefSty SYSTEM “Preface/pref.sty” >
     <!ENTITY IDXSty SYSTEM “Index/IDX.sty” >
     <!ENTITY TOCSTY SYSTEM “TOC/TOC.sty” >

     <!-- Book documents declared as SUBDOC -->
     <!ENTITY tocfile SYSTEM “Small/small.toc” SUBDOC >
     <!ENTITY ch03 SYSTEM “Small/ch03.sgm” SUBDOC >
     <!ENTITY xlsc SYSTEM “Small/xlsc.sgm” SUBDOC >
     <!ENTITY rnotes.TOC SYSTEM “InfoMgrRN/rnotes.TOC” SUBDOC >
     <!ENTITY rnotes.N SYSTEM “InfoMgrRN/rnotes.N” SUBDOC >
     <!ENTITY perl.TOC SYSTEM “Perl/perl.TOC” SUBDOC >
     <!ENTITY copytrade.N SYSTEM “Perl/copytrade.N” SUBDOC >
     <!ENTITY about.N SYSTEM “Perl/02about.N” SUBDOC >
     <!ENTITY intro.N SYSTEM “Perl/1intro.N” SUBDOC >
     <!ENTITY start.N SYSTEM “Perl/2start.N” SUBDOC >
     <!ENTITY datatypes.N SYSTEM “Perl/3datatypes.N” SUBDOC >
     <!ENTITY form.N SYSTEM “Perl/4form.N” SUBDOC >
     <!ENTITY commands.N SYSTEM “Perl/5commands.N” SUBDOC >
     <!ENTITY perl.NDX SYSTEM “Perl/perl.NDX” SUBDOC >
     <!ENTITY comments.N SYSTEM “Perl/comments.N” SUBDOC >

    ]>
    <BOOKCASE StyleSheet=style01>
     <BOOKCASENAME>Information Manager</>
     <BOOKCASEDESC>Information Manager Release Notes</>

    <!-- Include the four style sheets. -->

     &style01;
     &style02;
     &PrefSty;
     &IDXSty;

    <!-- *****BOOK 1 - Small example book***** -->
    <BOOK>
     <TITLE>DocBook DTD Examples</>
     <SHORTTITLE>SGML Examples</>

     <TAB TabLoc=”RE-1015-XLSCLIENTS-1”>Manpage</>

     <TOCFILE>&tocfile;</TOCFILE>
     <FILE>&ch03;</FILE>
     <FILE>&xlsc;</FILE>
    </BOOK>

    <!-- *****BOOK 2 - Information Manager Release Notes***** -->
    <BOOK>
     <TITLE>Information Manager Release Notes</>
     <SHORTTITLE>Info Manager Notes</>

     <TAB TabLoc=”7M6zf5B0CM9X3cS”>Contents</>
     <TAB TabLoc=”wP3zf5B-BM9X3cS”>Features</>
     <TAB TabLoc=”yP3zf5B-BM9X3cS”>To Do</>
     <TAB TabLoc=”mJ6G0CB1LG9I8gW”>Link Demos</>
     <TAB TabLoc=”0K6zf5B-BM9X3cS”>Figures</>

     <TOCFILE>&rnotes.TOC;</>
     <FILE>&rnotes.N;</>
    </BOOK>

    <!-- *****BOOK 3 - Perl Manual***** -->
    <BOOK StyleSheet=style02>
     <TITLE>Perl Manual</>

     <TAB TabLoc=”Xmhyf5Bu6M9X3cS”>Contents</>
     <TAB TabLoc=”3tpQGzASEYy94aK”>About This Book</>
     <TAB TabLoc=”Oo9fP6B59WwA0YK”>Index</>
     <TAB TabLoc=”DNph.0BBMXwA0YK”>Comments</>

     <TOCFILE>&perl.TOC;</>
     <FILE>&copytrade.N;</>
     <FILE>&about.N;</>
     <FILE>&intro.N;</>
     <FILE>&start.N;</>
     <FILE>&datatypes.N;</>
     <FILE>&form.N;</>
     <FILE>&commands.N;</>
     <FILE>&perl.NDX;</>
     <FILE>&comments.N;</>
    </BOOK>

    </BOOKCASE>

This example bookcase specification conforms to the `dtinfoBook.dtd` distributed with the Information Manager.

## Bookcase Specification

To build a bookcase into an information library, you use a bookcase specification to tell the Information Manager tools what to build.

In its simplest form, the bookcase specification contains the bookcase name and bookcase description, the style sheets that describe the formatting of each book, and the SUBDOC entity references for the SGML documents comprising the books.

You must use SGML SUBDOC entity declarations
to include the book documents in the bookcase specification. The structure of the bookcase specification is defined in `dtinfoBook.dtd`.

A general procedure for producing a bookcase specification is provided in the section Creating a Bookcase Specification.

The information you need to supply in the bookcase specification includes:

Bookcase name

- This name is used by the Information Manager and by the internal search engine. It must be no longer than eight alphanumeric characters and it must be unique within the bookcase.

Bookcase description

- This is a description or synopsis of the book(s) comprising the bookcase. Typical examples might be: UNIX Administration Guides, or Scientific Papers on Acoustic Sound Generation.

One or more style sheets

- Style sheets contain the collection of formatting instructions that define how an SGML document should be formatted both on-line and in print. You must identify one style sheet as the default style sheet for all books in the bookcase specification.

  You can include style sheets in the bookcase specification or you can reference them via an entity declaration at the top of the bookcase specification. See Example Bookcase Specification.

  To understand how the Information Manager handles multiple style sheets in a single bookcase specification, see Using Style Sheets.

  For information about creating style sheets, see Creating a Style Sheet.

One or more books

- The information you need to supply for each book in the bookcase specification includes:

  Book title

- The full title of each book in the bookcase. The length of a book title is technically unlimited. Optimally however, titles should be no longer than 50 characters in length.

Book short title

- An optional abbreviated title for each book. The short title is used by the Information Manager's search engine. Technically, the length of the short title is unlimited, but optimally it should be no more than 20 characters in length.

Tab information

- Tabs are displayed in an Information Manager reading window. They resemble binder tabs and enable readers to move quickly to different sections in an on-line book.

  The tab information you supply in the bookcase specification includes the names and unique identifiers of sections in a book that will be available through the browser interface.

  Tabs are optional and one or more of them may be specified for each book in the bookcase. The length of the text of each tab and the number of tabs in a given book is technically unlimited. However, on-line readability will be improved by using relatively concise tab names such as `Contents`, `Preface`, `Index`, and so forth, and limiting the number of tabs to be displayed.

Table of contents (TOC)

- Each book defined in the bookcase specification must have a hypertext TOC that conforms to the Information Manager `dtinfoTOC.dtd`.

  You can use the `dtdocbook2infolib tocgen` command to produce an Information Manager table of contents. See Creating a Table of Contents.

Book source documents

- These are the SGML-conforming document entities that make up each book.

  Because these documents may conform to different DTDs, you must use SGML SUBDOC entities to pull in the source information during the build process.

The figure Bookcase Specification illustrates the relationship of the bookcase specification and other documents used to build an information library.

### Bookcase Specification

### Creating a Bookcase Specification

To create a bookcase specification:

1. Using a text editor such as `vi`, `emacs`, or an appropriately configured SGML editor, open a new file in your book's build area. If you prefer, you can copy the Example Bookcase Specification below or any example bookcase specification included in this documentation and modify it for your purposes.

2. At the top of the file, specify the bookcase DTD. For example:

       <!DOCTYPE Bookcase PUBLIC
       “-//Common Desktop Environment//DTD DtInfo Bookcase Description//EN”
       [

   The open brace ( [ ) at the end of the DOCTYPE declaration indicates that a set of entity declarations will follow. See the `dtinfoBook.dtd(5)` man page.

3. Using an entity declaration, specify the style sheet to use. You can define multiple style sheets using entity declarations.

       <!-- Style sheets -->
       <!ENTITY style01 SYSTEM “style01.sty” >

4. Using the SGML SUBDOC entity feature, specify the documents that will comprise the book, including the TOC.

       <!-- Book files declared as SUBDOC -->
       <!ENTITY tocfile SYSTEM “small.toc” SUBDOC >
       <!ENTITY ch03 SYSTEM “ch03.sgm” SUBDOC >
       <!ENTITY xlsc SYSTEM “xlsc.sgm” SUBDOC >

5. After specifying all of the entities you will be using, close the entity declaration with a closing brace ( ] ) and a closing declaration delimiter ( > ).

       ]>

6. Enter the SGML start tag <BOOKCASE> and specify the default style sheet to use for the bookcase.

       <BOOKCASE StyleSheet=sty1>

   In this example, the BOOKCASE element's attribute `StyleSheet` is assigned the value `sty1`, which is the name of the STYLESHEET element in the style sheet file `style01.sty`.

   If multiple style sheets are declared in the entity subset declaration, you can specify any one of them as the default style sheet for the bookcase.

7. Enter the BOOKCASENAME and BOOKCASEDESC elements and their contents—in this case `SMALL` and `Demonstration small bookcase`, respectively.

   BOOKCASENAME can be no longer than eight alphanumeric characters, and must not contain periods.

   Next, using an entity reference, specify the style sheet to be included—in this case `style01`.

       <BOOKCASENAME>SMALL</>
       <BOOKCASEDESC>Demonstration small bookcase</>
       &style01;

   After referencing all style sheets for the bookcase, begin specifying the book(s) that make up the bookcase.

   Different style sheets can be assigned to different bookcases, and even to different books within a bookcase using an identifier reference. See Using Style Sheets. For information about creating style sheets, see Creating a Style Sheet.

8. Specify the book to build by entering the BOOK element's start tag, and the TITLE and SHORTTITLE elements and their contents.

       <BOOK>
       <TITLE>DocBook DTD Examples</>
       <SHORTTITLE>SGML Examples</>

9. If you are setting up binder tabs in your book, supply the tab information.

   For each tab, you must specify the TAB element's start tag— which requires the TabLoc attribute and its value—and the text (in this case “Manpage”) that will appear in the tab when it is displayed in the browser.

       <TAB TabLoc=“RE-1015-XLSCLIENTS-1”>Manpage</>

10. Use the <TOCFILE> tag to contain the table of contents document referenced via the SUBDOC entity declaration at the top of the bookcase specification.

        <TOCFILE>&tocfile;</TOCFILE>

11. Use <FILE> tags to contain the book documents referenced via SUBDOC entity declarations at the top of the bookcase specification.

        <FILE>&ch03;</FILE>
        <FILE>&xlsc;</FILE>

    You can also list multiple book documents in a single set of <FILE> tags. For example:

        <FILE>&ch03; &xlsc;</FILE>

12. After all documents are referenced for this book, close this book using the </BOOK> end tag.

        </BOOK>

    Repeat steps 8 thorough 11 for each additional book that is to be included in the bookcase.

13. After all books are specified, close the bookcase specification using the </BOOKCASE> end tag.

        </BOOKCASE>

The complete bookcase example is shown in Example Bookcase Specification.

#### Example Bookcase Specification

This is an example of a small bookcase specification. It defines one bookcase containing a single book and uses a single style sheet.

Although the style sheet in the example below is referenced via an entity reference, the complete text of the style sheet `STYLE01` could be included in the bookcase specification.

    <!DOCTYPE Bookcase PUBLIC
    “-//Common Desktop Environment//DTD DtInfo Bookcase Description//EN”
    [
    <!-- Style sheets -->
    <!ENTITY style01 SYSTEM “style01.sty” >

    <!-- Book files declared as SUBDOC -->
    <!ENTITY tocfile SYSTEM “small.toc” SUBDOC >
    <!ENTITY ch03 SYSTEM “ch03.sgm” SUBDOC >
    <!ENTITY xlsc SYSTEM “xlsc.sgm” SUBDOC >
    ]>
    <BOOKCASE StyleSheet=sty1>
    <BOOKCASENAME>SMALL</>
    <BOOKCASEDESC>Demonstration small bookcase</>
    &style01;

    <BOOK>
    <TITLE>DocBook DTD Examples</>
    <SHORTTITLE>SGML Examples</>

    <!-- Tab information -->
    <TAB TabLoc=”RE-1015-XLSCLIENTS-1”>Manpage</>

    <TOCFILE>&tocfile;</TOCFILE>

    <FILE>&ch03;</FILE>
    <FILE>&xlsc;</FILE>

    </BOOK>

    </BOOKCASE>

This example bookcase specification conforms to the `dtinfoBook.dtd` distributed with the Information Manager.