| Debugging C and C++ code in a Unix environment | ||
|---|---|---|
| Prev | Appendix A. | |
Under Unix, there are several formats for documentation in common use.
Online manual pages (`man-pages') are the traditional format for documentation under Unix. Man-pages are almost always reference documentation, documenting exhaustively switches and parameters. Man-pages are written in nroff format (a typesetting language), and mostly viewed as ASCII text with simple markup (bold, italic).
You can search through a man-page using the search facility of your pager. We recommend less rather than the default more.
If you have the source version of a manual page, you can make a nice printed version with a command sequence like groff -Tps -mandoc /usr/man/man1/ls.1 | lpr
If you have only the formatted version (`catman') of a manual page, you can try printing that; if that does not work, you can filter it to get plain ASCII with col: col -b < /var/catman/cat5/shells.5 | lpr
The `info' format is the preferred format of the Free Software Foundation. Info is an old hypertext format which you can read through info. The info reader is not very comfortable, but has a good search facility, and it does not require X. However, using xemacs for reading info makes life easier.
`info' format is not written directly; it is produced from files in the TeXinfo [1] format (these files are not installed on most systems; you'll probably have to unpack source archives to find them). You can produce nice printable versions through something like texi2dvi make.texi | dvips -f | lpr
HTML (HyperText MarkupLanguage) is the default format of information on the World Wide Web; its hypertext facilities and the nice browsers for it make it increasingly popular as a documentation format. It is however difficult to search through a number of HTML files with most browsers. X is not required for reading HTML; there are text-mode browsers available for it (e.g. lynx), and it can even be read without a browser.
PDF (Portable Document Format) is a successor to PostScript with hypertext facilities. Unlike HTML, it provides the author full control of the layout of a document. You need a windowing system to read PDF.
Many programs come with documentation in `unstructured' formats, such as plain ASCII files (e.g. READMEs), (La)TeX files and PostScript files. Because of their unstructuredness, they are difficult to search through. Also, documentation in these formats is often not installed; you'll have to get it from the source.
You can view documentation in DVI format (TeX's output format) through xdvi, and you can view PostScript through gv, ghostview, pageview or gs.
| [1] |
TeXinfo is a set of TeX macros specifically aimed at producing high-quality printouts, while maintaining readability on simple text terminals. |