Atari Mega Archive 1/Atari Mega Archive - Volume 1.iso/gnu/gscript/gs261b.zoo/doc/readme.st

Text File | 1994-01-07 | 19.2 KB | 425 lines

/*
 *    Atari Ghostscript 2.61
 */

GHOSTSCRIPT OVERVIEW:    9/93

Ghostscript is the GNU project's postscript language interpreter (the
kernal is written and maintained by Peter Deutsch -- [e-mail]).
It can be used to convert postscript files into formats suitable for
non-postscript printers, or to display postscript files on the screen.

The primary enhancements to the GS 2.61 kernal are increased support
for level 2 postscript, and the ability to use platform fonts in place
of the (slightly deficient) GS fonts.  This ST version of GS does not
make use of the platform font capability, but in principle someone
could write some routines which would allow Atari GS to use GDOS or
SpeedoGDOS fonts.

A good deal of the Atari-specific code has been rewritten for GS 2.61.
GS now operates as a full GEM application. By default, GS will open
two windows, one for the image and one for text I/O. Text I/O is slow
but it is a start. I really can't think of an application where fast
console I/O is needed anyway, so it shouldn't be too painful.

The binary distribution contains the executables, a bunch of postscript
support files, some relevant docs, and the default Ghostscript font.
Since the changes to the standard Unix GS source are now trivial, I
have included the source files specific to the ST in the same archive.

The standard source and fonts for 2.61 (you can use the old fonts if
you want) are available from prep.ai.mit.edu and its mirror sites, and
a good number of other sites which carry unix source code, ftp.uu.net.

Towards the end of this file is a brief description of some features
of Atari GS which are specific to the Atari platform. You may want to
review it after getting GS installed.


SYSTEM REQUIREMENTS:

To run GS, you probably need a minimum of 2.5M ram and 1M of free disk
space (as long as you write no files to disk).  How much you can get
by with really depends on the PostScript files you want to process,
since alot of memory is allocated dynamically.  If you get all of the
GS fonts, you will need another 3M of disk space.  I run GS on a 4M
520ST with an 85M hard drive and a monochrome monitor, so it is hard
for me to estimate a minimum hardware configuration.  You can always
try with less.

Keep in mind that a 300dpi image requires a little over 1M of memory,
so high resolution printing requires either lots of memory or band
printing (see the docs).  Color is a real memory hog, so you may have
to decrease the resolution for color images (screen images cannot be
printed in bands).  Documents which load lots of fonts can also hog
lots of ram.

You can probably get by without a hard drive if you are willing to use
only the ghostscript default font.  The font files take up about 3 Meg
of disk space.  For graphics, the default font is fine, but text will
be ugly.


INSTALLATION:

In addition to the executable, you will need a set of PostScript
support files, some fonts (at least the default font), and a file
called fontmap.  When GS is executed, it reads a number of the
PostScript files to initialize itself.  The fontmap file contains a
list of which fonts reside in which disk files.  Ghostscript must be
able to locate all of these files in order to execute successfully.

I have Ghostscript installed as follows:

f:\gs        GS source and executable,
f:\gs\ps    GS PostScript support files and
        other PostScript source (pictures),
f:\gs\fonts    GS fonts.

When Ghostscript needs a file, it searchs a list of directories
until it finds what it needs. Which directories it searches is
determined as follows:

1.) The current directory is searched first.

2.) Directories to be searched can be specified from the GS command
line with the -I option.

3.) Directories specified by the GS_LIB environment variable are
checked next.  Gem users may be unfamiliar with environment variables.
Basically, this is just a global variable stored by the computer in a
location which is accessible by all programs running on the machine.
Most shells have commands that allow you to set environment variables.
If you are running from the desktop, you may need an auto-folder
program (I believe GEMENV is the name of one such program) which will
set environment variables for you.

If GS cannot find the files it needs, it will look to see if the
environment variable GS_LIB has been defined.  If the environment
variable GS_LIB is "c:\gs,d:\gs,e:\gs" GS will search the directories
c:\gs, d:\gs, and e:\gs in sequence for the files that it needs.  This
comma-separated list of directories is called a "path".

4.) If all else fails, GS searches a default path of
".,f:\gs,f:\gs\ps,f:\gs\fonts", which is compiled into GS.  This
corresponds to my setup.  When GS needs a file, it first looks in the
current directory (.), then in f:\gs, then in f:\gs\ps, and finally in
f:\gs\fonts.

If your installation corresponds to the default path, you need not
worry about any environment variables.  If the directories used in
your installation do not correspond to the default path, you will want
to set up your computer to automatically define GS_LIB to be a COMMA
separated path (corresponding to your setup) for ghostscript to
search.  If you specify file paths on the command line, you may use
either '/' or '\' as a path separator.

To install:

1) Copy gs261b.zoo to the desired directory (f:\gs to use the default
    search path).

2) Unpack the archive with 'zoo e// gs261b.zoo'
    This will produce a directory structure as follows:
    . (current directory)    GS executable,
    .\ps            GS PostScript support files and examples,
    .\fonts            Default font and fontmap.

    If you want the root gs directory to be somewhere besides
    f:\gs, define the environment variable GS_LIB to be a comma
    separated search path which contains the files in the
    'ps' and 'fonts' directories. You will probably want to
    set up your system so that this environment variable is
    defined    automatically at boot time (or you can use gemGS
    to define it whenever GS is run).

USAGE:

To use ghostscript:

1) To display a file on the screen:
    Type 'gs file1.ps file2.ps ...' on the command line. The default
    device is the screen at 80 dpi. You can specify (with the -r
    option) as much resolution as you have memory for, but it may
    take forever to construct your image. See the file use.doc
    for how to change the device.

    GS will open a console window, and will write some initialization
    messages to it. The mouse will turn to a busy bee while GS is
    creating a bitmap of the image. If you are using the screen
    (stvdi) device, an image window will eventually open and the
    image will be displayed (this can take a long while for complicated
    files or high resolutions). You can then scroll around the image
    using the scroll bars or the cursor keys.

    Usually the last postscript command on a PS page will be
    "showpage". The showpage command causes the page to be displayed
    and then waits for the user to enter a <return> before proceeding
    to the next page. When all pages have been displayed, GS displays
    a GS> prompt in the console window. Postscript commands typed in
    the console window will then be executed by the PS interpreter. For
    example, typing "(file.ps) run" after the prompt will cause
    file.ps to be displayed. This is a useful thing to know, since
    it allows you to display more images without having to wait
    through another long GS initialization. The output device and
    the image resolution may also be changed from the command line
    using the putdeviceprops command. See the docs for details. I
    plan to make these actions available from menu selections in
    later versions. Typing "quit" at the command line will cause
    GS to exit.

    Selecting the Run entry of the File menu allows postscript
    files to be selected with the file selector. The selected
    file will automatically    be sent to the interpreter. I think
    the other menus are self-explanatory.

    If the environment variable GS_WIN is set to "off", then windows
    will not be used. In this case, you can move around the image with
    the cursor keys, and type "q" when you have finished viewing
    the image. Press the help key for further information.

2) To use a printer device:
    Type "gs -sDEVICE=djet500 file.ps" for a
    deskjet 500, "gs -sDEVICE=epson file.ps", etc. Type "gs -h" for
    a list of available printer devices. I found it convenient to
    define a shell alias for "gs -sDEVICE=djet500". The printer output
    will be written in a file called "gs_pr.XXX", where XXX is a
    unique number. See the docs for other ways to select a device
    or to see which devices are installed. Output can be redirected
    to a file of your choosing, or to the printer with the
    "-sOutputFile=filename" option. OutputFile=PRN: or CEN: will
    send output to the printer port (CEN: prints faster, but is
    less compatible).

3) To send the output file to the printer:
    Since it is a binary graphics file, you will
    need a print utility which does NOT try to add carriage
    returns and such at ends of lines. I wrote a small program
    to print these files, called 'bpr'. It was intended for a
    DeskJet, but it apparently works reasonably well with other
    printers. Bpr is available from lifshitz.ph.utexas.


ATARI FEATURES:

Here is a brief overview of the Atari-specific features:

1.) Windows are now used by default.  When GS is started, a console
window is opened and stdin, stdout, and stderr are directed to it.
This makes GS a real GEM application, and eliminates some awkwardness
with using windows in earlier versions.  Windows may be disabled by
setting the GS_WIN environment variable to "off".  This is different
from the previous usage of the GS_WIN variable.  Despite the added GEM
functionality, GS can still require a large number of command line
parameters.  For this reason, users may still find some use for gemGS,
a GEM shell which I wrote for GS.  GemGS 1.3 should still work well
with GS 2.61, except that the windows option in GemGS should be turned
off.  This prevents GemGS from forcing several GS command line
parameters which are no longer necessary, but GS 2.61 will still use
windows.

The console and image windows are standard, with all of the standard
gadgets.  Everything operates in the normal fashion, except for the
arrow buttons in the scroll bars of the image window.  These normally
scroll one line, which makes little sense for an image.  So, I used
these buttons for "top of page", "bottom of page", etc.  Note that
closing the console window will cause GS to exit.

The x coordinate of the console window will always snap to the nearest
word, so it may not end up exactly where you put it when you move the
window.  This is an attempt to keep the text word aligned, which is
supposed to improve text output speed.

2.) The stvdi screen device supports 1-, 2-, 4-, 8-, and another attempt
at 16-bit color.  The 16-bit color has not been thoroughly tested, so
it may not work properly, if at all.  There are some improvements in
the way 2 and 4 bit color are handled, which should result in better
speed, more free memory, and more accurate color.  Please note that
only so much that can be done with 2-bit color.

Vdi routines are used to determine the screen parameters and to copy
to the screen, so graphics should work with lots of different screen
devices.  The price of compatibility, however, is alot of image
transformation.  Some transformations are now written in assembler in
an attempt to speed things up a bit.

The screen driver allocates colors dynamically as the GS kernal
requests them.  For 2 and 4 bit color, GS spaces colors equally
throughout the color cube, and then approximates the needed colors by
dithering the two closest colors in the palette.  Because of the
dynamic color allocation, you may see colors changing on your screen
while GS is running.  In all but 2-bit mode, GS attempts to avoid
changing the color of the desktop, so if your foreground and
background colors are black and white, you shouldn't see too many
disturbing color changes.  Of course, the original palette is restored
when GS exits.  Thanks to Markus Wenzel for the routines to set and
save the color palette.  In the future, I will try to make these color
changes a little less disconcerting.

3.) There are two ways to send output directly to the printer.
Including '-sOUTPUTFILE=PRN:' on the command line will send output to
the centronics port via Gemdos.  The name 'OutputFile' can be used
instead of 'OUTPUTFILE' if desired.  The option '-sOUTPUTFILE=CEN:'
will write output directly to the centronics port.  The routines for
direct centronics output were contributed by Chris Strunk
(CS-TeX)--THANKS!  Direct centronics output is generally much faster
(about a factor of 4 for heavy graphics).  For some unknown reason,
the CEN: option does not work properly on some STEs and TTs.  (A
solution to this problem will probably require the debugging efforts
of someone who has this difficulty.)

For those with an Atari SLM printer, this driver sends output directly
to the printer (running the Diablo emulator), so there is no need to
specify the OUTPUTFILE. Some problems have been reported with using
the old Diablo emulator, so the newest one is recommended.

4.) The number of available drivers has increased to the point that it
is not feasible to include all that an ST owner might reasonably use.
The current choice of 21 drivers was decided mostly by a vote of GS
users on the internet (a couple were included at my whim).  Type 'gs
-h' for a list of the available drivers.

stvdi    - The screen device. Supports 1, 2, 4, 8, and 16 bit color,
slm      - Atari SLM laser printer (thanks to Robert Stabl),
gemimg   - GEM bitmap format (thanks to Marcus Haebler),
djet500  - HP DeskJet 500,
djet500c - Color HP DeskJet 500,
cjd500   - Another DeskJet 500c driver -- higher quality output -- slower,
cjd550   - DeskJet 550c driver,
laserjet - HP LaserJet (and old deskjets),
bj10e    - Cannon BubbleJet,
escp2    - Epson esc p2 language printers, including the Stylus 800,
epson    - Epson 9 and 24 pin printers (limited resolutions),
eps9high - High resolution Epson 9-pin device (makes multiple passes),
epsonc   - Color epson printers,
necp6     - NEC 360 dpi printer,
gifmono  - GIF monochrome bitmap format,
gif8     - GIF 8-bit color format,
pbmraw   - Mono portable bitmap format,
ppmraw   - Color portable bitmap format,
filter   - Filter device,
dps      - Display postscript (partial implementation),
level2   - Level 2 postscript (partial implementation).

The following environment variables are specific to the Atari port
of GS. See use.doc for standard environment variables (like GS_LIB).

