WTFM (Write the Fine Manual) with Pod2man text-converter
Because it was the authors first effort to write a man page, talk was that it was good to use Pod2Man. Pod2man is an application that converts text using Plain Old Document (POD) formatting to traditional manual (man) pages. POD markup is easy to do and
pod2man is conveniently pre-installed on most Linux distributions (as it is part of the Perl package).
To get a good idea of what to do, here is a basic example demonstrating the formatting (of a fictitious program
=encoding UTF8 =head1 NAME dr-smile - output platitudes to help to improve one's mood =head1 SYNOPSIS dr-smile [B<--happy>] [B<--joke>=F<type>] =head1 DESCRIPTION B<dr-smile> outputs jokes and happy thoughts designed to make one fell F<--better>. It has the ability to output pleasant thoughts, jokes, good memories, optimistic fortunes... B<dr-smile> I<isn't> a replacement for a professional doctor, please use responsibly and enjoy. Additional options are available in the configuration file F</etc/dr-smile.conf>. =over 4 =item B<-h>, B<--happy> A general happy thought will be output (e.g. C<dr-smile --happy>). =item B<-j> F<type>, B<--joke>=F<type> A good-sense joke will be told. The types are: F<knock> and F<oddball>. Read more in B<jokes(1)>. =back
There is both text formatting and section formatting that is required for a man page.
All the POD text formatting tags needed to know are as follows:
Man pages use two types of formatting (that I’ve ever seen). That are implemented by POD’s bold formatting and PODS filename-or-italic formatting:
|Formatting type||Used for|
|POD Bold formatting||
|POD Filename formatting
POD Italic formatting
There are three section tags that are used in
pod2man (that I know of). The
pod2man manual refers to these as Command Paragraphs and they are: header/category sections, item sub-sections, and “over” sub-sub-sections for additional descriptions of item sections. References to all of these are in the above example.
- Header/Category sections are the block descriptors and their contents (like NAME, and DESCRIPTION…).
- Item sections refer to options generally and often override
=oversections for their list item.
- Over sections refer to option descriptions.
General layout structure
Man pages follow a basic (though liberal) structure can be well represented by this:
NAME The name of the command, followed by a one-line description of what it does. SYNOPSIS A representative invocation of how to run the command and options it has. DESCRIPTION A detailed description of the functioning of the command. OPTIONS A list of it's options (these are sometimes put in DESCRIPTION). EXAMPLES Some examples of common usage. BUGS List known bugs. SEE ALSO A list of referenced or related commands. AUTHOR Specifying the contact information. COPYRIGHT Specifying the copyright information.
The order of categories varies a bit from man page to man page. The first four categories are almost always the same, however the remaining vary a bit. The above layout is an mnemonic aggregate of category order of the man pages that the author has seen.
Convert pod format to manual page
Pod2man usage is basic:
pod2man dr-smile.pod > dr-smile.1
However, these additional options will probably be wanted to be added, plus compression:
pod2man --section=1 --center="dr-smile manual" --name="dr-smile" --release="1.0" dr-smile.pod | gzip > dr-smile.1.gz