Perl's Plain Old Documentation: maintaining manpages
Prev | Chapter 14. Writing Documentation | Next

## Perl's Plain Old Documentation: maintaining manpages

We use Perl's pod (plain old documentation) for manpages. Every file installed with Lire in `/usr/bin/` must have a manpage. Every file installed in `/usr/share/perl5/Lire/` and `/usr/lib/lire/` should have a manpage. It would be nice if the files in `/etc/lire/` were documented in manpages too. And perhaps for some files in `/usr/share/lire/xml/`, `/usr/share/lire/reports/`, `/usr/share/lire/filters/` and `/usr/share/lire/schemas/` manpages could be useful.

Since the files in `/usr/bin/` are commands, ran by Lire users, the manpages describing these should focus on the user perspective. Describing the inner workings and implementations of the commands is less important than describing why someone would want to run the specific command. If there's need to make some remarks on the internals of these scripts, a section called DEVELOPERS could be added to the manpage. The perl modules installed in `/usr/share/perl5/Lire/` and the commands in `/usr/lib/lire/` are not intended as interfaces for the user. Only people wanting to change or study the operation of Lire itself will interact with these files; therefore, the manpages should explain the inner workings and implementations of these files. The configuration files in `/etc/lire/` might be changed by users. These should be properly documented: in manpages or in the Lire User's Manual.

Prev | Up | Next
Chapter 14. Writing Documentation | Home | Docbook XML: Reference Books and Extensive User Manuals