Want your new Linux program to look professional? Give it a man page. We’ll show you the easiest and fastest way to do it.
The pages of man
There is a kernel of truth in the old Unix joke, “the only command you need to know is the man. Man pages contain a wealth of knowledge, and they should be the first place to turn when you want to learn more about a command.
Providing a manual page for a utility or command you wrote elevates it from a useful piece of code to a complete Linux package. People expect a man page to be provided for a program that was written for Linux. If you support Linux natively, a man page is required if you want your program to be taken seriously.
Historically, man pages have been written using a set of formatting macros. When you call the man to open a page, he calls Groff to read file and generate formatted output, depending on the macros in the file. The output is redirected to less, then displayed for you.
Unless you frequently create man pages, writing one and inserting the macros manually is hard work. Creating a man page that analyzes properly and looks fair may exceed your goal of providing a concise, but complete, description of your command.
You should be focusing on your content, not fighting an obscure set of macros.
pandoc to the rescue
the pandoc program reads markdown files and generates new ones in about 40 different markup languages and document formats, including the man page one. It totally transforms the process of writing the man page so you don’t have to struggle with hieroglyphics.
To get started, you can install pandoc on Ubuntu with this command:
sudo apt-get install pandoc
On Fedora, the command you need is:
sudo dnf install pandoc
On Manjaro, type:
sudo pacman -Syu pandoc
Sections of a man page
Man pages contain sections that follow a standard naming convention. The sections that your man page needs are dictated by the sophistication of the command you describe.
At a minimum, most man pages contain these sections:
Last name: The name of the command and a single single line that describes its function.
Synopsis: A brief description of the calls that someone can use to launch the program. These display the types of command line parameters accepted.
The description: A description of the command or function.
Options: A list of command line options and what they do.
Examples: Some examples of common use.
Output values: The possible return codes and their meaning.
Bugs: A list of known bugs and quirks. Sometimes this is supplemented with (or replaced with) a link to project issue tracking.
Author: The person (s) who wrote the command.
Copyright: Your copyright message. These also usually include the type of license the program is released under.
If you go through some of the more complicated man pages, you will see that there are many other sections as well. For example, try man man. You don’t have to include them all, just the ones you really need. man pages are not a place for words.
Here are a few other sections that you’ll see quite frequently:
See also: Other commands related to the subject that some would find useful or relevant.
Files: A list of files included in the package.
Warnings: Other points to know or to watch out for.
The story: A history of changes to the order.
The Linux manual is made up of all of the man pages, which are then divided into these numbered sections:
Executable programs: Or, shell commands.
System calls: Functions provided by the kernel.
Calls to the library: Functions in program libraries.
File formats and conventions: For example, “/ etc / passwd”.
Various: Macro packages and conventions, such as groff.
System administration commands: Usually reserved for root.
Core routines: Not usually installed by default.
Each man page should indicate which section it belongs to, and it should also be stored in the appropriate location for that section, as we will see later. The man pages for commands and utilities belong to the first section.
The format of a manual page
The groff macro format is not easy to analyze visually. On the other hand, markdown is child’s play.
Below is a man page in groff.
The same page is shown below in the markdown.
The first three lines form what is called the raw material. These must all start with a percent sign (%), with no leading space but an after, followed by:
The first line: Contains the name of the command, followed by the manual section in parentheses, without spaces. The name becomes the left and right sections of the man page header. By convention, the name of the command is in all caps, although you will find many others that are not. Everything after the command name and manual section number becomes the left section of the footer. It is convenient to use it for the software version number.
The second line: The name (s) of the authors. These are displayed in an automatically generated authors section of the man page. You don’t need to add an “Authors” section. You just need to include at least one name here.
The third line: The date, which also becomes the central part of the footer.
Sections are indicated by lines that begin with a pound sign (#), which is the markup that indicates a header in the markdown. The pound sign (#) must be the first character on the line, followed by a space.
The name section contains a single line that includes the name of the command, a space, a hyphen (-), a space, and then a very short description of what the command does.
The synopsis contains the different formats that the command line can take. This command can accept a search pattern or a command line option. The two asterisks (**) on either side of the command name mean that the name will be displayed in bold on the man page. A single asterisk (*) on each side of a text causes the man page to display it underlined.
By default, a line break is followed by a blank line. To force a hard break without a blank line, you can use a trailing backslash ().
The description explains what the command or program does. It should cover important details succinctly. Remember, you are not writing a user guide.
Using two number signs (##) at the start of a line creates a level two header. You can use them to break your description into smaller pieces.
The Options section contains a description of all of the command line options that can be used with the command. By convention, they are displayed in bold, so include two asterisks (**) before and after them. Include the textual description of the options on the next line and start it with a colon (:), followed by a space.
If the description is short enough, man will display it on the same line as the command line option. If it is too long, it appears as an indented paragraph starting on the line below the command line option.
The examples section contains a selection of different command line formats. Note that we start the description lines with a colon (:), just like we did in the options section.
This section lists the return values that your command returns to the calling process. This can be the shell if you called it from the command line, or a script if you started it from a shell script. We also start the description lines with a colon (:) in this section.
The bugs section lists known bugs, pitfalls, or quirks that people should be aware of. For open source projects, it is common to include a link here to the Project Issue Tracker to check for bugs or report new ones.
The copyright section contains your copyright statement and, generally, a description of the type of license under which the software is released.
An efficient workflow
You can edit your man page in your favorite editor. Most people who support syntax highlighting will be aware of markdown and color the text to highlight the headings, as well as bold and underline it. It’s great as far as it goes, but you’re not looking at a rendered man page, which is the real proof in the pudding.
Open a terminal window in the directory that contains your markdown file. Once opened in your editor, periodically save your file to your hard drive. Each time you do so, you can run the following command in the terminal window:
pandoc ms.1.md -s -t man | / usr / bin / man -l –
Once you have used this command, you can press the up arrow to repeat it and then press Enter.
This command also calls pandoc on the markdown file (here it is called “ms.1.md”):
The -s (stand-alone) option generates a full man page from top to bottom, rather than just man-formatted text.
The -t (output type) option with the “man” operator instructs pandoc to generate its output in man format. We haven’t told pandoc to send its output to a file, so it will be sent to stdout.
We also send this output to man with the -l (local file) option. It tells man not to search the man database for the man page. Instead, it should open the file named. If the filename is -, man will take its entries from stdin.
In summary, you can save from your editor and press Q to close man if it is running in the terminal window. Then you can press the up arrow and then enter to see a rendered version of your man page, just inside man.
Create your man page
Once you have completed your manual page, you need to create a final version of it and then install it on your system. The following command tells pandoc to generate a man page called “ms.1”:
pandoc ms.1.md -s -t man -o ms.1
This follows the convention of naming the man page after the command it describes and appending the manual section number as if it were a file extension.
This creates an “ms.1” file, which is our new man page. Where do we put it? This command will tell us where the man is looking for the man pages:
The results give us the following information:
/ usr / share / man: The location of the standard manual page library. We are not adding pages to this library.
/ usr / local / share / man: This symbolic link points to “/ usr / local / man”.
/ usr / local / man: This is where we need to place our new man page.
Note that the different sections of the manual are contained in their own directories: man1, man2, man3, etc. If the section directory doesn’t exist, we need to create it.
To do this, we type the following:
sudo mkdir / usr / local / man / man1
We then copy the “ms.1” file to the correct directory:
sudo cp ms.1 / usr / local / man / man1
man expects man pages to be compressed, so we’ll use gzip to compress it:
sudo gzip /usr/local/man/man1/ms.1
To have man add the new file to his database, type the following:
That’s all! We can now call our new man page the same as any other by typing:
Our new man page is found and displayed.
It looks like any other man page, with bold, underlined, and indented text where appropriate.
The description lines corresponding to the option they describe appear on the same line. Lines too long to fit appear under the option they describe.
We have also automatically generated an “Authors” section. The footer also includes the software version number, date and name of the command, as defined in the foreword.
If you want . . .
Once pandoc has created your man page, you can also directly edit the file in groff macro format before moving it to the man page directory, and gzip.