🚀 go-pugleaf

In articles <15768@vail.ICO.ISC.COM> and <15795@vail.ICO.ISC.COM>,
rcd@ico.ISC.COM (Dick Dunn) comments on articles <18@nx32s.anduk.co.uk>
and <20@nx32s.anduk.co.uk>, posted by lee@anduk.co.uk (Liam R. Quin).

I would like to comment on several of the points that have been raised.

********************************************************************************
In article <15795@vail.ICO.ISC.COM>, Dick Dunn writes
> In article <20@nx32s.anduk.co.uk>, lee@anduk.co.uk (Liam R. Quin) writes:
> > In article <15768@vail.ICO.ISC.COM> I (Dick Dunn) wrote:
> > > In article <18@nx32s.anduk.co.uk>, lee@anduk.co.uk (Liam R. Quin) posted
> > > the beginning of an introduction supposedly for troff.
> > > However, much of
> > > it is specific to a formatter based on troff but significantly changed.
> > This is only superficially correct.
> > The notes apply to all the versions of troff I've seen.
> 
> It is much more than "superficially correct"!  It doesn't matter if it ap-
> plies to all versions of troff you've seen--that's a personal view.  I can
> as easily say that much of it applies to *no* version of troff I've seen.

In fact, Mr Quin's notes apply to many versions of troff, including 
common troff, ditroff, and nroff as well as UCB's Gremlin ditroff,
Eroff, Xroff, profficient troff, PWB, DWB, DWB 2.0, and sqtroff.

> The point is that, as far as I can tell, the extensions do not exist in
> *any* version of troff that AT&T has ever sold or licensed.  That's a lot
> of instances of troff over the years even if it isn't all of them.

Almost two years ago, SoftQuad and AT&T entered into a co-marketing 
arrangement which was announced in the press at the time.  Under the
terms of this agreement, negotiated over many months and following 
evaluations by AT&T of various products, 

	SoftQuad Publishing Software is available in source 
	and binary form through AT&T and SoftQuad as an enhanced 
	product derived from AT&T's UNIX(R) system Documenter's 
	Workbench(TM) Release 2.0 Software.

In its current release, SQPS has also been incorporated by AT&T's
IMS group into its "Standard Operating Environment" (SOE) for 
internal use, and is being widely sold by AT&T to its customers.

Similar extensions exist in both the UCB and profficient versions.
The version in use at AT&T Bell Labs also includes extensions that 
never made it into the mainstream product (or SQPS for that matter) but 
are documented in Nahrain Gehani's book "Document Formatting and 
Typesetting on the UNIX System".

********************************************************************************
> > > "old troff" comments also apply to "new troff" (i.e., ditroff).
> > I don't think that 1978 is very new...
> 
> The first ditroff appeared more on the order of early '80's.  After that,
> pic was added, then grap was added.  These require changes in troff.  Grap
> corresponds to DWB 2.0, which is probably no older than 1986 or 1987.  The
> recent changes also give a much-improved nroff.

Troff was developed around 1973 by the late Joseph F. Ossanna.  This 
program was based upon an earlier text formatter written by Doug McIlroy.
which in turn was patterned after J. Saltzer's original RUNOFF for the 
Cambridge Time Sharing System in the late 1960's.  Brian Kernighan's 
ditroff appeared in 1979 and DWB 2.0 followed in 1986.

