From: clewis@ferret.ocunix.on.ca (Chris Lewis)
Newsgroups: comp.text,news.answers,comp.answers
Subject: comp.text Frequently Asked Questions
Summary: Discussions on text processing in general, and troff in particular
Keywords: typesetting troff groff ditroff wysiwyg sgml word desktop dwb
Date: 12 Jan 93 05:22:43 GMT
Expires: 9 Feb 93 05:22:30 GMT
Reply-To: textfaq@ferret.ocunix.on.ca (Text FAQ commentary reception)
Followup-To: comp.text
Organization: Elegant Communications Inc., Ottawa, Canada
Supersedes: <textfaq_725606542@ecicrl>

Archive-name: text-faq
Last-Modified: Wed Dec  9 02:53:12 EST 1992

	    Frequently Asked Questions for comp.text
			   Chris Lewis
			Nils-Peter Nelson

(This list was originally compiled by Jaap Akkerhuis, Dick Dunn, Nick
Haines, Steve Harley, Harro Kremer, Chris Lewis, John Macdonald, Bob
Morris, Nils-Peter Nelson, Chip Rosenthal.)

If you have comments or additions, please contact Chris Lewis,
textfaq@ferret.ocunix.on.ca (note Reply-to).

| Changes are marked with a "|" in left column.  Many newsreaders
| (ie: rn, trn) allow you to search for them with "g^|".

Changes this issue: Psroff is now PL14.  A few minor diddles.

Questions discussed:

General interest:

  GN1. What is the difference between word processing, desktop
         publishing, technical publishing, electronic publishing, etc?
  GN2. Which do I need?
  GN3. What is a markup language?
  GN4. What is SGML? ODA?
  GN5. What is WYSIWYG? Do I need it?
  GN6. What is PostScript?
  GN7. What is TeX?
  GN8. What are some popular Desktop Publishing packages?
  GN9. Where can I read more?

Specific to troff:

  TR1. What is troff? Why are there so many questions about it?
  TR2. How many varieties of troff are there? What are the differences?
  TR3. What are some of the filters for troff output?
  TR4. What other troff printer drivers are there?
  TR5. How do I get my troff to drive my printer?
  TR6. None of the mentioned packages support *my* printer.  Help?
  TR7. How to I embed PostScript in troff?
  TR8. What are fonts?  How do I add fonts?
  TR9. What are width tables?
  TR10. How do I make width tables?
  TR11. What are: pic, eqn, tbl, grap, refer?
  TR12. How do I preview my troff on my screen?
  TR13. I need makedev, but my DWB doesn't come with it.
  TR14. How can I get nroff/troff for DOS?
  TR15. What books can I get about DWB?

The discussions below are organized in digest-form, so you may
scan ahead for "^Subject:" to move from one topic to the next
(the ^G command does this in rn), and you may search for "^Subject: GN5"
(for example) to jump to the discussion of a particular question.
(The caret "^" before "Subject" is a convention of regular expressions
that restricts the search to match only at the beginning of a line.)

--------
Subject: GN1. What is the difference between word processing, desktop
publishing, technical publishing, electronic publishing, etc?

Electronic Publishing is an all-encompassing term that means
using computers (instead of hot lead) to set type for
documents.  Although publishing includes a sequence of
processes right through distribution, EP tends to emphasize
document composition through production of a single master copy.

It is helpful to picture a graph with "complexity" along
the X axis and "length" along the Y axis.  Complexity
varies from straight text to footnotes and indexing to
tables to line drawings to gray-scale illustration to
full color.  Length varies from 1 page to 10,000 or more
(better make the Y axis logarithmic!)

Word processing dominates the lower left of the graph
(business letters).  Desktop publishing dominates the lower
right (advertising layout).  Host-based text formatters like
troff, TeX and Scribe dominate the upper-left (phone book).
Proprietary systems have traditionally dominated the upper
right (Sears catalog, encyclopedia); these are being supplanted
by hybrids consisting of pieces from the other segments.

The middle of the graph is fair ground for everyone but is
increasingly the domain of Technical Publication systems like
Interleaf and FrameMaker.

--------
Subject: GN2. Which do I need?

