Disclaimer: This is a guide for basic manual writing. It uses a simple markup language and converter to create a manual. It is good for beginners. For a good general overview of man pages read this, for more common approaches to writing manuals read this post.
To get a good idea of how to write a manual seeing the markup of a POD (Perl’s Plain Old Document) works well. This is a POD for a fictitious program called
=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 feel F<--better>. It has the ability to output pleasant thoughts, jokes, good memories, optimistic fortunes, or just give you a big hub. B<dr-smile> is for I<entertainment> and for light mood change requirements. Please use responsibly and with greater change requirements please see an appropriate professional. 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
Man pages are mainly created with these types of formatting:
Note: E<> is technically for escapes, however, I have seen it used before in another pod2man document—whether intentional or not I am not sure. Read the manual
perlpod for markup information.
From a general observation over the years, bold and italic formatting get used in these situations:
- program names
- other manuals
- occasionally manuals
Manual page categories are generally formatted with a certain order. The order of categories vary a bit per man page but the first four are usually present. Here is the general structure and their purpose
NAME The name of the command followed by a one-line description of what it does. SYNOPSIS A command's invocation with its listed options, or a functions parameter listings with its header file. DESCRIPTION An in-depth explanation of the command or function. OPTIONS A explanation(s) of what an option does these are sometimes put in the DESCRIPTION. EXAMPLES Some examples of common usage. FILES Files related to the command or function. BUGS List of known bugs. SEE ALSO A list of referenced or related commands. AUTHOR, HISTORY, COPYRIGHT, LICENSE Information about the author...
For how to create the categorical entries, I only know the basic formatting. Look at the above example to see how it is done.
- Category begin is defined with the
- Indenting is done with the
- Category item is defined with the
- Category end to define a new category is done with the
Document to manual conversion
pod2man usage is basic. First look at manual section definitions here to know what section it should belong to. For my miscellaneous, fictitious program:
pod2man dr-smile.pod > dr-smile.7
Additional information may be wanted to add to the manual along with compression:
pod2man --section=7 --center="General Commands Manual" --release="1.0" \ dr-smile.pod | gzip > dr-smile.7.gz
To view the man page use
man -l dr-smile.7.gz.