Man Pages Are Hard

Posted on Mar 21, 2021

If you follow my stuff on sourcehut you’ve probably noticed that I went into a sort of documentation rampage this last couple of days. Mostly, “discharging” information from README files onto each project’s manpage. I was a bit tired of having redundant information in two places and I also had noticed that some stuff was completely missing from both! Horrible!

Manual pages have this reputation that they’re hard to write, arcane, and obscure. Also, there’s this tendency in code hosting platforms to give the README file some protagonism by showing it as a sort of intro to the repo or project you’re looking at. That’s not bad, especially for smaller repos that are just a small program or script, not intended to be a “serious thing.”

But if you’re writing some sort of program that you want your users to install, please include a manpage! You know why? Because when you’ve installed some program, looking for the README file is actually harder… With a manpage, your users can do this wonderful magic trick:

$ man amazingtool

We all know that and how to read manpages. But the thing is that when you want to start writing them, oh darling…

Manual pages still use, for historical reasons, troff.1 And troff is… weird for nowadays standards. If LaTeX has a reputation of being hard, troff is even more arcane; you sort of may understand LaTeX if you’ve touched other markup languages in the past… but troff? Oh, sweetie, that’s another kind of beast! 2

Online documentation for writing manpages is bad. The closest you’ll find is groff’s documentation for its own man macros. Little secret, you probably have them on your system as well (man groff_man), but if you like reading this kind of stuff on a browser… lovely Ari has you covered! here they are.

I’m not planning to write a tutorial on how to write manpages here, because in all seriousness, I think I learned more by reading the source of manpages rather than anything else… and learning basic man macros isn’t that hard.

I’ve struggled against style and conventions waaaay more than against the language itself. You know, manpages are radically different to each other, everyone seemingly writing whatever they want on them. What is supposed to go into a manpage, what is not, etc. I know every project has its own needs, but lacking some sort of standard way of doing thing… even if you deliberately break the rules because it works better for you that way… not having any rules is unnerving, to say the least.

Or do we actually have some rules? Yes, we have some:

$ man man-pages

There you have a huge specification, written by the Linux project itself and for itself, but which is possibly the only style and content guidelines I know of for manual pages. From which sections are obligatory, which shouldn’t be used at all (looking at you AUTHORS, which makes absolutely no sense) to fine-grain details like when to use italics or boldface fonts. Of course a set of guidelines like this won’t ever cover it all for you, but it’s a great resource that has saved me lots of time and made my documentation way better in a snap.

Also there’s this article by the one and only Lars Wirzenius:3 Writing manual pages. I found it very helpful, because it boils down quite a lot from man-pages(7) and, to my taste, the way they format examples for the EXAMPLES section is less cumbersome than Linux’s.

If you’re interested in writing manpages, and you should if you’re writing code that you want people to use, I truly think those are the best resources you can look up to learn the basics on how to structure them, format them, etc., besides the arcane technicalities of troff and its GNU reincarnation groff.

At least I can say that one user has already thanked me for the improvements in the manpage for minitimer! I’m sure your users will also thank you!

  1. Which is actually a very weird use-case for troff, as terminal output was rather nroff. ↩︎

  2. One day I might get into more details about the story of text editing and typesetting on UNIX (which I find fascinating…), but let’s say that troff’s weird line-based syntax has a lot to do with the old ED line editor. ↩︎

  3. If you don’t know who he is… please, search him up. Linux wouldn’t have gone anywhere without him in the early, early days. ↩︎