1#
2# CDDL HEADER START
3#
4# The contents of this file are subject to the terms of the
5# Common Development and Distribution License, Version 1.0 only
6# (the "License"). You may not use this file except in compliance
7# with the License.
8#
9# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10# or http://www.opensolaris.org/os/licensing.
11# See the License for the specific language governing permissions
12# and limitations under the License.
13#
14# When distributing Covered Code, include this CDDL HEADER in each
15# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16# If applicable, add the following below this CDDL HEADER, with the
17# fields enclosed by brackets "[]" replaced with your own identifying
18# information: Portions Copyright [yyyy] [name of copyright owner]
19#
20# CDDL HEADER END
21#
22
23Version 3.15 source code for a few programs that can be used with PostScript
24printers. Most of the important changes are described in the VERSION file. The
25main Makefile is also slightly different so take a look at the next section or,
26equivalently, check the comments at the beginning of Makefile before you build
27or install the programs.
28
29If you change LIBDIR or FONTDIR (in Makefile) make the corresponding changes to
30the pathnames defined in common/path.h before compiling the programs. If you're
31on a UTS system compile the programs with the native compiler! The new postreverse
32is backwards compatible, but output from the new translators should not be passed
33through old versions of postreverse. The likely result in that case will be no
34output at all. ENCODING (in Makefile) controls how dpost encodes lines of text.
35By setting ENCODING to 2 I've selected the fast, but not thoroughly tested method
36that usually results in a 20% improvement in throughput. If you have problems
37set ENCODING to 0 and recompile dpost. That results in a default version of dpost
38that produces output essentially identical to earlier versions. The -R, -B, and
39-q options usually result in better performance from postio. Take a look at the
40man page or file postio/README if you want to change the default.
41
42There are potential conflicts with earlier versions, so I strongly recommend you
43install the new code on all your systems at about the same time. The new version
44of postreverse is safe and should be included if any new translators are installed.
45The important files that get replaced on a complete install are:
46
47 /usr/lib/postscript/* ie. $(LIBDIR)/* in Makefile
48 /usr/lbin/postscript/* ie. $(BINDIR)/* in Makefile
49 /usr/lib/macros/pictures ie. $(MACRODIR)/pictures in Makefile
50 /usr/lib/macros/color ie. $(MACRODIR)/color in Makefile
51 /usr/lib/font/devpost/* ie. $(FONTDIR)/devpost/* in Makefile
52 /usr/lib/font/PDQ/devpost/* ie. $(FONTDIR)/PDQ/devpost/* in Makefile
53 /usr/bin/dpost only if it's already there
54
55The final pathnames depend on the values assigned to LIBDIR, BINDIR, MACRODIR,
56FONTDIR, MANDIR, and ROOT in Makefile. When Makefile is ready type,
57
58 make all
59
60to build (but not install) everything or,
61
62 make install
63
64to build and install the entire package, although you'll probably have to be root
65before the install will work. If you're just interested in part of the package
66(eg. installing dpost and the font files) type,
67
68 make TARGETS="dpost font" install
69
70There are makefiles in most of the subdirectories, but they're not designed to
71be used on their own, especially not if you're installing things. Each needs
72many of the definitions made in Makefile before they're guaranteed to work. As
73long as you run make in this directory using Makefile you won't have to worry
74about any other changes or additions. The appropriate definitions will be exported
75before any of the other makefiles are used.
76
77There's a long list of people who have made significant contributions to this
78package. Included in that list are Richard Flood, Chris Warth, Guy Riddle, Paul
79Glick, Allan Wilks, Rick Becker, Johnathan Shopiro, Alan Buckwalter, Chi Choy,
80Carmela L'Hommedieu, and Maryann Csaszar. Many thanks to all of them and anyone
81else I (unintentionally) omitted.
82
83----------------------
84
85There's not much you'll need to change, but you may not agree with some of my
86choices, so before you do anything else, check the following definitions in
87Makefile:
88
89
90 ENCODING - An integer (0, 1, 2 or 3) that sets the default text encoding
91 scheme used by dpost. Increasing ENCODING (up to 3) decreases
92 print time and the size of output files produced by dpost. 0 is
93 slow, but the most stable choice and produces output essentially
94 equivalent to previous versions of dpost. 2 and 3 are encoding
95 schemes based on widthshow. Both are fast, perhaps 20% faster
96 than the 0 level scheme, but neither is well tested. Setting
97 encoding to 3 is not recommended, and will result in ragged right
98 margins. The encoding scheme can also be set at run time using
99 the -e option. Setting ENCODING to 2 may be worth a try.
100
101 ROOT - A string that's prepended to all the installation directories
102 (eg. BINDIR). Only used when things are installed, and probably
103 won't be of much use to anyone.
104
105 BINDIR - Where programs, like dpost and postprint, are installed. You may
106 want to change this definition. Things are set up so the programs
107 get put in a directory that's probably not in anyone's PATH.
108
109 FONTDIR - Where the binary font files go. Should be set to troff's font
110 directory on your system. If you change it do the same thing to
111 the definition of FONTDIR in ./common/path.h.
112
113 LIBDIR - All the files from directory ./postscript that end in .ps (plus
114 a few others) get put here. Mostly prologues for translators. If
115 you change it fix the corresponding paths in ./common/path.h
116 before doing a compile.
117
118 MANDIR - Where the manual pages are installed. This one is undoubtedly
119 wrong!
120
121 MACRODIR - Macro packages get installed here. The ones I've included handle
122 picture inclusion and color selection.
123
124 OWNER - Owner of any files that are installed.
125
126 GROUP - The group that's assigned to all installed files.
127
128 SYSTEM - The version of Unix you're running. Recognized choices are,
129
130 SYSV - System V
131 V9 - Ninth Edition
132 BSD4_2 - Berkeley
133
134 Primarily for conditional compilation in postio.
135
136 CFLAGS - Some of the programs use floating point arithmetic, so if you're
137 running on a system without floating point hardware add the -f
138 option before compiling the programs.
139
140 LIST - The command that's run to produce a source listing. Not terribly
141 important, but the default will only be right on MHCC systems.
142
143 TARGETS - The default group of things (ie. source directories) that make
144 operates on when you select targets like install or clobber.
145
146 DKHOSTDIR - If your system has DKHOST software this is where it should be.
147 Used for conditional compilation in postio, and only if SYSTEM
148 is set to SYSV. Needed so dk.h and libdk.a are picked up. To
149 disable the DKHOST stuff just remove this definition.
150
151 DOCDIR - Documentation about the picture drawing macro gets put in this
152 directory. Includes a short paper and the associated PostScript
153 files that describe how to use the macros and submit jobs on
154 MHCC systems. It's undoubtedly not right for your system and
155 won't be installed unless you add docs to the TARGET list. If
156 you're going to install the documentation you'll undoubtedly
157 have to edit docs/pictures. All the .BP calls will have to
158 reflect the new DOCDIR directory, and the command line used to
159 submit jobs will have to change.
160
161----------------------
162
163Brief descriptions of the programs and source directories follow. Check the man
164pages for more detailed information about the programs.
165
166postio
167 A program that can be used to send files to PostScript printers over an
168 RS-232 serial line. If you're on System V, have the DKHOST software
169 package, and request a line that doesn't begin a / postio may treat it
170 as a Datakit destination. The new version of postio can run as a single
171 process or as separate read and write processes, and can also be used to
172 establish an interactive connection to the printer. Check the man page
173 for more details.
174
175 EXAMPLES:
176
177 A typical command line would look like,
178
179 postio -l /dev/tty?? file.ps
180
181 If your printer is running at something other than 9600 baud (eg.
182 19200) use the -b option to select the appropriate speed,
183
184 postio -l /dev/tty?? -b19200 file.ps
185
186 Adding the -R2 option to to either of the command lines would force
187 postio to run as separate read and write processes.
188
189dpost
190 Translates output produced by the device independent troff into PostScript.
191 The default font files (in /usr/lib/font/devpost) assume a resolution of
192 720, which isn't expected to match your printer's resolution.
193
194 EXAMPLE:
195
196 A typical command line (assuming you have up to date versions of eqn
197 and pic) would be,
198
199 pic file | tbl | eqn | troff -mm -Tpost | dpost >file.ps
200
201 If old versions of eqn and pic are installed try,
202
203 pic -T720 | tbl | eqn -r720 | troff -mm -Tpost | dpost >file.ps
204
205postprint
206 Translates ASCII files into PostScript.
207
208 EXAMPLE:
209
210 pr -n file | postprint >file.ps
211
212postreverse
213 A simple program that reverses pages in files that conform to Adobe's 1.0
214 or 2.0 file structuring conventions. Can be used with all the translators
215 in this package, even though the output from dpost often doesn't conform
216 to either convention.
217
218 EXAMPLE:
219
220 postprint file | postreverse >file.ps
221
222buildtables
223 A collection of programs and data files that can be used if you want to
224 have a PostScript printer generate new troff width tables for printer or
225 host resident fonts. All the ASCII width tables in ./font/devpost were
226 built this way.
227
228common
229 Common source and header files used when most of the programs are compiled.
230 The only changes here may be to the pathnames defined in common/path.h.
231 The definitions of LIBDIR and FONTDIR in Makefile must agree with what's
232 in path.h.
233
234doc
235 Additional documentation, that right now only includes a short paper that
236 shows how to use the picture inclusion macros. What's supplied will not
237 be right for all systems.
238
239font
240 Font and device description files for many of the standard PostScript
241 fonts. The ASCII files can be found in directory font/devpost, and are
242 built assuming a device resolution of 720 dpi, which isn't expected to
243 match your printer's actual resolution. All the fonts available on the
244 LaserWriter Plus (and a few others) are supported, but all may not be
245 available on your printer. Characters that troff uses but that aren't on
246 PostScript fonts are built up using definitions in font/devpost/charlib.
247
248 The mapping from troff's one or two character font names into PostScript
249 font names is handled by the definitions made in postscript/dpost.ps. If
250 you build a new font file put the ASCII version in directory font/devpost,
251 add an appropriate definition to postscript/dpost.ps, and then build and
252 install the new binary font file and prologue by typing,
253
254 make TARGETS="postscript font" install
255
256 Building new ASCII font files is described in more detail in font/README
257 and buildtables/README. Files that you'll find in the buildtables source
258 directory, once you understand what's there, let the printer generate
259 the width tables for you.
260
261macros
262 Stand-alone troff macro packages that currently support picture inclusion
263 and color selection (also reverse video) and only work with dpost.
264
265man
266 Manual pages for all the programs supplied with this package.
267
268misc
269 Some interesting and perhaps useful programs obtained from various sources.
270 All are unsupported! Included is an example lp interface program that came
271 from Maryann Csaszar.
272
273postscript
274 PostScript files, mostly prologues, used by the translators supplied in
275 this package. All the files in this directory that end in .ps (and a few
276 others) are copied to /usr/lib/postscript (ie. $(LIBDIR)) when you do an
277 install.
278
279template
280 Files that may help if you're writing a PostScript translator. The basic
281 outline of the C code, the PostScript prologue, and the makefile has been
282 included.
283
284tests
285 Simple test files for all the PostScript translators supplied with this
286 package.
287
288----------------------
289
290The new translators all attempt to conform to Adobe's Version 2.0 file structuring
291conventions. dpost falls short, but only because page independence is sacrificed
292for efficiency. None of the translators use their own dictionary, but perhaps the
293most glaring omission is the lack of a %%BoundingBox comment in output produced by
294most of the translators. Both are issues I hope to address in the next release.
295
296Changing the default behavior for dpost and postio isn't difficult. You get the
297fast (but not completely tested) version of dpost by setting ENCODING in Makefile
298to 2 before compiling dpost - which is what I've supplied. Speeding up the default
299version of postio requires more work, and isn't strongly recommended. The required
300changes (all simple fixes to the C code), are outlined in postio/README.
301
302
303 Richard Drechsler
304 MH 2F-241 x7442
305 mhuxa!drexler
306
307