README for xdocviewer 2.0.1
---------------------------

CHANGES since xdocviewer 1.0
----------------------------

xdocviewer 2.0.1 adds support for the Solaris 2.0 and 2.1 AnswerBook releases,
It has been tested against the "minimal" (i.e., completely on-disk)
configuration of AnswerBook for Solaris 2.0 and AnswerBook for Solaris 2.1.

xdocviewer 2.0.1 does NOT support the AnswerBook release that comes with
Solaris 2.2 (and future versions)!!!  Sun drastically changed the format of
the AnswerBook in the Solaris 2.2 version.  I have neither the time nor the
inclination to figure out what the h*ll they did (I also have no steady access
to a Solaris 2.x machine, anyway).

xdocviewer is a Perl language script that allows one to display Sun's
AnswerBook documentation on machines that only run plain X11 servers, such as
X terminals.  It makes these basic assumptions:

- You need AnswerBook installed somewhere, and the "bookinfo" file installed
  (default is /etc/bookinfo).  If you don't have a bookinfo file, you can
  create one by running the "answerbook_demo" script on the AnswerBook CD-ROM
  and then make an appropriate substitution of "../" to something else
  (like "/cdrom/" or "/usr/AnswerBook/SysSoft_1.3", for example).  Then install
  the "bookinfo" file somewhere, like /etc/bookinfo, or somewhere else (and
  then set your BOOKINFO env. variable appropriately).

- You need the XView libraries - libxview.so.3.x, libxview.sa.3.x, and
  libolgx.so.3.x and libolgx.sa.3.x - installed somewhere, either in a standard
  place (/usr/lib, /usr/local/lib, or in your X11 installation directory's lib
  directory) or somewhere else with the LD_LIBRARY_PATH variable set as
  appropriate to point to them.

- You need a GhostScript previewer.  The supported ones are ghostview 1.3 and
  gspreview 2.1.  Both of these support the "-page" option which allows you to
  bring up a document at a specific page, rather than at page 1.  It is presumed
  that later versions of each (ghostview 1.4.1 and gspreview 2.2, for example)
  will probably work as well.

- You need Perl (-:  This script was written using Perl 4.0.19.  It should
  work fine under Perl 4.0.35 or 4.0.36, as far as I know.

Previous versions of this README have led to confusion on how to use this Perl
script.  What you need to do is this:

Take the "xdocviewer" script, make it executable and change the first line to
point to wherever your "perl" executable lives.  Then, move it to your
destination directory; e.g. "/usr/local/bin".  Change the name of the script
to "docviewer"; e.g. "/usr/local/bin/docviewer".  This is very important;
both the "answerbook" script as well as the "Navigator" program expect to fire
up a document viewer program by the name of "docviewer".  IF YOU TRY TO RUN
THIS SCRIPT DIRECTLY, OR KEEP IT'S NAME "xdocviewer", IT WILL FAIL.  Just as
the OpenWindows NeWS-based "docviewer" program expects to be fired up from
another program with appropriate arguments, so does this Perl script!

You then need to modify your "answerbook" shell script - as stated in the
comments in the Perl script - to make sure that the Perl script is executed
as "docviewer" ahead of the NeWS-based "docviewer".  Ordinarily, the default
"answerbook" tries to put the directory $ABHOME/bin (which normally
contains the NeWS-based "docviewer") ahead of the rest of your $PATH, and thus
the script will not get run.  Also, the default "answerbook" tries to use a
NeWS program ("psh") to determine what version of the OpenWindows server is
running; it only needs this information to determine which version of the
Navigator program to use (which depends on the XView libraries).  If you know,
for example, that you have the OpenWindows 3.x XView libraries, you can
comment out the "psh" invocation in the script and simply hard-code the
version variable to be "3".  You might consider renaming the thus-modified
"answerbook" script to be something else, like "xanswerbook" - especially in
case other people use "answerbook" directly under OpenWindows on a Sun, in
which case they might not like having a GhostScript previewer pop up on their
screen (-:  Renaming the changed "answerbook" would avoid these problems.

Once you have made these changes, you should be able to run the "answerbook"
script without difficulties.

If you have problems, bug reports or questions, send e-mail to the author:

	earle@isolar.Tujunga.CA.US		(Internet)
a.k.a.	isolar!earle@elroy.JPL.NASA.GOV		(UUCP)

Enjoy,

	- Greg Earle

P.S. I am no longer working for Sun Microsystems, so please do not send e-mail
     to my previous address, "earle@Sun.COM" or "earle@poseur.JPL.NASA.GOV".
     Thanks.