Path: utzoo!attcan!lsuc!sq!murray From: murray@sq.com (Murray Maloney) Newsgroups: comp.text Subject: Re: Troff Macro Programming A: Part 1 [repost] Keywords: sqtroff ditroff troff DWB Message-ID: <1989May29.165203.17889@sq.com> Date: 29 May 89 20:52:03 GMT References: <18@nx32s.anduk.co.uk> <15768@vail.ICO.ISC.COM> <20@nx32s.anduk.co.uk> <15795@vail.ICO.ISC.COM> Reply-To: murray@sq.com (Murray Maloney) Distribution: comp Organization: SoftQuad Inc., Toronto Lines: 243 Checksum: 39528 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