[Note: You must get Part??.Z as well as Patch.??.Z and apply all patches to get the current version. This README is the original version. - archivist@cs.toronto.edu] PSROFF RELEASE 3.0 README 2.17 91/04/02 Feb 19, 1991 Chris Lewis Please see the end of this file for my contact information. If you have problems installing/using this software, please contact me - I REALLY MEAN it - that's why I include my phone number. Please read this document before configuring. If you have difficulties, read the TROUBLE file. See the INSTALL file for explicit installation instructions. See the LICENSE file for the copyright restrictions on this software. Note that the name "psroff" clashes with a program contained in Adobe Transcript and has caused endless confusion on the net. To prevent confusion, please refer to this package on the net as "Chris's psroff", or "non-Adobe psroff", or "psroff (not Transcript)" so that people will know what you're talking about. This software was unfortunately named psroff accidentally, long before I knew that there was a thing called psroff in Transcript. Adobe is aware of the situation, but provided that everybody is clear about which one they mean, there won't be a problem. Normal UNIX troff only prints its output on WANG C/A/T Phototypesetters. This package contains a generic interface between standard troff and other types of printers. The package has a driver for PostScript printers (Eg: Apple Laserwriters), a driver for HP LaserJet and DeskJet family printers (including incremental downloading of PK or SFP format fonts), and Ditroff output options (tpscript driving Postscript printers, jetroff driving HP Laserjets, xtroff driving X.11, xproof driving DMD terminals, psdit), Sun PageView driving X windows, Display Postscript on NeXT, DEC Windows and IBM RS/6000. In fact, this package can be used to, in effect, upgrade CAT troff to be ditroff. There are limitations (listed near the end), but you get what you pay for. Not only that, but this release supports ditroff *input* too. Therefore, if you have any kind of troff, this will work for you. Applicability/additional requirements: - You must have a troff - ALL versions of troff work with this software (CAT troff, ditroff, and groff). - Printers: - If you have a laserjet, you should be able to use this package directly. Alternately, you can cause psroff to generate ditroff and drive jetroff with it. If you're going to drive the printer directly, you'll need additional fonts. - I believe the above comments also hold true for DeskJet printers. - If you have a postscript printer use postscript output. Or, generate ditroff and use tpscript. Mine's better, so there! ;-) - If you have ditroff drivers (eg: dit2dvi etc.) you can configure psroff to drive them. - If you have a HPLJ III, this release comes with width tables for the built-in fonts. - If you're intending to use ditroff *input*, you should ensure that you have makedev, or the PD makedev clone "mkfont" from comp.sources.unix in 1988. There was a bug in mkfont which bites on some machines, if your ditroff doesn't like the width tables mkfont generates, contact me, I have a teensy patch for it. - psxlate has support for n-up printing in Postscript. For this you will also need the psnup distribution from comp.sources.misc (volume 16). Beware of the use of any ditroff-only-isms when you're using CAT troff with psroff. However, when used with ditroff, psroff should be fully functional. This is a formal release. There are probably rough edges however, particularly with fine-tuning width tables for specific printers and some of the more esoteric ditroff configurations. Further, there is some testing code for emulating ditroff drawing commands when used with CAT troff (see catconv). I encourage people to experiment with psroff (particularly the configuration files) and PLEASE PLEASE PLEASE send me your changes so that I can encorporate them into new releases and updates. This package is currently in production at our site and has been so for over three years (in various stages of development). By all appearances, this software is also in serious production in 100's of sites throughout the world. The first version of psroff (version 1.0) was posted in comp.sources.unix in October 1989. Psroff release 2.0 was posted to alt.sources in November 1990. An extremely primitive program called "lcat" was the original precursor, it was posted to mod.sources in 1984 (which is why the copyrights go so far back). Please note: I have discontinued the mailing list, because nothing ever went out on it. Patches are shipped out through comp.sources.bugs and alt.sources. A current list of FTP and UUCP access sites can be obtained by sending me mail. Credits: The MANY people who've helped me get psroff working on a wider range of platforms and printers than I would have thought possible. Elegant Communications for letting me do this, Ron Florence for assistance far beyond the call of duty in getting Laserjet driving to work, Rick Richardson of PC Research, Liam Quin of SoftQuad, Mark Moraes at U of Toronto, Dave Cahlander at Amdahl, Henry McGilton (and Pageview support) at Sun, Ronald Khoo at ibmpcug.uk, N K Krishnan for supplying the HP LJIII widths in TFM format, and Adobe for not getting too upset about the (accidental) name clash. Remarks: - This was originally developed with a relatively old (eg: Lisa Xenix) CAT troff, and may be slightly incompatible with the latest versions of CAT troff. See BSDHACK and FONT8/FONT4 in defs.h, however, I've yet to see a version of troff that needs either BSDHACK or FONT8. - This supports some of the newer drawing commands available in groff and later versions of ditroff (eg: RS/6000) - The PostScript driver is fully complete. It uses the built-in fonts on the AppleLaser. A few characters not in these fonts are faked by the invocation of drawing routines defined in the file "ps.lib" (which is the definitions of things needed by the driver). Or the bracket font (also in ps.lib). Eg: 1/2, 1/4, 3/4, circle, bell system logo and box are constructed by PostScript subroutines and/or the bracket font. The Bell System logo isn't really - try this: \s36\(bs\s0 The first person to correctly identify what it is (without reading ps.lib) gets a pat on the back ;-) Two characters that don't exactly map properly are left and right hand. I use double arrows instead. This seems to be a relatively common convention. There are some facilities for downloading postscript fonts (see HW in ps.fonts) - The ditroff driver is fully complete and should work flawlessly provided that you use the proper width tables and you get the troff font:character -> ditroff font:character translations right. You will probably want to take the ditroff width tables that come with your ditroff backend and run them through gfnttab (discussed later). - The ditroff *input* handler is quite new, and hasn't been tested all that extensively. Preliminary results seem to suggest that it does work, but documentation is scanty, and there's not much in the way of automated install or configuration checking for real ditroff. See the DITROFF file for additional information. - Fonts: - postscript driving - psroff uses what's on the printer - the configuration (ps.fonts) supplied corresponds to a subset of the AppleLaserwriter PLUS. This should be satisfactory with all modern postscript printers (the original Laserwriter apparently is missing some of the fonts). You may have problems with Helvetica Narrow fonts on printers like LN03's. There are ways of building new fonts and downloading them. See pk2ps and the HW definitions in ps.fonts. - ditroff driving - psroff uses whatever comes with the ditroff-> printer converter. Eg: with xtroff, psroff would use the font files that come with X windows. With jetroff, psroff would use the font files that come with jetroff, etc. If you're driving a postscript printer via a ditroff backend, chances are that you're using fonts on the printer (eg: tpscript) and the "ps" widths will be satisfactory or can be manually tweaked slightly. - HPLJ: to support downloading, you must obtain a set of font files that are sufficient for the sort of stuff you are doing. psroff has been designed to work with MATH8 encoded fonts (for the CAT S font), and ROMAN8 encoded fonts for all others (eg: R, I, B etc.). Minimally, you should obtain from Hewlett Packard (or other sources) Roman, RomanItalic, and RomanBold all in ROMAN8 encodings, in the following point sizes: 6 7 8 9 10 11 12 14 16 18 20 22 24 28 36 From most sources these will be in HP "SFP" format. I've included with psroff a set of PK (TeX) format font files for the S font in all of the sizes listed above. These "S" fonts are designed to be as close to HP MATH8 as possible. Font sources: - PC Research's Jetroff font distribution (comp.sources.unix & uunet). Free (actually shareware). Will give you 4 or 5 complete sets of fonts at all useful sizes. See INSTALL and LASERFONTS. Probably good enough to use with the optimizer. - TeX PK fonts: will generate 6 or more complete sets of fonts, at all useful sizes, but some of the fonts will be slightly off in size. Not good with the optimizer unless you can fire up metafont. - HP Soft fonts: HP font floppies are a good source of very nice looking fonts. - New HP product: there is a new package from HP which has a "street cost" of about $40 which includes several scalable typefaces and a PC program to generate them as SFP's at any size you want. THIS is the way to go. Note that the Laserjet III personality for psroff uses Latin-1 and Math-8 and several other fonts to get a complete troff set, as opposed to Roman-8 and a fake Math-8 for laserjet + and laserjet II. If you get the scalable typefaces from HP to use on your pre LJIII's, start with the lj3.fonts file (has the encodings and font selections) See the LJIII file for more information on how the LJIII variant works, and some pointers on how to upgrade your pre-LJIII printers to work as well. Psroff supports both PK and SFP format font files. Normal PK font files (eg: that come with TeX) do not have anything close to the same encoding as HP. The S PKs I supply are specially reordered (actually a merge of four PKs) to reflect MATH8 encoding. You can also use TeX PK fonts directly (after a name change to reflect psroff's file naming conventions) for the non-S fonts. cmr, cmit, and cmb can be used for Roman, Italic and Bold respectively. *BEWARE*, there are a *lot* of characters missing or out-and-out wrong in Knuth's standard PK files (relative to ROMAN8 ordering). Particularly box-drawing characters. I've included a couple R, I and B PK files that can be used to have a bit of fun until you have better font files. pk2sfp gives a method of merging PK files - see testmerge entry in utils/Makefile. R.10.pk, I.10.pk and B.10.pk in the lj.fonts directory were created this way. From Hewlett Packard, SFP's usually come on DOS diskettes that can be "cat"'ed to the printer. These are what you want. Just remember to do BINARY copies from the floppies... I got this mail message from Ronald Florence about HPLJ fonts: > May 14, 1990 (or thereabouts) > I just received a notice in the mail from HP, announcing > that they are about to discontinue the following soft > fonts: > TmsRmn/Helv Roman 8 (33412AD) > TmsRmn/Helv Roman 8 (33412AF) > TmsRmn/Helv Ascii (33412AE) > Together, the first two sets provide Times Roman and > Helvetica SFP fonts, including bold and italics, from > 6 to 30 points. They can be ordered from HP Direct > (800/538-8787). These are the fonts that Ronald has been using and they work quite well. Other soft fonts will probably work, but you may have to tweak the translation tables. So, order yours today... (No, neither of us are in the employ of HP). You may also be able to get good SFP's from the font archive at Waterloo. Alternately, if you have TeX fonts, the file LASERFONTS describes how to make fonts compatible with psroff. Software is supplied (utils and widths directories) to extract width information from PK and SFP font files and is built into the makefiles. - The width tables supplied (widths/widthps) are in ditroff makedev-input-format (ASCII ditroff width tables). I've specified them in ditroff format because it's easier to manipulate than CAT troff ft?? or ft??.c files. dit2catwid/gfnttab convert these width files into ft?? files. Further, if you're going to use a ditroff backend (tpscript, xtroff etc.) you'll probably need to feed them through the "makedev" utility so that the backend can understand the width tables. I do not supply a makedev, but one has been posted in comp.sources.unix in 1988, and is available from archive sites such as uunet, it was written by Duane Hesser, dhh@teltone.com) is included with jetroff. pk2ditwid takes PK and SFP files and produces widthtables compatible with gfnttab (but not necessarily with makedev). If you have ditroff, you will HAVE to run the widths through makedev/mkfont. - Width tables: Postscript: ( is how you sent output to your postscript printer. You might use "lp -dlaserwriter".) These are in the utils subdirectory: showfont: If you type: showfont | (eg: showfont Times-Roman) this will dump the entire Postscript Times-Roman font (plus some constructions that troff2ps uses) in a table. Each character is in a box, along with several numbers. The number in the center at the bottom of the box is the width in CAT scaling (size of 6 point character in 1/432's). The ditroff width tables are the size of a 10 point character, by default in 1/300's, but can be changed by a resolution directive in a DESC file (eg: widthps is in 1/720's). dit2catwid.c: takes ditroff like font tables and converts them to CAT codes suitable for (at least) Xenix troff. (some attempt has been made to make it work for systems that need a.out.h headers on their width tables). See the gfnttab script to see how it's used. gfnttab: Used to run dit2catwid to compile the width tables and place them in /usr/lib/font//ft??. see lib/psrofflib.S psdtwid: fire it off to your Postscript printer, and it will send back a shar file containing ditroff style char tables. (Neat - thanks Michael!) usage: psdtwid | widths/widthps/*: width tables for postscript and ditroff driving postscript. (Most from tpscript (thanks Michael), but some generated here with psdtwid) widths/width*/*: other width tables. - Width tables: ditroff backends: (eg: jetroff, xtroff, psdit etc.) [It is suggested that you specify the "ps" widths first for testing, and then use the following instructions when fine tuning the widths to get them precisely right] - install the backends *first*. - Find the DESC/R/S/I etc. files that come with the backend, or are generated by installing the backend (eg: jetroff's makefont stuff). - Copy these files to the appropriate widths/width subdirectory. Notes: - I've used "jt" for jetroff, the jt.fonts file is already at least partially set up. - "ps" is for ditroff->postscript (tpscript) and direct postscript driving and these width files are supplied. And would probably work with other ditroff->postscript converters except for possible character mapping changes (see jt.fonts). - Make in the widths directory will build the ft* files that you need, and make install will install them in the proper places. (normally /usr/lib/font//ft*). These are also done by top level make invocations. - Some ditroff backends (jetroff f'r instance) need to be able to read the "makedev compiled" font files. For which you need makedev or mkfont (see above). - Width tables: HPLJ. See the installation instructions. - There is some code to allow the sending of arbitrary commands to the driver - the ".sR" macro. This works well unless you're using the ".MT" macro in MM. sR directives before the ".MT" will confuse MM. See the manual page for psroff.1 for details on .sR. Further, ".tm" has been redefined to make use of the .sR facility. - psroff has 8-font troff support, but: a) it's never been tested. b) I'm no longer convinced that the cat.5 man page is correct on how the decoding works. - psroff has BSDHACK support (one of the tilt opcodes being replaced by an opcode to multiply the next vertical motion by 64), but this has not been tested. I never heard of it before til I saw it in Froyen's troff2lj source. This cannot be defined at the same time as 8-font support. Frankly, I can't understand why they bothered - so you save a few opcodes here and there - vcat output is enormous! - ".S" files are the source files and are converted to a filename without the suffix by a sedscript that contains the configuration. Whenever you touch the top-level makefile, the sedscript is changed and all of the ".S" files are rebuilt. If you make a makefile change (eg: configuration), do a "make makefiles" before using submakes. (though, if you simply say make, this will be done for you). Only change .S files... See the MANIFEST for a file-by-file description of the files. See the INSTALL file for detailed installation instructions. Future directions: They are two-fold: replacing the ".tm/.sR" mechanism for communication with the backend. There is a new method, using a FSA to recognize a special sequence of bell symbols (see catconv). I haven't converted over to it, because under some not-yet-understood situations, it doesn't work. Hence, psfig and drawing commands occasionally misbehave. Once this is reliable, all special commands (eg: the .fp fakeouts) will be converted over to the FSA mechanism. You may have noticed a compile flag called "OPT" which is defined in the distributed version of defs.h. If enabled (via -Z/W), this enables the optimizer. It works well with Postscript output, but not with laserjet unless the fonts you use are VERY good. It's disabled by default. The optimizer does two things: it emits as many characters as it can as one print directive, rather than one CAT code per print. On postscript and HPLJ's this is a BIG win (printer execution speeds 3 or more times faster), but it won't work with ditroff. The optimizer requires access to the CAT troff width tables (even when used with ditroff), and if troff2ps can't find them, it simply doesn't optimize. Psroff limitations: - With the use of catconv and CAT troff, psroff supports: - all drawing commands (including the newer \D'fn' (set fill), \D'tn' (line thickness), \D'p x y x y x y ...' (draw polygon), and filled versions of \D'c...', \D'e...', \D'p...' (by capitalizing the letter)). Drawing commands are NOT supported in HPPCL. (I think I have polygons right, but I don't know whether I got fill parameters correct - "n" is 0...1000, where 0 is all black, and 1000 is all white). - psfig. - catconv/CAT Troff and psroff do not support: - \s(nn, \S, \H, \f(xx - Ditroff: - psroff doesn't support character slant (\S) or height (\H). - Psroff only supports CAT troff sizes in HPPCL (some mechanism to relax this for HPLJIII's is easy to implement). All sizes are available in Postscript and ditroff. - psroff doesn't implement "w" (word breaks in ditroff output). - psroff doesn't support "stipple" (I have NO idea what this is - apparently a Berkeleyism.) CONTACT INFO (note that I've moved): Chris Lewis Elegant Communications Inc. Box 13215, Kanata PO Kanata, Ontario, K2K 1X4 Voice Phone: Canada (613) 832-0541 Userid's for e-mail contact: Psroff enquiries/help: psroff-request Non-psroff mail only: clewis UUCP routing: uunet!mitel!cunews!latour!ecicrl! Possible internet routing: @ferret.ocunix.on.ca Alternate: @eci386.uucp