Word processors and Desktop publishers are more than adequate
for documents of tens of pages.  Because they are mostly
limited to PC's and Macintosh, they may be impediments in
producing long documents, which would have to be done in
digestible chunks (say, a chapter at a time).  High-end systems
are usually UNIX-based, which means computer power and document
capacity are limited only by how much you want to spend.

--------
Subject: GN3. What is a markup language?

All formatters need to distinguish the text to be printed
from instructions about how to print; the latter is called
markup.  Procedural markup tells the software what to do
(space down, invoke a macro); generic markup describes the
thing to be printed (heading, cross-reference, etc.)  Troff
and TeX are examples of procedural markups; ODA and SGML
prescribe rules for generic languages; and good macro packages
for troff or TeX make them, more-or-less, generic markup
languages.

--------
Subject: GN4. What is SGML? ODA?

SGML is the Standard Generalized Markup Language.  SGML is defined
in International Standard ISO 8879:1986.  SGML is a language for
formally describing the structure and contents of documents.  SGML
is also the syntax used by documents so described.

SGML is an important move in the direction of separating information
from its presentation, i.e. making different presentations possible
for the same information.  The better macro packages for TeX and
troff attempt to do the same thing.  This is in contrast with WYSIWYG -
see GN5.

SGML is more fully discussed in comp.text.sgml.

SGML is the name of a directory at the public FTP site ftp.ifi.uio.no
where you can find a (draft) FAQ, a bibliography, and more information.

ODA: Office [Open] Document Architecture, takes a similar approach
but stresses blind interchange.  ODA is defined in the multi-part
standard ISO 8613:1988, in the CCITT T.410 series recommendations,
and in ECMA standard 101.

--------
Subject: GN5. What is WYSIWYG? Do I need it?

What-you-see-is-what-you-get: essential for advertising layout,
but a useless time-waster for a phone book.  WYSIWYG is the
opposite of SGML, in that in SGML you know what something
is (say, a chapter heading) but you don't know what it looks
like; in WYSIWYG you know what it looks like but you don't
know what it is.  The obvious benefit of WYSIWYG is that the
author is aware at all times of the final appearance of the
document; the liability is that the vendor gets to choose the
internal representation of the document, and may not tell you
what it is.  The best trade-off would be a WYSIWYG system with
a well-documented, usable markup language.  We should caution
that few of the self-proclaimed WYSIWYG systems actually show
the exact same thing on screen as you get on a printer:
What You See Is Sort Of Like What You Get.  When 300 dpi,
17 inch terminals are common true WYSIWYG will be practical.

--------
Subject: GN6. What is PostScript?

PostScript is a language for output devices.  It does for output
devices what Unix does for processors, viz., it allows a common
software interface despite differences in hardware platform.
PostScript controllers exist for paper printers from 4 pages
per minute up to 92 ppm, from 300 dots per inch to over 6000 dpi
typesetter, and for film recorders, color printers and X Window
terminals.  Without PostScript, every text formatter has to
understand the idiosyncrasies of every vendor's hardware.
See comp.lang.PostScript for more.  PostScript is a registered
trademark of Adobe Corporation.

--------
Subject: GN7. What is TeX?

