Can a man page be its own cheat sheet?

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 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

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

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 2 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

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 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 4 She judges the exercise on one point, which is whether that elusive flag has become quick to find again.

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 5 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 6 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 7

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 9 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 Perl combines several of these ideas in perlcheat, a man page that openly presents itself as one big cheat sheet, syntax included.10

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 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

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 12 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 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 Between a trick you forget and a rewritten man page, the second wins.