How to write a simple Manpage - Psychology, Philosophy, and Licenses
In this thread you'll learn how to write a very simple man page for your programs.
I won't go into the details of what and where are Manpages. If you want more information refer to the followings:
Sections of a manpage
A manpage normally contains those sections (taken from the man 7 mdoc)
For example, you might want to ommit the RETURN VALUE but add a COMMANDS section if the program
has a shell interface that accepts a set of commands.
Manpages follow a format code called Groff (or Troff).
As with any markup you'll use some code to change the appearance of the text.
The main format macros well use are the followings:
Writing the manpage
The empty Manpage should look similar to this:
Let's fill it up section by section but first let's explain the first line.
This line describes the manpage, it's the decoration at the top and bottom of the page.
Replace name_of_program with the name of the program.
Replace 1 by the section the program belongs to. (1 Executable programs or shell commands)
Replace "Jun 15, 2014" by the current date.
The last 2 strings are other decorations.
The NAME section:
This section contains a one-liner with the name of the program and the simplest description.
The SYNOPSIS section:
This section contains (for CLI) all the short-hand arguments regrouped together without any explanation.
Here we've made, for easier reading, the "nixers" bold, the "-hv" bold and the "rice-max-mode" italic.
The DESCRIPTION section:
This section contains a big description of what the program purpose is.
We've made the "nixers" word bold and separated the first paragraph from the other (.PP).
The OPTIONS section:
In this section every command line arguments are explained.
The .TP let's you align everything after the shorthand option.
We've made the shorthands bold using ".B" and the arguments of shorthand italic "\fI \fR"
You don't usually have to escape "-" but it's sometimes better to do so.
The RETURN VALUE section:
Here's the part where you explain what the program will return in multiple cases. (echo $?)
Everything that is inside ".RS" ".RE" will be considered as it's own block following the format that
was used just before ".RS".
".IP" is used to indent the bullet "\(bu 2" and ".B" with ".\fR" to format the return value to bold.
The ENVIRONMENT section:
In this section you mention what environment variable the program follows.
It's an example of a section that could've been ommited.
The ERRORS section:
It regroups well known errors that might happen while using the program.
When refering to an external command or manpage you need to put inside parenthesis to which section it belongs.
It's also a good idea to format them to bold.
The SEE ALSO section:
This section regroups all the manpages that are related or mentioned in the manpage.
The AUTHOR section:
It is an example of a custom section.
Testing the Manpage
To see what the Manpage will look like execute:
Note: If a manpage belongs to the section 1 (Executable programs or shell commands) it should have the extension ".1".
I won't go into the details of putting the manpage in the manpath.
This is how a simple Manpage is written. Once you get the idea it's really easy. I haven't walked through all the format macros but those are the simpliest ones.
More to read from one of our fellow users:
Great thread, thanks! mandoc is also pretty neat.
this will come in handy for all the useful things I make. /s
also, what are those numbers in the top left corner of the scrot?
I am always fearing my manpages look too ugly or are hard to understand.