Dennis Ritchie and Ken Thompson wrote this first version at the insistence of Douglas McIlroy, their manager. (Probably not the very first manager who rode his reports to make sure they did all the paperwork, but very possibly the most influential!) The first version, as you can see, was on paper and collected in a binder, which eventually comprised one volume of the multi-binder Unix OS manual. Today, we access them via the command line or through online repos. This is the modern-day incarnation of something pretty revolutionary - Unix was the first OS to include all of its documentation online in machine-readable form.

Today, the inclusion of a man page or other comprehensive documentation with a new program or utility is considered an essential step in creating and maintaining complete, usable software. Releasing a program without one looks suspicious, immediately giving your intended users cause to wonder where else you skimped on effort.

Tell me about how man pages are put together, though

Like all complex documentation, there are a couple different layers of organization at play here: organization within the manual, and then organization within each individual man page. First, I’ll cover the order of information within each man page, and then I’ll talk about the organization of said pages within the greater manual - and why that matters even though you’re not dealing with a physical binder of information.

Here are all the possible sections of a Linux man page, in their expected order:

Name

Synopsis

Configuration

Description

Options

Exit status

Return value

Errors

Environment

Files

Versions

Attributes

Conforming to

Notes

Bugs

Example

See Also

Generally, no man page will have all of these. Some are typical only to pages within certain sections of the manual. The current man page style guide at man7.org strongly suggests putting whatever you want to tell your eventual users in a form that matches these sections and their order, rather than improvising, reinventing, and needlessly challenging your readers.

My favorites are Examples, Versions, and See Also, as that’s where the authors’ intent and impact tend to come through most clearly, by how they directly suggest you use their work, what they think is most relevant, and how they describe the evolution of their program across versions.

Beyond the sections within the pages, there’s the matter of manual order. When you read a man page or search for one online, you’ll see numbers in parentheses after the commands you’re looking up: sed(1), fdisk(8), exit(3), to name a few. These numbers refer to the physical manual and indicate where in said manual this man page would be, depending on what’s being described. Here’s the current Linux section structure:

General commands System calls Library functions, covering in particular the C standard library Special files File formats and conventions Games and screensavers Miscellanea System administration commands and daemons

Once you know this, you’ll find the resource you’re looking for faster. If you wanted flags, parameters, and related commands for man, for instance, you’d want its entry in section 1. However, to learn about macro and groff information, you’d want man(7). Or the next section of this post.

The history of man formatting tools, or: Luminaries of computer science, revisited

As I said in the beginning: using something workable and declaring it a prototype or otherwise temporary solution is a risk, particularly during such a formative period of computer science.

The extremely thorough version of the story, complete with correspondence with some of the parties originally involved, can be found at this 2011 research project by Kristaps Dzonsons. If you’re at all inclined to nerd out on this subject, it is well worth spending some time over there. Some of what I’m about to cover is reasonably inferred without the use/availability of primary sources, some is based on primary resources, and all is covered in greater depth at the link.

The story starts with RUNOFF, written by Jerry Saltzer in the MAD computer language in 1964. It was created for the CTSS operating system to format his doctoral thesis proposal for printing. Its next incarnation was called roff, written in PDP-11 assembly. This is the version that was used to format the first three editions of the Unix Programmer’s Manual. It was brought to Bell Labs by Rudd Canaday in 1967 as a prototype for a porting project - but was used for five more years. Despite its relatively long reign as the go-to text formatting utility for early Unix, the PDP-11 assembly source code for roff has been lost. Other original Unix code has been recovered from the original tapes, but roff now exists only as memories and through its impact on the rest of the tools described in this section.

The next incarnation, nroff (or “new roff”) was created in 1972. It was also for Unix, and it created output suitable for simple fixed-width printers and terminal windows. This version, written by Joe Ossanna, was also in PDP-11 assembly and included programmable macros. The next, a year later, was troff (or “typesetter roff”). It was originally in PDP-11 assembly, but Ossanna rewrote it in C a couple of years later. This version worked with the Wang Graphics Systems CAT typesetter and one other output. After Ossanna’s early death, the utility languished until Brian Kernighan picked it up.

Kernighan’s next version of it was called ditroff (for “device-independent roff”), setting the roff family free from its dependence on that CAT typesetter. This version was used by AT&T and derivative Unix systems for many years, so you may find this paper, last updated by Kernighan in 1982, worth a look - it describes his process and decisions around this update, which included fixing font limitations and using dynamic memory.

At this point, it’s the next evolution, groff, that’s present on most Linux and GNU OSes. It was written by James C. Clarke for the GNU Project in C++, based on troff, and originally released as part of SunOS 4.1.4. Since then, there have been tools that work in the same space with names like awf, cawf, and mandoc, but groff is probably what your man pages are formatted with if you’re looking them up with the terminal on a Linux or Mac machine.

This was a lot of detail, but it’s still a higher-level exploration of this history. If you’re intrigued (and it’s worth it to be), dig deeper into that 2011 research project. It’s a fine tour of different forks of different OSes, possible alternate technological realities, and other stabs at making ubiquitous and ubiquitously useful tools for users across several decades.

Man pages, today and tomorrow

These days, there are a few separate (but often overlapping) archives of man pages. The ones you’ll get via your terminal either come with the OS or are added as you install new programs. You can find them at /usr/share/man, where they’re divided into directories using the manual section numbering system I described earlier.

New man pages are typically written by someone on the team that created the utility or program they pertain to. If you inherit the responsibility of maintaining said utility, you also inherit the responsibility of maintaining its man page.

However, you can also find them outside of the terminal - and sometimes, particularly with long man pages, it’s a bit easier to read them in a browser. (It can’t just be me that likes to know the length of what I’m reading before I start.) Michael Kerrisk runs man7.org, a major repo of man pages that also includes great, thorough, opinionated documentation on how to write your own man pages. Other repos, including die.net and kernel.org, are also highly recommended (and appropriately high in search results). These are also great places to look if you’re interested in helping maintain these repos.

But You Want to Write Your Own Man Page

Of course you do!

First thing: get familiar with the formatting. It’s fairly different than any tool I’ve interacted with before, so it takes a context shift. Here’s part of the code for the ls man page on my system, for example: