Pod2man is an application that converts text using Plain Old Document (POD) format to a manual (man page). Using Pod2man is really convenient in the way that it is pre-installed on just about every Linux distribution because it is part of the Perl package.
To write a man page, the formatting is this:
=encoding UTF8 =head1 NAME dr-smile - dispenses output of platitudes designed to improve ones mood =head1 SYNOPSIS B<dr-smile> [--happy] [--joke] =head1 DESCRIPTION B<dr-smile> outputs happy thoughts designed to make one feel better. It has the ability to output pleasant thoughts, jokes, good memories, optimistic fortunes... dr-smile is not 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. =item B<-j>, B<--joke> A good-sense joke will be told. =back ...
Basic text formatting is as follows:
Program names and options use the bold font and are followed by their corresponding man page number (e.g.
The basic structure of man pages is 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 if not wanting to 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 three categories are almost always the same, however the remaining vary. The above layout is an mnemonic aggregate of category order of the man pages that I’ve seen.
Using pod2man to convert text
Pod2man usage is basic:
pod2man dr-smile.pod > dr-smile.1
However these options will probably be wanted to be add, plus compression:
pod2man --section=1 --center="dr-smile manual" --name="dr-smile" --release="1.0" dr-smile.pod | gzip > dr-smile.1.gz