---
title: "Can a man page be its own cheat sheet?"
locale: "en"
url: "https://irz.fr/en/articles/man-pages-own-cheatsheet-en"
markdown_url: "https://irz.fr/en/articles/man-pages-own-cheatsheet-en.md"
category: "tech"
tags: ["CLI", "documentation", "Unix", "open source", "learning"]
published_at: "2026-08-24T10:45:00.000Z"
author: "Camille Morel"
translation: "https://irz.fr/fr/articles/man-pages-own-cheatsheet-fr.md"
---

# Can a man page be its own cheat sheet?

Julia Evans asked people for their favorite man pages, then tried rewriting one. The exercise looks like reverse engineering: each organizational convention says something about the program underneath.

Julia Evans admits it about grep: she can never remember what grep's `-l` flag is called, and digging it out of the man page takes her, in her own words, forever.[1](https://jvns.ca/blog/2026/02/18/man-pages/) That small daily failure turned into a question worth asking on her blog: could this kind of file carry its own crib sheet inside itself? Before writing anything she asked her Mastodon followers to name their favorites, and the collection that came back rewards a close look.[1](https://jvns.ca/blog/2026/02/18/man-pages/)

## The alphabet overflows

The problem fits into two lines of SYNOPSIS. `ls` enumerates `[-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]`, and `grep` follows closely behind. Once a page lists nearly the whole alphabet, the synopsis line has stopped doing its job.[1](https://jvns.ca/blog/2026/02/18/man-pages/)

These limits are not cosmetic. A man page lives in a terminal, in plain ASCII, at roughly **80 columns**; it must remain readable inside a pager without images or clickable links. Within such a tight frame the organization of information becomes a design decision in its own right — which is exactly what Evans gathered from that call for favorites, since five programs arrived at five different answers to one problem: finding a flag quickly.

## The displaced summary

rsync's answer surprised Evans the most. Its SYNOPSIS stays minimal:

```
rsync [OPTION...] SRC... [DEST]
```

All the complexity moves into an **OPTION SUMMARY** block that most other programs simply lack, one line per flag in the manner of `--verbose, -v   increase verbosity`, followed later by the usual OPTIONS part carrying full descriptions.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[2](https://download.samba.org/pub/rsync/rsync.1) We checked the layout on the page Samba publishes; there it sits exactly as described, with a terse synopsis up front plus one-line summaries carrying the detail.[2](https://download.samba.org/pub/rsync/rsync.1)

> **Two ways to survive a SYNOPSIS**
> - grep stacks options into the synopsis until the alphabet runs out, with no visible hierarchy.: Show everything
> - rsync keeps a short synopsis and moves detail into a one-line-per-option summary.: Relocate
> grep and rsync man pages; Evans' detailed rewrite targets the grep case.

## Group by intent

strace approaches the problem from another side: its OPTIONS block sorts flags by family — General, Startup, Tracing, Filtering — instead of alphabetically.[3](https://man7.org/linux/man-pages/man1/strace.1.html) Readers rarely hunt for the option tied to one lone letter. They look for whatever filters what; here the layout follows that instinct.

This observation led Evans to try the same move on grep. She produced an OPTIONS SUMMARY grouped by category (DISPLAY, HOW TO MATCH, WHICH FILES TO SEARCH, MISC) and published the draft as it stood.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[4](https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf) She judges the exercise on one point, which is whether that elusive flag has become quick to find again.

> The grep exercise
> **Rewriting means deciding**
> - Go through the real options of the existing page.: Read
> - Sort by intent: display, matching, files, misc.: Group
> - One line per option, without losing meaning.: Condense
> - Check every flag against the official manual.: Verify
> The four moves of the exercise; the fourth is the one most often skipped.

## A typo slips in

That last step deserves attention, because Evans' own draft illustrates it despite herself. In her rewrite the leading-context flag appears as `--before-context-num`, while the GNU manual gives `--before-context=NUM`.[4](https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf)[5](https://www.gnu.org/software/grep/manual/grep.html) A hyphen instead of an equals sign is nothing serious inside an experimental draft, yet it is precisely the kind of detail that breaks a copy-paste.

The exercise does carry a catch: rewriting documentation produces a hypothesis, then that hypothesis has to face the original again. Rewriting shows how well you understood the program, and occasionally how badly.

## Examples first

Ask around, as Evans did, and a second consensus appears: pages showing real command lines win. The OpenBSD project carries that reputation, and its `tail` page closes with the two precise usages Evans says she relies on.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[6](https://man.openbsd.org/tail) The GNU page for the same tool contains no examples at all, which is no isolated oversight. Evans notes that GNU prefers maintaining its info manuals and quotes the coreutils manual stating they are no longer maintained there, while still declining to enter territory she describes as political.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[7](https://man7.org/linux/man-pages/man1/tail.1.html)

curl goes furthest of all: every flag on its man page ships with a ready-made invocation, and in the curl repository each option lives in its own file with an `Example` field. The entry for `--cert` quietly teaches you that `--key` probably belongs beside it, as in `curl --cert certfile --key keyfile $URL`.[8](https://curl.se/docs/manpage.html)[9](https://github.com/curl/curl/blob/master/docs/cmdline-opts/cert.md) When the material allows it, an entire page can turn into one scannable grid. Several respondents named `man ascii` their favorite, and its columns of octal, decimal, hex and character probably explain why.[1](https://jvns.ca/blog/2026/02/18/man-pages/) Perl combines several of these ideas in `perlcheat`, a man page that openly presents itself as one big cheat sheet, syntax included.[10](https://perldoc.perl.org/perlcheat)

## Clear and true

Serious work sits behind these hacks. In January Evans described her effort on four Git pages (`git add`, `git checkout`, `git push`, `git pull`), built on an explicit method: roughly **80 test readers** recruited through Mastodon were asked to report whatever actually confused them, from misunderstood terms to muddled sentences and sections contradicting each other.[11](https://jvns.ca/blog/2026/01/08/a-data-model-for-git/) Her conclusion deserves to be remembered by anyone maintaining a man page, since writing things both clear and true turns out to be genuinely hard. The cost of untangling every detail would have been a project of its own, so some sentences, those around `push.default` included, stayed deliberately vague.[11](https://jvns.ca/blog/2026/01/08/a-data-model-for-git/)

Her question therefore never was a pure style question. Each tool protects something different first: rsync protects brevity by moving its flag list out of the synopsis, strace protects intent-based lookup with families, curl and OpenBSD open with sample commands for a friendly first contact, `man ascii` tabulates for fast reference and Perl simply ships a cheat sheet. Read any page's conventions closely enough and its maintainers' priorities become visible.

## A constrained format

Workarounds outside the man page already exist: tldr.sh maintains a community database of command snippets for anyone who finds a man page too heavy, fish generates shell completions straight from these same files, and Dash-style documentation browsers bolt on an index so readers can jump straight to a flag.[1](https://jvns.ca/blog/2026/02/18/man-pages/)[12](https://tldr.sh) All of these route around the limitation instead of working within it. Given how much software still prints its help into a bare terminal, man pages are likely to outlive every one of these workarounds.

Evans' exercise suggests the opposite move, which is to treat the constraint as a subject worth studying. She herself kept going after that February post, publishing example sections for `tcpdump` and `dig` in March.[13](https://jvns.ca/blog/2026/03/10/examples-for-the-tcpdump-and-dig-man-pages/) Rewriting a man page forces you to decide where every switch belongs, which means guessing how maintainers think about their program before confronting that reading with actual behavior. It is reverse engineering applied to documentation, and the payoff arrives either way: you leave knowing your tool one level deeper, even when the rewritten file ends up in the trash.

For any remaining doubt Evans supplies the clincher herself: her personal trick for locating an option consists of searching `^ *-a` in the pager, a regex she systematically forgets.[1](https://jvns.ca/blog/2026/02/18/man-pages/) Between a trick you forget and a rewritten man page, the second wins.

## References

1. [Julia Evans, Notes on clarifying man pages, February 18, 2026](https://jvns.ca/blog/2026/02/18/man-pages/)
2. [rsync man page (rsync.1, samba.org)](https://download.samba.org/pub/rsync/rsync.1)
3. [strace man page (man7.org)](https://man7.org/linux/man-pages/man1/strace.1.html)
4. [Julia Evans, draft OPTIONS SUMMARY for grep (gist)](https://gist.github.com/jvns/9f5966633875a4758e0d947a5b4dbdcf)
5. [GNU grep manual (GNU Project)](https://www.gnu.org/software/grep/manual/grep.html)
6. [tail man page (OpenBSD)](https://man.openbsd.org/tail)
7. [tail man page (GNU coreutils, man7.org)](https://man7.org/linux/man-pages/man1/tail.1.html)
8. [curl man page (curl.se)](https://curl.se/docs/manpage.html)
9. [curl, docs/cmdline-opts/cert.md (curl repository)](https://github.com/curl/curl/blob/master/docs/cmdline-opts/cert.md)
10. [perlcheat, Perl's cheat sheet shipped as a man page](https://perldoc.perl.org/perlcheat)
11. [Julia Evans, A data model for Git (and other docs updates), January 8, 2026](https://jvns.ca/blog/2026/01/08/a-data-model-for-git/)
12. [tldr.sh, community-maintained examples database](https://tldr.sh)
13. [Julia Evans, Examples for the tcpdump and dig man pages, March 10, 2026](https://jvns.ca/blog/2026/03/10/examples-for-the-tcpdump-and-dig-man-pages/)