General Layout
Manual (man) pages should obey a particular layout. This isn’t strictly necessary, but will help make your man page similar to every other in your system and not confuse or surprise your users.
When you display the man page of a program, you will normally find some of all of the following sections in usual order of appearance:
NAME
The name of the program, followed by a one-line description of what the program does. This will be read by apropos, man -k and whatis. So it’s an important section that I will be detailing further below.
SYNOPSIS
This is the command syntax used by your program. Command line syntax follows certain conventions you will want to adhere to. More details below.
DESCRIPTION
This is where you describe what the program does. It can be as long as needed, but language should be concise and clear and you shouldn’t put in here any details that will be repeated in other sections.
OPTIONS
If your program uses argument options, as described in the SYNOPSIS section, this is where you list explain what each option does.
EXAMPLES
Sometimes you may feel a need for this section, so you can better illustrate some command usage, or program behavior and output.
EXIT STATUS
Describes the application various exit status. If your program behaves conventionally – exits with status 1 on error for instance – this section isn’t strictly necessary. But you may wish to detail here any other non conventional exit codes.
SEE ALSO
Sometimes your program may be closely related to other system programs. You should in that case list those program here, along with their manual section number. For instance, if your program wraps the grep command, you may wish to reference it in here. Just write the program name followed by its manual section number between parenthesis; grep (1). You shouldn’t however list here programs that aren’t common Linux applications. If your program is related to some obscure application, chances are the user reading the man page doesn’t have it installed and it doesn’t make sense to make a reference to it. Just use it for common applications that are likely installed in the user computer.
BUGS
Any known bugs in the application should be placed in here, so the user is well informed and expects them.
AUTHOR
Your name and your email address.
COPYRIGHT
Specify here any copyright information for this manual page (not the program).
These are the most common sections in man pages. Some may be absent and you will no doubt find other sections. Just try to be consistent in how you use them by following the above advise.
Remember, although we do read man pages individually, they are all part of a documentation entity knownn as Manual that is managed by programs like mandb. Each man page is in fact, a chapter of this larger “book”. So you will want for the Linux Manual to be internally consistent.
Manual Sections
The linux manual is split into eight numbered sections, organized as follows:
1 Executable programs or shell commands
2 System calls (functions provided by the kernel)
3 Library calls (functions within program libraries)
4 Special files (usually found in /dev)
5 File formats and conventions eg /etc/passwd
6 Games
7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8 System administration commands (usually only for root)
9 Kernel routines [Non standard]
Man pages file names and location
A man page file should be named according to the following format:
<program_name>.<section>
So, for example, a man page for a normal program called ppenv would be named ppenv.1. And if it had a configuration file you could create another man page named ppenv.5 to document this configuration file syntax and usage. If ppenv was in fact a system administration command and not a regular user program, it should be named ppenv.8, instead of ppenv.1
The system stores man pages in the /usr/share/man/ directory. This directory is further divided into section directories, one per section. So a typical tree is:
/usr/share/man
├── man1
├── man2
├── man3
├── man4
├── man5
├── man6
├── man7
├── man8
User created man pages however should not be installed there!
Instead they are installed on /usr/local/man or /usr/local/share/man. On many linux distributions, the first is in fact a symlink to the second. The command manpath will list the locations in which the mandb (explained below) command will look for manual pages:
$ manpath
/usr/local/man:/usr/local/share/man:/usr/share/man
manpath reads these locations from the /etc/manpath.config configuration file.
Installing a man page
The installation process is rather simple and only requires the man page to be gziped and copied to the correct location. Then for the man command to find it, it needs to be added to man database, with the mandb command.
$ sudo cp ppenv.1 /usr/local/share/man/man1
$ sudo gzip /usr/local/share/man/man1/ppenv.1
$ sudo mandb
What you must keep in mind is that you may need to create the man1, man2, etc. directories inside of /usr/local/share/man. In Ubuntu (and as is the case with Ubuntu-MATE) those directories aren’t created for you. Usually the man directory in /usr/local/man is empty when the operating system is installed.
Also keep in mind that a man page for the manual section 1, should go to the man1 directory and not anywhere else. As is the case for all other manual sections.
Assuming all of the above was done (and the file ppenv.1 contained well formated man source code, as described in the second part of this tutorial), the manual page was successfully installed. And the command man ppenv would now display the expected man page.
How man works
When the command man ppenv is executed, what actually happens is that man runs the groff command. groff is a text formatter that reads special macros in a file and prints the formatted contents to the standard output (the screen). groff will then often pipe its standard output to a pager program for easier reading; usually the less command.
You can read man groff for a more informative explanation on how to use it, but this isn’t strictly necessary for understanding and creating man pages.
These macros that groff reads and interprets always start with a . (dot) followed by the macro name. Some macros have additional parameters, others don’t.
Example of a complete man page contents
The zcat command can be used to see the contents of any man page that has already been installed. The output is the actual source code of a man page.
Below is the man page of a bash shell script named ppenv that you can get from https://bitbucket.org/krugar/ratscripts
$ zcat /usr/local/share/man/man1/ppenv.1.gz
.\" manpage for ppenv
.\" Contact [email protected] to correct errors or typos
.TH ppenv 1 "01 August 2016" "version 1.3.1" "ppenv manpage"
.SH NAME
ppenv - print the current python environment
.SH SYNOPSIS
.B ppenv
.RI "[" OPTION "]..."
.SH DESCRIPTION
.B ppenv
prints information about the current python environment, including python
version(s), the git branch of the current directory and information on
installed packages, IPython and the the ipdb and pydb debuggers.
.PP
.B ppenv
.RI "works best with " pyenv .
It can still report information without pyenv installed, but will have limited
reporting functionality. Git information will not print if git is not installed,
and any level of reporting more verbose than the
.IB -1 " option"
will be ignored if pip is not installed on the currently active environment.
.PP
If pyenv is installed, ppenv can show all python versions that were enabled
through either the 'global', 'local' or 'shell' options of pyenv. It also
supports the pyenv virtualenv extension.
.PP
The currently active python version is always highlighted, or prefixed with an
.RB ' * '
if running ppenv with the
.IB -c " option"
or in a terminal without color support.
.PP
.RB The " (system) " "flag indicates packages that are not installed on the
currently active environment but can still be reached through the
.IR "PATH" ". Do not confuse with"
.BR 'system' ", that may be displayed on the first line of the output; That's
the system python installation, usually at
.IR /usr/bin ", that is printed by"
.BR ppenv " when pyenv is not installed, or has not activated any environment."
See below.
.SH OPTIONS
.TP
.B -1
Prints only the first line of the output, consisting of the Python environment
.RB "and git branch. " "This is the default option" .
.TP
.B -2
.RB "(implies " -1 ") Prints also the second line of the output, with"
information on IPython and the ipdb and pydb debuggers. If pip is not installed
.RB "on the current environment, it will have the same effect as " -1 .
.TP
.B -a
.RB "(implies " -2 ") Prints all information. This includes a list of installed"
packages. If pip is not installed on the current environment, it will have the
.RB "same effect as " -1 .
.TP
.B -o
.RB "(implies " -a ") Any outdated packages will be highlighted, based on
the 'pip list -o' command.
.PP
.RS
.B "Note:"
All the above options are mutually exclusive. If they are used together, only
the rightmost option will take effect.
.RE
.TP
.B -c
Forces the use of no color in the program output. This option is not necessary
.RB "on terminals without color support, since " "ppenv" " will know when it"
needs to switch to a non color output.
.TP
.B -h
Prints program usage information and exits successfully.
.TP
.B -v
Prints the program version number and exits successfully.
.SH EXAMPLES
The following will show a typical output on a directory with a git repository
with the 'develop' branch checked out.
.PP
.RS
.BR $ " pyenv shell 3.5.2 2.7.11"
.br
.BR $ " ppenv -c"
.br
python: *3.5.2 2.7.11 (shell) git branch: develop
.RE
.PP
The following shows a pyenv python 2.7.11 installation where neither IPython or
ipdb are installed. But because they are both installed on the system
.RI "Python environment and available in the " PATH ", they still get listed as"
.RB "as being available, hence the " (system) " flag."
.PP
.RS
.BR $ " pyenv shell 2.7.11 3.5.2"
.br
.BR $ " ppenv -2c"
.br
python: *2.7.11 3.5.3 (shell) git branch: develop
.br
ipython: yes (system) ipdb: yes (system) pydb: no
.RE
.PP
Changing to a virtual environment named 'soray' that has been set with
the 'local' option of pyenv, for easier switching when walking to the directory,
results in a similar output to the following.
.PP
.RS
.BR $ " pyenv shell --unset"
.br
.BR $ " cd ~/Projects/Scripts"
.br
.BR $ " ppenv -c"
.br
python: soray *3.5.2 (local virtual) git branch: dataopers
.RE
.PP
The following shows a typical output when pyenv is not installed, or when it
doesn't have any environment activated. The currently active Python installation
is the system one. Also showing the output of git when the prompt is in a
directory outside any git repository.
.PP
.RS
.BR $ " ppenv -2c"
.br
python: system *2.7.12 (global) git branch: n/a
.br
ipython: yes ipdb: yes pydb: no
.RE
.SH EXIT STATUS
If python is not installed on the system, this program will end with exit status
1.
.SH BUGS
No known bugs.
.SH AUTHOR
Mario Figueiredo ([email protected])
.SH COPYRIGHT
MIT License
.PP
Copyright (c) 2016 Mario Figueiredo
.PP
This document is part of the ppenv software.
.PP
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
.PP
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.