TeX is a batch formatter similar to troff developed by Don Knuth
at Stanford.  It is most popular in universities and is freely
traded because of the lack of licensing restrictions. ArborText
sells a commercial version for big and small (ie PC's) machines.
There are various versions for PC-class machines. LaTeX (Leslie
Lamports version of TeX) is a more friendly version of the same
formatter. It does for TeX what macros does for troff.  See
comp.text.tex - which contains a FAQ.

Oh, and to save yourself sounding like an idiot, the "eX" in "TeX"
is pronounced as in "deck", not "sex".

--------
Subject: GN8. What are some popular Desktop Publishing packages?

Aldus practically invented Desktop publishing with "PageMaker".
Ventura is the largest selling of the high-end PC packages.
WordPerfect and Word are lower in functionality but less
expensive and exist on both DOS and Macintosh.
See comp.text.desktop for more information. Interleaf
and FrameMaker are workstation-based and are higher in
price and functionality, and require more substantial
machine resources, but give you more in return.  FrameMaker
is now available for Windows 3.1, giving transportability
between the DOS/Windows, Mac and UNIX world.  See comp.text.desktop,
comp.text.frame and comp.text.interleaf.

--------
Subject: GN9. Where can I read more?

Publish!, Business Publishing and Seybold Report are all
excellent journals for keeping up to date.  There are
books devoted to most of the major packages, too many
to mention here.

Richard Rubinstein's book "Digital Typography", Addison-Wesley
is apparently a readable book that goes into the details of
composition systems, fonts and reproduction.

--------
Subject: TR1. What is troff? Why are there so many questions about it?

Troff is one of the oldest text formatters in existence. Because
it was distributed as part of the Unix operating system for
many years, it is by default on several hundred thousand machines,
far more than any other Unix text formatter.  It originated
in AT&T Bell Laboratories in 1971 and its author was Joseph
Ossanna.  Its legitimate father was a program called runoff,
written at MIT in the 1960's.

Because there is no comp.text.troff, additional questions related
to troff are shown below.  The remainder of the FAQ list is
devoted to troff; bail out now if you are not interested.

--------
Subject: TR2. How many varieties of troff are there? What are the differences?

The original Ossanna troff generates proprietary printer
codes for the Wang C/A/T Phototypesetter; we'll call this
"CAT Troff".  This version comes bundled in many systems,
in particular, SunOS, most other Berkeley-derived systems,
and is contained in the Xenix Text Processing package.
The AT&T, BSD and Xenix variants all differ slightly, but not
in any important ways.  CAT troff is useless without filters to
convert the "CAT codes" to something else, especially since the
C/A/T is as common as a California condor.  These filters are
described later.

In 1981, Brian Kernighan of Bell Laboratories rewrote
troff to generate a generic typesetting language.
These troffs are called "ditroff" (for device-independent troff) and
contain some additional features such as arbitrary line drawing, and
more flexible font handling.  "Documenter's Workbench" (DWB) is
a package containing ditroff and several other typesetting filters.
| The latest AT&T version is DWB 3.3, which sold as source code;
most commercial binary variants (Elan, SoftQuad, Image Network, etc.)
are based on DWB 2.0.  The Free Software Foundation
distributes a re-engineered version of ditroff called groff.

If you have a troff and want to know which it is, type:
	troff < /dev/null > /dev/null
If it responds with "typesetter busy" or "No /dev/cat; use -t or -a",
you have CAT troff, otherwise it's ditroff.  If you get an answer from:
	dwbv
you have the AT&T release 3.0 or later.  The differences are too
numerous and subtle to document here, but the variants are about
95% compatible.  All are ASCII based, but DWB 3.3 and Groff also
accept ISO 8859-1 (aka Latin 1), the Western European character set.

--------
Subject: TR3. What are some of the filters for troff output?

Psroff is a suite of programs that allow you to translate CAT
troff output or ditroff output format into PostScript, HP Laserjet
(with incremental font downloading) or ditroff.  See description
of hp2pbm below for driving printers other than these three.

Psroff works with all versions of CAT troff and ditroff, including
groff.  Psroff allows you to change fonts on the fly (unlike any other
CAT troff converter).  Psroff has been used to drive HP Laserjet and clone
printers, PostScript (including Display PostScript and Sun Pageview),
X windows previewers (such as xditview and xtroff), Ghostscript and
many others.

Psroff comes with a large suite of utility programs that allow you to
create, manipulate, display HP Laserjet and PostScript fonts, as well as
construct width tables for these fonts from a variety of sources, including
TeK PK format, HP SFP, and PostScript.  Psroff also comes with a number of
other utilities, such as PostScript page reordering, Ascii-2-PostScript
converters etc.  Psroff 3.0 is the only troff HP Laserjet filter fully
| supporting scalable fonts or HPGL/2 graphics on HP LJ III printers.

Psroff 3.0 is capable of performing some limited emulation of ditroff
features (eg: line drawing) with CAT troff.

| Psroff 3.0 is available from comp.sources.unix, volume 24.  Or from
| ftp.uunet.ca, in /distrib/chris_lewis/psroff (fully patched).  Patch
| level 14 is current.  The author is Chris Lewis, clewis@ferret.ocunix.on.ca.

Adobe Transcript is a commercial package similar to psroff, in that it
contains filters for converting ditroff or CAT troff.  But only to
PostScript.  It also contains filters for Ascii-2-PostScript, and
is often installed as part of SunOS printcap filters.  Adobe Transcript
contains a user interface script called "psroff" which should not be
confused with the other psroff (but often is).  Information can be
acquired on its availability by contacting Adobe.  Supports psfig
with a little hacking (instructions in psfig release)

The groff package from the Free-Software-Foundation includes drivers
for PostScript, DVI, X and constant-width printers, and the complete
suite of troff preprocessors with the exception of grap.  It is available
via anonymous ftp from several sources (it needs the FSF C++ or AT&T
C++ 2.0 compilers to compile, but many binary versions are also available
for FTP).  Supports character kerning (unlike CAT troff or DWB).  Does not
contain an HP Laserjet driver.  A "dvi2lj" or psroff 3.0 can be used as a
HP Laserjet driver for groff.  Groff has made some slight changes
in the ditroff and width table formats, so use with non-groff drivers
may need a little fiddling.  Written by James Clark.  The latest
version is 1.06.  The latest version can always be ftped from
prep.ai.mit.edu:pub/gnu.

--------
Subject: TR4. What other troff printer drivers are there?

    - thack: CAT to PostScript.   c.s.u. archives.
      For very casual use only.  Has no width tables, and can't,
      for example, make tbl box corners line up.)  Available from
      c.s.u archives.  Very simple to build/install.

    - tpscript: ditroff to PostScript (reasonably good filter)
      c.s.u archives.  Does not support psfig.

    - jetroff: ditroff to HP Laserjet (no support for III scalable
      fonts).  Commercial version (jetroff 2) no longer available.
      Jetroff 1.0 (shareware) is available from c.s.m archives.
      Author: Rick Richardson.  Would need some fiddling to work
      with groff.

    - troff2lj: CAT troff to HP Laserjet.  Limited font handling
      functionality - package discontinued by author when psroff
      2.0 was released.

    - lcat/lroff: obsolete, should be junked, precursor to psroff.

    - hp2pbm: not a troff-2-something filter per-se.  However,
      given a HP Laserjet driver, hp2pbm can convert HP Laserjet
      codes to Jef Poskanzer's PBM format, which permits you
      to use any of the many output formats supported by PBM.
      Author: Chris Lewis and Klaus Schallhorn.  Hp2pbm and PBM+
      are accessible from c.s.m archives.  Hp2pbm includes a
      24 pin Epson driver and a built-in G3 FAX driver.
    
    - cat2desk is a version of lcat/lroff modified to work with
      Deskjets.  Psroff will work with newer deskjets (especially
      scalable font ones with PCL4), but not older ones (the font
      format is different) which are PCL3.

