What is format of man page in Linux and macOS? How to write a man page

Preface

In Linux and macOS, we often need to use man xxx to view the introduction and usage of a program, system call, etc. This interface is called manual page, but sometimes it is simply called manpage.

I’m curious about:

1. What format is the man page file?
2. How to write it?
3. Where is it usually stored?

The man page is a very important part of UNIX and Linux. Next, let’s study and explain these issues one by one. I believe that after you finish reading this blog, you will have a deeper understanding of the man and man page, and can deepen your understanding of Linux and UNIX.

What is format of man page?

Real UNIX books should be written in troff.

This sentence is from the preface of “Advanced Programming in the UNIX Environment (First Edition)” by W. Richard Stevens. It tells a key: troff is a very important text processor on UNIX.

troff is a text formatting system. Similar to Markdown, which is more popular now, and LaTex, which is used more in academic.

But just like UNIX and many programs born in UNIX, due to historical reasons, troff also havs modern version - groff.

if you want to know more, you can read the book “Unix: A History and a Memoir”. The author was a member of Bell Labs and the No. 9 user of the UNIX system.

groff is the GNU version of troff. It is functionally compatible with troff, but has many extensions. You can see specific differences by using the command man 7 groff_diff in the terminal.

The format of manpage is also troff. In Ubuntu it is nroff (also a derivative of troff).

To prove it,

Mac users can use the following command to view the file type of pwd(1)’s manpage:

$ file /usr/share/man/man1/pwd.1
/usr/share/man/man1/pwd.1: troff or preprocessor input text, ASCII text

Linux users can use the following command to view the file content, because Ubuntu archives with gzip, and after viewing it, you can see that it is in troff syntax:

$ less /usr/share/man/man1/pwd.1

But now man supports reading HTML files, so you also can use HTML to write manpage, but it is not common.

How to write a manpage

We must know the troff/groff syntax before writing it.

Regarding how to use groff, you can use info groff command to view a very detailed tutorial.

Regarding the syntax of groff, you can use man 7 groff command to view it.

groff’s official website: https://www.gnu.org/software/groff/#documentation

Here is a simple manpage to demonstrate. The source file is as follows:

You can use man command to view it:

Where is manpage stored?

The man command uses the environment variable $MANPATH and the configuration file /private/etc/man.conf file (macOS) or /etc/manpath.config (Ubuntu) to find the directories where manpage is stored.

So if you find manpage file through them. Moreover, we can also modify both of them, or add manpage to the specified directory.

I hope these will help someone in need~