您好！去年我花了一些时间编写 Git 手册页，之后我一直在思考，什么样的手册页才算好。
我花了很多时间为一些工具（例如 tcpdump、git、dig 等）编写速查表，这些工具的主要文档都是 man 手册。这是因为我经常发现 man 手册很难找到我想要的信息。
最近我一直在想——手册页本身能不能包含一份超棒的速查表？怎样才能让手册页更容易使用？我还在初步思考这个问题，但想先简单记下来。
我在 Mastodon 上询问了一些人他们最喜欢的 man 手册页，以下是我在这些 man 手册页中看到的一些有趣的例子。
期权概要
如果你读过很多手册页，你可能在SYNOPSIS看到过类似这样的内容：一旦列出几乎整个字母表，就很难做到面面俱到。
ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,] grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]这ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,] grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]
rsync 的手册页提供了一个我从未见过的解决方案：它的概要部分非常简洁，如下所示：
Local: rsync [OPTION...] SRC... [DEST]然后还有一个“选项概要”部分，其中包含每个选项的一行概要，如下所示：Local: rsync [OPTION...] SRC... [DEST]
--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然后是常见的“选项”部分，其中对每个选项进行了完整描述。--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
按类别组织的“选项”部分
strace 手册页按类别（如“常规”、“启动”、“跟踪”、“过滤”、“输出格式”）而不是按字母顺序组织其选项。
我尝试对grep命令的手册页进行修改，并按类别创建一个“选项摘要”部分，结果可以在这里看到。我对结果不太满意，但这确实是一次有趣的尝试。在编写这段文字的时候，我一直在想我总是记不住 grep 命令的-l选项的名称。每次在手册页里找到它都感觉像是要花上好长时间，所以我在思考什么样的结构能让我更容易找到它。也许按类别划分比较好？
作弊表
有几个人向我推荐了 Perl 的手册页（ perlfunc 、 perlre等），我注意到其中有一个手册页 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 手册的 ASCII 80 字符宽的精简速查表。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 手册”。有人提到了 OpenBSD 的 man 手册，而OpenBSD 的 tail 命令man 手册中正好包含了我在最后使用的两种 tail 命令用法示例。
我印象中最常见的是把“示例”部分放在手册页的末尾，但有些手册页（比如前面提到的rsync 手册页）会把示例放在开头。我之前写git-add和git rebase手册页的时候，就在开头放了一个简短的示例。
目录以及各章节之间的链接
这不是 man 手册本身的属性，但终端中的 man 手册存在一个问题，那就是很难知道 man 手册包含哪些部分。
在编写 Git 手册页时，我和 Marie 做的一件事是，在 Git 网站上托管的 HTML 版本的手册页的侧边栏中添加目录。
我还想在某个时候为 Git 手册页的 HTML 版本添加更多超链接，这样您就可以点击“不兼容选项”跳转到相应部分。由于 Git 的手册页是用 AsciiDoc 生成的，因此在 Git 项目中添加此类链接非常容易。
我认为添加目录和内部超链接是一个不错的折衷方案，既可以改进手册页的格式（至少在 HTML 版本的手册页中），又无需维护完全不同的文档形式。不过，要实现这一点，你需要搭建一个类似 Git 的 AsciiDoc 系统这样的工具链。
每个选项的示例
curl 手册页包含了每个选项的示例，HTML 版本中还有一个目录，方便您更轻松地跳转到感兴趣的选项。
例如， --cert的示例很容易看出，您可能还需要传递--key选项，如下所示：
他们实现的方式是，每个选项都有一个文件（ curl --cert certfile --key keyfile https://example.com
https://github.com/curl/curl/blob/dc08922a61efe546b318daf964514ffbf41583 25/docs/cmdline-opts/append.md) 并且该文件中有一个“示例”字段。
表格数据格式化
不少人说他们最喜欢的 man 手册页是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)明显地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是一个比较特殊的 man 手册页，但我认为它最棒的地方（除了拥有 ASCII 参考手册本身就很有用之外）在于它采用了表格格式，因此很容易快速找到所需信息。这让我不禁思考，是否还有其他方法可以在 man 手册中采用“表格”形式来展示信息，从而简化阅读过程。
GNU 方法
当我谈到 man 手册时，经常会有人提到 GNU coreutils 的 man 手册（例如man tail ）没有示例，而 OpenBSD 的 man 手册则有示例。
我不想过多深入探讨这个问题，因为它似乎是一个相当政治化的话题，我肯定无法在这里全面阐述，但以下是我认为的一些事实：
- GNU 项目倾向于使用“info”手册而非 man 手册来维护文档。此页面说明“man 手册已停止维护”。
- 阅读“info”手册有三种方式：HTML 版本、Emacs 版本，或者使用独立的
info工具。我听说一些 Emacs 用户喜欢 Emacs 自带的 info 浏览器。我好像还没遇到过使用独立info工具的人。 - tail 命令的 info 手册条目链接在 man 手册页的底部，其中确实包含示例。
- 自由软件基金会过去曾出售 GNU 软件手册的印刷版（也许他们现在偶尔还会出售？）。
当手册页的内容变得相当复杂时，就很难查阅了：虽然我从未用过 coreutils info 手册，以后可能也不会用，但我几乎肯定会更喜欢通过 HTML 文档来使用GNU Bash 参考手册或GNU C 库参考手册，而不是通过 man 手册。
还有一些与手册页相关的内容
以下是一些我觉得很有意思的工具：
- fish shell自带一个Python 脚本，可以自动从 man 手册页生成 Tab 键补全。
- tldr.sh是一个由社区维护的示例数据库，例如，你可以运行
tldr grep。很多人都告诉我他们觉得它很有用。 - Dash Mac 文档浏览器内置了一个不错的 man 手册查看器。我仍然使用终端的 man 手册查看器，但我很喜欢它包含目录，看起来是这样的：
思考一种受限格式很有意思。
手册页的格式非常受限，想想如何在如此有限的格式选项下做出精彩的内容，真是件很有趣的事。我很想听听你认为设计精良的其他手册页，以及你喜欢它们的原因，评论区在这里。