DECdocument
Producing Online and
Printed Documentation
Previous Contents Index

Chapter 10
Diagnosing Errors in a Printed Book

This chapter lists common problems you may encounter when building a book to be printed or displayed on a character-cell terminal.

Problem:

The left margin of your text begins in the left gutter.

Action:

Make sure you have used a <P> tag to mark the beginning of the text element.

Problem:

Your figures and examples do not appear directly after the text that introduces them.

Action:

Use the KEEP argument in <FIGURE_ATTRIBUTES> and <EXAMPLE_ATTRIBUTES> tags.

Problem:

Captions and numbers appear on your tables, figures, and examples and you do not want them to.

Action:

Code your tables, figures, and examples as informal, meaning without arguments to the <TABLE>, <FIGURE>, and <EXAMPLE> tags.

Problem:

Bad breaks occur in a multipage table that has many table units.

Action:

Use the <TABLE_ROW_BREAK>(FIRST) and <TABLE_ROW_BREAK>(LAST) tags to control specific table row breaks. See Table 3-2 for information on using these tags.

Problem:

When processing a document for the MAIL destination, DECdocument issues a fatal message regarding exceeded disk quota. 


 
    -SYSTEM-F-EXDISKQUOTA, disk quota exceeded

Action:

Check to see whether you are out of disk space in your account, or eliminate the KEEP attribute in the <TABLE_ATTRIBUTES>, <FIGURE_ATTRIBUTES>, and <EXAMPLE_ATTRIBUTES>, and <LINE_ART> tags.

Problem:

You get a fatal message about DECdocument not being able to locate certain font files.

Action:

Make sure you are using the correct destination and the proper doctype. Using an online doctype with a destination for printed devices could cause this error.

Problem:

You want a centered heading.

Action:

Use the <CHEAD> tag.

Problem:

A table, figure, example or piece of text does not appear, but DECdocument does not issue any warning messages.

Action:

Make sure that you have not used the <COMMENT> tag around any element that you want to appear. Also, make sure you did not conditionalize elements within your file, and have not specified the /CONDITION qualifier more than once on the DOCUMENT command line. DECdocument only reads the final occurrence of qualifiers on the command line.

Part 3
Processing a Book for Bookreader

 This part describes how to use DECdocument to process a book to be viewed by Bookreader.

Chapter 11
Building and Viewing a Book for Bookreader

This chapter introduces the Bookreader bookshelf file structure. It then explains how to process and view books for Bookreader using SDML files. You can create SDML source files to produce both a Bookreader book and a printed book.

This chapter assumes that you have read Part 2, and understand the following terms:

11.1 Bookshelf File Structure

The Bookreader library is set up to contain book files and bookshelf files. When you use Bookreader to read books, you can select a book or a bookshelf from the main bookshelf library. Selecting a book displays the book in a separate window. Selecting a bookshelf displays the books and bookshelves nested within that bookshelf in the library window.

Figure 11-1 shows a main bookshelf library that Bookreader displays when you invoke it.

Figure 11-1 Bookreader Library Containing Books and Shelves

The LIBRARY.DECW$BOOKSHELF file can contain books as well as other bookshelves, as shown in Figure 11-2.

Figure 11-2 Nesting Bookshelves Under LIBRARY.DECW$BOOKSHELF

Bookshelf files contain the following information:

Bookshelf files can exist anywhere on your system. You can create a bookshelf file within your personal directory and read books from there, or you can read books from a bookshelf file that exists in the system directory. The main system bookshelf file exists in the SYS$COMMON:[DECW$BOOK] directory, when Bookreader is installed on your system. Only a privileged user can copy books into the system bookshelf. When you invoke Bookreader from the DECwindows FileView menu, you will be reading from the system LIBRARY.DECW$BOOKSHELF file. To open a bookshelf from a directory other than the system directory, follow the steps described in Section 11.5.

To create and tailor your bookshelf file structure, use the ONLINE_BOOKSHELF doctype described in Section 11.4.

11.2 Preparing to Build a Bookreader Book

To build a Bookreader book, you need to consider text, tables, figures, examples, indexes, glossaries, footnotes, and the License Management Facility (LMF). You may also need to include special SDML tags. Part 1 of this book explains how to create SDML files for both a printed book and a book displayed by Bookreader. If you have coded your files according to those rules, your Bookreader book should process successfully.