--------
Subject: TR5. How do I get my troff to drive my printer?

    a) If you already have CAT troff and you don't need pic or grap:

       Your best bet is psroff if you want to drive printers supported
       by psroff (PostScript, HP Laserjet, ditroff filters, PBM+
       supported devices (including Epson 24 pin, FAX).  Transcript
       is an alternative for PostScript output (but doesn't
       allow you to mount fonts, no drawing support).

    b) You already have ditroff:

       You may already have a driver for your printer.  Check.
       If not, your best bets are jetroff, psroff, tpscript,
       transcript.
    
    c) You don't have a troff or, you have CAT troff and you need pic
       and grap:

       Get "a DWB", such as groff (no grap), DWB 3, or one of the
       commercial variants.

--------
Subject: TR6. None of the mentioned packages support *my* printer.  Help?

This area is not entered into lightly. Look for a commercial
or free package that supports your device.  Failing that, try
to acquire (legally!) the source code for another device and
modify it.  The AT&T documentation "Troff User's Manual" has
a Reference section that completely documents the ditroff
language.  SunOS and Psroff 3.0 documentation contain
descriptions of the CAT troff language.  Psroff 3.0 is
designed for drop-in drivers, and may be the easiest to
extend.  Coupled with hp2pbm, psroff3.0 can probably drive
just about any kind of printer that supports raster graphics
with relatively little trouble (see Epson 24 pin driver for
guidance).

