Table of Contents
DocView is a documentation server for SCO UnixWare. It creates a mini-website dedicated to serving most of the documentation installed on a UNIX system. The documentation server is a separate instance of an Apache HTTP server running off of a separate port number (8458) so as to not interfere with any other web servers on the host.
DocView makes available the documentation to anyone with access to the DocView server, using any web browser they choose. DocView can be easily reconfigured to serve only to browsers running on the same machine. See the section called “Disabling network documentation service” for more information.
Here are some of the features that make DocView useful:
Integrates guides, manual pages, GNU info files, and miscellaneous text and HTML documentation installed by packages.
Accessible with any modern browser.
Provides full-text search capability across the complete set of installed documentation.
Inserts a navigational toolbar at the top of each page to permit direct access to the main DocView functions.
If enabled, can provide networked access to a single documentation set. This means individual workstations don't need to have copies of documentation installed.
DocView is installed on a SCO UnixWare system using the standard scoadmin package manager. If it is not installed when the operating system is installed, you can follow these instructions to install it when logged onto the system as user root.
DocView requires certain packages to already be installed on the system:
apache
mod_perl
htdig
Once the prerequisite packages are installed, you can install DocView as follows:
Start the scoadmin manager and select the Software Manager.
Select the item for the operating system, such as UnixWare Enterprise System. Expand it by double-clicking on it, or selecting View->Expand.
Then expand the following selections:
UnixWare Enterprise System UNIX
Utilities
Extended Utilities
Select DocView Documentation Server.
Select from the menu Software->Install New .... Then follow the standard process for selecting the media and installing the package.
Installing the package puts the files in place and configures the DocView webserver. It should also automatically start the webserver. See also the section below on starting and stopping the server.
Once the server is started, you should be able to browse the documentation by clicking on the "DocView" icon. You can also just point a browser at:
http://localhost:8458
In order for the search system to work, the search index must be generated on the system. The search index is not generated during installation because it takes significant time and disk space. See the instructions in ``Administering a DocView server'' for more information.
DocView makes browsing online documentation easy. Just point your favorite web browser at the DocView server on port 8458:
http://localhost:8458
If DocView is enabled for network documentation service, then you can browse the documentation from other machines on the network using this URL:
http://machine.domain:8458
As you browse, you will notice that across the top of each page is a DocView toolbar. That toolbar is dynamically inserted on each page by the DocView server and provides instant access to the main DocView functions, such as Search and Man Pages.
The DocView home page serves as a starting point for finding information by subject. The list on the left side of the home page gets you started. It points to SCO UnixWare guides and any optional documentation that is installed. There may also be a link to Developer documentation, depending on what packages are installed.
Use the Search function to locate information by keywords (the system administrator must first generate the search index). The full search form provides instructions on how to pose search queries for best results.
Use the Manual Pages form to locate a particular man page. It works in a manner similar to the command line man command. Typing a name in the search field normally looks for an exact match on that man page name. If the name exists in more than one manual page section, you will get a list to choose from. Or you can specify the section name from the select list. If you are not quite sure of the name, then check the Search Descriptions checkbox. That will search man page descriptions for the keyword you specify in the search field. You can also select the Display List of Manpages button, which displays a complete list of man pages installed on the system.
You may notice that some manual pages are displayed as plain formatted text with some hot links. The hotlinks are generated using the man2html utility that looks for text strings of the form name(number), which would normally be a reference to another manual page. However, it does not check to see if such a manual page exists before presenting the link. Therefore, some of those hotlinks will not lead to valid man pages.
If any documentation prepared using the GNU Info system is installed on the system, it is available through DocView as well. DocView uses the info2html utility to display such files. The list of Info files is automatically updated each time you use it, so new documentation should show up there immediately (make sure to clear your browser cache if it doesn't).
Some documentation may be available in languages other than English. Most browsers allow you to set language preferences. If you do that, then the DocView server tries to respond with the best match of translated doc. It also will provide translated links in the top navigational header and in any forms that it generates, if your language list includes one of the supported languages. See the Search form for a list of currently supported languages.
The system administrator may need to perform certain tasks to maintain a DocView server. Most of the DocView files are installed under /usr/lib/docview and /var/lib/docview.
The DocView server is controlled by an init script so that it can start automatically when the system boots. By default, the server starts automatically for local service after rebooting the system. See the next section to control the automatic start feature.
You can use the same init script to start and stop the server manually. This is also necessary when you change the configuration of DocView and want to restart it.
/etc/docview stop stop the server /etc/docview start start the server /etc/docview restart stop and then start the server
Normally the process ID for the server is stored in /var/lib/docview/docview.pid, and a lock file is created at /var/lib/docview/docview.lock. The lock file prevents a second server from being started accidentally.
When you start the server manually, you should see a message indicating that it started. If not, then try using the restart option. There may be a lock file left behind that prevents it from starting.
By default, the DocView server is configured to automatically start when the system is rebooted. It is controlled by the following startup script:
/etc/rc2.d/S95docview
Removing that script or making it non-executable will prevent the server from starting on reboot.
The search system is based on the ht://dig search engine. It uses a search index that is generated by following all the links on a website, downloading each page, scanning for words, and following any links on that page to other pages. A configuration file controls the extent of link following so only documentation files on the server system are indexed.
The search index is not generated during the installation of DocView. The indexing process can take considerable time and system resources, depending on how much doc is installed and how fast the machine is. It is best to run the indexing process when the machine is relatively inactive.
The search index can be 80 megabytes and larger. During the sorting process, it generates temporary files that can double that. Be sure you have sufficient space available under /var/lib/docview where the index files are stored. If you have enough disk space for the index but not enough for the temporary files, you can set the TMPDIR environment variable to a temporary directory on another larger filesystem. That directory should already exist.
The basic command for generating the search index is:
/usr/lib/docview/conf/rundig
Here is some additional useful information about the indexing process:
The DocView server must be running for indexing to take place.
You can try running the command as a cron job. If that fails, run it directly from the command line. The cron environment may limit resources that prevent the indexing process from completing properly for large doc collections.
The first time rundig is run, it will generate a configuration file tailored for the system, and then run the collection process. That can take several hours, depending on the speed and load on the machine. When it completes, you should be able to use the Search system in DocView.
The rundig command has a few options:
rundig [-i] [-a] [-s] [-v|-d]
Build a complete new index, not an update. This takes longer, but ensures correct results. It is necessary when documents are removed from the system, because an incremental indexing process will not remove documents.
Keep old files while indexing. This options lets you keep using the old search index while the new one is generated. It requires lots of disk space.
Print statistics after completion.
Verbose output (-d more verbose). These options display information about each document being indexed. They are useful for debugging purposes. One word of caution: the -d option can generate hundreds of megabytes of information.
If you reindex often and have sufficient disk space, you can speed up reindexing by commenting out a line in the rundig script that removes the db.wordlist file upon completion. That large file takes a lot of space but makes incremental indexing jobs run faster. If you want to keep that file, use an ordinary text editor on the rundig script file to locate and comment out the rm command.
DocView generates one search index that includes documentation in all languages to which it has access on the system.
The DocView server is initially configured to serve the documentation to any machine on your network. You can change the configuration to only serve to browsers running on the same machine.
As root, edit the file /usr/lib/docview/conf/httpd.conf to change the directive ServerName from the fully qualified network name for the machine to 127.0.0.1. For example:
ServerName 127.0.0.0
In the same file, add this directive:
BindAddress 127.0.0.1
In the same file, change the Listen directive to the following:
Listen 127.0.0.0:8458
Save the file and restart the DocView server with this command:
/etc/docview restart
If the search index has not been run since installation, then do the following step (a). If the search index has been run already, then do step (b). You can tell if it has been run because the file /usr/lib/docview/en/htdig.conf is not zero length (which means it has been configured).
Edit the file /usr/lib/docview/conf/install.conf and change:
$HOMENAME=`hostname -f`;
to
$HOSTNAME="127.0.0.1";Now when the index is run for the first time, it will be configured only for local access.
If the index has already been run at least once, then edit the file /usr/lib/docview/en/htdig.conf and change all instances of your fully qualified network hostname to 127.0.0.1. Be sure to leave the port number as 8458.
If the search index has been generated, it will have to be entirely rebuilt because the file addresses in the database use the local address, not the network address. If you don't rebuild it, only local users can use the search function successfully. To rebuild the search index, or to build it for the first time, run this command:
/usr/lib/docview/conf/rundig -i
DocView allows you to extend the list of doc that DocView displays on its home page by using metadata, as described below. You can also update the man page lists, and add GNU Info doc.
DocView provides a feature to extend the list of documentation available through its server. If you install new documentation that you want to include in DocView's lists, you supply a doc metadata file and execute the doctool configuration script.
Each package installing documentation should install a metadata file in the standard location /usr/share/meta/doc. That metadata file provides information about the documentation as described below. That information is used the DocView configuration program to generate the lists of available documentation.
The postinstall script for a package installing doc should execute the command:
doctool --add pathname/mydoc.desktopThe path should be relative to /usr/share/meta/doc, where the metadata file is installed. This program executes the installation for all the doc presentation systems. This program is located in /usr/bin/doctool.
When a package is removed, so is the metadata. The pre removal script should execute the command:
doctool --remove pathname/mydoc.desktop
There are two types of metadata files: .directory files for categories, and bookid.desktop for documents.
Both metadata files use a format of fieldname=value to identify the metadata fields.
For each installed book or guide that has a table of contents to point to, there will be a corresponding bookID.desktop file, where bookID identifies the document.
The .desktop files are arranged in a directory hierarchy that corresponds to the logical hierarchy of the document lists that are presented to the user. Each directory is a category or grouping of documents, and may have subcategories.
The metadata for a category/directory will be in a hidden file named .directory within the directory.
The following fields in the .desktop files are used for generating entries for documentation items in the navigation lists:
This field contains the default title to display in the default language list. The title may include spaces.
Where xx is a language code, indicating that this translated title should be used when the user's language is set to this language code.
The full pathname to the table of contents HTML file for the document. That table of contents file should point to the rest of the document's HTML and image files using relative HREFs.
The name of the icon to display next to the title in KHelpCenter.
The Comment field provides a description of the item. It can also appear many times in the file with localization codes as for the Name field.
Provides a relative weight to an item indicating where it should appear in its list. Larger weight numbers appear lower on the list (they sink). Items with identical weights in the same list are sorted alphabetically within that value. Items without weights appear after all items with weight values. The use of decimal values permits inserting new entries between existing entries to any degree necessary.
In addition to the above fields, a .directory metadata file that identifies a category can have the following fields:
A directory of type group contains a tightly coupled group of documents, while a directory of type category contains documents fitting into a more general category. See below for processing differences.
Location of text content to be displayed when the category list is displayed.
This example metadata file NET_nfs.desktop adds a link to the table of contents of the Administering the Network File System topic.
[Desktop Entry] Name=Administering the Network File System (NFS) DocPath=/usr/share/doc/OpenUNIX8/en/NET_nfs/CONTENTS.html X-COL-Weight=9
The metadata file is installed by its package at /usr/share/meta/doc/HelpTopics/NEThome/NETgroup/NET_nfs.desktop. The postinstall script configures it into the system using this command:
/usr/bin/doctool --add HelpTopics/NEThome/NETgroup/NET_nfs.desktop
This example metadata file .directory (note the leading dot) adds a group heading Apache Documentation to the main home page.
[Desktop Entry] Name=Apache Documentation Type=group X-COL-Weight=10
The metadata file is installed by its package at /usr/share/meta/doc/ApacheDoc/.directory. The post export installation script configures it into the system using this command:
/usr/bin/doctool --add ApacheDoc/.directory
Documents that are to appear under this new group should install their metadata file under /usr/share/doc/meta/ApacheDoc to be included in that group.
If additional man pages are installed on the system, then they will automatically be found during a search for a particular man page in both DocView and on the command line. However, the list of man page descriptions is not automatically updated. The list of descriptions is used in listing all the pages in a man section, and in apropos searches in DocView and the command line (also man -k).
To update the list of man page descriptions, log in as root and execute the following command:
/usr/bin/makewhatis
The list of man pages available through DocView depends on the configuration of the man(1) utility on the system. The system file /etc/default/man sets various parameters that affect the man command. In particular, the lines with MANPATH values indicate which directories to search to locate man pages on the system. To include additional man directories, add entries for MANPATH to that file.