为什么手册页没有示例？

52

为什么大多数手册页中都没有包含一些常见的示例？他们通常会解释所有可能的选项，但这会使初学者更难理解其“通常”用法。

man history

— 迪帕克·乔伊
source

1

我的猜测是，他们希望节省宝贵的磁盘空间，例如摆脱CR。cf. 贝克特，瓦，第8页：“很多宝贵的空间已经保存。[...]通过回避后，过多的反身代词的发言权。”

— 彼得-恢复莫妮卡

3

尝试解决此问题的一种方法是tldr-pages.github.io，尽管我不明白为什么他们可以轻松地预先下载所有内容以进行脱机访问。

— 内森·朗

man jq有超过1000行示例（在Ubuntu 16.04上）

— Motte001 '16

49

这就要看男人页......传统上，他们已经包含在例子部分-但由于某些原因，从该名男子页Linux下通常失踪（和我假设其他使用GNU命令-这是大多数这些天）。另一方面，在Solaris上，几乎每个手册页都包含“示例”部分，通常包含几个示例。

如果我猜到了，FSF / GNU长期以来一直不鼓励使用man页面，而是希望用户使用信息来代替文档。info页面往往比男人网页更全面，而且通常不包括的例子。 info页面也更具“主题性”-即通常可以一起找到相关命令（例如，用于查找文件的命令）。

另一个原因可能是GNU及其man页面在许多彼此不同的操作系统上使用（毕竟，不同Linux发行版之间存在很多差异）。发行人的意图可能是添加与特定OS /发行版相关的示例-显然很少这样做。

我还要补充一点，这些man页面从来都不打算“教初学者”。UNIX是由计算机专家（以前称为“黑客”）开发的，旨在供计算机专家使用。因此，手册页并不是用来教新手的，而是快速帮助需要提示某些晦涩选项或奇怪文件格式的计算机专家的，这反映在手册页的分段方式中。

man-页面因此旨在

快速参考以刷新您的记忆；显示如何调用该命令，并列出可用选项。
对命令各个方面的深入而透彻（通常是非常技术性的）描述。它是由计算机专家为其他计算机专家编写的。
命令使用的环境变量和文件（即配置文件）的列表。
参考其他文档（例如书籍）和其他man页面-例如用于配置文件和相关/相似命令的格式。

就是说，我非常同意您的观点，man页面应该有示例，因为它们可以比深入手册页本身更好地解释用法。Linux man页面通常没有太糟糕的例子...

Solaris手册页-zfs（1M）的Example部分的示例：

（...）
例子
     示例1：创建ZFS文件系统层次结构

     以下命令创建一个名为pool / home的文件系统
     和一个名为pool / home / bob的文件系统。挂载点
     / export / home为父文件系统设置，并且为
     由子文件系统自动继承。

       ＃zfs创建池/主目录
       ＃zfs set mountpoint = / export / home池/ home
       ＃zfs创建池/家庭/鲍勃

     示例2创建一个ZFS快照

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

       ＃zfs快照池/家庭/ bob @昨天

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

     以下命令创建快照的昨天
     池/主目录及其所有后代文件系统。每
     快照按需安装在.zfs / snapshot目录中
     在其文件系统的根目录。第二条命令销毁
     新创建的快照。

       ＃zfs快照-r池/家庭@昨天
       ＃zfs destroy -r pool / home @昨天

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

系统管理命令zfs（1M）

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

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

这个特定的手册页带有16（！）这样的示例。
（我承认我自己大多数情况下都遵循这些示例，而不是阅读此命令的整个手册页...）

— 巴德·科珀鲁德
source

2

最后一句话突出了手册中包含示例的问题。在没有完全了解该工具特定应用的含义的情况下，以最适合自己需求的示例为例。后来，人们只能说“我这样做了”，但并没有真正说出原因或含义。

— 库沙兰丹

6

@Kusalananda在我的辩护中，我已经阅读了各种选项以及我实际需要的子命令-尚未了解全部内容。这与我的使用无关紧要...尽管存在滥用的危险，但示例确实可以达到目的-并且，如果您所需要的只是命令的最基本用法，则几乎不需要阅读所有钟声。

— 巴德·科珀罗德

@Kusalananda它也可能取决于命令。我所知道的大多数Unix和GNU utils都有详细的文档说明，但是您需要使用这些文档来做任何明智的事情。较新的Solaris命令（尤其是zfs）设计得很自然。例如，zfs destroy pool/filesystem是基本用法，适用于90％的用例。像-rfor 这样的简短选项recursive比较特殊，使用前需要先咨询，因为它们可能会有意想不到的副作用。

— user121391 '16

26

我认为对此没有很好的答案。这是文化的东西。一些手册页确实有示例用法。例如man rsync。您可以尝试写信给手册页作者并要求他或她添加一些示例用法，或者（更好）自己提供一些示例用法示例，从而改变文化。如果您向自由软件作者提供补丁，尤其是文档补丁，则实现预期结果的可能性比简单请求高大约一万倍。

— 法希姆·米莎（Faheem Mitha）
source

7

这取决于：

您会发现有趣的大多数程序都是在一段时间内开发的，最初是为了解决问题，后来是改善解决方案。程序的开发人员解释了他们认为重要的知识（文档不是他们要解决的问题）。
对于某些程序，开发人员更喜欢提供示例程序或脚本，以显示如何使用给定的程序（或库）。同样，这样做是为了解决一个问题：使程序更易于测试。

其中一些示例可能基于用户的错误报告，以及在简短的手册中找到位置后的示例。手册中很少提供冗长的示例，而简短的示例则具有以下问题：它们往往是琐碎的，重复的，并且不能真正为用户提供如程序工作方式的良好组织描述那样的洞察力。
在某些情况下，您会找到由未参与开发过程的其他人提供的文档。也就是说，开发人员除查看文档外没有参与。这种努力可以忽略。

— 托马斯·迪基
source

5

“这种努力可以忽略。” 我不确定这是什么意思。

— Faheem Mitha

如果文档不是基于经验的，则不会提供任何有用的信息。

— Thomas Dickey

实际上，不基于经验的文档可能会产生负面影响-即，这完全是错误的。

— alephzero

当然-之所以提到它，是因为OP无疑想到的一些示例都属于此类（我将不提供该论坛的列表）。

— Thomas Dickey

2

@ThomasDickey。我完全不同意这种评估。编写实用程序的能力并不一定具有向最终用户解释API的能力。T

— chiggsy

6

如果您正在寻找替代手册页的方法，则可以随时尝试使用bro pages，它们仅显示命令的各种示例，然后您可以在社区提交的示例列表中对其进行投票。例如，该命令bro tar将为您提供：

— BandW2011
source