| topic started 8/1/2000; 2:44:21 PM last post 8/1/2000; 2:44:21 PM |
8/1/2000; 2:44:21 PM (reads: 1530, responses: 0) |
| Pod
documentation is text that is included in a Perl file (usually .pl or
.pm) that is used both to document the file (like extended /*...*/
comments in C) and to automatically generate HTML documentation. Most
of the macro descriptions on the "Write/modify problems" page are
generated by Pod documentation. Documentation for pod can be found online at http://www.cpan.org/doc/manual/html/pod/perlpod.html or by typing "perldoc perlpod" and "perldoc pod2html" at a Unix prompt. Be aware, however, that WeBWorK performs some custom modifications on Pod, as described in this document. (For those interested in technical details, the modifications are currently performed in the file cgi/cgi-scripts/pod2webwork.pl). Pod documentation begins with an "=command" line and end with a "=cut" line. These lines must be surrounded above and below by a blank line. This is an easy source of errors; a line with any whitespace (such as a single tab) is not considered blank. The most commonly used "=commands" are the "=headn Title" commands, where n is a number from 1 to 6. The number indicates the hierarchical level of the section. "Title" is the title used for the section. The pod2HTML converter will automatically build a table of contents at the head of the page, based on these headers. The order of entries is the same as the order of headers in the source file, with head1 at the top of the hierarchy, head2 indented once, head3 indented twice, etc. Although it is possible to start with a head3, followed by a head5 and then a head1, it is strongly recommended that you start with head1 and do not skip any levels of the hierarchy (e.g. don't have a head3 directly under a head1).
|