8    Using Online Documentation

In addition to online help, which is already integrated into many applications, all other documentation associated with the operating system, including manuals and reference pages, can be viewed on line from the CD-ROM labeled Documentation Volume 1.

The following topics are discussed in this chapter:

• An overview of documentation file formats and online viewers (Section 8.1)

• Mounting the Documentation CD-ROM (Section 8.2)

• Using the Netscape Navigator application to view HTML versions of the online documentation set (Section 8.3)

• Netscape application integration (Section 8.4)

• Installing the Adobe Acrobat Reader application (Section 8.5)

• Using the Adobe Acrobat Reader application to view PDF versions of the documentation (Section 8.6)

• Copying the documentation set files to your system's hard disk (Section 8.7)

8.1    Documentation Formats and Online Viewers

The online documentation set is available in both Hypertext Markup Language (HTML) and Portable Document Format (PDF) versions. Two viewers are supported:

• You can use the Netscape Navigator application to view the HTML or PDF versions of the documentation. This version of the operating system is shipped with Netscape Communicator 4.75, which includes Netscape Navigator. The Netscape software subset is installed automatically if the installation process detects a graphics card on your system.

  After installing the operating system, you can invoke Netscape through the CDE front panel or from the command line in a terminal emulator window. Detailed online help for Netscape is available through the Help menu on the main window.

• You can use the Adobe Acrobat Reader application to view PDF versions of the documentation.

  After installing the operating system, you can invoke Acrobat Reader either as a Netscape helper application or from the command line in a terminal emulator window. Detailed help for Acrobat Reader is available through the Help menu.

  See the Adobe Acrobat Reader Online Guide for information about setting up Netscape Navigator to view PDF files. You can access this document from the Acrobat Reader Help menu.

8.2    Mounting the Documentation CD-ROM

The operating system documentation is shipped on the CD-ROM labeled Documentation Volume 1. Mount instructions also are included on the inside of the CD-ROM jacket.

Follow these steps to mount the CD-ROM so that you can view the online documentation set with Netscape Navigator or Acrobat Reader:

1. Log in as root or use the su command to gain root privileges.

2. Insert the CD-ROM into your system's CD-ROM drive.

3. Use the following command to mount the CD-ROM on /usr/share/doclib/online if you have only one CD-ROM attached to your system:

   # mount -r /dev/disk/cdrom0c /usr/share/doclib/online
   

   If you have more than one CD-ROM device, enter a command similar to the following to determine the CD-ROM devices connected to your system. Then, decide which CD-ROM device you want to use.

   # ls /dev/disk/cdrom*c
   /dev/disk/cdrom0c
   /dev/disk/cdrom1c
   

8.3    Viewing Online Documents with Netscape

Follow these steps to view the online documentation set with Netscape Navigator:

1. Mount the Documentation CD-ROM as described in Section 8.2.

2. Start Netscape Navigator by using one of the following methods:

   • From the CDE desktop:

     1. Click on the arrow above the Text Editor icon on the CDE Front Panel to display the Personal Applications subpanel.

     2. Click on the Netscape icon.

   • Enter the following command to start Netscape Navigator from the command line in the background:

     # /usr/bin/X11/netscape &
     

     See netscape(1) for more information.

3. Click on the Documentation link to go to the Documentation home page.

4. Documentation categories are listed in the frame down the left side of the page. Click on a category to display links to HTML and PDF versions of the individual books in that category.

Section 8.5 describes how to install Acrobat Reader. The Adobe Acrobat Reader Online Guide, available from the Acrobat Reader Help menu, provides information about setting up Netscape Navigator to view PDF files.

8.4    Netscape Application Integration

The following information is provided to help you when you use Netscape applications on this operating system:

• A sample resource defaults file for Netscape Communicator is located in the /usr/doc/netscape/Netscape.ad file. Comments within this file indicate possible settings for each resource. This file is provided for informational purposes and need not be installed.

• The file /usr/bin/X11/netscape is actually a shell script that performs the following actions:

  • Creates a Communicator user configuration directory if $HOME/.netscape does not already exist.

  • Copies the Navigator preferences file from /usr/doc/netscape/default-netscape-preferences to $HOME/.netscape/preferences.js if it does not already exist in the $HOME directory.

  • Sets the MOZILLA_HOME environment variable to point to the Communicator installation directory /usr/lib/netscape. The Communicator Java class files, nethelp files, plugins, registry, and others are all installed under this directory. See the /usr/lib/netscape/README file for more information on MOZILLA_HOME and other environment variables.

  • Invokes the /usr/bin/X11/real-netscape file, which is the actual Communicator binary.

  This information may be important to know if you should download newer copies of Navigator from other sources (for example, the Netscape web site) and install the files from those kits over the links in $HOME/.netscape. If you want to use the previous version, you need to remove these files so that the /usr/bin/X11/netscape script is able to recreate the symbolic links described previously that point to the older versions of these files.

8.4.1    Mosaic-to-Netscape Bookmark Conversion

If Mosaic was your previous browser, you need to convert your Mosaic hotlist files to equivalent Netscape Communicator bookmark files. To accomplish this conversion, invoke the shell script /usr/doc/netscape/hot-convert.sh with no arguments.

It is recommended that you define the Global Types File and Global Mailcap File used by Netscape as follows:

• Global Types File: /usr/lib/netscape/mime.types

• Global Mailcap File: /usr/lib/netscape/mailcap