GS_WIN:    Set this to "off" to disable windows. Otherwise the value of
    this variable is ignored.

GS_DISPLAY: Set this to "chunky8" to tell GS that your screen hardware
    uses chunky pixel format. I don't think any graphics boards
    actually use this format, but if they do, this will allow GS
    to skip two image format transformations and save some time.
    Otherwise GS will transform GS's native chunky format to standard
    GEM color planes, and then transform back to chunky format for
    display.

GS_DEBUG: This is used by me during debugging. I doubt it is of interest
    to anyone else.


KNOWN BUGS, LIMITATIONS and POSSIBLE PROBLEMS:

See the doc files for some known bugs and problems.

1.) 16 bit color is still under construction; it may not work properly.

2.) Control-C to abort printing is not handled very gracefully.

3.) Fatal errors can cause GS to close the console window before the
    error message can be read.

4.) Some PageStream output tickles a bug in the GS kernal, causing a
    crash.

5.) The CEN: output option does not work properly on some STEs and TTs.

6.) Programs which talk control of the printer port can interfere with
    Ghostscript's Atari SLM laser printer device. Also, you should
    have the latest Diablo emulator to avoid output problems under
    MultiTOS.


TIPS:

Here are a few miscellaneous tips.

1) Read the supplied documentation! It is a bit sparse for beginners,
    but it is helpful and is quicker than sending me questions.
    Use.doc is the most important file for casual users. GS is
    an excellent tool for learning PostScript programming, but
    it is not the intention of the docs to teach PS to you.
    If you want to learn PostScript programming, you will probably
    need to buy a PS programming book.

2) Try to arrange things so that you don't have to restart GS very
    often. This startup takes a good deal of time. Once GS has
    displayed an image, another can be displayed by typing
    "(file.ps) run" on the command line, or by selecting a
    file using the Run entry of the File menu. If you MUST
    restart GS often, putting the initialization files in a
    ram disk significantly decreases initialization time
    (at least on my system).

3) There is a GEM shell for ST-GS, called gemGS. You may
    find it useful if you hate typing command lines. Also, gemGS
    allows the selection of individual pages from large documents,
    although this feature is rather slow. GemGS 1.2 is compatible
    with GS 2.41, and gemGS 1.3 is intended for GS 2.52 and GS 2.61.
    When using GemGS 1.3 with GS 2.61, turn off the windows option
    in GemGS.

4) The ps directory contains some files on which to test ghostscript.
    These are some of the files that where used to test the port.

5) GS can be used to view or print the output of dvips (TeX dvi to PS
    translator). The combination of TeX (a typesetting program), dvips,
    and GS can be used to preview TeX documents which contain graphics
    at high resolution (if you need this sort of thing and have the
    memory). I have gone up to 300dpi and it seems to work OK. Dvips
    allows PS graphics to be easily included in TeX documents.

6) You can change the ghostscript prompt by editing the gs_init.ps file.
    Search the file for GS or >, and then change this to whatever you
    want the prompt to be. Many other changes can be made in this
    file to alter the behavior of GS. For example, you can redefine
    the 'showpage' command so that it doesn't wait around for a
    CR to be typed after every page (this can be done from the
    command line also).

7) You may find interesting things in the following Usenet newsgroups:
    gnu.ghostscript.bug
    comp.lang.postscript
    comp.sources.postscript

ACKNOWLEDGMENTS:

Many kind people have contributed to the Atari version of Ghostscript.
Some of the more direct contributions are:

Hauke Hess:    Original screen driver upon which stvdi was based,
Robert Stabl:    The Atari SLM laser printer driver,
Marcus Haebler:    360 dpi NEC P6 and GEM image drivers,
Chris Strunk:    Contributed code for direct centronics printing,
Steve Eker:    Contributed assembly image transformation algorithms,
Steven Ourada:    Contributed assembly image transformation algorithms,
Markus Wenzel:    Color palette save and restore routines,
J. Bammi:    For gcc and numerous library bug fixes.

Please forgive me if I forgot to mention an important contribution,
and gently remind me of my omission.

FOR MORE INFO:

The original source files, docs, and fonts can be obtained from
many places. I obtained the ones I used from "ftp.uu.net".

Send bug reports to:

Tim Gallivan
Center for Relativity
University of Texas
Austin, TX
[e-mail]