Bash Script 4: Man pages

For the last 3 posts, the conv.sh script has evolved to a stable place. Let’s look at creating a simple manual, or man page. This really is quite easy, once you’ve got the basic formatting down.

Creating a basic man page

Here is the basic page:

.\" Manpage for conv
.\" All of these lines here are comments.
.\" They will not be shown to the end user.
.\"
.\" Remember that certain characters need escaping, like the dash.
.TH man 1 "18 Oct 2018" "1.0" "conv man page"
.SH NAME
conv.sh \- convert a video file to x264/mp3/mkv format
.SH SYNOPSIS
conv.sh [-hv] [filename]
.SH DESCRIPTION
conv is a high level shell program for converting videos
.SH OPTIONS
.PP
\-h
.RS 4
This shows the help information
.RE
.PP
\-v
.RS 4
This increases verbosity
.RE
.SH SEE ALSO
avconv(1)
.SH BUGS
No known bugs.
.SH AUTHOR
Barry Gilbert (compguyaug.com)

I’m going to name this file “conv.1”.

Let’s go through the lines and their meaning:

Lines 1-5 are just comments. These can be scattered throughout the document and will not appear to the end user.
Line 6 is the header (TH). There should only be one of these in the file, and it should match this format. Just updated the date, version, and program name.
Lines 7, 9, 11, 13, 24, 26, and 28 are section headers (SH). There are several of these in the file and these are the standard ones, but others can be added as well.
Line 8, 10, 12, 25, 27, and 29 are the content to show under the respective sections.
Lines 14-23 are different, because they are the options sections, and I want things formatted in a specific way. Keep reading to learn more about the options

Options Formatting

For this, I wanted to follow the standard formatting for options, to keep the man pages looking the same. Basically, for each option there are 5 lines, 3 of which control how the content is rendered.

.PP – Starts a single option section. This should be immediately followed by the option tag itself.
.RS 4 – Starts the option description.
.RE – Ends the option description.

Manpage Levels

Before we install that manpage, let’s talk about levels. This man page has a level of 1, or User commands. There are others as well:

Level Description
1 User commands (Programs)
2 System calls
3 Library calls
4 Special files (devices)
5 File formats and configuration files
6 Games
7 Overview, conventions, and miscellaneous
8 System management commands

Installing the man page

In Ubuntu, the man pages live in the folder /usr/share/man/man1. Your system may be slightly different, but the utility manpath will show you the search path for man pages on your system. To install the man page, just run these 2 lines:

sudo install -g 0 -o 0 -m 0644 conv.1 /usr/share/man/man1
sudo gzip /usr/share/man/man1/conv.1