req@warwick.UUCP (Russell Quin) (04/29/86)
I've just finished reading Narain Gehani's new book, _Document_Formatting_and_Typesetting_on_the_UNIX_System (Silicon Press 1986). %A Narain Gehani %T Document Formatting and Typesetting on the \s-2UNIX\s0 System %D 1986 %I Silicon Press %C Summit, N.J. ISBN: 0-9615336-0-9 Lib. Congress Catalogue Number: 85-61997 Gehani works for Bell Labs in Murray Hill. He's also written two books on Ada, three books on C, and has edited some others. The book is said to be (according to the blurb on the back) "... the first comprehensive book about the UNIX system document formatting facilities .... "... written especially for readers with little or no experience with the UNIX system formatting facilities... experienced readers will also find [it] very useful. The novice is gradually introduced to the ... facilities. The reader familiar with these facilities will learn about their advanced aspects." It is neither comprehensive nor suitable for novices. The introduction has all the gradual-ness of a cliff-face. It does not get very advanced, either -- if you have already read the relevant UNIX documentation, you are very unlikely to learn much. That's rather strong criticism. After describing the book somewhat less emotionally, I'll explain why I felt that way. |----------------------------------------------------------------------- There are 8 chapters and 3 appendixes, plus glossary, bibliography & index. These are: 1 Introduction -- an overview including some basic troff and -mm requests. 13pp 2 Specifying The Document Format -- a detailed description of the -mm package, and some of the troff basic escape sequences (\f(CW, \fP, distance units (i, c, p etc), \(sq and so on). There are also more details on preparing the input file. Macro definitions are covered very briefly. 88pp 3 Specifying Tables -- in which tbl is explained in some detail, although not all of the features are covered. The interaction between -mm and tbl is mentioned at a user's level -- including .TH and multi-page tables, although there is no example of this. 42pp 4 Specifying Figures -- pic is covered in some detail. The version dexcribed is rather new, though; there is a summary of recent changes, but mention when the features are introduced would probably be better for most users. 68pp 5 Specifying Formulas -- this chapter treats eqn in some detail. A few techniques not mentioned in the Kernighan-Cherry paper are described, but some important basics are omitted or explained only very briefly. Again, the version described is new, supporting macros with parameters. 43pp 6 troff/nroff - The Formatters -- a brief overview of nroff and troff. This contains mostly excerpts from the original manual by Osanna, but written in less formal English and with only a small subset covered. The format is almost identical. 7 WRITER'S WORKBENCH Software -- an overview of the various utilities provided by wwb, including spellwwb, punct, splitinf, double, diction & style. Gehani also mentions `grope', which is not part of wwb, but he doesn't say who distributes it. 12pp 8 Example Document Templates -- Some examples of combinations of the mm macros to give various styles for letters, papers, books and so on. There is a brief overview of how to produce an index using ".tm" and "sort", but this contains bugs. For most people this will probably be the most useful chapter in the book. 22pp App.A More Document Formatting Tools -- some other UN*X programs, most of which are either Berkely-ware or have been unbundled. These include ideal, grap, the -ms macros (a very brief summary, shorter than "man 7 ms " gives), the -mv macros (in the same sort of non-detail), and refer. No mention is made of bib, or of the BSD refer support programs, although lookbib gets a single sentence. 5pp [sic] App.B Document Formatting Commands -- excerpts from the manual pages for some of the programs mentioned, somewhat paraphrased. 11pp App.C Some Font Examples -- ten pages of font samples. As the typesetter used to produce them isn't mentioned, they seem a little pointless. But they're quite pretty. Perhaps Gehani doesn't realise that fonts vary dramatically from machine to machine. 10pp There are also a very short (3pp) glossary, an annotated bibliography (5pp), and a comprehensive index (18pp). |----------------------------------------------------------------------- In each chapter, Gehani seems to have taken the original paper or reference manual section-by-section, and done a quick re-write. There are minor errors and gross omissions. In every case, I was left with the feeling that a beginner would do better with: * a short introduction which explains how to prepare input for troff and which sets out the basic concepts, and * the original papers and reference manuals Although Gehani has attempted to simplify and de-mistify, the incompleteness will only confuse. As an example of what I mean: In the explanation of how to define your own troff macros, [on pp.88-9] the string "\\$n (1 <= n <= 9)" is given to be learnt parrot-fashion as a means of accessing arguments, although _no_mention_ is made of the way in which backslashes are stripped. This is like telling someone that in C, "++x" returns a value one greater than "x", and forgetting to tell them about the side-effect it has of incrementing "x"... There are many other omissions, and there are other occasions when the reader is given a faulty mental model, a wrong way of looking at things, that could cause confusion. There's a bug in his example of index generation, for instance, where his example gives the output of ".tm \fIxxx\fP" as "\fIxxx\fP". This is perhaps because he wanted to simplify the explanation. I prefer accuracy, or at least a mention that details are omitted. Perhaps it will be useful to have a lot of information in one volume, and it does seem to have been reasonably well bound. It is certainly rather easier reading than the technical and somewhat dry troff documentation, and may well be suitable as an introduction to them. But the omissions are too important to be ignored, and beginners would be advised that the book is not enough. Which makes me wonder if it is worth-while at all, especially because there's no real mention of the areas in which the book is lacking. Overall, give people the manuals with (or instead of) this book. ============================================================================== Bibliographical note: the "other papers" I've mentioned, and have called "documentation" or "manuals" are in Volume Two of the Version 7 Unix Programmer's Manual. If you have 4.[123]BSD, they're in the same place, mostly in vol.2A, but also in vol.2C. If you have System Five, look in the DWB [or WWB] binders (there seems to be more than one); they may be elsewhere, too. The papers cover: eqn (Kernighan & Cherry) ideal (C.J.Van Wyke) troff (Ossanna) pic (Kernighan) refer (M.E.Lesk) -- BSD systems come with a clearer document in Vol.2C tbl (M.E.Lesk, 1979) -- ARPA req%warwick.uucp%daisy.warwick.ac.uk@ucl-cs.arpa EARN/BITNET req%warwick.uucp%UK.AC.WARWICK.DAISY@AC.UK JANET req%warwick.uucp@uk.ac.warwick.daisy UUCP seismo!mcvax!ukc!warwick!req (req@warwick.UUCP) For FRPList (mail.frplist), use "frplist" instead of "req" in the above. I cannot reply to ARPA mail -- please include a BITNET or UUCP path.