Baa*_*rud 51
这取决于手册页......传统上，他们已经包含了一个带有示例的部分 - 但由于某种原因，Linux 下的手册页通常缺少它（我假设其他使用 GNU 命令的人 - 这些天是大多数）。另一方面，例如在 Solaris 上，几乎每个手册页都包含示例部分，通常带有几个示例。
如果我猜的话，FSF/GNU 长期以来一直不鼓励使用man页面，而是更喜欢用户使用信息作为文档。info页面往往比男人网页更全面，而且通常不包括的例子。 info页面也更“热门”——即相关命令（例如查找文件的命令）通常可以一起找到。
另一个原因可能是 GNU 及其man页面用于许多不同的操作系统，这些操作系统可能彼此不同（毕竟不同的 Linux 发行版之间存在很多差异）。其意图可能是发布者添加了与特定操作系统/发行版相关的示例——这显然很少这样做。
我还要补充一点，man页面从来没有打算“教初学者”。UNIX 是由计算机专家（旧术语“黑客”）开发的，旨在供计算机专家使用。因此，手册页不是为了教新手，而是为了快速帮助需要提醒一些晦涩选项或奇怪文件格式的计算机专家 - 这反映在手册页的分区方式中。
man-pages 因此旨在作为
- 快速参考以刷新您的记忆；向您展示应如何调用该命令，并列出可用选项。
- 对命令的所有方面的深入而彻底的——通常是非常技术性的——描述。它是由计算机专家为其他计算机专家编写的。
- 命令使用的环境变量和文件（即配置文件）的列表。
- 参考其他文档（例如书籍）和其他
man页面 - 例如。用于配置文件和相关/类似命令的格式。
也就是说，我非常同意你的观点，man页面应该有示例，因为它们比翻阅手册页本身更能解释用法。太糟糕的例子通常在 Linuxman页面上不可用......
Solaris 手册页示例部分的示例 - zfs(1M)：
（……）
例子
示例 1 创建 ZFS 文件系统层次结构
以下命令创建一个名为 pool/home 的文件系统
和一个名为 pool/home/bob 的文件系统。挂载点
/export/home 是为父文件系统设置的，并且是
由子文件系统自动继承。
# zfs 创建池/家
# zfs set mountpoint=/export/home pool/home
# zfs 创建池/家/bob
示例 2 创建 ZFS 快照
以下命令创建一个名为昨天的快照。
此快照按需挂载在 .zfs/snapshot 中
pool/home/bob 文件系统根目录下的目录。
# zfs 快照池/home/bob@yesterday
示例 3 创建和销毁多个快照
以下命令创建名为昨天的快照
pool/home 及其所有后代文件系统。每个
快照按需挂载在 .zfs/snapshot 目录中
在其文件系统的根目录。第二条命令销毁
新创建的快照。
# zfs 快照 -r pool/home@yesterday
# zfs destroy -r pool/home@yesterday
SunOS 5.11 最后更改：2012 年 7 月 23 日 51
系统管理命令 zfs(1M)
示例 4 禁用和启用文件系统压缩
以下命令禁用压缩属性
（……）
这个特殊的手册页附带了 16 个（！）这样的例子......向 Solaris 致敬！
（而且我承认我自己主要遵循这些示例，而不是阅读此命令的整个手册页......）
- @Kusalananda 在我的辩护中，我*已经*阅读了各种选项以及我实际上*需要*的子命令 - 只是不是全部（还）。它与我的使用完全无关......尽管存在误用的危险，但示例*确实*是有目的的-如果您所需要的只是命令的最基本用法，则几乎没有必要阅读所有花里胡哨的内容。 (7认同)
- 最后一句话突出了一个_问题_，手册中有示例。人们采用最适合自己需要的示例，而没有完全理解该工具的特定应用程序的含义。后来，人们可以只说“我是这样做的”，但不是真正的原因或含义。 (2认同)
Fah*_*tha 27
我认为对此没有很好的答案。这是一个文化问题。一些手册页确实有示例用法。例如man rsync。您可以通过写信给手册页作者并要求他或她添加一些示例用法或（更好）自己提供一些示例用法来尝试改变文化。如果您为自由软件作者提供补丁，尤其是文档补丁，那么实现预期结果的可能性比简单请求高出大约一万倍。
- `rsync` 是一个非常奇怪的手册页，使用一种第一人称非正式对话。例如：`以下是我如何使用 rsync 的一些示例。为了备份我妻子的主目录（其中包含大型 MS Word 文件和邮件文件夹），我使用了一个运行`(...) 的 cron 作业，也许这应该是模型。 (2认同)
这取决于：
大多数您感兴趣的程序都是经过一段时间开发的，最初是为了解决问题，后来是为了改进解决方案。程序的开发人员解释了他们认为重要的知识（并且文档不是他们要解决的问题）。
对于某些程序，开发人员更喜欢提供示例程序或脚本来展示如何使用给定的程序（或库）。同样，这样做是为了解决一个问题：使程序更易于测试。
一些示例可能基于用户的错误报告，并且在手册中找到了简短的位置。手册中很少提供冗长的示例，而简短的示例存在的问题是，它们往往是琐碎的、重复的，并且不能像对程序工作方式的组织良好的描述那样真正为用户提供更多的洞察力。
在某些情况下，您会发现由未参与开发过程的其他人提供的文档。也就是说，开发人员除了查看文档之外没有参与。这种努力是可以忽略的。
- “这种努力可以无视。” 我不确定这意味着什么。 (5认同)
- @托马斯迪基。我完全不同意这个评价。编写实用程序的能力不一定具有向最终用户解释 API 的能力。吨 (2认同)