The AT&T/SoftQuad distributed version of troff is the latest step in 
the evolution of RUNOFF-based formatters.  As such, it has supplanted 
ditroff as the so-called `new troff'.

********************************************************************************
> > I chose to use longer names in some of the examples for several reasons.
> > * It is *much* easier to start off with a higher-level representation.
> 
> I agree, but it doesn't work!  I have often wished for longer names, and
> for some safer way to partition the name space.  But one of the uses of
> troff input format is as an exchange format.  If one takes great liberties
> with the notation, that use is lost.  (My own teaching experience suggests
> that one is better to stay on the straight and narrow; students have enough
> to remember just what's correct and what isn't, let alone some sense of
> conditional validity and substitution.)

While troff's use as an interchange format has always been a goal, it has 
never really been a reality.  Not only have successive versions of troff 
included significant changes in the command set, but nroff, troff, and
ditroff have never been 100% compatible.  With so many ROFF-based formatters 
available, each with its personality (in the form of undocumented behavior), 
one would have to be especially careful to remember what's correct with a 
given version, on a given machine, attached to a given printer.

There are, however, quite a number of requests and escape sequences that 
have remained consistent since the V7 version was documented.  By 
restricting yourself to that set, you can be fairly confident of producing
a document that you can distribute freely.  This restriction applies
no matter which version you use.  

There are two provisos in the case of SoftQuad's and UCB's versions 
-- where long name syntax has been added -- 
	(1) You should disable long-name requests.
	(2) You should read a string named `[' with \*[[].
This seems a reasonable price to pay, both in terms of re-education
and added effort in formatting a document.  A simple sed script could
be used to perform the conversion required in (2).

********************************************************************************
> Who are "you"?  Troff input almost always involves two parties--the
> document author and the macro author.  They can (and frequently do) get
> into conflicts.  Suppose that it's the document author who defines ps12 and
> uses it with macros which have been scrunched.  (Note in passing:  The
> business of pulling out the separator between command and arguments is a
> Bad Idea...but it's still common.)

Not only do we agree that the separator should not be removed, we recommend
against it to prevent the possibility of conflicts like the one you describe.
Therefore, scrunching sqtroff macros does not include removing spaces between 
commands and their arguments; our documentation is quite clear on that.  
We also recommend that users and macro writers test for potential conflicts
by using two conditions that were introduced by SoftQuad.  For example,

	.if d name .tm Macro/request/string name already defined
	.if r name .tm Register name already defined

The potential for conflict has always existed.  The author has 
always had the option of defining a macro `p' which could, arguably, 
also cause misinterpretation. For example, 
	.de p
	.tm Argument 1 is: \\$1
	.tm Argument 2 is: \\$2
	..
	.p s 12

should result in the terminal messages:
	Argument 1 is: s
	Argument 2 is: 12

Given the same macro definition,
	.ps12

will not invoke the macro `p' with the argument `s12' on any version of troff.
No documentation ever has touched on this.  So, while you can argue that 
troff has always had semantic inconsistencies, you should also be aware 
that expected behavior is not always documented or otherwise defined.

The interpretation of 
	.ps12 

by sqtroff depends on whether there is a macro called `ps12' or not.
If there is a macro named `ps12', it is invoked as any other macro.
Else if there is a macro/request named `ps', it is invoked with argument "12"
and a warning message (optional) is issued to advise you.

(warning) No macro/request ".ps12", interpreted as ".ps" and argument(s)

********************************************************************************
> > Troff knows whether or not a macro/string/register has been defined.
> > It simply doesn't tell the user (although some versions produce a
> > warning, and it's fairly easy to change ditroff to do this).
> 
> One can make a good case either way for number registers.  However, macros
> and strings share the same name space with one another--and with the
> built-in commands.  It is an important, documented, time-honored property
> of troff that "...control lines with unrecognized names are ignored."

A property that is preserved in sqtroff and augmented by a warning message
to advise the unfortunate troff programmer who might not be able to find 
the source of a problem otherwise.

********************************************************************************
> > So troff can, in fact, do this.  It could probably even work out whether
> > to do [ or xxx in \*[xxx] depending on whether xxx was a defined name,
> > although there seems to be no need for this.
> 
> No, not if the string [ is defined.  If there has been a
> 	.ds [ stuff
> then \*[xxx] *must* produce stuffxxx]

You've got a valid point here.  In order to provide an extended syntax,
SoftQuad had to pick a pair of delimiters so that sqtroff would know 
when long names were being used.  Deciding that it would be prudent to 
provide compatibility with at least one other enhanced ditroff -- used 
at the UCB computer center -- `[' and `]' were selected.  We realized 
that this change could cause problems for user-developed macro packages,
but the majority of those polled felt that the advantages gained
were worth the effort required to comply with the new syntax.

Quoting from the UCB addendum to the Nroff/Troff User's Manual:

	Because of the longer, variable-length names, spaces  are
	now required to separate commands and arguments (e.g., .nr XX 4,
	.nrXX 4, and .nr XX4, etc. are no longer equivalent.

	Strings, number registers and fonts of any length name may be 
	called with \*[x...x], \n[x...x] and \f[x...x], respectively.
	Special characters may also be called with \[x..x].  The format
	of a number register may be accessed with \g[x...x], and the 
	current input-line horizontal position may be stored in 
	register x...x with \k[x...x].  Size changes of any number of
	digits may be called with \s[x...x].

********************************************************************************
> I am interested in the "UCB (non-proprietary) version"--the last I'd heard,
> Berkeley had not managed to "free" nroff/troff from AT&T code and they
> didn't have anyone working on it.  Details?

It's highly unlikely that anyone would be able to write a fully compatible
troff without significant study of the AT&T source code because of the 
complexity of the original code (such a program's legal status would 
probably be unclear at best).  People have written vastly-simplified
nroff-only subsets: see various source archives for copies.

The most recent information I have on UCB's gremlin ditroff is 
article <252@ucbopal.CC.Berkeley.ARPA> in newsgroup `net.text' 
and dated July 1985.  I have no way of knowing if the poster 
is still there or otherwise connected to the network.

If you feel lucky, you can try contacting

	Edward Moy
	Academic Computing Services
	University of California
	Berkeley, CA 94720
	edmoy@ucbopal.ARPA
	ucbvax!ucbopal!edmoy

********************************************************************************
> > ...and there is a strong case for adding better error messages to
> > troff...
> 
> Quite true.  But one ought to be careful to distinguish "errors" from
> "warnings", in order not to bury useful error messages where they won't be
> noticed.  For example, using an undefined command is probably a warning
> that one ought to be able to switch on during debugging, but (per above)
> it's not an error so you don't want to see it normally.

This is something that sqtroff is careful to do.  There are four levels 
of error/warning messages in sqtroff.  The 0th level is for outright 
errors that will cause processing to terminate.  The other levels
are obtained by using the (new) `-wN' option on the command line
or by using the (new) `.warn N' request inside the file.  Each level
provides more extensive error checking, akin to `lint'.

********************************************************************************
Murray C. Maloney		uucp:		{utai|utzoo|uunet}!sq!murray
Documentation Specialist	Internet:	murray@sq.com
SoftQuad Inc.			Phone:		(416) 963-8337