Release notes for VMS changes to Ghostview
8/18/92, Terry Poot <tp@mccall.com>

Introduction
------------

I've gotten Ghostview version 1.4 working on VMS 5.5, compiled with VAX C
v3.2, and using Ghostscript 2.4.1 and George Carrette's
<gjc@mitech.com> port of the R5 Athena widgets.

Ghostscript availablility is, I believe, mentioned in the Ghostview readme
files.

George's kit for building the Athena widgets is available from
vmsnet.sources archive sites, including FTP from white.cerritos.edu
[130.150.200.22] and acfcluster.nyu.edu , and mailserver access from
MAILSERV@Cerritos.edu. (Send a message with 'help' in the body for
instructions.) You will also need the directories mit/lib/Xmu and
mit/lib/Xaw from the MIT X11r5 source kit. I think you can get them from
export.ai.mit.edu. I don't know of any non-FTP way other than finding a
friend who can send them to you (that's what I did).

There's nothing I can think of in the changes to require any of these
specific versions. I suspect it will work on VMS 5.0 or later, possibly
even 4.7. I don't have any of these systems to test on, however. Also, any
Ghostscript supported by Ghostview should work, as NO changes were made to
Ghostscript to support Ghostview on VMS.

I did this port specifically because I required a Postscript previewer for
my current project, to preview files created by my applications. It is
likely that anything I don't use hasn't been tested much, if at all.
However, the relatively small number of changes is encouraging, and the
changes themselves have all been tested.

The 2 large areas of changes are processing of print requests, and the
communications between Ghostview and Ghostscript. The changes to the print
code are in the routine print_file in misc.c, and changes to the resources
used by that code are in main.c. Changes to the communications code are all
in the ghostview widget, which is in ghostview.c, with changes to the
widget structure in ghostviewp.h. Most other changes were simple things
like dealing with different include files to get the program to compile.

Building
--------

There are 2 build procedures provided. If you have MMS, you can use the
DESCRIP.MMS description file. If not, there is a DCL procedure name
VMS_BUILD.COM. The command procedure builds everything, whereas MMS will
only build the things that have changed. 

VMS POSIX is used to convert the application defaults file to a C include
file for use as fallback resources. The include file is provided for the
shipped version of the application defaults file, but if you don't have
POSIX installed, you won't be able to automatically update the include file
to match changes you make to the application defaults file. Note that the
data in the include file is used only if you do NOT install the application
defaults file on your system (see the Installation section below). 

(If you have a unix system available, you can move files back and forth
manually and run ad2c on that machine to create an updated app-defaults.h.)

If you have MMS:

First, edit DESCRIP.MMS. Change the second line to show the proper location
on your system for the command procedure that defines the Athena logical
names (this is the LOGICALS.COM procedure that came with George Carrette's
Athena widget kit). Also, if you don't have VMS POSIX 1.0 installed on your
system, delete the line that starts:

source:app-defaults.h : source:Ghostview.ad

and the following action lines, or just add a "!" before the POSIX/RUN
command. 

Once you've made these changes, just type "MMS" and it should build.

If you don't have MMS:

First, edit VMS_BUILD.COM. Change the first line to show the proper
location on your system for the command procedure that defines the Athena
logical names (this is the LOGICALS.COM procedure that came with George
Carrette's Athena widget kit). Also, if you don't have VMS POSIX 1.0
installed on your system, delete or comment out the line that contains the
command POSIX/RUN. Then simply type in "@VMS_BUILD".

You might notice that we don't use all the source files. The ones not part
of the VMS build procedure aren't needed for VMS. This includes setenv.c,
getenv.c, and all source files for the select file widget. The file
vms_types.h is new, and is used to define VMS data structures in
ghostview.c. This file was written by Jym Dyer in 1989, so I don't know if
the email address in the file is still good. I added a definition to it
(IOSB_GET_T). It was already Copyright'ed under the GPL, so there's no
conflict including it here.

Installation
------------

To run Ghostview, you must define a foreign command for it. This can be
done in a user's login.com, or in the system wide sylogin.com for
convenience. The command to do this is:

$ gv :==$dev:[dir]gv.exe

Fill in the device and directory for your site. Note the "$" after the
":==". It's important that it be there.

You can call this something other than gv, but DON'T call it ghostview!!!
Repeat: DON'T CALL IT GHOSTVIEW!!! If you do, Ghostscript will no longer
work on your system, except (maybe) when called by Ghostview. The reason,
for the curious, is that Ghostscript expects the environment variable
GHOSTVIEW, if it exists, to be the window id of the window it should draw
on. That's how Ghostview gets Ghostscript to use a Ghostview window for
output. Symbols, including foreign command symbols, will be seen as
environment variables, so Ghostscript will try to use your command
definition as a window id, and choke and die.

Speaking of Ghostscript, the default resource setup expects it to be
defined as a foreign command named gs. If you choose to call the
Ghostscript command something else, you'll need to change the interpreter
resource of Ghostview to the command needed to run Ghostscript (or supply
the -interpreter command line option). It MUST be defined as a foreign
command so that Ghostview can set some command line options.

The application defaults file can be installed system-wide by copying it to
DECW$SYSTEM_DEFAULTS:GHOSTVIEW.DAT (you have to have privileges to do
that). Alternately, each Ghostview user can copy it to
DECW$USER_DEFAULTS:GHOSTVIEW.DAT. (DECW$USER_DEFAULTS usually points to the
user's login directory.) If that file is not found, the compiled in values
will be used. Therefore, if you install the application defaults file, you
don't really have to worry about keeping app-defaults.h up to date, as it
is only used if the app defaults file isn't found. You will especially want
to install the file if you don't have VMS POSIX available to maintain the
include file that is derived from it.

Notes for application users
---------------------------

There aren't too many differences to worry about. 

No attempt has been made to port the select file widget. Any prompt for a
file name will simply pop up a dialog box into which you type the file
name. I'd have tried to integrate the DECwindows file selection widget, but
this is an Athena program, and I figured the hassle to get it all to work
together wouldn't be worth the trouble. Besides, in my application, I
didn't need it. :-)

Also the print related resources have been changed a bit. 

The printCommand resource must be a command that takes a filename argument.
The default for printCommand is "Print_dcl/Delete". The "_dcl" suffix is to
avoid any symbol redefinitions of the print command.

The printerVariable resource is the name of a logical name that may contain
qualifiers to the print command. The logical name has been changed from
PRINTER to GV_PRINT_QUAL to make it a little bit safer to set system wide,
for instance with a /QUEUE=xxx qualifier to point to the queue serving your
postscript printer. The printPrompt resource has been changed to "Print
Qualifiers: " to reflect this usage.

defaultPrinter defaults to NULL, but it will be set the the equivalence
string for GV_PRINT_QUAL at application startup if that logical is set (or
whatever logical might be named in printerVariable if you change it). Thus
you can default the print queue either with a logical name or by putting it
in Ghostview's application defaults file.

Any print command can be used, but bear in mind that it must take one
argument, which is a temporary file name. The print command must delete
this file or it will be left lying around. printerVariable may be used to
pass any qualifiers to the command. It can be used to select a print queue,
form, etc. This is the item that is prompted for when you tell it to print.
(printPrompt has been changed from "Printer Name:" to "Print Qualifiers:").
If you define a logical name or symbol named GV_PRINT_QUAL (or some other
name if you change printerVariable) it will be used as the
default response for this prompt.

The command executed in any print request is the value of printComand,
followed by a space and then by the print qualifiers specified by the user
(which default to defaultPrinter, see above) followed by another space and
then the temp file name. You can fill in these 2 resources to suit
your needs. Just remember the user can over-ride the second one at run
time. (That's why the /DELETE is part of the print command as distributed,
rather than included as a default in defaultPrinter.)

This would make a bit more sense if I'd renamed the resources, but that
would have created a lot of VMS specific code for little actual gain. If it
helps you keep track of them, here's a brief summary table:

resource           VMS Value           What it is
--------           ---------           ----------
printCommand       PRINT_DCL/DELETE    The print command
printerVariable    GV_PRINT_QUAL       logical name to hold default qualifiers
defaultPrinter     <empty>             Default qualifiers, over-ridden by
                                       GV_PRINT_QUAL if set
printPrompt        "Print Qualifiers:" Just a prompt string

Notes for widget users
----------------------

See the notes for application users for differences in resources.

The widget uses VMS Event Flag number 23. You can change the event flag
number by changing the define for XtEFN in ghostview.c. Ghostview can
tolerate other modules in the program setting the flag, as it always checks
for actual I/O completion using IOSB's. However, if you clear the flag, Xt
may miss an I/O completion and your program could hang. Best to simply
avoid it.

I've made changes to the definitions of the widget data in ghostviewp.h.
I've ifdef'ed out data items not used in the VMS version and added a few
that I needed under VMS. I might have missed a few of the former kind, but
if so,  they should just sit around unused and not bother anyone.
--
Terry Poot <tp@mccall.com>                   The McCall Pattern Company
(uucp: ...!rutgers!depot!mccall!tp)          615 McCall Road
(800)255-2762, in KS (913)776-4041           Manhattan, KS 66502, USA
