Item 46: Embed your documentation with POD.
| Ahh, documentation! Just what all programmers love to spend their time writing when they could be coding, or perhaps playing NetHack, or even enjoying some non-nerdlike activity like friends , family, or exercise. Given that some developers spend ten, twelve, or more hours a day just getting their code to run, it's not surprising that a lot of documentation winds up being written in a half-hearted way, or is written by non-programmers, or is not written at all. A good many software developers, especially those working on sizable projects, work to coding standards that require them to start off function definitions with block comments that provide key information about that functionoverview, inputs, outputs, preconditions, change history, and the like. If those embedded comments are formatted precisely enough, they can be parsed by scripts (probably Perl scripts!) and reformatted into documentation. A source file could thus contain (or be) its own programming reference. This is a Good Thing, because it allows developers to tweak the documentation each time they tweak the code without having to locate and edit a separate document. Sometimes this is about all the documentation that a developer can manage to do correctly. The down side to embedded documentation, however, is that unless you're working in a language or environment that supports it, you or someone in your group has to write and maintain tools that extract the goodies from your source files and generate documentation from them. Someone also has to decide what format the comments are going to be in, and someone has to enforce it. It would be nice, of course, if your comments were formatted like those from other groups so that you could share tools, but without any standards that isn't likely to happen. Fortunately, Perl directly supports embedded documentation. Perl does it in a standardized way that is part of the core of the language, with a feature called POD, or "Plain Old Documentation." Perl source code can contain embedded documentation in POD format. The Perl parser ignores POD sections when compiling and interpreting scripts, but other programs supplied with the Perl distribution can scan source files for documentation sections and format them as man pages, HTML, plain text, or any of a number of other formats. POD basicsPOD is a very simple markup language designed so that documentation written in POD can be translated readily into other formats (text, HTML, etc.). POD is easily readable in raw form if worse comes to worse , too. A POD document consists of paragraphs set off by blank lines. There are three different kinds of paragraphs:
Note that some POD formatters will recognize function names (an identifier followed by parentheses) and other special constructs "in context" and automatically apply appropriate formatting to them. In addition, most POD formatters can convert straight quotes to "smart" matching quotes, doubled hyphens to em dashes, and so forth. Here is an example POD file: POD file
When translatedin this case, by my pod2mif filterit yields: Translated POD file
Man pages in PODAlthough you can use POD for many different purposes, man pages written in POD should follow certain conventions so that they will resemble other Unix man pages. Variables and function names should be italicized . Names of programs, as well as command line switches, should be bold . The man page should have a proper skeleton. The first-level headings traditionally appear in CAPITAL LETTERS. The most important of the first-level headings, in the traditional order, are:
See the pod2man man page for more information about the layout of man pages. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
EAN: 2147483647
Pages: 116