If you can get a PostScript driver and are running on current
SunOS, you could consider developing a NeWSprint driver for
your printer. NeWSprint is Sun's NeWS (PostScript language
interpreter extended for driving displays; not the same thing
as "Display PostScript"(tm).  This may be easier than developing
a troff driver, since all NeWSprint really needs is the ability to
send a bitmap to a printer. Source and developer's documentation are
shipped standard with NeWSprint.

Thack is ideal for quick hacks with CAT troff for printers that
have dynamically scalable fonts (aside from the fact that thack
has no facilities for building width tables).

--------
Subject: TR7. How to I embed PostScript in troff?

There are two methods:

    - including "absolute" PostScript.  PostScript that knows where
      it goes on the page, and decides its own scaling.
      All versions of ditroff support this one way or another.
      CAT troff does as well when coupled with psroff.  This is
      most often supported by some permutation of \! or \X'...'
      directives.

    - including PostScript, automatically scaling and placing the
      image.  This requires that the PostScript be EPS (so that the
      size and origin of the image is accessible).  Groff and
      DWB 3.3 have facilities for including EPS files and automatically
      placing/scaling them on the page, including leaving space in the
      troff text for the image.

      Psfig (c.s.u archives) is a troff preprocessor which will permit
      this sort of automatic placement/scaling with an older version
      of ditroff (such as DWB 2.1) as long as the backend printer driver
      understands it.  Psroff 3.0 and Adobe Transcript support psfig with
      ditroff, but only Psroff 3.0 will support psfig with CAT troff.

Caution: many PC and MAC graphics packages generate sloppy PostScript which
cannot be gracefully included in other documents.

--------
Subject: TR8. What are fonts?  How do I add fonts?
    
A font is a set of characters in an specific typeface.  Unlike
TeX, troff does not consider the same typeface at different
sizes to be different fonts.

You have to make the width tables, install them, and tell the
troff filter how to emit/request the fonts.  The details differ
from one package to another.  Check the documentation.

--------
Subject: TR9. What are width tables?

Both CAT troff and ditroff need to know the width of each character
that you use.  The widths of each character (along with some additional
characteristics) are arranged in a file for each font.  There are
basically five different width table formats:

	1) CAT troff: uses a binary table of 224 unsigned chars.
	2) MIPS (and RISC/Ultrix) CAT troff uses an ASCII dump of (1)
	3) DWB 2.x and several of the commercial variants use an ASCII
	   format that is compiled into a binary form by a special program
	   called "makedev".
	4) DWB 3.x uses the ASCII format mentioned in (3) - doesn't need
	   to be compiled.
	5) Groff uses the ASCII format mentioned in (4) with minor variations.

If the width tables are wrong, character spacing will look funny - up
to and including overlapping characters, and broken right justification.

--------
Subject: TR10. How do I make width tables?

Creating them is not hard.  Getting the actual metrics sometimes is.

The AT&T documentation "Troff User's Manual" describes the DWB width
table format.  Your DWB may already have a manual page for it.

Psroff 3.0 contains documentation on DWB and CAT troff format width
tables.

DWB 3.3, Psroff 3.0 and tpscript each have a utility for automatically
creating width tables by sucking the data out of a PostScript device.

Psroff 3.0 and jetroff have utilities for creating width tables from
HP laserjet fonts.

Psroff 3.0 can convert between any of the 5 width table formats.

Consult the documentation to find out where to put the files.

--------
Subject: TR11. What are: pic, eqn, tbl, grap, refer?

These are the basic troff preprocessors shipped with DWB:

    - pic allows you to draw arbitrary line-drawing graphics in a
      machine-independent fashion.
    - eqn allows you to construct mathmatical equations.
    - tbl provides a mechanism for specifying and displaying
      automatically sized/configured tables 
    - grap uses pic to construct graphs.
    - refer provides a mechanism for searching for and formatting
      bibligraphic references.

Neither pic nor grap are included with CAT troff, but eqn, tbl and
frequently refer are present.  Groff does not at present support grap.