These files allow Netscape to invoke the proper helper applications for viewing file types not directly viewable in Netscape. You can do this by selecting Preferences... from the Netscape Options menu. Then select Helper Applications and enter the correct values.

For more information about using Netscape, refer to the Netscape Navigator Online Handbook, which is available by clicking on the link to Other documentation on the home page.

8.5    Installing Acrobat Reader

The PDF versions of the online documents are best viewed by using Acrobat Reader as a Netscape Navigator helper application. This section tells you how to install Acrobat Reader on your system.

Note

Acrobat Reader requires 16 MB of free disk space. Use the df command to ensure that the file system where you install Acrobat Reader has sufficient space before beginning this installation.

Follow these steps to install Acrobat Reader:

1. Log in as root or use the su command to gain root privileges.

2. Mount the Documentation CD-ROM as described in Section 8.2.

3. Change to this directory:

   # cd /usr/share/doclib/online/ACROREAD
   

4. View the following file to find the name of the directory that contains the Tru64 UNIX version of Acrobat Reader:

   # more 00README.TXT
   

5. Change to the directory that contains the Tru64 UNIX version of Acrobat Reader:

   # cd  tru64_unix_directory
   

6. View the following file for information about uncompressing the installation file and running the installation script:

   # more 00README.TXT
   

7. Follow the instructions in the 00README.TXT file to uncompress the installation file and run the installation script.

8. After you read the license agreement, accept the license terms and continue.

9. Select an installation directory for Acrobat Reader. The default is /usr/local/Acrobat3. If you accept this default and the directory does not exist, it is created automatically.

   The installation completes and you see the command line prompt. Section 8.6 describes how to start and use Acrobat Reader once it is installed.

The Adobe Acrobat Reader Online Guide, which is available from the Acrobat Reader Help menu, provides information about setting up Netscape Navigator to view PDF files.

8.6    Viewing Online Documents with Acrobat Reader

The PDF versions of the online documents are best viewed by using Acrobat Reader as a Netscape Navigator helper application. You can, however, view them directly with Acrobat Reader. You should review the 00README.TXT file in the ACRO_DUX and ACRO_SUP subdirectories under the /usr/share/doclib/online/DOCS directory. These files map file names to document names so that you can locate specific documents.

Follow these steps to view the online documentation set with Acrobat Reader:

1. Mount the documentation CD-ROM as described in Section 8.2.

2. Install Acrobat Reader as described in Section 8.5.

3. Run Acrobat Reader in the background:

   # /usr/local/Acrobat3/bin/acroread &
   

   See the Adobe Acrobat Reader Online Guide, which is available from the Help menu, for information on how to use Acrobat Reader.

4. Select Open... from the File menu to open the Open dialog box, where you can select a PDF file.

   The PDF versions of the documents are in the /usr/share/doclib/online/DOCS directory on the documentation CD-ROM.

   • The ACRO_DUX subdirectory contains the base operating system documentation set.

   • The ACRO_SUP subdirectory contains the supplementary documentation set.

   The 00README.TXT file in both subdirectories maps file names to document names so that you can locate specific documents. You cannot use Acrobat Reader to view text files. To view this file you might consider using the more command. For example:

   
# more /usr/share/doclib/online/DOCS/ACRO_DUX/00README.TXT
   

8.7    Copying Online Documentation to Disk

Instead of reading the online documentation set from the CD-ROM, you can copy the documentation files to a disk on your system. Copying the documentation files to a disk eliminates the need to keep the CD-ROM permanently mounted. The entire set of online documentation files consumes about 218 MB of disk space in the /usr file system.

Follow these procedures to copy the documentation files to a disk on your system. Use the same directories shown in the examples so you will not have to modify library bookshelf files.

1. Log in as root or use the su command to gain root privileges.

2. Insert the Documentation CD-ROM into the drive (the remainder of these instructions assume the CD-ROM device name is /dev/disk/cdrom0c).

3. Mount the CD-ROM on /mnt:

   # mount -r /dev/disk/cdrom0c /mnt
   

4. Enter commands similar to the following to copy HTML and PDF versions of the documents from the CD-ROM to subdirectories in the /usr/share/doclib/online/DOCS directory. These instructions illustrate the process with the CD-ROM mounted on the /mnt directory.

   Note

   The backslashes ( \ ) in the following examples represent line continuation characters; do not enter them on the command line.

   • To copy HTML versions of the entire documentation set, enter the following commands:

     # cd /mnt/DOCS/HTML
     # tar cpf - . |     \
     (cd /usr/share/doclib/online/DOCS/HTML;tar xvpf -)
     

     The documentation HTML files consume about 86 MB of disk space.

   • To copy PDF versions of the base operating system documentation set, enter the following commands:

     # cd /mnt/DOCS
     # tar cpf - ./ACRO_DUX |    \
     (cd /usr/share/doclib/online/DOCS/ACRO_DUX;tar xvpf -)
     

     The PDF files consume about 29 MB of disk space.

   • To copy the PDF versions of the supplemental documentation set, enter the following commands:

     # cd /mnt/DOCS
     # tar cpf - ./ACRO_SUP |  \
     (cd /usr/share/doclib/online/DOCS/ACRO_SUP;tar xvpf -)
     

     The supplemental documentation set PDF files consume about 8  MB of disk space.

5. Unmount the CD-ROM:

   # cd /
   # umount /mnt
   

Follow the instructions in Section 8.3 if you want to start Netscape Navigator to view HTML files or the instructions in Section 8.6 if you want to start Acrobat Reader to read PDF files.