Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/unix/volume24/psroff3.0/part01/README

Text File | 1991-10-09 | 20.4 KB | 444 lines

        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,
      [e-mail]) 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:
      (<printercommand> 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 <fontname> | <printercommand>
          (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/<printer>/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 | <printercommand>

    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<xx> 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/<xx>/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 [phone]
    Userid's for e-mail contact:
    Psroff enquiries/help: psroff-request
    Non-psroff mail only: clewis
    UUCP routing: uunet!mitel!cunews!latour!ecicrl!<userid>
    Possible internet routing: <userid>@ferret.ocunix.on.ca
    Alternate: <user>@eci386.uucp