linux - 放入手册页的最佳实践

Question

是否有编写手册页的最佳实践指南？

布局中应该包括什么？标准的有：
名称
概要
描述
示例
参见

还有其他像OPTIONS，AUTHOR。

作为用户，拥有什么有用？什么没有帮助？

score 4 · Accepted Answer

如果您找不到任何 1970 年代贝尔实验室“troff”文档的旧装订副本，其中有一些关于编写手册页的不错的部分，:-) 那么我建议在 Jens 的网站上尝试编写手册页的“HOWTO”。

Unix 第 7 版手册以多种格式在线提供。

score 1 · Accepted Answer

BUGS 部分很好，EXAMPLES 部分总是有用的。一些手册页包含列出相关配置文件的 FILES 部分，或详细说明任何有影响的环境变量的 ENVIRONMENT 部分。

需要明确的是，哪些部分或类型的信息对用户有用取决于您正在记录的程序或实用程序的性质。

score 1 · Accepted Answer

有一个随 UNIX 系统分发的规范手册页大纲，或者至少通常有。一般来说，我会填写所有字段，如果不适用，请添加“无”之类的行。

score 1 · Accepted Answer

人们有时忘记放入手册页的一件事是函数返回值的含义。这很容易忘记，但是对于必须使用您的功能的人来说，遗漏会使生活变得更加困难。此外，SYNOPSIS 中的简单代码段或良好的最小工作示例非常有用。

我经常对手册页做的一件事是尝试找到相关的命令，即使我知道我正在查看的内容并没有达到我想要的效果。在这种情况下，SEE ALSO 很棒。

score 0 · Accepted Answer

这取决于你的软件是做什么的。如果它是一个小型的独立应用程序，我当然会将 AUTHOR 部分放在手册页中，这样如果用户发现错误，他们可以轻松找到电子邮件地址向您报告错误。

至于最佳实践，我不知道，除了手册页应该简洁、详细但不包含太多不需要的信息，例如，如果它只是一个工具，则不需要内部工作。

5 回答 5