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 ...
Get Classic Shell Scripting now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
