让 man 手册更清晰的几点笔记
原文由 Julia Evans 于 发布，订阅该博客
你好！去年花了一段时间打磨 Git 的 man 手册之后，我一直在思考，什么样的 man 手册才算得上好。
我花了很多时间给那些以 man 手册为主要文档的工具（比如 tcpdump、git、dig 等）写速查表。这是因为我常常觉得，man 手册很难快速定位到我想要的信息。
最近我一直在想——man 手册本身能不能就内置一份出色的速查表？怎样才能让 man 手册更好用？这些想法还很初步，但我想先把一些随想记录下来。
我在 Mastodon 上问了一些人最喜欢哪些 man 手册，下面是那些手册里一些有意思的设计。
选项总览（OPTIONS SUMMARY）
如果你读过很多 man 手册，应该在 SYNOPSIS 里见过类似这样的写法：一旦要把几乎整个字母表都列出来，就很难看懂
ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]
grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]rsync 的 man 手册提供了一种我以前没见过的解法：它把 SYNOPSIS 写得非常精简，像这样：
Local:
rsync [OPTION...] SRC... [DEST]然后专门设了一个“OPTIONS SUMMARY”小节，用一行话概括每个选项，比如这样：
--verbose, -v increase verbosity
--info=FLAGS fine-grained informational verbosity
--debug=FLAGS fine-grained debug verbosity
--stderr=e|a|c change stderr output mode (default: errors)
--quiet, -q suppress non-error messages
--no-motd suppress daemon-mode MOTD再往后才是常规的 OPTIONS 小节，对每个选项做完整说明。
按类别组织的 OPTIONS 小节
strace 的 man 手册不是按字母顺序，而是按类别（比如“通用”“启动”“跟踪”“过滤”“输出格式”）来组织选项。
作为实验，我试着把 grep 的 man 手册改成按类别分组的“OPTIONS SUMMARY”，你可以在这里看到结果。我还不确定怎么评价这个结果，但过程挺有意思的。写的时候我在想，我总是记不住 grep 的 -l 选项。每次在手册里找它，都感觉要花好久，所以我在想什么样的结构能让我更快找到它。也许分类会有帮助？
速查表
有几个人向我推荐了 Perl 的那套 man 手册（perlfunc、perlre 等），其中我注意到 man perlcheat 里有这样的速查表小节：
SYNTAX
foreach (LIST) { } for (a;b;c) { }
while (e) { } until (e) { }
if (e) { } elsif (e) { } else { }
unless (e) { } elsif (e) { } else { }
given (e) { when (e) {} default {} }我觉得这太酷了，也让我好奇，除了这种方式，是否还有别的办法能写出适合放在 man 手册里的、80 列宽的精简 ASCII 速查表。
示例很受欢迎
最常见的评价就是类似“我喜欢任何带示例的 man 手册”。有人提到了 OpenBSD 的 man 手册，OpenBSD tail 的手册末尾就恰好给出了我平时用 tail 的那两种用法的示例。
我印象中 EXAMPLES 小节大多放在手册末尾，但有些手册（比如前面提到的 rsync 手册）会把示例放在开头。我在整理 git-add 和 git rebase 的手册时，也在开头放了一段简短示例。
目录与章节间链接
这不是 man 手册本身的属性，但在终端里看手册时，一个问题是很难一眼看出手册都有哪些章节。
在整理 Git 的 man 手册时，我和 Marie 做的一件事，就是在 Git 官网托管的 HTML 版手册侧边栏里加了目录。
我还想在某个时候给 HTML 版的 Git 手册加上更多超链接，这样你就可以直接点击“INCOMPATIBLE OPTIONS”跳到对应小节。在 Git 项目里加这种链接很容易，因为它的手册是用 AsciiDoc 生成的。
我觉得加目录和内部超链接算是个不错的折中方案：至少在 HTML 版里，我们可以在不用另起一套文档的前提下，让手册的格式有所改进。不过要实现这一点，就得搭建一套像 Git 那样的 AsciiDoc 工具链。
如果能有某种通用的办法，让人在手册里快速查到某个选项的含义（比如“-a 是干什么的？”）就太好了。我知道的最好技巧是用 man 的翻页器去搜类似 ^ *-a 这样的模式，但我总是记不住这么做，最后还是在手册里把每个 -a 都翻一遍，直到找到想要的那一项。
每个选项都配示例
curl 的 man 手册为每个选项都配了示例，HTML 版还有目录，可以更方便地跳到你关心的选项。
比如 --cert 的示例就很容易让人看出，你很可能还需要同时传入 --key 选项，像这样：
curl --cert certfile --key keyfile https://example.com他们的实现方式是为每个选项单独建一个文件（https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md），文件里有一个“Example”字段。
用表格呈现数据
有不少人说 man ascii 是他们最喜欢的手册，长这样：
Oct Dec Hex Char
───────────────────────────────────────────
000 0 00 NUL '\0' (null character)
001 1 01 SOH (start of heading)
002 2 02 STX (start of text)
003 3 03 ETX (end of text)
004 4 04 EOT (end of transmission)
005 5 05 ENQ (enquiry)
006 6 06 ACK (acknowledge)
007 7 07 BEL '\a' (bell)
010 8 08 BS '\b' (backspace)
011 9 09 HT '\t' (horizontal tab)
012 10 0A LF '\n' (new line) 显然 man ascii 是个比较特别的手册，但我觉得它厉害的地方（除了 ASCII 对照表本身就一直很有用之外）在于表格形式让人扫一眼就能找到需要的信息。这也让我想，手册里是不是还有更多可以用“表格”来呈现信息、让内容更易扫读的机会。
GNU 的做法
聊到 man 手册时，经常会有人提到 GNU coreutils 的手册（比如 man tail）没有示例，而 OpenBSD 的手册则有示例。
这个话题似乎有点敏感，我也不打算深入展开，这里肯定讲不透彻，但以下几点我认为是事实：
- GNU 项目更倾向于用“info”手册来维护文档，而不是 man 手册。这个页面上说“man 手册已不再维护”。
- 阅读“info”手册有三种方式：看 HTML 版、在 Emacs 里看，或用独立的
info工具。我听一些 Emacs 用户说他们喜欢 Emacs 里的 info 浏览器。我好像从没遇到过用独立info工具的人。 - tail 的 info 手册条目在 man 手册底部有链接，里面是有示例的
- FSF 过去会销售 GNU 软件手册的纸质书（也许现在偶尔还在卖？）
man 手册复杂到一定程度后就会变得很难导航：虽然我从没用过 coreutils 的 info 手册、以后大概也不会用，但对于 GNU Bash 参考手册或《GNU C 库参考手册》这类文档，我几乎肯定更愿意看它们的 HTML 版，而不是用 man 手册来查。
一些与 man 手册相关的小工具
这里有几个我觉得有意思的工具：
- fish shell 自带一个 Python 脚本，可以从 man 手册自动生成 Tab 补全
- tldr.sh 是一个由社区维护的示例库，比如你可以运行
tldr grep来查看。很多人告诉我它很有用。 - Dash 这款 Mac 文档浏览器内置了一个不错的 man 手册查看器。我平时还是用终端里的手册查看器，但我喜欢它自带目录，界面长这样：
思考一种受限的格式很有意思
man 手册是一种非常受限的格式，在如此有限的排版选项下思考能做出什么来，本身就很有趣。
虽然我很喜欢写作，但我一直有个坏习惯就是从不看文档，所以要让我去想自己到底觉得手册里什么有用，其实有点难。我也不确定这篇文章里提到的大多数东西是否真的会改善我的体验。（除了示例，示例我超爱）
所以我很想听听你觉得哪些 man 手册设计得好、好在哪里，评论区在这里。
评论
登录后参与讨论