#

# 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