xref: /illumos-gate/usr/src/cmd/lp/filter/postscript/

#
# 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

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

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

Last Index update Tue Apr 23 14:26:46 UTC 2024