![\"\"](\"https://jvns.ca/images/dash.webp\")
Hello! After spending some time working on the Git man pages last year, I’ve been thinking a little more about what makes a good man page.
\nI’ve spent a lot of time writing cheat sheets for tools (tcpdump, git, dig, etc) which have a man page as their primary documentation. This is because I often find the man pages hard to navigate to get the information I want.
\nLately I’ve wondering – could the man page itself have an amazing cheat sheet in it? What might make a man page easier to use? I’m still very early in thinking about this but I wanted to write down some quick notes.
\nI asked some people on Mastodon for their favourite man pages, and here are some examples of interesting things I saw on those man pages.
\nIf you’ve read a lot of man pages you’ve probably seen something like this in the SYNOPSIS: once you’re listing almost the entire alphabet, it’s hard
ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]\n\ngrep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]\nThe rsync man page has a solution I’ve never seen before: it keeps its SYNOPSIS very terse, like this:
\n Local:\n rsync [OPTION...] SRC... [DEST]\nand then has an “OPTIONS SUMMARY” section with a 1-line summary of each option, like this:
\n--verbose, -v increase verbosity\n--info=FLAGS fine-grained informational verbosity\n--debug=FLAGS fine-grained debug verbosity\n--stderr=e|a|c change stderr output mode (default: errors)\n--quiet, -q suppress non-error messages\n--no-motd suppress daemon-mode MOTD\nThen later there’s the usual OPTIONS section with a full description of each option.
\nThe strace man page organizes its options by category (like “General”, “Startup”, “Tracing”, and “Filtering”, “Output Format”) instead of alphabetically.
\nAs an experiment I tried to take the grep man page and make an “OPTIONS SUMMARY” section grouped by category, you can see the results here. I’m not sure what I think of the results but it was a fun exercise. When I was writing that I was thinking about how I can never remember the name of the -l grep option. It always takes me what feels like forever to find it in the man page and I was trying to think of what structure would make it easier for me to find. Maybe categories?
A couple of people pointed me to the suite of Perl man pages (perlfunc, perlre, etc), and one thing I noticed was man perlcheat, which has cheat sheet sections like this:
SYNTAX\n foreach (LIST) { } for (a;b;c) { }\n while (e) { } until (e) { }\n if (e) { } elsif (e) { } else { }\n unless (e) { } elsif (e) { } else { }\n given (e) { when (e) {} default {} }\nI think this is so cool and it makes me wonder if there are other ways to write condensed ASCII 80-character-wide cheat sheets for use in man pages.
\nA common comment was something to the effect of “I like any man page that has examples”. Someone mentioned the OpenBSD man pages, and the openbsd tail man page has examples of the exact 2 ways I use tail at the end.
\nI think I’ve most often seen the EXAMPLES section at the end of the man page, but some man pages (like the rsync man page from earlier) start with the examples. When I was working on the git-add and git rebase man pages I put a short example at the beginning.
\nThis isn’t a property of the man page itself, but one issue with man pages in the terminal is it’s hard to know what sections the man page has.
\nWhen working on the Git man pages, one thing Marie and I did was to add a table of contents to the sidebar of the HTML versions of the man pages hosted on the Git site.
\nI’d also like to add more hyperlinks to the HTML versions of the Git man pages at some point, so that you can click on “INCOMPATIBLE OPTIONS” to get to that section. It’s very easy to add links like this in the Git project since Git’s man pages are generated with AsciiDoc.
\nI think adding a table of contents and adding internal hyperlinks is kind of a nice middle ground where we can make some improvements to the man page format (in the HTML version of the man page at least) without maintaining a totally different form of documentation. Though for this to work you do need to set up a toolchain like Git’s AsciiDoc system.
\nIt would be amazing if there were some kind of universal system to make it easy to look up a specific option in a man page (“what does -a do?”). The best trick I know is use the man pager to search for something like ^ *-a but I never remember to do it and instead just end up going through every instance of -a in the man page until I find what I’m looking for.
The curl man page has examples for every option, and there’s also a table of contents on the HTML version so you can more easily jump to the option you’re interested in.
\nFor instance the example for --cert makes it easy to see that you likely also want to pass the --key option, like this:
curl --cert certfile --key keyfile https://example.com\nThe way they implement this is that there’s [one file for each option](https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md) and there’s an “Example” field in that file.
\nQuite a few people said that man ascii was their favourite man page, which looks like this:
\n Oct Dec Hex Char \n ───────────────────────────────────────────\n 000 0 00 NUL '\\0' (null character)\n 001 1 01 SOH (start of heading) \n 002 2 02 STX (start of text) \n 003 3 03 ETX (end of text) \n 004 4 04 EOT (end of transmission)\n 005 5 05 ENQ (enquiry) \n 006 6 06 ACK (acknowledge) \n 007 7 07 BEL '\\a' (bell) \n 010 8 08 BS '\\b' (backspace) \n 011 9 09 HT '\\t' (horizontal tab)\n 012 10 0A LF '\\n' (new line) \nObviously man ascii is an unusual man page but I think what’s cool about this man page (other than the fact that it’s always useful to have an ASCII reference) is it’s very easy to scan to find the information you need because of the table format. It makes me wonder if there are more opportunities to display information in a “table” in a man page to make it easier to scan.
When I talk about man pages it often comes up that the GNU coreutils man pages (for example man tail) don’t have examples, unlike the OpenBSD man pages, which do have examples.
\nI’m not going to get into this too much because it seems like a fairly political topic and I definitely can’t do it justice here, but here are some things I believe to be true:
\ninfo tool. I’ve heard from some Emacs users that they like the Emacs info browser. I don’t think I’ve ever talked to anyone who uses the standalone info tool.After a certain level of complexity a man page gets really hard to navigate: while I’ve never used the coreutils info manual and probably won’t, I would almost certainly prefer to use the GNU Bash reference manual or the The GNU C Library Reference Manual via their HTML documentation rather than through a man page.
\nHere are some tools I think are interesting:
\ntldr grep. Lots of people have told me they find it useful.
Man pages are such a constrained format and it’s fun to think about what you can do with such limited formatting options.
\nEven though I’m very into writing I’ve always had a bad habit of never reading documentation and so it’s a little bit hard for me to think about what I actually find useful in man pages, I’m not sure whether I think most of the things in this post would improve my experience or not. (Except for examples, I LOVE examples)
\nSo I’d be interested to hear about other man pages that you think are well designed and what you like about them, the comments section is here.
\n", "content_markdown": "Hello! After [spending some time working on the Git man pages](https://jvns.ca/blog/2026/01/08/a-data-model-for-git/) last year, I’ve been thinking a little more about what makes a good man page.\n\nI’ve spent a lot of time writing cheat sheets for tools (tcpdump, git, dig, etc) which have a man page as their primary documentation. This is because I often find the man pages hard to navigate to get the information I want.\n\nLately I’ve wondering – could the man page *itself* have an amazing cheat sheet in it? What might make a man page easier to use? I’m still very early in thinking about this but I wanted to write down some quick notes.\n\nI [asked some people on Mastodon](https://social.jvns.ca/@b0rk/116092583707187579) for their favourite man pages, and here are some examples of interesting things I saw on those man pages.\n\n### [an OPTIONS SUMMARY](https://jvns.ca/blog/2026/02/18/man-pages/#an-options-summary)\n\nIf you’ve read a lot of man pages you’ve probably seen something like this in the `SYNOPSIS`: once you’re listing almost the entire alphabet, it’s hard\n\n```\nls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]\n\ngrep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]\n```\n\nThe [rsync man page](https://download.samba.org/pub/rsync/rsync.1) has a solution I’ve never seen before: it keeps its SYNOPSIS very terse, like this:\n\n```\n Local:\n rsync [OPTION...] SRC... [DEST]\n```\n\nand then has an “OPTIONS SUMMARY” section with a 1-line summary of each option, like this:\n\n```\n--verbose, -v increase verbosity\n--info=FLAGS fine-grained informational verbosity\n--debug=FLAGS fine-grained debug verbosity\n--stderr=e|a|c change stderr output mode (default: errors)\n--quiet, -q suppress non-error messages\n--no-motd suppress daemon-mode MOTD\n```\n\nThen later there’s the usual OPTIONS section with a full description of each option.\n\n### [an OPTIONS section organized by category](https://jvns.ca/blog/2026/02/18/man-pages/#an-options-section-organized-by-category)\n\nThe [strace man page](https://man7.org/linux/man-pages/man1/strace.1.html) organizes its options by category (like “General”, “Startup”, “Tracing”, and “Filtering”, “Output Format”) instead of alphabetically.\n\nAs an experiment I tried to take the `grep` man page and make an “OPTIONS SUMMARY” section grouped by category, you can [see the results here](https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf). I’m not sure what I think of the results but it was a fun exercise. When I was writing that I was thinking about how I can never remember the name of the `-l` grep option. It always takes me what feels like forever to find it in the man page and I was trying to think of what structure would make it easier for me to find. Maybe categories?\n\n### [a cheat sheet](https://jvns.ca/blog/2026/02/18/man-pages/#a-cheat-sheet)\n\nA couple of people pointed me to the suite of Perl man pages (`perlfunc`, `perlre`, etc), and one thing I noticed was [man perlcheat](https://linux.die.net/man/1/perlcheat), which has cheat sheet sections like this:\n\n```\n SYNTAX\n foreach (LIST) { } for (a;b;c) { }\n while (e) { } until (e) { }\n if (e) { } elsif (e) { } else { }\n unless (e) { } elsif (e) { } else { }\n given (e) { when (e) {} default {} }\n```\n\nI think this is so cool and it makes me wonder if there are other ways to write condensed ASCII 80-character-wide cheat sheets for use in man pages.\n\n### [examples are very popular](https://jvns.ca/blog/2026/02/18/man-pages/#examples-are-very-popular)\n\nA common comment was something to the effect of “I like any man page that has examples”. Someone mentioned the OpenBSD man pages, and the [openbsd tail](https://man.openbsd.org/tail) man page has examples of the exact 2 ways I use tail at the end.\n\nI think I’ve most often seen the EXAMPLES section at the end of the man page, but some man pages (like the [rsync man page](https://download.samba.org/pub/rsync/rsync.1) from earlier) start with the examples. When I was working on the [git-add](https://git-scm.com/docs/git-add) and [git rebase](https://git-scm.com/docs/git-rebase) man pages I put a short example at the beginning.\n\n### [a table of contents, and links between sections](https://jvns.ca/blog/2026/02/18/man-pages/#a-table-of-contents-and-links-between-sections)\n\nThis isn’t a property of the man page itself, but one issue with man pages in the terminal is it’s hard to know what sections the man page has.\n\nWhen working on the Git man pages, one thing Marie and I did was to [add a table of contents](https://git-scm.com/docs/git-rebase) to the sidebar of the HTML versions of the man pages hosted on the Git site.\n\nI’d also like to add more hyperlinks to the HTML versions of the Git man pages at some point, so that you can click on “INCOMPATIBLE OPTIONS” to get to that section. It’s very easy to add links like this in the Git project since Git’s man pages are generated with AsciiDoc.\n\nI think adding a table of contents and adding internal hyperlinks is kind of a nice middle ground where we can make some improvements to the man page format (in the HTML version of the man page at least) without maintaining a totally different form of documentation. Though for this to work you do need to set up a toolchain like Git’s AsciiDoc system.\n\nIt would be amazing if there were some kind of universal system to make it easy to look up a specific option in a man page (“what does -a do?”). The best trick I know is use the man pager to search for something like `^ *-a` but I never remember to do it and instead just end up going through every instance of `-a` in the man page until I find what I’m looking for.\n\n### [examples for every option](https://jvns.ca/blog/2026/02/18/man-pages/#examples-for-every-option)\n\nThe [curl man page](https://curl.se/docs/manpage.html) has examples for every option, and there’s also a table of contents on the HTML version so you can more easily jump to the option you’re interested in.\n\nFor instance the example for `--cert` makes it easy to see that you likely also want to pass the `--key` option, like this:\n\n```\n curl --cert certfile --key keyfile https://example.com\n```\n\nThe way they implement this is that there’s \\[one file for each option\\]([https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583](https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583) 25/docs/cmdline-opts/append.md) and there’s an “Example” field in that file.\n\n### [formatting data in a table](https://jvns.ca/blog/2026/02/18/man-pages/#formatting-data-in-a-table)\n\nQuite a few people said that [man ascii](https://www.man7.org/linux/man-pages/man7/ascii.7.html) was their favourite man page, which looks like this:\n\n```\n Oct Dec Hex Char \n ───────────────────────────────────────────\n 000 0 00 NUL '\\0' (null character)\n 001 1 01 SOH (start of heading) \n 002 2 02 STX (start of text) \n 003 3 03 ETX (end of text) \n 004 4 04 EOT (end of transmission)\n 005 5 05 ENQ (enquiry) \n 006 6 06 ACK (acknowledge) \n 007 7 07 BEL '\\a' (bell) \n 010 8 08 BS '\\b' (backspace) \n 011 9 09 HT '\\t' (horizontal tab)\n 012 10 0A LF '\\n' (new line) \n```\n\nObviously `man ascii` is an unusual man page but I think what’s cool about this man page (other than the fact that it’s always useful to have an ASCII reference) is it’s very easy to scan to find the information you need because of the table format. It makes me wonder if there are more opportunities to display information in a “table” in a man page to make it easier to scan.\n\n### [the GNU approach](https://jvns.ca/blog/2026/02/18/man-pages/#the-gnu-approach)\n\nWhen I talk about man pages it often comes up that the GNU coreutils man pages (for example [man tail](https://man7.org/linux/man-pages/man1/tail.1.html)) don’t have examples, unlike the OpenBSD man pages, which [do have examples](https://man.openbsd.org/tail).\n\nI’m not going to get into this too much because it seems like a fairly political topic and I definitely can’t do it justice here, but here are some things I believe to be true:\n\n- The GNU project prefers to maintain documentation in “info” manuals instead of man pages. [This page](https://www.gnu.org/software/coreutils/manual/coreutils.html) says “the man pages are no longer being maintained”.\n- There are 3 ways to read “info” manuals: their HTML version, in Emacs, or with a standalone `info` tool. I’ve heard from some Emacs users that they like the Emacs info browser. I don’t think I’ve ever talked to anyone who uses the standalone `info` tool.\n- The [info manual entry for tail](https://www.gnu.org/software/coreutils/manual/html_node/tail-invocation.html) is linked at the bottom of the man page, and it does have examples\n- The FSF used to [sell print books](https://www.fsf.org/gnu-press) of the GNU software manuals (and maybe they [still do](https://shop.fsf.org/) sometimes?)\n\nAfter a certain level of complexity a man page gets really hard to navigate: while I’ve never used the coreutils info manual and probably won’t, I would almost certainly prefer to use the [GNU Bash reference manual](https://www.gnu.org/software/bash/manual/bash.html) or the [The GNU C Library Reference Manual](https://sourceware.org/glibc/manual/latest/html_mono/libc.html) via their HTML documentation rather than through a man page.\n\n### [a few more man-page-adjacent things](https://jvns.ca/blog/2026/02/18/man-pages/#a-few-more-man-page-adjacent-things)\n\nHere are some tools I think are interesting:\n\n- [The fish shell](https://fishshell.com/) comes with a [Python script](https://github.com/fish-shell/fish-shell/blob/master/share/tools/create_manpage_completions.py) to automatically generate tab completions from man pages\n- [tldr.sh](https://tldr.sh) is a community maintained database of examples, for example you can run it as `tldr grep`. Lots of people have told me they find it useful.\n- the [Dash](https://kapeli.com/dash) Mac docs browser has a nice man page viewer in it. I still use the terminal man page viewer but I like that it includes a table of contents, it looks like this:\n\n\n\n### [it’s interesting to think about a constrained format](https://jvns.ca/blog/2026/02/18/man-pages/#it-s-interesting-to-think-about-a-constrained-format)\n\nMan pages are such a constrained format and it’s fun to think about what you can do with such limited formatting options.\n\nEven though I’m very into writing I’ve always had a bad habit of never reading documentation and so it’s a little bit hard for me to think about what I actually find useful in man pages, I’m not sure whether I think most of the things in this post would improve my experience or not. (Except for examples, I LOVE examples)\n\nSo I’d be interested to hear about other man pages that you think are well designed and what you like about them, the [comments section is here](https://comments.jvns.ca/post/116093529820975727).\n", "dateCreated": "2026-09-19T21:30:23.395188495+00:00", "date_created": "2026-02-18T00:00:00+00:00", "date_modified": "2026-02-18T00:00:00+00:00", "date_published": "2026-02-18T00:00:00+00:00", "description": "Hello! After spending some time working on the Git man pages last year, I’ve been thinking a little more about what makes a good man page. I’ve spent a lot of time writing cheat sheets for tools (tcpdump, git, dig, etc) which have a man…", "external_url": "https://jvns.ca/blog/2026/02/18/man-pages/", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/jvns-ca/2026/02/2026-02-18-notes-on-clarifying-man-pages.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/jvns-ca/2026/02/2026-02-18-notes-on-clarifying-man-pages.md" }, "id": "urn:aggr:item:7b689d179a5c11de426402b974099867f8609f57", "isBasedOn": { "@id": "https://jvns.ca/blog/2026/02/18/man-pages/" }, "mainEntity": { "@id": "https://jvns.ca/blog/2026/02/18/man-pages/", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/jvns-ca/2026-02-18-notes-on-clarifying-man-pages/#webpage" }, "dateModified": "2026-02-18T00:00:00+00:00", "datePublished": "2026-02-18T00:00:00+00:00", "headline": "Notes on clarifying man pages", "timeRequired": "PT7M", "url": "https://jvns.ca/blog/2026/02/18/man-pages/", "wordCount": 1546 }, "name": "Archived snapshot: Notes on clarifying man pages", "preview": null, "reading_minutes": 7, "replicated_at": null, "source": "jvns-ca", "source_name": "Julia Evans", "summary": null, "tags": [], "temporalCoverage": "2026-09-19T21:30:23.395188495+00:00", "title": "Notes on clarifying man pages", "url": "https://aggr.aymericbeaumet.com/items/jvns-ca/2026-02-18-notes-on-clarifying-man-pages/", "word_count": 1546 }