This chapter explains how to install and use the AnswerBook2TM product to browse, search, and print online documentation. It includes the following information:
The name of this product is Solaris 7 but code and path or package path names may use Solaris 2.7 or SunOS 5.7. Always follow the code or path as it is written.
The AnswerBook2 product is the Sun online documentation system. It uses a web-browser interface that lets you view and print a variety of SolarisTM information, including SGML-based AnswerBookTM collections, Display PostScriptTM AnswerBook collections, and man pages.
The AnswerBook2 product provides a search engine that lets you find information throughout the documentation library. You can install document collections on a centralized documentation server or on a local server.
Throughout the AnswerBook2 documentation, the term AnswerBook1 refers to the version of the AnswerBook product provided with pre-2.6 versions of the Solaris operating environment.
The AnswerBook2 product provides the following features and functions:
Uses a web-browser-based interface so that you can view online documentation from any platform (running any operating system), provided that your web browser supports HTML 3.2
Depending on your web browser's functionality, lets you copy information from AnswerBook2 documents and paste it into other locations, such as your command line
Provides a search interface for finding words and word phrases throughout the documentation library
Gives you the ability to print chapters and books directly from the AnswerBook2 interface in a PostScript format that is near print-quality output
Lets you view old and new AnswerBook documents using a single interface
Lets you define a subset of document collections (a Personal Library) to be displayed when using a specific document server
Allows you to choose a language in which to view on-screen instructions and Help information
Uses a client-server architecture that allows the documents to be stored in a single location (server) and accessed from the user's desktop (client)
Provides a command-line interface (CLI) and a browser-based interface (GUI) for performing administrative functions
The following list identifies the new or substantially enhanced features provided in this release of the AnswerBook2 software.
Man pages (Reference Manual) in AnswerBook2 format
Traditional UNIX®-style manual (man) pages are available in AnswerBook2 format. The search interface allows you to choose to search only the SGML-based man pages installed on the documentation server.
Support for multimedia content
If the document source includes audio or video files, the AnswerBook2 system lets you access them according to what you have defined in your browser for audio and video support.
Ability to run an AnswerBook2 server directly from the Solaris 7 Documentation CD (server administrators only)
You can run the AnswerBook2 server directly from the Solaris 7 Documentation CD using the ab2cd script, if you have the CD and you have root access to the system on which the CD is connected. For detailed information about this feature, see "To Run a Documentation Server From the Solaris 7 Documentation CD".
Ability to use various CGI-based web servers (server administrators only)
The AnswerBook2 server can run either as an NSAPI plug-in using the server that is included in the AnswerBook2 server packages or as a CGI-based application using any httpd server that supports CGI (such as Netscape ServerTM or Sun WebServerTM). For detailed information about changing to a CGI-based web server and some possible limitations, see "Running the AnswerBook2 Server as a CGI Process".
Ability to control display of style sheet errors (server administrators only)
To control whether the word "BUG" is displayed to the users in red when style sheet errors occur, turn on or off the AnswerBook2 debugging function. You set this when you start up the document server. For more information, see Starting and Stopping the Documentation Server in the AnswerBook2 Help.
The AnswerBook2 product consists of the following elements:
A client web browser - The Solaris 7 release includes the Netscape browser; however, you can use any HTML 3.2-compliant browser to view Sun's online documentation.
If you just want to view online documentation and you have access to a documentation server's URL, you only need this element. All other elements are part of the documentation server system (a machine on which the document collections are installed and which runs a web-based server to deliver them to you). If you do not have access to a documentation server at your site, you can view all released Solaris documentation at: http://docs.sun.com
A documentation server - Performs query functions and "serves" documents to the client browser. Includes templates that provide a common "look and feel" for document viewing and printing; and provides both web-browser and command-line administration interfaces that perform database, password authentication, and other administrative functions.
Document collections - Can be new (SGML) documents or old (Display PostScript) documents.
This section lists some common questions about the AnswerBook2 product along with answers to those questions.
What is AnswerBook2?
The AnswerBook2 product uses a standards-based document server to deliver online documentation through your favorite web browser. The AnswerBook2 interface lets you browse, search, and print a variety of Solaris information, including AnswerBook1 collections and man pages.
How is AnswerBook2 different from AnswerBook?
The previous AnswerBook product (now called AnswerBook1) used Display PostScript to display electronic versions of documents primarily developed for paper delivery. The AnswerBook2 product uses a web browser to display documentation developed for online delivery using SGML and to display existing AnswerBook1 documents.
Some key differences between the products are:
Web-browser interface - You can use any HTML 3.2-compliant browser on any platform to view online documentation with the AnswerBook2 product.
Source flexibility - The AnswerBook2 server can deliver AnswerBook1 (Display PostscriptTM) documents or AnswerBook2 (SGML) documents.
Client-server support - The AnswerBook2 product allows you to install the server and document collections in a central location and view the documents from other systems. In addition, it includes a "fail-over" mechanism in which the document administrator can define multiple documentation servers so that links between documents always work.
Cross-platform - For this release, the AnswerBook2 document server must run in the Solaris 7 operating environment (SPARC or Intel). However, AnswerBook2 clients can run on any platform, and future releases might provide server functionality on additional platforms.
Default search behavior - The AnswerBook2 product uses AND for its default search behavior rather than OR (the default search behavior in the AnswerBook1 product).
Can I still view my old AnswerBook collections with AnswerBook2?
Yes, unless your old AnswerBook documents were created before the release of the Solaris 2.2 operating environment. To add AnswerBook1 collections to the AnswerBook2 server's database, the document administrator uses the AnswerBook2 "add collection" function and points to the directory containing the AnswerBook1 ab_cardcatalog file.
Does AnswerBook2 provide the same functionality for AnswerBook1 and AnswerBook2 documents?
No. For consistency, the AnswerBook2 interface for AnswerBook1 documents is similar to the AnswerBook1 product interface. Thus, the AnswerBook2 product provides the following differences in functionality for AnswerBook1 and AnswerBook2 collections:
You cannot show or hide all levels of an AnswerBook1 table of contents listing; you can only show or hide details for a specific section within the table of contents.
AnswerBook1 content pages do not include Other Topics sections. To navigate from one page to another, you can use the Next Topic link or return to the table of contents and select another section in the book.
AnswerBook1 content pages display the entire chapter at one time, not smaller sections.
Search results icons poorly represent the probability of a match for AnswerBook1 information; the icons tend to be either completely filled or completely empty.
Search terms are not highlighted in AnswerBook1 text.
Some AnswerBook1 graphics cannot be displayed inline; they are identified by an icon that, when clicked displays a PostScript image of the graphic.
A Man Pages by Keyword search includes only the AnswerBook2 (SGML-based) man pages on the server, not the AnswerBook1 man pages.
The AnswerBook1 man pages use the same interface as other AnswerBook1 documents; they do not have a special man page interface.
The document server software and Solaris 7 document collections are on the Solaris 7 Documentation CD. Figure 8-1 through Figure 8-6 list the specific document collections available and identify those documents that are available only in hard-copy (printed) format.
To view online documentation using the AnswerBook2 system, you need an HTML 3.2-compatible browser (such as HotJavaTM, Netscape NavigatorTM, or LynxTM), and access to a documentation server (a URL that identifies a machine on which the document collections are installed and which runs a web-based server to deliver them to you). For more information, choose from the following:
For detailed information about using the AnswerBook2 product or administering a documentation server, use the AnswerBook2 Help once you have a documentation server to access.
The following table indicates what you need to do or install to provide specific AnswerBook2 functionality.
Table 8-1 When and What to InstallIf you want to do this... | Then do this... |
---|---|
View online documentation from your desktop (any platform, any operating environment). | Start a web browser and enter the documentation server's URL (for example, http://imaserver:8888/). See "Launching the AnswerBook2 Viewer". |
Automatically launch a web browser with the appropriate server URL from your desktop. | If you are running the Solaris 7 operating environment, identify a documentation server and select the AnswerBook2 option from the CDE Help menu or the OpenWindowsTM Programs menu. See "Launching the AnswerBook2 Viewer". |
Enable your system (machine) to deliver (serve) documentation. | Install the documentation server software from the Solaris 7 Documentation CD. See "Installing Documentation Server Software". |
Add documentation from the Solaris 7 Documentation CD or other locations to your document server. | The document administrator is the only user authorized to perform this function. See "To Install Document Collections Onto the Server". |
The system launches a web browser with the URL for the document server if you are running the Solaris 2.6 (or later version) operating environment and you either:
Select the AnswerBook2 icon from the Help menu on the CDE Front Panel.
Select AnswerBook2 from the OpenWindows Programs menu.
Enter the answerbook2 command at the command line.
The system determines the web browser to launch by searching your path and launching Netscape NavigatorTM or the first web browser it finds. For information on how the system determines the URL for the documentation server, see "Finding a Documentation Server".
You can also access the AnswerBook2 product from any HTML 3.2-compliant web browser. Start your web browser and enter the appropriate documentation server URL. For example, if your system administrator installed an AnswerBook2 documentation server on the system imaserver using the default port number, you would type the URL: http://imaserver:8888/
Once you have launched the AnswerBook2 viewer, you click on underlined text (depending on how your browser is configured to display its links) to navigate to a book or chapter. For more information about how to navigate through the AnswerBook2 system, see the AnswerBook2 Help.
When you launch the AnswerBook2 viewer from the Solaris operating environment, the software displays a list of collections installed on the default documentation server. The default server is identified using the following mechanisms in this sequence:
If you have defined the environment variable AB2_DEFAULTSERVER the AnswerBook2 viewer launches using the URL defined by that variable.
For example, you might have the following line in your .cshrc file:
setenv AB2_DEFAULTSERVER http://imaserver.eng.sun.com:8888/ |
If the machine from which you initiated the AnswerBook2 function is a documentation server, the AnswerBook2 viewer launches using the URL: http://localhost:port
Where port is the port number on which the documentation server is running and defaults to 8888.
If your document administrator has registered the AnswerBook2 server with FNS (Federated Naming Service), the AnswerBook2 viewer uses the URL of the registered server.
If you have no document servers available and you have Internet access, you can also access Sun's master document server at: http://docs.sun.com/
This section explains the requirements you must meet and decisions you should make before you install the AnswerBook2 server software.
This section applies only to the person who is administering an AnswerBook2 server system. Users who are only viewing online documentation do not need to read this section. There is no specific installation needed to be an AnswerBook2 client.
There is no client-level access control for this product. If a client machine can access the URL for a documentation server, it can view the documents on that server.
This section contains the following information:
For detailed information about administering a documentation server, use the online Help available from the AnswerBook2 interface once you have installed the documentation server software.
Before you start the installation process, verify that your system meets the requirements listed in "Hardware and Software Requirements" and decide where you want to install the software as explained in "Installation Choices".
Before you start the installation process, verify that the systems on which you plan to install AnswerBook2 server software meet the hardware and software requirements listed in Table 8-2 and Table 8-3.
Table 8-2 Hardware and Software Requirements
Component |
Requirement |
---|---|
Documentation server system hardware |
SPARCstationTM 2 computer or higher (SPARCstation 5 computer recommended) Intel-based personal computer |
Operating environment |
Solaris 7 (for SPARC or x86, as appropriate) |
Admin GUI and AnswerBook2 client viewer |
Any HTML 3.2-compliant browser, such as Netscape Navigator, HotJava, or Lynx |
Table 8-3 Disk Space Requirements Table
Directory Path |
Description |
Space |
---|---|---|
/usr/lib/ab2/ |
Contains executable files, server processing files, library files, and graphics and document source files for the product interface. |
26.0 Megabytes |
/var/log/ab2/ |
Contains catalog files and log files, if logging functions are enabled. |
5.0 Megabytes (recommended - grows as server is used) |
/etc/init.d/ab2mgr |
Server start-up file |
0.01 Megabytes |
In addition, you need to set aside some amount of disk space (600 Megabytes recommended) for the actual book files. The exact amount of space depends on the specific collections. For a list of collections available on the Solaris 7 Documentation CD, see the README file located on that CD.
Before you install the AnswerBook2 server software, you should consider your installation choices:
Install everything on one system
The AnswerBook2 server software and Solaris 7 document collections are on the Solaris 7 Documentation CD. If you install both parts of the server product on a single system, when you finish the installation process and start the server, it will be ready to serve documents to all clients. See "To Install the AnswerBook2 Server Software" for more information.
Install server and documentation on separate systems
You can install the documentation server software on one system and point to document collections that are located on a different system. You might want to do this if you have minimal space available on your server's system or if you have existing collections on another system. To do this, you need to add each collection manually to the server's database and the Scan for Locally Installed Collections function will not find these collections. See "To Install the AnswerBook2 Server Software" for more information.
Run a server from the CD
If you are operating in a non-networked environment (stand-alone) or you only occasionally view the online documentation, you can run the AnswerBook2 server directly from the Solaris 7 Documentation CD. A documentation server run from the CD tends to be slower than a documentation server installed on your system. Do not use this approach if you expect other users to access this documentation server. For more information, see "To Run a Documentation Server From the Solaris 7 Documentation CD".
To install documentation server software, you can use the point-and-click interface available from the Solaris Web StartTM utility, or you can use standard installation utilities, such as pkgadd .
Insert the Solaris 7 Documentation CD into your CD-ROM drive.
The Volume Manager should automatically mount the CD.
If you choose to use the Solaris Web Start utility to install your products, double-click on the installer icon, follow the instructions on the Web Start screens, and go to Step 6.
The Web Start utility provides pre-selected groups of packages for you to install. Follow the instructions on the Web Start screens to continue.
If you choose to use the pkgadd utility or the swmtool utility, log in as superuser on the documentation server machine.
For example, enter the following at the command line:
% su - |
Change directory to the location of the documentation server packages.
For example, you might enter a command similar to the following to go to the location of the server software packages for a SPARC server:
# cd cdrom/Solaris_2.7_Doc/sparc/Product/ |
Where cdrom is the mount-point for the CD-ROM device and defaults to: /cdrom/sol_2_7_doc
Launch the installation utility and select the server software packages.
For example, use the following command to launch the pkgadd utility:
# pkgadd -d . |
Select these server software packages:
SUNWab2r (0.25 Megabytes) - Installs in root partition and provides configuration and start-up files.
SUNWab2s (1.00 Megabytes) - Provides shared files for performing document processing.
SUNWab2u (26.00 Megabytes) - Provides executable and back-end processing files for server and administration functions.
Start up the server, if needed.
Installing the packages should cause the server to start up on the default port of 8888. If it does not start, use the following command to start it:
# /usr/lib/ab2/bin/ab2admin -o start |
Install the book collections.
Your documentation server cannot do its job if no documents are installed for it to serve. You can install collections from the Solaris 7 Documentation CD or from other locations, such as existing document collections or collections that come on other CDs. For more information about installing document collections, see "To Install Document Collections Onto the Server".
(Optional) Change configuration files and create links to run the documentation server as a CGI process on an existing httpd server.
If you already run an httpd server on your system, yo u can run the documentation server as a CGI process on that server. You must ins tall the standard documentation server software, then change several configurati on files and create links to run the documentation server as a CGI process. For more information, see "Running the AnswerBook2 Server as a CGI Process".
(Optional) Register the server.
If you want other users to automatically find your documentation server through Federated Naming Service (FNS), you need to register the server. To register your server, use the following command:
# /usr/lib/ab2/bin/ab2regsvr server_url |
Where server_url is the fully qualified URL to get to this server (for example: http://imaserver.eng.sun.com:8888/). See "Registering the Server" for more information.
Your documentation server cannot do its job if no documents are installed for it to serve. You can install collections from the Solaris 7 Documentation CD or from other locations, such as existing document collections or collections that come on other CDs.
To install document collection packages from the Solaris 7 Documentation CD, you can use the point-and-click interface available from the Solaris Web Start utility, or you can use standard installation utilities, such as pkgadd . To install document collections:
Insert the Solaris 7 Documentation CD into your CD-ROM drive.
The Volume Manager should automatically mount the CD.
If you choose to use the Solaris Web Start utility to install your products, double-click on the installer icon, follow the instructions on the Web Start screens, and go to Step 6.
The Web Start utility provides pre-selected groups of packages for you to install. Follow the instructions on the Web Start screens to continue.
If you choose to use the pkgadd utility or the swmtool utility, log in as superuser on the documentation server machine.
For example, enter the following at the command line:
% su - |
Change directory to the location of the document collection packages.
For example:
# cd cdrom/Solaris_2.7_Doc/common/Product/ |
Where cdrom is the mount-point for the CD-ROM device and defaults to /cdrom/sol_2_7_doc.
Launch the installation utility and select document collection packages to install.
For example, to launch the pkgadd utility:
# pkgadd -d . |
For a detailed list of document collections included on the Solaris 7 Documentation CD, see the README file located on that CD.
The document collection packages included on the Solaris 7 Documentation CD include a post-install script that add the collections to the server's database and restart the server.
If you install collection packages from any other location besides the Solaris 7 Documentation CD, you might need to use either the Admin GUI's Add Collection to List function or the ab2admin -o add_coll command to add these collections to the documentation server's database.
If you have document collections already installed on your system, you can use either the Admin GUI's Scan for Locally Installed Collections function or the ab2admin -o scan command to have them found and added to the documentation server's database. This function only works for locally-installed packages.
To serve document collections located on some other system, use the Add Collection to List function or the ab2admin -o add_coll command and provide the full path name to the ab_cardcatalog or collinfo file. For example, if the documentation server is imaserver and you want it to serve document collections located on the system elsewhere, you might use the following command:
# /usr/lib/ab2/bin/ab2admin -o add_coll -d /net/elsewhere/books/SUNWdtad/collinfo |
To give users the ability to locate your documentation server without knowing the URL, you can register the name of your server with the FNS system. Users can still access unregistered documentation servers if they know the URL.
How you register your server depends on two things:
Your familiarity with FNS commands
If you are familiar with standard FNS commands, such as fnbind, you can use those commands to register the server. However, to simplify the registration process, the /usr/lib/ab2/bin/ab2regsvr command can register your server for you. For more information, see "Registering Your Server Using the ab2regsvr Command" and "Registering Your Server Using Standard FNS Commands".
What name service you are using
NIS+ (Network Information Service Plus) is the primary name service used for Solaris 2.6 and later operating environments. If your system is using NIS+ and you have administrative privileges, you can register the server while logged in on either the NIS+ master or NIS+ client system.
NIS (Network Information Service) was the standard name service provided in SunOS 4.x (Solaris 1.x) environments. If your system is using NIS, you must be logged in as root on the NIS master system to register the documentation server.
The AnswerBook2 product also works with a file system-defined naming system (files) in which all names are manually entered into data files. These files are stored in the directory /var/fn/. In this case, to register the server, you must have root access to the system and registration applies only on the machine on which it is registered. Other machines cannot see a server registered under a file system mechanism.
To register your server, use the ab2regsvr command. The ab2regsvr command looks at your system's configuration and sets up the appropriate name space for your server.
To register your server, type:
# /usr/lib/ab2/bin/ab2regsvr server_url |
Where server_url is the fully qualified URL to get to this server (for example: http://imaserver.eng.sun.com:8888/).
The ab2regsvr command also provides some other options you might find useful:
To view a list of registered AnswerBook2 server URLs:
# /usr/lib/ab2/bin/ab2regsvr -l |
To remove a registered server from the list:
# /usr/lib/ab2/bin/ab2regsvr -d |
To change the URL for the currently registered AnswerBook2 server:
# /usr/lib/ab2/bin/ab2regsvr -r server_url |
Where server_url is the new URL to get to this server (for example: http://aserver.eng.sun.com:8888/). This replaces any existing URLs with the specified URL.
For more information about the ab2regsvr command, see the ab2regsvr(1m) man page.
If you want to use FNS commands to register your server and you already have FNS installed at your location, use the following command to register the specified URL as a documentation server for your organization (domain):
# fnbind -r thisorgunit/server/answerbook2 onc_answerbook2 \ onc_addr_answerbook2 server_url |
Where server_url is the fully qualified URL to get to this server (for example: http://imaserver.eng.sun.com:8888/).
To find out what servers are currently registered, use the following command:
% fnlookup -v thisorgunit/service/answerbook2 |
This returns a list of registered servers that looks similar to the following:
Reference type: onc_answerbook2 Address type: onc_addr_answerbook2 length: 19 data: 0x68 0x74 0x74 0x70 0x3a 0x2f 0x2f 0x61 0x6e 0x73 http://ans 0x77 0x65 0x72 0x73 0x3a 0x38 0x38 0x38 0x38 wers:8888 |
In this example, the registered server is http://answers:8888/.
If you get a response similar to the following, then no documentation servers are registered with FNS:
Lookup of 'thisorgunit/service/answerbook2' failed: \ Name Not Found: 'answerbook2' |
For more information about FNS, including how to install it, see the FNS documentation.
Rather than using the described name services to find a documentation server, the user can define a default AnswerBook2 server using the environment variable AB2_DEFAULTSERVER. For example, the user could have the following line in the .cshrc file:
setenv AB2_DEFAULTSERVER http://imaserver.eng.sun.com:8888 |
If the user has not defined an environment variable, when the user launches the AnswerBook2 product from the desktop, the product looks to see if the system from which it was launched is running a documentation server. If so, it launches using the URL: http://localhost:port, where port defaults to 8888.
If the user has not defined an environment variable and the current system is not a documentation server, when the user launches AnswerBook2 from the desktop, the system performs an fnlookup thisorgunit/service/answerbook2 command to find out what documentation servers are available. It then chooses one of those servers and launches the AnswerBook2 browser using that server name for the URL.
Insert the Solaris 7 Documentation CD into your CD-ROM drive.
Make sure you are logged in as superuser.
% su - |
Change the directory to (or bring up and go to) the top level of the CD-ROM volume.
This should look similar to the following location:
/cdrom/sol_2_7_doc/ |
This directory contains one directory, a README file, the installer utility, and the ab2cd script. Use the ab2cd script to run the documentation server directly from the CD.
Type the following command:
# ./ab2cd |
Access the documentation server using the URL:
http://server:8888/ |
Where server is the name of the machine to which the CD-ROM drive is attached.
Note that a documentation server run from the CD always runs on port 8888.
(Optional) If document collections are installed already on your server machine and you want the CD-driven server software to recognize those collections, use the following command: .
# ab2cd -s |
This form of the command causes the CD-driven server software to look for other collections installed on this system and add them to its database.
To stop running the server from the CD, type:
# /cdrom/sol_2_7_doc/ab2cd stop |
Running the documentation server directly from the CD tends to be slow. Do not use this approach if you expect other users to access this documentation server.
Keep these things in mind when you run the server from the CD:
The AnswerBook2 server always runs on port 8888 when run from the CD. If you already have an AnswerBook2 server running on your system using the default port (8888), the ab2cd script will display the following message:
A document server is already running on this system as server:8888.
Please shut down the current server before running the ab2cd command.
Use the following command to shut down the existing server:
# /usr/lib/ab2/bin/ab2admin -o stop |
Always use ab2cd stop to stop the server running from the CD. Do not use /etc/init.d/ab2mgr stop to stop the CD-based server.
The ab2cd stop command stops the AnswerBook2 server process and cleans up all files in the /tmp/ab2/ and /tmp/ab2cd_config/ directories. The /etc/init.d/ab2mgr stop command stops all server processes, but does not clean up the files in the /tmp/ab2/ and /tmp/ab2cd_config/ directories.
To run two AnswerBook2 servers (one on your system, one from the CD), keep these rules in mind:
The /etc/init.d/ab2mgr start command always starts the server on your system.
The ab2cd command always starts the server from the CD.
Always use the ab2cd stop command to stop the server running from the CD.
To stop both servers, first use the ab2cd stop command to stop the server running from the CD, then use either /etc/init.d/ab2mgr stop or /usr/lib/ab2/bin/ab2admin -o stop to stop the server running on your system.
By default, the AnswerBook2 documentation server runs as an NSAPI plug-in on top of the httpd server that is included in the SUNWab2u package. Because the AnswerBook2 server complies with standard web protocols, you can choose to run the documentation server as a CGI (Common Gateway Interface) process on top of some other web server already on your system (for example, Netscape Server or Sun Web Server).
Be aware that the following functions will not work if you change from the default AnswerBook2 web server:
/usr/lib/ab2/bin/ab2admin -o start
/usr/lib/ab2/bin/ab2admin -o stop
/etc/init.d/ab2mgr start
/etc/init.d/ab2mgr stop
restart from the Admin GUI
Because specific details differ by web server, this procedure describes the general steps you need to follow to use a CGI-based web server rather than the default (NSAPI plug-in) server. Specific examples are included below for Sun Web Server and Netscape Server.
Shut down the AnswerBook2 server if it is running.
Use one of the following commands:
# /usr/lib/ab2/bin/ab2admin -o stop # /etc/init.d/ab2mgr stop |
Edit your web server's configuration file and make icons available.
Your web server's documentation should explain specific details, such as where to find the configuration file. The entry /icons/ should point to /usr/lib/ab2/data/docs/icons/.
If /icons/ is already being used, link all files in /usr/lib/ab2/data/docs/icons/ to the existing /icons/ directory.
Link AnswerBook2 Help documents to the current documentation root directory.
Go to your web server's documentation root directory and create a soft link to /usr/lib/ab2/data/docs/.
Make AnswerBook2 cgi-bin files available to your server.
Go to your web server's cgi-bin directory and create soft links to the following:
/usr/lib/ab2/bin/cgi/admin /usr/lib/ab2/bin/cgi/nph-dweb /usr/lib/ab2/bin/cgi/gettransbitmap /usr/lib/ab2/bin/cgi/getepsf /usr/lib/ab2/bin/cgi/getframe /usr/lib/ab2/bin/cgi/ab2srwrap |
Edit your web server's configuration file and map /ab2/ to call AnswerBook2 cgi.
Your web server's documentation should explain specific details, such as where to find the configuration file. You need to change the entry for /ab2/ to /usr/lib/ab2/bin/cgi/nph-dweb/ab2/.
Edit the AnswerBook2 administration configuration file.
You need to edit the /usr/lib/ab2/bin/cgi/nph-dweb file and change the entries for servertype, errorlog, and accesslog.
By default, the Sun Web Server configuration file is /etc/http/httpd.conf and files are in /var/http/demo/. If you did not install in the default location (/usr/), all paths that begin /usr/lib/ab2/ should be the path where you installed the files (for example, /usr2/lib/ab2/).
Edit the /etc/http/httpd.conf file and put the following line in the server section of the file:
map /icons /usr/lib/ab2/data/docs/icons |
When you have made this change, use the following command to restart the SWS server:
# /etc/init.d/httpd start |
To verify your changes, enter the following URL in your web browser to see a Help icon:
http://localhost:port/icons/ab2_help.gif |
Where port is the port number on which your documentation server is running and defaults to 8888.
Go to the /var/http/demo/public/ directory and put in the following soft link:
# ln -s /usr/lib/ab2/data/docs/Help Help |
To verify your changes, enter the following URL in your web browser to see a Help icon:
http://localhost:port/Help/C/Help/books/Help/figures/ab2_help.gif |
Where port is the port number on which your documentation server is running and defaults to 8888.
Go to the /var/http/demo/cgi-bin/ directory and create the following soft links:
# ln -s /usr/lib/ab2/bin/cgi/admin # ln -s /usr/lib/ab2/bin/cgi/nph-dweb # ln -s /usr/lib/ab2/bin/cgi/gettransbitmap # ln -s /usr/lib/ab2/bin/cgi/getepsf # ln -s /usr/lib/ab2/bin/cgi/getframe # ln -s /usr/lib/ab2/bin/cgi/ab2srwrap |
To verify your changes, enter the following URL in your web browser to see the AnswerBook2 library page:
http://localhost:port/cgi-bin/nph-dweb/ab2 |
Where port is the port number on which your documentation server is running and defaults to 8888.
Edit the /etc/http/httpd.conf file and add the following entry in the host section of the file:
map /ab2 /var/http/demo/cgi-bin/nph-dweb/ab2 cgi |
Restart the SWS server using the following command:
# /etc/init.d/httpd start |
To verify your changes, enter the following URL in your web browser to see the AnswerBook2 library page:
http://localhost:port/ab2 |
Where port is the port number on which your documentation server is running and defaults to 8888.
Edit the /usr/lib/ab2/bin/cgi/nph-dweb file and change the following entries:
setenv servertype sws setenv errorlog setenv accesslog /var/http/logs/http.elf.1 |
For this example, the Netscape Server configuration file is /ul/netscape/suitespot/httpd-threads1/config/obj.conf and files are in /ul/netscape/suitespot/docs/. If you did not install in the default location (/usr/), all paths that begin /usr/lib/ab2/ should be the path where you installed the files (for example, /usr2/lib/ab2/).
Edit the /ul/netscape/suitespot/httpd-threads1/config/obj.conf file and add the following line:
NameTrans fn="pfx2dir" from="/icons" dir="/usr/lib/ab2/data/docs/icons" |
To verify your changes, restart the Netscape Server. Then, enter the following URL in your web browser to see a Help icon:
http://localhost:port/icons/ab2_help.gif |
Go to the /ul/netscape/suitespot/docs/ directory and put in the following soft link:
# ln -s /usr/lib/ab2/data/docs/Help Help |
To verify your changes, enter the following URL in your web browser to see a Help icon:
http://localhost:port/Help/C/Help/books/Help/figures/ab2_help.gif |
Where port is the port number on which your documentation server is running and defaults to 8888.
Go to the /ul/netscape/suitespot/cgi-bin/ directory and create the following soft links:
# ln -s /usr/lib/ab2/bin/cgi/admin # ln -s /usr/lib/ab2/bin/cgi/nph-dweb # ln -s /usr/lib/ab2/bin/cgi/gettransbitmap # ln -s /usr/lib/ab2/bin/cgi/getepsf # ln -s /usr/lib/ab2/bin/cgi/getframe # ln -s /usr/lib/ab2/bin/cgi/ab2srwrap |
To verify your changes, enter the following URL in your web browser to see the AnswerBook2 library page:
http://localhost:port/cgi-bin/nph-dweb/ab2 |
Where port is the port number on which your documentation server is running and defaults to 8888.
Edit the /ul/netscape/suitespot/httpd-threads1/config/obj.conf file and add the following entry:
NameTrans fn="pfx2dir" from="/ab2" dir="/ul/netscape/suitespot/cgi-bin/nph-dweb/ab2" name="cgi" |
To verify your changes, restart the Netscape server and enter the following URL in your web browser to see the AnswerBook2 library page:
http://localhost:port/ab2 |
Where port is the port number on which your documentation server is running and defaults to 8888.
Edit the /usr/lib/ab2/bin/cgi/nph-dweb file and change the following entries:
setenv servertype netscape setenv errorlog /ul/netscape/suitespot/httpd-threads1/logs/errors setenv accesslog /ul/netscape/suitespot/httpd-threads1/logs/access |
Table 8-4 lists some areas of known confusion in the AnswerBook2 product and provides suggestions for how to respond to them.
Table 8-4 Possible Server Problems
For this issue... |
Consider this... |
See also... |
||
---|---|---|---|---|
Edit the /usr/lib/ab2/dweb/data/config/dwhttpd.cfg file and change the host name to hostname.domain. For example, instead of the following line:
|
If the problem persists, try turning off the proxies on the web browser. |
|||
Browser errors indicating documentation server is not responding |
If the documentation server is not responding, restart it. |
For information on stopping and starting the server, see the AnswerBook2 Help. |
||
Error 404, File not Found when trying to access the documentation server |
A server process is running, however the server software has been removed. Reinstall the server software. |
For information on installing the software, see "Installing Documentation Server Software". |
||
User indicates that library page displays only the navigation bar and no document collections |
Verify that the collections template file (/usr/lib/ab2/dweb/data/config/ab2_collections.template) does not contain any empty or duplicate entries. |
If fixing the template file does not correct the problem, you might need to reinstall document collections or server software. For information about installing the software, see "To Install the AnswerBook2 Server Software". |
||
User reports seeing red text and the word "BUG" in a book (or several books) |
The book's source contains markup tags that AnswerBook2 does not recognize and the AB2_DEBUG environment variable is set to "1" on the server. |
To turn off the bug display, set the AB2_DEBUG environment variable to "0," stop the server and start the server. Contact whoever provided the book to get the markup fixed. |
||
Unable to access administrative functions on documentation server |
The documentation server uses access control mechanisms to identify users who can perform administrative functions. The AnswerBook2 administration tools allow the document administrator for the server machine to add and remove administrative users for the server and change their passwords. |
To add or remove administrative users for your server, see the AnswerBook2 Help. If you need access to another server, contact the document administrator for that server. |
||
Cannot perform administrative commands from AnswerBook2 Administration GUI (browser interface) |
Certain functions do not work from the Admin GUI because of permission issues. Try to perform the same function from the ab2admin command-line interface. |
For information about the command line options, see the ab2admin(1m) man page. |
||
A Scan for Locally Installed Collections function does not list document collections that are installed on a local mount point |
Verify that the directory into which the collections were installed has read access set for others. |
|
||
You added an AnswerBook1 collection, but users do not see it in their libraries |
Verify that the information in /var/log/ab2/catalog/ab1_cardcatalog is correct. |
This means something is wrong with the collection's data in the ab_cardcatalog file. |
||
You see the message Failed to add collection. when trying to add a collection through the Admin GUI |
Verify that the path to the collection's collinfo or ab_cardcatalog file is correct. |
|
||
Using the restart command to restart the documentation server failed or did not produce the expected results |
In some instances, the restart command does not work correctly. |
Use the stop and start commands instead. |
||
Document collections appear to be corrupted and need to be reinstalled |
Use the ab2admin -o del_coll function or Delete Collections from List in the Admin GUI to remove these collections from the documentation server's database. Then, use pkgrm to remove them from the server before installing the new packages. |
For more information about removing collections, see the AnswerBook2 Help. |