--------
Subject: TR12. How do I preview my troff on my screen?

    a) X windows: xditview and xtroff (X11R5 contrib directory, xtroff
       also from ftp.cs.toronto.edu) and gxditview (from groff) will
       preview ditroff format (groff requires gxditview), including
       psroff 3.0's ditroff output from CAT troff.
    b) Display PostScript (ie: AIX 3 & DEC dpsexec, NeXT,
       Sun Pageview, Ultrascript): any PostScript generating
       troff.  (Theoretically at least.  May need a teensy bit
       of PostScript hacking to get a reasonable pager (psroff3.0
       has this built in).  Pageview and Ultrascript have some
       limitations so may not work with a specific PostScript
       generator)
    c) Others: You can probably find a PBM converter for it,
       so use a Laserjet-generating troff configuration plus hp2pbm.
       (eg: Sun rasters, 3b1 screens, EGA, VGA, GIFF, TIFF etc.)
|       I preview on X by generating PCL with psroff, converting
|       to PBM with hp2pbm, then display with pbm2Xd (part of hp2pbm)
|       and xwud (part of X windows).
    d) Others: You may be able to find a DVI driver for it,
       so use a DVI-generating troff configuration (namely,
       groff's ditdvi) and use the appropriate dvi2<whatever> filter.

--------
Subject: TR13. I need makedev, but my DWB doesn't come with it.

A freeware version called "mkfont" is available from c.s.m, and
is also included in Jetroff 1.0.  The Jetroff version is to be
preferred because it's been extended a bit more to be an exact
"makedev" replacement w.r.t. command line arguments.

--------
Subject: TR14. Nroff/Troff on DOS machines

Arto Viitanen (av@ohdake.cs.uta.fi) has used djgpp (the MSDOS port of
gcc 2.01) to compile groff-1.05 for MSDOS. The binaries are available
at garbo.uwasa.fi in /pc/unix. The file is groff396.zip and it's 725 Kb.
This apparently works quite well, and has been used to process
manuscripts in excess of 400 pages.

Elan, Image Network, and SoftQuad have commercial versions of DWB
for DOS machines.  They tend to be a bit pricey - in the $500-$1200
range.

There are many freeware versions of nroff that have either already
been ported, or should be easy to port to DOS.  For example, C
implementations of Kernighan and Plauger's "Software Tools" "roff"
(see Ozan Yigit's implementation available from comp.sources.unix).
[roff isn't a complete implementation of nroff, depends on what
you need.]

Related: Ghostscript can be used on DOS to preview the output of any
PostScript-producing application, including groff.  If you do use
GhostScript, make sure that you get the latest version with the good
fonts.  GhostScript also contains CGA and VGA drivers for on-screen
preview.

I'd appreciate any other leads on DOS nroff/troffs.

--------
Subject: TR15. What books can I get about DWB?

General:

    Document Formatting and Typesetting on the UNIX System,
	2 volumes, Nerain Gehani, Silicon Press, ISBN 0-9615336-2-5.
	A very good general reference; covers troff, the preprocessors,
	and most of the popular macro packages.

    Typesetting Tables on the UNIX System, Henry McGilton, Mary McNabb.
	Trilithon Press, ISBN 0-9626289-0-5.  A very good, very complete
	reference and tutorial on TBL.

    Unix Text Processing, Dale Dougherty & Tim O'Reilly, Hayden Books,
	ISBN 0-672-46291-5.  A good discussion not just of troff (ms & mm),
	tbl, eqn, and pic, but also vi and ex, sed, and awk.

    Troff typesetting for Unix Systems, Sandra L. Emerson & Karen Paulsell
	(kjp@well?) Prentice-Hall, 0-13-930959-4.  This is a good book
	for people wishing to write raw troff (as in rolling your own
	macros)

    troff-Programmierung: proffessionelle Textverarbeitung und
        Schriftsatz unter UNIX, Claus Schirmer, Hanser Verlag 1990,
        ISBN 3-446-15649-6.  Reportedly a superb book on troff
	programming.  Ie: a ms-like macro package is built in a
	step-by-step way.  Don't know if there's non-German language
	version.

    The UNIX Text Processing System, Kaare Christian, Wiley, 1987.
	Is especially good on REFER, the best chapter on REFER
	available.
-- 
Chris Lewis; clewis@ferret.ocunix.on.ca; Phone: Canada 613 832-0541
Psroff 3.0 info: psroff-request@ferret.ocunix.on.ca
Ferret list: ferret-request@ferret.ocunix.on.ca
Xref: sparky comp.text:1525 comp.text.tex:14622