WTFM (Write the Fine Manual) with Pod2man text-converter

Disclaimer: I am not an expert on creating man pages but from the research I did I discovered this method to be very easy. It also worked for me as well because github has rendering support for this format. For a more traditional approach nixCraft has a better article for that.

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:

Bold B<text>
Italic I<text>
Link L<http://address.org/ >
Filename F<text>
email E<gt>name@address.comE<lt>

Program names and options use the bold font and are followed by their corresponding man page number (e.g. B<nano>(1)).

Layout Structure

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

Result

screenshot-manpage

Resources

About these ads

About Todd Partridge (Gently)

Good times, good people, good fun.
Follow

Get every new post delivered to your Inbox.

Join 52 other followers

%d bloggers like this: