Classic Shell Scripting - Arnold Robbins [223]
Finally, we looked briefly at the Korn shell's privileged mode, which attempts to solve many of the security issues associated with shell scripts.
Appendix A. Writing Manual Pages
Users of programs require documentation, and the programs' authors do too, if they haven't used the software recently. Regrettably, software documentation is neglected in most computer books, so even users who want to write good documentation for their programs often don't know how, or even where, to begin. This appendix helps to remedy that deficiency.
In Unix, brief programming documentation has traditionally been supplied in the form of manual pages, written in nroff/troff [1] markup, and displayed as simple ASCII text with man, nroff -man, or groff -man, typeset for some device xxx with ditroff -man -Txxx, groff -man -Txxx, or troff -man -Txxx, or viewed in an X window in typeset form with groff -TX -man.
Longer software documentation has historically been provided as manuals or technical reports, often in troff markup, with printed pages in PostScript or PDF form. troff markup is definitely not user-friendly, however, so the GNU Project chose a different approach: the Texinfo documentation system.[2] Texinfo markup is considerably higher-level than common troff packages, and like troff, allows documents to be prepared both for viewing as simple ASCII text, as well as typeset by the TEX typesetting system.[3] Most importantly, it supports hypertext links to allow much better navigation through online documentation.
Most documentation that you read online in Unix systems probably has been marked up for either troff [4] or Texinfo.[5] The makeinfo program from the Texinfo system can produce output in ASCII, HTML, XML, and DocBook/XML. Texinfo files can be typeset directly by TEX, which outputs a device-independent (DVI) file that can be translated into a wide variety of device formats by back-end programs called DVI drivers.
These are not the only markup formats, however. Sun Microsystems from Solaris 7 ships almost all of its manual pages in SGML form, and the Linux Documentation Project[6] promotes XML (an SGML subset) markup to facilitate its goal of translating GNU/Linux documentation into many of the world's human languages.
So, what markup system should a Unix program author adopt? Experience has definitely shown that high-level markup, even if more verbose, has great value. SGML (and thus, HTML and XML) is based on rigorous grammars, so it is possible to validate the logical structure of documents before compiling them into displayable pages. With sufficiently detailed markup, SGML documents can be translated reliably into other markup systems, and indeed, several book and journal publishers today do just that: authors submit material in any of several formats, publishers convert it to SGML, and then use troff, TEX, or some other typesetting system at the back end to produce printer-ready pages.
Unfortunately, the SGML software toolbox is still pretty deficient and not widely standardized, so the best choice for maximum software document portability is still likely to be either troff or Texinfo markup, and for manual pages, the format has to be troff, if the man command is to work everywhere.
Ultimately, one would like to be able to do reliable automated transformations between any pair of markup systems, but that goal remains elusive. What you can do today, however, is write manual pages in a restricted subset of troff markup, and have them converted automatically to HTML and Texinfo. To do so, you need two easily installable packages, man2html and man2texi.[7]
Manual Pages for pathfind
Even though complete documentation for markup systems fills one or more books, you can get by quite nicely with the easily learned troff subset that we present here. We show it step by step, as a semiliterate document to accompany the pathfind script from Section 8.1, and then collect the pieces into