Subject: Re: History of UNIX manpages: awf From: Henry Spencer Date: 22/10/2011 18:24 To: Kristaps Dzonsons > > Your source code is readily available, of course... If you haven't seen it already, you might also want to look at my paper "Awk as a Major Systems Programming Language", which was in the winter 1991 Usenix conference and ought to exist online at usenix.org. It talks about my experience doing serious programming in awk, and awf is one of the major examples. > > I'm guessing, from the source comments, that your rewrite was > > inspired by licensing constraints, but is there a particular reason > > for the license conflict -- e.g., a system you wrote it for? The inspiration came from the other end of things, so to speak: not a particular system we wanted nroff on, but a software package that we were trying to make highly portable. C News ran on almost any Unix system, but one headache was how to distribute documentation: we wanted to continue just shipping manpage sources, but a significant fraction of the audience didn't have nroff. The manpage source was simple enough -- especially since we rarely did anything elaborate even by manpage standards -- that I started wondering whether an awk program could process it into something halfway-readable. Things snowballed from there; once I had the basic framework in place, it was seductively easy to add more features. I can't remember for sure, but *probably* the tipping point was that a few of the C News manpages defined their own simple macros for a few things, so I had to implement at least a crude macro facility. Once that was done, what had begun as a specialized manpage formatter rapidly turned into something more general, with manpage-specific complexity moving out of the awk code and into the macro package. Doing the -ms subset was an obvious next move, since C News used -ms for its longer documents. The hard part was deciding where to stop, and in the end that was dictated mostly by "is it good enough to format all the C News documentation?". One reason why awf complains about encountering requests it doesn't understand is that I was running the C News documents through awf as a test, and wanted to know if they used anything I hadn't implemented yet. > > The second question: which reference did you use in writing it? > > AT&T roff was spread over many systems by then. Do you remember > > using a particular one as a reference? Was it from the manual or > > one of the longer reference documents? Insofar as it was based on any specific roff, it was some combination of the nroff that came with V7, and the original Device-Independent Troff; I'd been using the former for a decade, and the latter for several years. I really didn't refer to manuals much; I knew that stuff well, and my concern was much more with -man and -ms features than with nroff features. I looked at our local man(7) manpage -- derived from the V7 one -- to make sure I hadn't missed anything in the -man macros, and perhaps also the V7 troff reference document to check fine points of (e.g.) .if functionality. (I had one of the original printed-by-Bell-Labs V7 document sets, and routinely used it as my main Unix reference.) Henry