Ticket #292 (closed cage: fixed)
[CAGE] Update all Pod documentation to use sane, modern headings
Reported by: | allison | Owned by: | whiteknight |
---|---|---|---|
Priority: | normal | Milestone: | |
Component: | docs | Version: | trunk |
Severity: | medium | Keywords: | newbie |
Cc: | Language: | ||
Patch status: | Platform: | all |
Description
The Pod documentation in the repository currently uses a crufty old Perl 5 style, that gives document titles using "=head1 NAME" blocks, and breaks up the file into multiple "=head1 ALLCAPS" sections. Aside from making absolutely no sense outside the Perl tradition, this old style generates truly horrible html and man formatted documents, which are the primary way most people will read them.
- Modernize all files to use a single "=head1" for each document (the title of the document).
- Don't include the file name in the documentation (either they're reading the file in the source tree and so know the file path already, or they aren't and don't care about the file path).
- Demote subsections so they are all "=head2" or below (preserving the section hierarchy, so "=head3" changes to "=head4", etc).
- Use title case in all section titles ("Description" instead of "DESCRIPTION").
See r36470 for an example.