☰

为什么手册页没有示例？

tag-icon • tag-icon man history
为什么手册页没有示例？

大多数手册页不包含一些常见示例是否有原因？他们通常会解释所有可能的选项，但这使得初学者更难理解它“通常”如何使用。

答案1

这取决于手册页......传统上，他们有包括一个带有示例的部分 - 但由于某种原因，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 创建池/home
       # zfs set mountpoint=/export/home 池/home
       # zfs 创建池/home/bob

     示例 2 创建 ZFS 快照

     以下命令创建名为昨天的快照。
     此快照按需安装在 .zfs/snapshot 中
     pool/home/bob 文件系统根目录。

       # zfs 快照池/home/bob@yesterday

     示例 3 创建和销毁多个快照

     以下命令创建名为昨天的快照
     pool/home 及其所有后代文件系统。每个
     快照按需挂载在 .zfs/snapshot 目录中
     在其文件系统的根目录下。第二条命令销毁
     新创建的快照。

       # zfs snapshot -r pool/home@yesterday
       # zfs destroy -r pool/home@yesterday

SunOS 5.11 最后更改：2012 年 7 月 23 日 51

系统管理命令 zfs(1M)

     示例 4 禁用和启用文件系统压缩

     以下命令禁用压缩属性
（...）

这个特定的手册页附带了 16(!) 个这样的示例...向 Solaris 致敬！
（我承认我自己主要遵循这些示例，而不是阅读此命令的整个手册页......）

答案2

我认为这个问题没有一个好的答案。这是一个文化问题。一些手册页确实有示例用法。例如man rsync。您可以尝试通过写信给手册页作者并要求他或她添加一些示例用法或（更好）自己提供一些示例用法来改变文化。如果您向自由软件作者提供补丁，特别是文档补丁，那么实现所需结果的可能性比简单的请求高出大约一万倍。

答案3

这取决于：

  • 大多数您感兴趣的程序都是经过一段时间开发的，最初是为了解决问题，后来是为了改进解决方案。程序的开发人员解释了他们认为需要了解的重要内容（以及文档不是他们要解决的问题）。

  • 对于某些程序，开发人员更愿意提供示例程式或者脚本它展示了如何使用给定的程序（或库）。同样，这样做是为了解决一个问题：使程序更易于测试。

    一些示例可能基于用户的错误报告，并且何时短的在手册中找到一个位置。手册中很少提供冗长的示例，而简短的示例则存在这样的问题：它们往往是琐碎的、重复的，并且不能真正为用户提供与程序工作方式的组织良好的描述一样多的洞察力。

  • 在某些情况下，您会找到其他人提供的文档不是参与开发过程。也就是说，开发者除了审核文档之外，并没有参与。这种努力可以忽略不计。

答案4

如果您正在寻找手册页的替代品，您可以随时尝试兄弟页面，它仅显示命令的各种示例，然后您可以在社区提交的示例列表中对其进行投票。例如，该命令bro tar将为您提供：在此输入图像描述

相关内容