Online_Documentation_Library________________________ User's Guide This guide describes how to use the Online Documentation Library (ODL). Platforms Supported: OpenVMS Alpha OpenVMS VAX Tru64 UNIX[R] Revision/Update Information: This is an updated document. Compaq Computer Corporation Houston, Texas ________________________________________________________________ June 1999 The optical disc publication and all component parts as appearing herein are copyrighted. Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. The information in this document is subject to change without notice and should not be construed as a commitment by Compaq. Compaq assumes no responsibility for any errors that may appear in this document. © Digital Equipment Corporation 1999. All rights reserved. Compaq, the Compaq logo, and the DIGITAL logo are registered in the U.S. Patent and Trademark Office. The following are trademarks of Compaq Computer Corporation: Alpha, Bookreader, DECnet, DECwindows, DIGITAL, InfoServer, OpenVMS, PATHWORKS, Tru64 UNIX, and VAX. The following are third-party trademarks: DynaText Software is a registered trademark of Electronic Book Technologies. HyperHelp is a trademark of Bristol Technology, Inc. Motif and OSF/1 are registered trademarks of the Open Software Foundation, Inc. Netscape Navigator is a trademark of Netscape Communications Corporation. PostScript is a registered trademark of Adobe Systems, Incorporated. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. All other trademarks and registered trademarks are the property of their respective holders. This document is available on CD-ROM. This document was prepared using VAX DOCUMENT Version 2.1. _________________________________________________________________ Contents Preface................................................... v 1 Setting-up the Tru64 UNIX ODL 1.1 Quick Start................................... 1-1 1.2 Required Environment.......................... 1-2 1.3 Mounting the ODL CD-ROM(s).................... 1-3 1.4 Running the ODL Setup Procedure............... 1-6 1.4.1 Sample Tru64 UNIX Installation Log........ 1-7 1.4.2 If You Do Not Install BNU................. 1-8 2 Setting-up the OpenVMS ODL 2.1 Quick Start................................... 2-1 2.2 System Requirements........................... 2-2 2.2.1 Operating System Requirements............. 2-2 2.2.2 Disk Space Requirements................... 2-3 2.2.3 Required Environments..................... 2-3 2.3 Mounting the ODL CD-ROMs...................... 2-3 2.3.1 Mounting on Systems with a Single CD-ROM Reader.................................... 2-4 2.4 Running the ODL Setup Procedure............... 2-5 2.4.1 If Warnings or Errors are Encountered in Running the ODL Setup Procedure........... 2-7 2.4.2 If You Do Not Install BNU................. 2-8 iii 3 Accessing Information on the ODL 3.1 Running BNU................................... 3-1 3.1.1 Accessing the ODL Across the Network from OpenVMS................................... 3-2 3.2 Searching Book Titles and Content............. 3-3 3.2.1 The Recommended Search Method............. 3-3 3.2.2 How the Search Progresses................. 3-3 3.2.3 Canceling a Search........................ 3-4 4 Extending the ODL 4.1 BNU Initial Default Library................... 4-1 4.2 How BNU Finds the Libraries................... 4-2 4.3 BNU Bookshelf Structure....................... 4-2 iv _________________________________________________________________ Preface This guide provides introductory information about the Online Documentation Library (ODL) and the Bookshelf Navigation Utility (BNU). BNU provides a seamless interface to continued viewing of Bookreader documentation, as well as other industry standard formats and browsers for viewing online information. Contents of This Guide Chapter 1 describes platform-specific information on installing and using the ODL for Tru64 UNIX. Chapter 2 describes platform-specific information on installing and using the ODL for OpenVMS Alpha and OpenVMS VAX. Chapter 3 explains how to access information on the ODL. Chapter 4 explains how to extend the ODL to include Bookreader, HTML, and other files that you have created yourself or have obtained from Compaq or a third party. Providing Feedback Compaq welcomes your comments on its products. To make it easy for you to provide feedback, Compaq has created the following Internet mail account: cdrom_docs@zko.dec.com Use this account to provide comments on this guide, and the ODL. v Conventions The following conventions are used in this guide: ___________________________________________________________ Convention____________Meaning______________________________ For_OpenVMS_platforms:_____________________________________ UPPERCASE TEXT Uppercase letters indicate the name of a command, a file, a parameter, a procedure, or utility. $ The dollar sign ($) indicates the DIGITAL Command Language (DCL) prompt on OpenVMS systems. This prompt may be different on your system. ___________________________________________________________ For_UNIX_platforms:________________________________________ % The percent sign (%) indicates the user prompt on Tru64 UNIX systems. # The pound sign (#) indicates the system manager prompt on Tru64 UNIX systems. Tru64 UNIX, References to Tru64 UNIX and Tru64 Tru64 UNIX Systems UNIX Systems refer to the Tru64 UNIX (formerly DIGITAL UNIX) operating system running on Alpha processor hardware. ___________________________________________________________ For_all_platforms:_________________________________________ $ MOUNT DKA400: Boldface monospace text represents VAXDOCJUN981 user input in interactive examples. > mount -r /dev/rz4c /mnt device-name volume- Lowercase italics indicate a variable label string. These variables include product identifiers, hardware devices, directory locations, file ______________________names,_and_mount_points._____________ vi 1 _________________________________________________________________ Setting-up the Tru64 UNIX ODL This chapter describes how to install the Tru64 UNIX ODL. 1.1 Quick Start This overview is intended to be a "quick start," providing a summary of how to set up the ODL and install and invoke BNU. The device and label specifications will vary according to your system configuration, version of Compaq Tru64 UNIX installed, and the version of the ODL. Tru64 UNIX V5.0 and higher provide full support for FibreChannel, SCSI-3, and wide SCSI devices. The implementation of this support required a major change to the Tru64 UNIX device naming scheme, which is reflected in the following descriptions of mounting the CD-ROM reader. A detailed discussion of each of these steps begins in Section 1.3. The example commands make the following assumptions: o You are logged in as superuser (root). o If the version of Tru64 UNIX installed is V5.0 or higher, then the CD-ROM reader device is /dev/disk /cdrom0c. This value can be obtained for your system using the following command. # /sbin/hwmgr -view devices Otherwise, the CD-ROM reader device is /dev/rz4c. The device unit for the CD-ROM, 4 in this case, can be obtained for your system by using the following command. # file /dev/rrz*c Look for the line in the output that contains the prefix RRD. o The CD-ROM label is U99Q4_1. Setting-up the Tru64 UNIX ODL 1-1 Setting-up the Tru64 UNIX ODL 1.1 Quick Start The steps involved in installing the ODL, including example commands, are summarized below. 1. Create the mount point directory. # mkdir -p /usr/share/doclib/ODL/U99Q4_1 2. Insert the ODL CD-ROM into the CD-ROM reader. 3. Mount the ODL CD-ROM on the mount point directory. For Tru64 UNIX V5.0 and higher: # mount -r /dev/disk/cdrom0c /usr/share/doclib/ODL/U99Q4_1 For versions of Tru64 UNIX lower than V5.0: # mount -r /dev/rz4c /usr/share/doclib/ODL/U99Q4_1 4. Change directory to the setup directory. # cd /usr/share/doclib/ODL/U99Q4_1/setup 5. Run the setup script. # ./setup.scp 6. Exit the Common Desktop Environment (CDE) session and log back in using a non-root user name. 7. Run BNU. % bnu 1.2 Required Environment BNU and associated viewers require Tru64 UNIX Version 3.2C running DECwindows Motif Version 1.2-3 or later. Some viewers, such as Netscape Navigator on Tru64 UNIX, may require later versions of the Tru64 UNIX Operating System and/or DECwindows Motif to work properly. To read online documentation on the ODL, you must have the following environment: o A bitmap DECwindows display (a workstation or a personal computer using PATHWORKS software). o A CD-ROM reader. Alpha hardware systems are shipped with a CD-ROM reader. 1-2 Setting-up the Tru64 UNIX ODL Setting-up the Tru64 UNIX ODL 1.2 Required Environment In addition, you must have the following browsers: o Bookreader. Bookreader is packaged with DECwindows Motif, which is part of the Tru64 UNIX operating system environment. o Netscape Navigator at Version 3.0 or greater. Netscape Navigator is packaged with the Tru64 UNIX Operating System, and is also available on the web for licensed Tru64 UNIX customers at: http://www.UNIX.digital.com/products/internet/index.html 1.3 Mounting the ODL CD-ROM(s) To mount the ODL CD-ROM, perform the following steps: 1. Log in as root and open a dtterm. That is, enter "root" for the username in the Compaq Tru64 UNIX Welcome login screen, followed by the root password. Then, click on the left-most up-arrow on the CDE button bar to popup the Personal Applications menu. From this menu, single click on Terminal to start a dtterm window. Use this dtterm to issue the commands in the following steps. 2. Create a directory that will be the mount point for the CD-ROM, using the following command: # mkdir -p mount-point This mount point directory must be named according to the disk label (printed on the CD-ROM) and be located in: /usr/share/doclib/ODL For example, if the disk label is U99Q4_1, the command to create the mount point directory would be: # mkdir -p /usr/share/doclib/ODL/U99Q4_1 3. Load the CD-ROM into the drive. 4. Mount the CD-ROM using the -r option to indicate that the CD-ROM is read-only. Setting-up the Tru64 UNIX ODL 1-3 Setting-up the Tru64 UNIX ODL 1.3 Mounting the ODL CD-ROM(s) On Tru64 UNIX versions 5.0 and higher, use a command in the following format: # sbin/mount -r /dev/disk/cdromCD-ROM-drive-numberc mount-point where: CD-ROM-drive-number is the number the system has assigned in forming your CD-ROM reader device name. mount-point is the mount point you have just created. If you do not know the unit number for the CD-ROM drive, use the SysMan Hardware Manager command as follows to find the device name assigned by the system to the CD-ROM drive. For more information on the Hardware Manager, consult the Compaq Tru64 UNIX System Management Manual in the Compaq Tru64 UNIX Operating System shelf of the ODL. # /sbin/hwmgr -view devices On Tru64 UNIX versions less than V5.0, use a command in the following format: # sbin/mount -r /dev/rzunit-numberc mount-point where: unit-number is the unit number of your disc drive and mount-point is the mount point you have just created. If you do not know the unit number for the CD-ROM drive, use the file command as follows to find the device name, which contains the unit number. # file /dev/rrz*c The file command returns output similar to that shown in the following example: /dev/rrz0c: character special (8/2) SCSI #0 RZ1BB-BS disk #0 (SCSI ID #0) (SCSI LUN #0) /dev/rrz1c: character special (8/1026) SCSI #0 RZ1BB-BS disk #8 (SCSI ID #1) (SCSI LUN #0) /dev/rrz2c: character special (8/2050) SCSI #0 RZ1BB-BS disk #16 (SCSI ID #2) (SCSI LUN #0) /dev/rrz4c: character special (8/5122) SCSI #0 RRD46 disk #40 (SCSI ID #5) (SCSI LUN #0) To find the unit number for the CD-ROM, look for the line in the output that contains the prefix RRD. In this example, this is the last line, which shows that the CD-ROM drive is rrz4c and that the unit number is 4. 1-4 Setting-up the Tru64 UNIX ODL Setting-up the Tru64 UNIX ODL 1.3 Mounting the ODL CD-ROM(s) For example, # mount -r /dev/rz4c /usr/share/doclib/ODL/U99Q4_1 5. To ensure that a CD-ROM is remounted in the event that your system crashes or is rebooted, follow these steps: a. Using the text editor of your choice, open the file /sbin/bcheckrc and search for the following section: # # mount local (non-nfs) filesystems # echo 'Mounting local filesystems' /sbin/mount -a -v -t nonfs b. To ensure that your CD-ROM will be mounted at system startup, add the following lines after the mount local section, replacing device_number or CD-ROM- drive-number with the appropriate value for your CD-ROM drive, and mount_point with the directory on which you mounted the CD-ROM: On Tru64 UNIX version V5.0 and higher, # # mount CD # echo 'Mounting CDROM' /sbin/mount /dev/disk/cdromCD-ROM-drive-numberc mount-point On Tru64 UNIX versions lower than V5.0, # # mount CD # echo 'Mounting CDROM' /sbin/mount /dev/rzdevice-numberc mount-point The system will mount the CD-ROM on the mount point you specify on every reboot. Setting-up the Tru64 UNIX ODL 1-5 Setting-up the Tru64 UNIX ODL 1.4 Running the ODL Setup Procedure 1.4 Running the ODL Setup Procedure Perform the following steps to install the BNU subset. You must be logged in as the superuser (root) to perform these steps: After mounting the ODL CD-ROM as above, run the setup script found in the setup directory under the mount point directory. For example: # cd /usr/share/doclib/ODL/U99Q4_1/setup # ./setup.scp You should run the setup script every time you receive a new ODL. The setup script checks to make sure you are running the most current version of BNU, verifies the installation, invokes setld to install the BNU subset if necessary, and configures your system library to access the current ODL CD-ROM(s). To reconfigure the system library at anytime: You can use setld to send a configuration message to the installed BNU subset control program. The BNU subset is BNUBASEnnn, where nnn is the version: BNUBASE201 for BNU V2.1 If the configuration message is LIBRARY, the system library will be configured to access any available libraries. For example: # setld -c BNUBAS201 LIBRARY This includes the Tru64 UNIX Operating System documentation library (V4.0 or later), as well as any ODL libraries that are mounted in the system ODL area. These ODL libraries are identified by matching the path /usr/share/doclib/ODL/U99Q4_1/contents.odl. Any library matching this path and having a unique TITLE entry will be added to the system library. If the configuration message is a label (anything other than INSTALL, DELETE or LIBRARY) and the corresponding library, /usr/share/doclib/ODL/U99Q4_1/contents.odl, exists and has a TITLE new to the system library, that library will be added to the system library. 1-6 Setting-up the Tru64 UNIX ODL Setting-up the Tru64 UNIX ODL 1.4 Running the ODL Setup Procedure If the mount point directory (/usr/share/doclib/ODL/U99Q4_ 1) does not exist, the directory is created and a message is printed to mount the CD-ROM there. Mount the CD-ROM on this directory and re-run the setld command. 1.4.1 Sample Tru64 UNIX Installation Log The following is a sample installation log from a Tru64 UNIX ODL Setup: ------------------------------------------------------------------------ Online Documentation Library Setup ------------------------------------------------------------------------ Checking for installed version of BNU (please wait)... Installing BNUBASE201... Checking file system space required to install specified subsets: File system space checked OK. 1 subset(s) will be installed. Loading 1 of 1 subset(s).... Bookshelf Navigation Utility Copying from /odl/U99Q4_1/setup/BNU (disk) Verifying 1 of 1 subset(s) installed successfully. Configuring "Bookshelf Navigation Utility" (BNUBASE201) Replace existing /usr/share/doclib/ODL/library.odl ((y)/n)? Installation of the Bookshelf Navigation Utility (BNUBASE201) subset is complete. Configuring "Bookshelf Navigation Utility" (BNUBASE201) Installation of the Bookshelf Navigation Utility (BNUBASE201) subset is complete. Configuring "Bookshelf Navigation Utility" (BNUBASE201) adding "Compaq Tru64 UNIX Online Documentation Library (April 1999)" to /usr/share/doclib/ODL/library.odl... Checking for existing Adobe Acrobat Reader version... Adobe Acrobat Reader detected: lrwxrwxrwx 1 root system 32 Sep 22 1998 /usr/bin/X11/acroread -> /usr/local/Acrobat3/bin/acroread Acrobat4 appears to be already installed. Re-installing Adobe Acrobat Reader V4.0 is not recommended. Setting-up the Tru64 UNIX ODL 1-7 Setting-up the Tru64 UNIX ODL 1.4 Running the ODL Setup Procedure Do you wish to install Adobe Acrobat Reader V4.0 (y/(n))? done. 1.4.2 If You Do Not Install BNU Although not recommended, the ODL books can be accessed through a Bookreader bookshelf hierarchy, without installing BNU, as follows: 1. Mount the ODL CD-ROM (as described in Section 1.3). 2. Invoke Bookreader. 3. Use the File... Switch Library option in Bookreader to bring up the Bookreader: Switch Library window. 4. In the Selection Field, enter the following file specification: /usr/share/doclib/ODL/label/decw_book/library.bks For example: $ /usr/share/doclib/ODL/U99Q4_1/decw_book/library.bks 5. Click on OK. The Bookreader bookshelf hierarchy is opened, displaying the category shelves. 1-8 Setting-up the Tru64 UNIX ODL 2 _________________________________________________________________ Setting-up the OpenVMS ODL This chapter describes how to install the ODL on both OpenVMS Alpha and OpenVMS VAX systems. 2.1 Quick Start This overview is intended to be a "quick start," providing a summary of how to set up the ODL and install and invoke BNU. The device and label specifications may vary according to your system configuration and the version of the ODL. A detailed discussion of each of these steps begins in Section 2.3. This quick start assumes that: o You are in the system account. o You have CD-ROM reader devices of DKA400: and DKA500:. o You wish to install the June 1999 version of the ODL for OpenVMS Alpha. Here are the steps: 1. Insert the ODL CD-ROMs into the CD-ROM readers and mount them. $ MOUNT/SYSTEM/NOWRITE DKA400: AXPDOCJUN991 $ MOUNT/SYSTEM/NOWRITE DKA500: AXPDOCJUN992 2. Invoke the ODL setup command to begin the ODL setup procedure. This installs BNU. $ @DISK$AXPDOCJUN991:[SETUP]SETUP Compaq recommends that you accept the defaults for all options once the setup procedure begins. Setting-up the OpenVMS ODL 2-1 Setting-up the OpenVMS ODL 2.1 Quick Start 3. If not already defined on startup, add the definition for the Netscape symbol for ODL users. This is done by adding the definition to individual users' login.com file or in SYLOGIN. $ NETSCAPE == "$SYS$SYSTEM:NETSCAPE-EXPORT" 4. Log out and log in again. 5. Invoke BNU. $ BNU If you cannot meet all the requirements for installing BNU and viewers, you have the option of accessing the Bookreader books on the ODL by using a Bookreader bookshelf hierarchy (see Section 2.4.2). Note, however, that an increasing amount of information will be provided in HTML and other formats on the ODL in the future. You will be unable to access these books using the Bookreader bookshelf hierarchy. 2.2 System Requirements This section describes the requirements for running BNU and associated viewers. 2.2.1 Operating System Requirements BNU and associated viewers[1] have the following operating system requirements: ___________________________________________________________ Software____Operating_System_Required______________________ BNU V2.1 Version 6.1 of OpenVMS Alpha or OpenVMS VAX running DECwindows Motif Version 1.2-3 or later Netscape DECwindows Motif for OpenVMS windowing software Navigator (minimum Version 1.2-3 with mandatory update or V3.03_______Version_1.2-4_or_later)________________________ ____________________ [1] Previous versions of the ODL may have HyperHelp books. The current default ODL Setup procedure, however, does not install HyperHelp. 2-2 Setting-up the OpenVMS ODL Setting-up the OpenVMS ODL 2.2 System Requirements 2.2.2 Disk Space Requirements BNU and associated viewers have the following approximate disk space requirements. ___________________________________________________________ Software____VAX_________AXP________________________________ BNU less than less than 1MB 1MB Netscape 5MB 9MB Navigator__________________________________________________ 2.2.3 Required Environments BNU requires the following environment: o A bitmap DECwindows display (a workstation or a personal computer using PATHWORKS software) o A CD-ROM reader o Bookreader software Bookreader is packaged with DECwindows Motif, which is part of the OpenVMS Alpha and OpenVMS VAX operating system environments. Netscape Navigator requires the following environment: o A minimum of 16MB RAM; more is recommended. o Video display equipped with at least 256 colors. 2.3 Mounting the ODL CD-ROMs Mount the ODL CD-ROM, as follows: 1. Log into the system manager's account (SYSTEM). 2. Insert the ODL CD-ROMs into the CD-ROM readers. 3. Enter the MOUNT command in the following format: MOUNT/SYSTEM/NOWRITE device-name: volume-label The volume label is printed on the CD-ROM. For example, on OpenVMS Alpha: $ MOUNT/SYSTEM/NOWRITE DKA400: AXPDOCJUN991 $ MOUNT/SYSTEM/NOWRITE DKA500: AXPDOCJUN992 Setting-up the OpenVMS ODL 2-3 Setting-up the OpenVMS ODL 2.3 Mounting the ODL CD-ROMs To mount the OpenVMS VAX libraries, use the appropriate volume labels, for example VAXDOCJUN991 and VAXDOCJUN992. You can mount the Alpha or VAX CD-ROM on either platform. During mounting, the system defines a logical name for each CD-ROM, by prefixing the volume label with DISK$, as in DISK$AXPDOCJUN991. 2.3.1 Mounting on Systems with a Single CD-ROM Reader If you can only mount one of the CD-ROMS on your system, and you have enough disk space, you can copy some or all of the other CD-ROM to a hard disk accessible to your system. When copying, you need to be sure you preserve the directory structure and define the appropriate logical names. The following sample illustrates copying all of disc 2. 1. To copy an entire CD-ROM, you should have 650MB or more of space available on a hard disk mounted on your system. For example, to check the disk named USER1, use this command: $ SHOW DEVICE USER1: The free blocks must be greater than or equal to 1300000. 2. Create a directory on the hard disk: $ CREATE/DIR USER1:[AXPDOCJUN992] 3. Mount and then copy the contents of disc 2 to the hard drive (This example assumes that the CD-ROM reader device is DKA400): $ MOUNT/SYSTEM/NOWRITE DKA400: AXPDOCJUN992 $ COPY DISK$AXPDOCJUN992:[...]*.* USER1:[AXPDOCJUN992...] The COPY command preserves the directory structure. 4. Dismount disc 2: $ DISMOUNT DISK$AXPDOCJUN992 5. Make the logical name for the disc point to the directory: $ DEFINE/SYSTEM DISK$AXPDOCJUN992 USER1:[AXPDOCJUN992] 2-4 Setting-up the OpenVMS ODL Setting-up the OpenVMS ODL 2.3 Mounting the ODL CD-ROMs If you do not have extra disk space, you can switch back and forth between discs, remembering the following: o Always start BNU with disc 1 first. When finished, dismount disc 1 before attempting to mount disc 2; you cannot have two discs logically associated with the same physical device at the same time. o The master index in [README]ODL_MASTER_INDEX.* on disc 1 identifies which disc each product is on. o You need to have only one disc mounted to view the files on that disc. This is because each disc contains a copy of the library's top-level shelf in [000000]CONTENTS.ODL. o The ODL is divided into categories. There may be several categories on each disc, but each category is entirely on a single disc. The "Getting Started" category is always on disc 1, but the other categories may be on any disc of the set. o If you attempt to open a shelf on another disc that is not mounted, you will get an error message that the device does not exist. The first component of the filespec in the message tells you the device name (e.g. DISK$AXPDOCJUN992) you specified when you setup the library. You can then mount that disc (disc 2 in this example) and proceed. 2.4 Running the ODL Setup Procedure Run the ODL setup procedure even if you have already installed BNU from an earlier release. The ODL setup procedure needs to be run to configure BNU to access the current ODL CD-ROMs. The setup procedure is located at [SETUP]SETUP.COM on disc 1 of the CD-ROM set. 1. With disc 1 mounted (see Section 2.3), and from the system manager's account, run the Setup procedure on disc 1 as follows: @device-name:[SETUP]SETUP Setting-up the OpenVMS ODL 2-5 Setting-up the OpenVMS ODL 2.4 Running the ODL Setup Procedure For example, on an OpenVMS Alpha system: $ @DISK$AXPDOCJUN981:[SETUP]SETUP The following sample installation is taken from an OpenVMS Alpha installation; however, the process is the same for OpenVMS VAX. The ODL Setup Procedure displays the following information. ------------------------------------------------------------------------ Online Documentation Library Setup ------------------------------------------------------------------------ Do you want to install any new viewers [YES] Invoking the Polycenter Software Installation... The following product has been selected: DEC AXPVMS ODL V2.1 Platform (product suite) Do you want to continue? [YES] 2. Press Return to answer YES to both questions and continue the installation. The ODL Setup Procedure responds with: Configuration phase starting ... You will be asked to choose options, if any, for each selected product and for any products that may be installed to satisfy software dependency requirements. . . . Do you want the defaults for all options? [YES] 3. Press Return to accept the defaults for all options. Compaq recommends that you accept the defaults. The ODL Setup Procedure responds with: Do you want to review the options? [NO] 4. Press Return if you do not wish to review the options. By default, the ODL Setup Procedure installs BNU, Netscape Navigator, and the Bookbrowser license. 2-6 Setting-up the OpenVMS ODL Setting-up the OpenVMS ODL 2.4 Running the ODL Setup Procedure Enter YES if you wish to review options. The ODL Setup Procedure prompts you for the components you wish to install: o BNU o Netscape Navigator o HyperHelp o Bookbrowser License 5. The ODL Setup Procedure begins by displaying "Execution phase starting" and ends by displaying "Online Documentation Library configuration finished." To complete the installation: a. Define the Netscape symbol for ODL users (either in their login.com files or in SYLOGIN): NETSCAPE == "$SYS$SYSTEM:NETSCAPE-EXPORT" b. Log out and log in again. 2.4.1 If Warnings or Errors are Encountered in Running the ODL Setup Procedure The ODL setup procedure utilizes the POLYCENTER Software Installation utility, which accesses the POLYCENTER Product Database (PPD). This database keeps track of product versions that are installed on the host system. Depending on the state of the PPD, instances of running the ODL setup procedure in which warnings or errors are encountered have been observed. Generally, warnings which refer to version dependency problems can be overlooked. An example warning message generated by the ODL setup procedure is as follows: %PCSIUI-I-DONEASK, execution phase starting The following product will be installed: DEC AXPVMS ODL V2.1 The following product will be removed: DEC AXPVMS ODL V1.8 The following products will be reconfigured: DEC AXPVMS HYPERHELP V5.1-2 DEC AXPVMS NS_NAV_EXPORT V3.0-3 Setting-up the OpenVMS ODL 2-7 Setting-up the OpenVMS ODL 2.4 Running the ODL Setup Procedure %PCSI-E-SFTCNFINS, installed product DEC AXPVMS BNU V1.8 does not satisfy -PCSI-E-SFTCNFVER, DEC AXPVMS ODL V2.1 version requirements -PCSI-E-SFTVERREQ, DEC AXPVMS ODL V2.1 version requirements for DEC AXPVMS BNU a re -PCSI-E-SFTMINREQMAX, minimum V2.1, required (none), maximum (none), below ( none) Terminating is strongly recommended. Do you want to terminate? [YES] In cases such as these, it is generally recommended to respond "no" and permit the installation to procede despite the warning. If dependency problems continue, the following POLYCENTER command should be issued prior to running the ODL setup procedure again: $ PRODUCT REMOVE ODL You will be prompted to take action to optionally remove the ODL products that are no longer referenced. Respond "yes" to the offending product(s). This will cause them to be uninstalled so they will be installed on the next running of the ODL setup procedure. 2.4.2 If You Do Not Install BNU Although not recommended, the ODL books can be accessed through a Bookreader bookshelf hierarchy, without installing BNU, as follows: 1. Mount disc 1 (as described in Section 2.3). 2. Invoke Bookreader. 3. Use the File... Switch Library option in Bookreader to bring up the Bookreader: Switch Library window. 4. In the Selection Field, enter the following file specification: device-name:[DECW$BOOK]LIBRARY.BKS For example, on OpenVMS VAX: $ DISK$VAXDOCJUN981:[DECW$BOOK]LIBRARY.BKS 5. Click on OK. The Bookreader bookshelf hierarchy is opened, displaying the category shelves. 2-8 Setting-up the OpenVMS ODL 3 _________________________________________________________________ Accessing Information on the ODL This chapter describes how to access information on the ODL using BNU. It also explains how to print the PostScript (.PS) and the ASCII (.TXT) files from the CD-ROMs. 3.1 Running BNU Follow these steps to invoke and use BNU and associated viewers: 1. To invoke BNU: On OpenVMS: $ BNU On Tru64 UNIX, enter the following command from the shell prompt: % bnu BNU appears and displays a list of category bookshelves which organize products functionally. The Alphabetical Product Listing provides an alternative method of accessing product documentation. You can use this instead of the category bookshelves to access the full list of products. The Getting Started category shelf lists books relevant to the Software Products Library, including this manual. 2. Double-click on a category bookshelf to display the list of product documentation or subordinate bookshelves that it contains. 3. Double-click on a product name to display the list of books in that product's documentation set. 4. Double-click on the title of the book to display the book. Accessing Information on the ODL 3-1 Accessing Information on the ODL 3.1 Running BNU The appropriate viewer will launch to enable you to read the book online. If you are unfamiliar with Bookreader or Netscape Navigator: - Use the online help feature available in Bookreader for more information on its capabilities - From the Netscape Help menu, you can access the Netscape Navigator: Handbook 3.1.1 Accessing the ODL Across the Network from OpenVMS BNU is designed to access local devices on the system running BNU. However, you can transparently mount remote devices as local devices using any of the following mechanisms: o TCP/IP and NFS o DECdfs with DECnet or DECnet/OSI o InfoServer If you do not have access to any of these mechanisms, you can use logical names to make the remote devices appear as local devices to BNU. This approach is not supported by Compaq, but it may allow you to access the ODL bookshelves and Bookreader books on the remote device. However, you may get errors from other browsers such as Netscape Navigator. To use logical names to make remote devices appear local, define the DISK$volume_label logical names to the remote devices where the CD-ROMs are mounted. For example: $ DEFINE/SYSTEM/EXEC/TRANS=(CONCEALED,TERMINAL) - _$ DISK$AXPDOCJUN981 - _$ NODEB:DISK$AXPJUN981: $ DEFINE/SYSTEM/EXEC/TRANS=(CONCEALED,TERMINAL) - _$ DISK$AXPDOCJUN982 - _$ NODEC:DISK$AXPJUN982: You do not need to know the physical device name on the remote node. 3-2 Accessing Information on the ODL Accessing Information on the ODL 3.2 Searching Book Titles and Content 3.2 Searching Book Titles and Content 3.2.1 The Recommended Search Method You can search to shelf and book titles only, or search the book contents as well. Since searching shelf and book content on large category shelves or on the entire library can be prohibitively time-consuming, Compaq recommends that you search as follows: 1. Launch a separate window by selecting "New BNU (for search)" under the File menu, and search in the new window. Performing a search operation from a secondary BNU allows you to continue using the ODL from the original window while the search progresses or to cancel the search if it is taking too long. 2. Search using "Shelf and Book Titles" first. Limit the use of the "Shelf and Book Content" search to strings that you do not expect to find in titles. The search is not case sensitive. 3. Select one or more shelves to limit the scope of a search by clicking and/or dragging on shelves; discontiguous selections can be made using . If you do not select shelves, the entire ODL is searched. 4. To start the search, click "Search" in the search dialog or press "enter" after typing the search string. 3.2.2 How the Search Progresses When the search begins, a dialog box appears stating the type of search being performed and the books being searched. This is followed by a status message that updates as the search progresses. While the dialog box is up and the search is in progress, you cannot interact with any child windows of the BNU that is searching. Once the dialog box pops down (as a result of the search completing or being stopped) a new BNU containing the search results is launched and the ability to interact with the original BNU resumes. The new BNU is invoked with a temporary ODL shelf containing shelf and/or book entries which match the search criterion. Accessing Information on the ODL 3-3 Accessing Information on the ODL 3.2 Searching Book Titles and Content Depending on your software and hardware configuration, there may be a significant delay between the time this window disappears and the time the new BNU containing the search results is managed and visible. It is important that you wait for the new BNU window to appear and not click on anything during this interval. A similar time lapse occurs when starting a new BNU. Make sure you give the search results BNU or new BNU a few moments to come up at this time before taking further user action with either the search dialog or the rest of the original BNU. Additional searches invoke new BNU search windows. The search mode (shelf and book title or shelf and book content) can be changed from the search pulldown while the search dialog is still up. There is no need to cancel the dialog to change modes. 3.2.3 Canceling a Search You can cancel a search with the "Stop Search" button or by canceling the BNU process that is performing the search operation. The way you cancel the BNU process depends on the platform: o On Tru64 UNIX, select the "Cancel Other New or Search BNU(s)" option from the "File" pulldown in a different BNU window. Any child windows of the cancelled BNU remain active. o On OpenVMS Alpha, select the "Cancel Other New or Search BNU(s)," available only in the "BNU: Library" window. Alternatively, you can cancel or exit an ancestral BNU. An ancestral BNU is the BNU that started the current BNU or an ancestor of it. o On OpenVMS VAX, you can cancel a BNU only by exiting an ancestral BNU and the "Cancel Other New or Search BNU(s)" option on the menu cannot be selected. 3-4 Accessing Information on the ODL 4 _________________________________________________________________ Extending the ODL This chapter describes how to extend the ODL to include Bookreader, HTML, or HyperHelp files that you have created yourself or that were provided by Compaq or third parties. 4.1 BNU Initial Default Library The list of shelves and/or books that appears when BNU is first invoked is determined by the top-level ODL file. This is the initial default library file. This file can be specified in a variety of ways. BNU looks for the file in the following places, in the order listed: 1. A single command line parameter consisting of the filespec. 2. On OpenVMS, the filespec referenced by the logical name "ODLIBRARY" On Tru64 UNIX, the filespec referenced by the environment variable "ODLIBRARY" 3. On OpenVMS, the filespec referenced by the X resource: BnuLibrary.library (defined in SYS$COMMON:[DECW$DEFAULTS.USER]BNU.DAT, and can be overridden by setting X resources) 4. On OpenVMS, SYS$COMMON:[DECW$DEFAULTS.USER]LIBRARY.ODL On Tru64 UNIX, /usr/share/doclib/ODL/library.odl Extending the ODL 4-1 Extending the ODL 4.2 How BNU Finds the Libraries 4.2 How BNU Finds the Libraries BNU does not use logical names, search lists, or environment variables to find files. The bookshelves (.ODL files) use relative pathnames for references to files on the same CD-ROM. BNU on OpenVMS uses X Window System resource definitions to resolve references to files on another CD-ROM. BNU on Tru64 UNIX uses standard mount- points to resolve references to files on another CD-ROM. The ODL setup procedure on OpenVMS defines the necessary resources in the BNU resource file, SYS$COMMON:[DECW$DEFAULTS.USER]BNU.DAT. Setup defines one resource for each volume of the ODL. The resource name is BnuLibrary.volume_label where volume_label is the volume label of the target CD-ROM. The resource value is the name of the device where the CD-ROM is mounted. The default resource value is the logical device DISK$volume_label. OpenVMS always defines this logical device when a volume is mounted. On Tru64 UNIX, the standard mount point for each ODL CD-ROM is /usr/share/doclib/ODL/label, where label is the CD-ROM volume label. 4.3 BNU Bookshelf Structure This section describes how to set up bookshelves to be compatible with BNU. Bookreader books to be accessed by BNU do not require any changes. BNU contains bookshelf files that provide pointers to individual books, subordinate bookshelves, or both. In the ODL, all the bookshelves have a .ODL file extension; however, this is not a requirement. A bookshelf file is made up of the following entries: o TITLE entry. The keyword TITLE must appear in the bookshelf file, followed by the text of the title you want displayed for the bookshelf. For example: TITLE Product XYZ Bookshelf In the example, the title of the bookshelf would appear in the BNU as "Product XYZ Bookshelf". 4-2 Extending the ODL Extending the ODL 4.3 BNU Bookshelf Structure o A shelf entry for any subordinate shelves that appear on the shelf. The syntax for referencing a shelf is as follows: SHELF pathname shelf_title o A book entry for each individual book that appears on the shelf. The syntax for referencing books is as follows: [BOOK ] [HYPERHELP ] [HTML ] pathname book_title [ ] [PDF ] PDF is supported only on Tru64 UNIX. The keywords BOOK, HYPERHELP, HTML, and PDF refer to the type of book being referenced. BNU does not require any specific extensions for these files. If a filename is specified without an extension, the BNU will attempt to find it as specified. If unsuccessful, it will make one or sometimes two additional attempts to find a corresponding file by adding default file extensions. The first and second default filename extensions on OpenVMS for the various book types are listed below: ________________________________________________________ Type__________Default_1_____Default_2___________________ BOOK .bkb .decw$book HTML .html .htm HYPERHELP_____.hlp______________________________________ The first and second default filename extensions on Tru64 UNIX for the various book types are listed below: ________________________________________________________ Type__________Default_1_____Default_2___________________ BOOK bkb .decw_book HTML .html .htm HYPERHELP .hlp PDF___________.pdf______________________________________ - BOOK is used to reference any Bookreader books. Extending the ODL 4-3 Extending the ODL 4.3 BNU Bookshelf Structure - HYPERHELP refers to books created for the Bristol Technology HyperHelp application. - HTML refers to any books created in HTML format. - PDF refers to any books created in PDF format, for the Adobe Acrobat Reader. The pathname provides a pointer to the book or shelf file that is being referenced. The path name can be as follows: o If the book or shelf is located in the same directory as the bookshelf that references it, the path name need only consist of the file name, possibly omitting the file extension as described above. Sample book and shelf entries in which the books and shelf are located in the same directory as the bookshelf file are as follows: SHELF technicl.ODL Technical Documentation for Product XYZ BOOK manual1.BKB Overview of Product XYZ BOOK manual2.BKB User's Guide to Product XYZ HTML manual3.HTM Quick Reference Manual for Product XYZ o If the book (or shelf) is located in a different directory than the bookshelf file that is referencing it, the path name must reference the directory location and the file name and extension using ISO-9660 syntax. That is, path name components are separated with a slash (/). Path names to files in different directories can be as follows: - Relative path names. If a book (or shelf) is located in a subdirectory from the bookshelf referencing it, you can use a relative path name to reference it. In the following example, XYZDIRECT is a subdirectory that contains the book MANUAL1.BKB. XYZDIRECT/MANUAL1.BKB - Absolute path names. If you are referencing a file located in an entirely different directory (not a subdirectory), or a different device, start the path name with a slash (/). This indicates a top-level directory or different 4-4 Extending the ODL Extending the ODL 4.3 BNU Bookshelf Structure device. For example, to reference the OpenVMS file WORK1:[ABCDIRECT]MANUAL2.BKB using ISO-9660 syntax: /WORK1/ABCDIRECT/MANUAL2.BKB A typical bookshelf file is shown in the following example: TITLE High Performance Fortran BOOK user_gde.bkb Fortran User Guide BOOK ref_gde.bkb Fortran Reference Guide Extending the ODL 4-5