To build a Bookreader book, you must have the following:

  1. Profile
    A profile file specifies all the separate elements (such as chapters, appendixes, a front matter file, an index, and a table of contents) to include in a single book. A profile also determines the order in which these elements will be included. See Section 9.6.2 for more information on the profile file.
    To build your book, process the profile file by specifying it on the DOCUMENT command line.
  2. Front matter
    The front matter must contain at least a <FRONT_MATTER> tag, a <TITLE_PAGE> tag, a <TITLE> tag, and an <ENDTITLE_PAGE> tag.
  3. Symbols and cross-referencing
    You must supply symbol names for the following tags or DECdocument will issue an error-level message, and your bookbuild will not complete:
    DECdocument provides a symbol generator that automatically generates and adds symbol names to tags in SDML files that require symbol names, but do not have any assigned. See Section 4.7 for information on how to use the symbol generator.
    Be sure to check that all <REFERENCE> tag cross-references have the proper symbol name argument.
  4. Figures
    If your book contains figures, they must be identified with the appropriate <FIGURE_FILE> tag. For example: 


     
    <FIGURE_FILE>(BOOKREADER\filename.BRF\5.5)

  5. Formal figures, tables, and examples
    When introducing and cross referencing formal tables, figures, and examples, you must use the <REFERENCE> tag to create hotspots for the user. Otherwise, you can only access the tables, figures, and examples from the table of contents.

    11.3 Book Naming Conventions

    Before you process your Bookreader book, carefully consider the name of the SDML file and the book title.

    Use source file names that identify easily with your book title. Make file names recognizable to other users trying to locate the book file. For example, the source file name DECW_GUIDE.SDML is more precise than the name MY_BOOK.SDML.

    When choosing a title for your book, also consider the positioning of the book title within the Bookreader selection window. Key descriptive information about the book contents should appear first in the title. For example, naming your book "The User Interface Language Reference Manual for VMS DECwindows" puts the important information at the end and probably off the screen in the Bookreader selection window. Naming your book "VMS DECwindows User Interface Language Reference Manual" places the pertinent descriptive information at the beginning of the title and ensures that a viewer can see it without having to scroll to the right or make the window bigger. You can also use the <ONLINE_TITLE> tag in your front matter file immediately before the <TITLE> tag to change the title in the Bookreader title bar and Bookreader library.

    11.4 Building a Bookreader Book

    When you process your book, DECdocument automatically creates two files:

    You can view the book directly from its own bookshelf file, or you can add the book to the LIBRARY.DECW$BOOKSHELF file located in the system library. See Section 11.5 for more information on how to view your book.

    11.4.1 Online Doctypes and Destination for Bookreader

    For books that will be displayed by Bookreader, DECdocument provides these online doctypes:

    When you build a book for Bookreader, use the BOOKREADER destination. See Using Doctypes and Related Tags for more information on the MANUAL.ONLINE, SOFTWARE.ONLINE, and MILSPEC.ONLINE doctypes.

    11.4.2 Building the DECW$BOOK File

    To create a book that can be read by Bookreader, process your book with an online doctype and use the BOOKREADER destination. For example: 


        $ DOCUMENT/INDEX filename.sdml MANUAL.ONLINE BOOKREADER

    You can use qualifiers on the command line to control how processing occurs, which processors will be used, and what portion of a document gets processed. Some of the optional command-line qualifiers include:

    See Section 9.2 and the DECdocument Command Summary in Using Global Tags for more information on the optional command-line qualifiers.

    A Bookreader bookbuild succeeds if it yields no -E- or -F- level errors. If your bookbuild fails, search your LOG or LIS file for these messages. The bookbuild normally completes if DECdocument produces -W- level errors. For example, if all art files are not yet available, you can proceed with viewing the book, even though there may be device converter errors that signify one or more missing figure files.

    11.4.3 Processing an Online Table of Contents

    Navigation through a Bookreader book relies heavily on a table of contents. You can access the entire book, including topics, tables, figures, and examples, by clicking on individual entries within the table of contents. DECdocument automatically generates a table of contents for your Bookreader book.

    If your book will be both printed and displayed by Bookreader, and you have included the <CONTENTS_FILE> tag in your front matter file, make sure that the <CONTENTS_FILE> tag does not appear before the <TITLE_PAGE> tag.

    11.4.4 Processing an Online Index

    To process a Bookreader book with an index, you must include the <INDEX_FILE> tag within the profile file, and use the /INDEX command-line qualifier. You cannot process this file separately as with printed output. See Section 9.8 for more information on processing separate index files for printed output.

    A master index is an index that combines single indexes from several documents to create one master index for a documentation set. You can produce a master index for a printed document, but not for a Bookreader book. See Section 9.8.1 for more information on creating a master index for a printed book.

    11.5 Viewing a Processed Book

    When you have built a Bookreader book, you should have two files (bookname.DECW$BOOK and bookname.DECW$BOOKSHELF). You are then ready to display your book through Bookreader. You can view your book from your private directory, or you can add it to the system library and view it from there. Manipulating the system library requires privileges, so you may have to contact your system manager.

    11.5.1 Viewing a Book from a Private Directory

    You can view your book from a private directory by performing the following steps:

    1. Create a directory and place both the bookname.DECW$BOOK and bookname.DECW$BOOKSHELF files there. For example: 


          $ CREATE/DIRECTORY disk:[ANDERSON.ONLINE_REVIEW]

    2. Define a symbol to run Bookreader. For example: 


          $ BR == "$SYS$SYSTEM:DECW$BOOKREADER"

    3. Invoke Bookreader by supplying the symbol you just created on the command line with the specification of the bookshelf file. Unless you specify the device and directory of the bookshelf file, Bookreader will try to open your file from the default system DECW$BOOK area, which will result in an error. (You can omit the .DECW$BOOKSHELF because it is the default file extension.) 


          $ BR disk:[ANDERSON.ONLINE_REVIEW]bookname.DECW$BOOKSHELF

    11.5.2 Viewing a Book from the System Directory

    To place your finished book in the main system library,¹ follow these steps:

    1. Copy the book and the bookshelf files into the
      SYS$COMMON:[DECW$BOOK] directory. 


          $ COPY disk:[ANDERSON.ONLINE_REVIEW]bookname.DECW$BOOK - 
    _$ SYS$COMMON:[DECW$BOOK]*/LOG 
    $ COPY disk:[ANDERSON.ONLINE_REVIEW]bookname.DECW$BOOKSHELF - 
    _$ SYS$COMMON:[DECW$BOOK]*/LOG

    2. Append the bookshelf file to the library bookshelf file that Bookreader opens first. 


          $ APPEND SYS$COMMON:[DECW$BOOK]bookname.DECW$BOOKSHELF - 
    _$ SYS$COMMON:[DECW$BOOK]LIBRARY.DECW$BOOKSHELF

    3. Invoke Bookreader as you normally do. Your book will be listed in the library.

    11.5.3 Defining the DECW$BOOK Logical

    When VMS DECwindows is installed, the DECW$BOOK logical is defined to refer to the SYS$COMMON:[DECW$BOOK] directory. When you invoke Bookreader, it translates DECW$BOOK and displays the books that exist in the SYS$COMMON:[DECW$BOOK] directory. You can redefine the DECW$BOOK logical to read additional directories (such as on the VMS Online Documentation Library CD).

    To redefine the DECW$BOOK logical to read books located on the CD, follow these steps:

    1. Determine the device name of the CD reader that exists on your system (for example, DUB1). Enter the following command at the DCL prompt¹ : 


          $ DEFINE/SYSTEM DECW$BOOK DUB1:[DECW$BOOK]

    2. Invoke Bookreader to display all the books available on the CD.

    To redefine the DECW$BOOK logical to read books located in the SYS$COMMON:[DECW$BOOK] directory and on the VMS Online Documentation Library CD, follow these steps:

    1. Enter the following command at the DCL prompt: 


          $ DEFINE/SYSTEM DECW$BOOK SYS$COMMON:[DECW$BOOK], DUB1:[DECW$BOOK]

    2. Invoke Bookreader to display all the books available in the SYS$COMMON:[DECW$BOOK] directory and on the CD.

    Note
    For more information on redefining the DECW$BOOK logical, refer to the documentation enclosed in the VMS Online Documentation Library CD.

    Note

    ¹ These steps require system privileges. Contact your system manager.

    11.6 Customizing a Library

    You can customize the Bookreader library structure by creating and processing an SDML file that contains the following special tags:

    For example, you may have numerous books listed on one level in the main bookshelf file that can be grouped together into a few bookshelves, as shown in Figure 11-3.

    Figure 11-3 Bookreader Library Containing Books and Shelves

    To create a customized Bookreader library structure as shown in Figure 11-3, you need to create an SDML file that contains both special customizing tags and their symbol definitions. Or, you can create two SDML files, as shown in Example 11-1 and Example 11-2. The first SDML file contains the special customizing tags. The second SDML file contains the symbol definitions referred to in the first SDML file.

    Example 11-1 Library_Filename.SDML 

     
    <SHELF_CREATE>(vms_sys_mgmt\LIBRARY)
         <BOOK_REF>(using_bookreader\AA-BOOKS-AA)
         <BOOK_REF>(vax_document\AA-LA95A-TE)
 
         <SHELF_REF>(vms_base_docset\VMS_BASE)
 
         <SHELF_CREATE>(vms_decw_usr\VMS_DECW_USER)
              <BOOK_REF>(vms_decw_overview\AA-MG17A-TE)
              <BOOK_REF>(vms_decw_ug\AA-MG18A-TE)
              <BOOK_REF>(vms_decw_desk_app\AA-MG19A-TE)
         <ENDSHELF_CREATE>
 
         <INCLUDE>(vms_system_management.sdml) 
 
         <SHELF_CREATE>(vms_gen_user\VMS_GENERAL_USER)
              <BOOK_REF>(vms_gloss\AA-LA03A-TE)
              <BOOK_REF>(vms_intro\AA-LA04A-TE)
              .
              .
              .
         <ENDSHELF_CREATE>
    <ENDSHELF_CREATE>

    Example 11-2 Symbol_file.SDML to Define Bookshelf Symbols and Titles 

        <DEFINE_SYMBOL>(vms_sys_mgmt\LIBRARY) 
 
    <DEFINE_BOOK_NAME>(using_bookreader\Using the Bookreader) 
    <DEFINE_BOOK_NAME>(vax_document\DECdocument Quick Reference Guide) 
    <DEFINE_BOOK_NAME>(vms_base_docset\VMS Base Documentation Set) 
    <DEFINE_BOOK_NAME>(vms_decw_overview\Overview of VMS DECwindows) 
    <DEFINE_BOOK_NAME>(vms_decw_ug\VMS DECwindows User's Guide) 
    <DEFINE_BOOK_NAME>(vms_decw_desk_app\VMS DECwindows Desktop Applications) 
    <DEFINE_BOOK_NAME>(vms_gloss\VMS Glossary) 
    <DEFINE_BOOK_NAME>(vms_intro\Intro to VMS) 
 
    <DEFINE_SYMBOL>(vms_decw_usr\VMS DECwindows User Documentation) 
    <DEFINE_SYMBOL>(vms_gen_user\VMS General User Subkit)

    Note that in Example 11-2, the first shelf created is the overall library shelf and must be coded with the <DEFINE_SYMBOL> tag. You can group the remaining books and shelves together within the symbols file; their hierarchy is determined by the SDML file containing the bookshelf tags. You must also use the <DEFINE_SYMBOL> tag for book symbols, and the <DEFINE_BOOK_NAME> tag for bookshelf symbols.

    Table 11-1 describes the special tags used to customize a bookshelf. See Using Doctypes and Related Tags for more information on these tags.

    Table 11-1 Tags Used to Customize a Bookshelf
    SDML Tag Description
    <SHELF_CREATE> Creates the overall bookshelf file. You must supply a symbol name argument to the tag to define the shelf title. This symbol name definition will be the actual name of the overall bookshelf. If you do not define the bookshelf symbol name, DECdocument uses the first argument as the title.
    <BOOK_REF> Provides a BOOK entry for a bookshelf file. This entry is a pointer to an existing book file. Do not use the directory or file type unless you are including books or shelves to be stored outside the directory where you are building the customized bookshelf file. You must supply a symbol name and a file name argument to this tag to refer to the title of the book.
    <SHELF_REF> Provides a SHELF entry that refers to an existing bookshelf file that has already been created. You must supply a symbol name and a file name argument to this tag to refer to the title of the book.
    <ENDSHELF_CREATE> Terminates the <SHELF_CREATE> tag.

    To process the Library_Filename.SDML file, use the ONLINE_BOOKSHELF doctype and the BOOKREADER destination as follows: 


        $ DOCUMENT/SYMBOLS=symbol_file.sdml Library_Filename.sdml - 
    _$ ONLINE_BOOKSHELF BOOKREADER

    The output library file is named Library_Filename.DECW$BOOKSHELF. You can access this new library structure (instead of the default system library structure) by creating a symbol to run Bookreader and specifying the newly created library file on the command line. See Section 11.5.1 for more information on creating a symbol to run Bookreader.

    Previous Next Contents Index