OpenSolaris_b135/cmd/lp/filter/postscript/README
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License, Version 1.0 only
# (the "License"). You may not use this file except in compliance
# with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#
Version 3.15 source code for a few programs that can be used with PostScript
printers. Most of the important changes are described in the VERSION file. The
main Makefile is also slightly different so take a look at the next section or,
equivalently, check the comments at the beginning of Makefile before you build
or install the programs.
If you change LIBDIR or FONTDIR (in Makefile) make the corresponding changes to
the pathnames defined in common/path.h before compiling the programs. If you're
on a UTS system compile the programs with the native compiler! The new postreverse
is backwards compatible, but output from the new translators should not be passed
through old versions of postreverse. The likely result in that case will be no
output at all. ENCODING (in Makefile) controls how dpost encodes lines of text.
By setting ENCODING to 2 I've selected the fast, but not thoroughly tested method
that usually results in a 20% improvement in throughput. If you have problems
set ENCODING to 0 and recompile dpost. That results in a default version of dpost
that produces output essentially identical to earlier versions. The -R, -B, and
-q options usually result in better performance from postio. Take a look at the
man page or file postio/README if you want to change the default.
There are potential conflicts with earlier versions, so I strongly recommend you
install the new code on all your systems at about the same time. The new version
of postreverse is safe and should be included if any new translators are installed.
The important files that get replaced on a complete install are:
/usr/lib/postscript/* ie. $(LIBDIR)/* in Makefile
/usr/lbin/postscript/* ie. $(BINDIR)/* in Makefile
/usr/lib/macros/pictures ie. $(MACRODIR)/pictures in Makefile
/usr/lib/macros/color ie. $(MACRODIR)/color in Makefile
/usr/lib/font/devpost/* ie. $(FONTDIR)/devpost/* in Makefile
/usr/lib/font/PDQ/devpost/* ie. $(FONTDIR)/PDQ/devpost/* in Makefile
/usr/bin/dpost only if it's already there
The final pathnames depend on the values assigned to LIBDIR, BINDIR, MACRODIR,
FONTDIR, MANDIR, and ROOT in Makefile. When Makefile is ready type,
make all
to build (but not install) everything or,
make install
to build and install the entire package, although you'll probably have to be root
before the install will work. If you're just interested in part of the package
(eg. installing dpost and the font files) type,
make TARGETS="dpost font" install
There are makefiles in most of the subdirectories, but they're not designed to
be used on their own, especially not if you're installing things. Each needs
many of the definitions made in Makefile before they're guaranteed to work. As
long as you run make in this directory using Makefile you won't have to worry
about any other changes or additions. The appropriate definitions will be exported
before any of the other makefiles are used.
There's a long list of people who have made significant contributions to this
package. Included in that list are Richard Flood, Chris Warth, Guy Riddle, Paul
Glick, Allan Wilks, Rick Becker, Johnathan Shopiro, Alan Buckwalter, Chi Choy,
Carmela L'Hommedieu, and Maryann Csaszar. Many thanks to all of them and anyone
else I (unintentionally) omitted.
----------------------
There's not much you'll need to change, but you may not agree with some of my
choices, so before you do anything else, check the following definitions in
Makefile:
ENCODING - An integer (0, 1, 2 or 3) that sets the default text encoding
scheme used by dpost. Increasing ENCODING (up to 3) decreases
print time and the size of output files produced by dpost. 0 is
slow, but the most stable choice and produces output essentially
equivalent to previous versions of dpost. 2 and 3 are encoding
schemes based on widthshow. Both are fast, perhaps 20% faster
than the 0 level scheme, but neither is well tested. Setting
encoding to 3 is not recommended, and will result in ragged right
margins. The encoding scheme can also be set at run time using
the -e option. Setting ENCODING to 2 may be worth a try.
ROOT - A string that's prepended to all the installation directories
(eg. BINDIR). Only used when things are installed, and probably
won't be of much use to anyone.
BINDIR - Where programs, like dpost and postprint, are installed. You may
want to change this definition. Things are set up so the programs
get put in a directory that's probably not in anyone's PATH.
FONTDIR - Where the binary font files go. Should be set to troff's font
directory on your system. If you change it do the same thing to
the definition of FONTDIR in ./common/path.h.
LIBDIR - All the files from directory ./postscript that end in .ps (plus
a few others) get put here. Mostly prologues for translators. If
you change it fix the corresponding paths in ./common/path.h
before doing a compile.
MANDIR - Where the manual pages are installed. This one is undoubtedly
wrong!
MACRODIR - Macro packages get installed here. The ones I've included handle
picture inclusion and color selection.
OWNER - Owner of any files that are installed.
GROUP - The group that's assigned to all installed files.
SYSTEM - The version of Unix you're running. Recognized choices are,
SYSV - System V
V9 - Ninth Edition
BSD4_2 - Berkeley
Primarily for conditional compilation in postio.
CFLAGS - Some of the programs use floating point arithmetic, so if you're
running on a system without floating point hardware add the -f
option before compiling the programs.
LIST - The command that's run to produce a source listing. Not terribly
important, but the default will only be right on MHCC systems.
TARGETS - The default group of things (ie. source directories) that make
operates on when you select targets like install or clobber.
DKHOSTDIR - If your system has DKHOST software this is where it should be.
Used for conditional compilation in postio, and only if SYSTEM
is set to SYSV. Needed so dk.h and libdk.a are picked up. To
disable the DKHOST stuff just remove this definition.
DOCDIR - Documentation about the picture drawing macro gets put in this
directory. Includes a short paper and the associated PostScript
files that describe how to use the macros and submit jobs on
MHCC systems. It's undoubtedly not right for your system and
won't be installed unless you add docs to the TARGET list. If
you're going to install the documentation you'll undoubtedly
have to edit docs/pictures. All the .BP calls will have to
reflect the new DOCDIR directory, and the command line used to
submit jobs will have to change.
----------------------
Brief descriptions of the programs and source directories follow. Check the man
pages for more detailed information about the programs.
postio
A program that can be used to send files to PostScript printers over an
RS-232 serial line. If you're on System V, have the DKHOST software
package, and request a line that doesn't begin a / postio may treat it
as a Datakit destination. The new version of postio can run as a single
process or as separate read and write processes, and can also be used to
establish an interactive connection to the printer. Check the man page
for more details.
EXAMPLES:
A typical command line would look like,
postio -l /dev/tty?? file.ps
If your printer is running at something other than 9600 baud (eg.
19200) use the -b option to select the appropriate speed,
postio -l /dev/tty?? -b19200 file.ps
Adding the -R2 option to to either of the command lines would force
postio to run as separate read and write processes.
dpost
Translates output produced by the device independent troff into PostScript.
The default font files (in /usr/lib/font/devpost) assume a resolution of
720, which isn't expected to match your printer's resolution.
EXAMPLE:
A typical command line (assuming you have up to date versions of eqn
and pic) would be,
pic file | tbl | eqn | troff -mm -Tpost | dpost >file.ps
If old versions of eqn and pic are installed try,
pic -T720 | tbl | eqn -r720 | troff -mm -Tpost | dpost >file.ps
postbgi
Translates BGI (Basic Graphical Instruction) files into PostScript. The
default line width, as with posttek, is one pixel, which probably won't
produce acceptable results on write-white engines, like the ones used in
the QMS PS-2400 or Dataproducts 2665. The -w option can be used to set a
new line width. For a different default change the definition of linewidth
in postscript/postbgi.ps.
Support for PRISM (ie. color BGI) jobs has been included, although what
you get by default may not be acceptable, at least not on the ColorScript
100. A simple solution is add the -P"/prism true def" option to the postbgi
command line when you're translating PRISM jobs. In fact nothing breaks if
you include the -P"/prism true def" option when translating STARE (black
and white BGI) jobs. The only difference most users will notice is that
plots are smaller than normal.
EXAMPLES:
For normal STARE jobs, scaled to almost fill a page, use
postbgi file >file.ps
while most PRISM jobs require,
postbgi -P"/prism true" file >file.ps
postdaisy
Translates Diablo 630 files into PostScript.
EXAMPLE:
postdaisy file >file.ps
postdmd
Translates DMD bitmap files into PostScript. The original program (ie. abm)
was written by Guy Riddle. The Ninth Edition bitfile format is supported,
although unless you use the -u option they will be unpacked and completely
reformatted before being sent to the printer.
EXAMPLE:
postdmd file >file.ps
postmd
A program that can be used to display large matrices as gray scale images
on PostScript printers. May help if you're looking for patterns in large
matrices. Input files are matrix elements, written as a series of floating
point numbers in row major order. Check the man page for more details.
EXAMPLE:
postmd file >file.ps
postprint
Translates ASCII files into PostScript.
EXAMPLE:
pr -n file | postprint >file.ps
postreverse
A simple program that reverses pages in files that conform to Adobe's 1.0
or 2.0 file structuring conventions. Can be used with all the translators
in this package, even though the output from dpost often doesn't conform
to either convention.
EXAMPLE:
postprint file | postreverse >file.ps
posttek
Translates tektronix 4014 files into PostScript. Most of the code was
borrowed from the DMD tektronix emulator. The default line width is one
pixel, which gives the good results on 300dpi write-black engines, but one
pixel wide lines hardly show up on write-white engines like the ones used
in the PS-2400 or Dataproducts 2665. The -w option can be used to set a
new line width. The argument is in points, where one point is about 1/72
of an inch. For a different default change the definition of linewidth
in postscript/posttek.ps.
EXAMPLE:
posttek -w.5 file >file.ps
picpack
A simple picture packing pre-processor that works in combination with the
troff, dpost, and the picture inclusion macros. It's not a replacement
for the original picture inclusion mechanism (in dpost) but may help if
you have an application that needs everything together in a single file
before dpost runs. The original picture inclusion mechanism is still the
preferred approach!!
EXAMPLE:
picpack file | troff -mm -Tpost >file.t
buildtables
A collection of programs and data files that can be used if you want to
have a PostScript printer generate new troff width tables for printer or
host resident fonts. All the ASCII width tables in ./font/devpost were
built this way.
common
Common source and header files used when most of the programs are compiled.
The only changes here may be to the pathnames defined in common/path.h.
The definitions of LIBDIR and FONTDIR in Makefile must agree with what's
in path.h.
doc
Additional documentation, that right now only includes a short paper that
shows how to use the picture inclusion macros. What's supplied will not
be right for all systems.
font
Font and device description files for many of the standard PostScript
fonts. The ASCII files can be found in directory font/devpost, and are
built assuming a device resolution of 720 dpi, which isn't expected to
match your printer's actual resolution. All the fonts available on the
LaserWriter Plus (and a few others) are supported, but all may not be
available on your printer. Characters that troff uses but that aren't on
PostScript fonts are built up using definitions in font/devpost/charlib.
The mapping from troff's one or two character font names into PostScript
font names is handled by the definitions made in postscript/dpost.ps. If
you build a new font file put the ASCII version in directory font/devpost,
add an appropriate definition to postscript/dpost.ps, and then build and
install the new binary font file and prologue by typing,
make TARGETS="postscript font" install
Building new ASCII font files is described in more detail in font/README
and buildtables/README. Files that you'll find in the buildtables source
directory, once you understand what's there, let the printer generate
the width tables for you.
macros
Stand-alone troff macro packages that currently support picture inclusion
and color selection (also reverse video) and only work with dpost.
man
Manual pages for all the programs supplied with this package.
misc
Some interesting and perhaps useful programs obtained from various sources.
All are unsupported! Included is an example lp interface program that came
from Maryann Csaszar.
postscript
PostScript files, mostly prologues, used by the translators supplied in
this package. All the files in this directory that end in .ps (and a few
others) are copied to /usr/lib/postscript (ie. $(LIBDIR)) when you do an
install.
template
Files that may help if you're writing a PostScript translator. The basic
outline of the C code, the PostScript prologue, and the makefile has been
included.
tests
Simple test files for all the PostScript translators supplied with this
package.
----------------------
The new translators all attempt to conform to Adobe's Version 2.0 file structuring
conventions. dpost falls short, but only because page independence is sacrificed
for efficiency. None of the translators use their own dictionary, but perhaps the
most glaring omission is the lack of a %%BoundingBox comment in output produced by
most of the translators. Both are issues I hope to address in the next release.
Changing the default behavior for dpost and postio isn't difficult. You get the
fast (but not completely tested) version of dpost by setting ENCODING in Makefile
to 2 before compiling dpost - which is what I've supplied. Speeding up the default
version of postio requires more work, and isn't strongly recommended. The required
changes (all simple fixes to the C code), are outlined in postio/README.
Richard Drechsler
MH 2F-241 x7442
mhuxa!drexler