我需要为 C 库编写手册页吗？

Question

我为 Linux 和 FreeBSD 编写了一个小型 C 库，并且我将为它编写文档。我试图了解有关创建手册页的更多信息，但没有找到为库制作手册页的最佳实践的说明或描述。我特别感兴趣的是放置函数手册页的哪个部分？ 3？也许有很好的例子或手册？为库中的每个函数创建手册页是一个坏主意吗？

Answer 1

库的手册页将放在第 3 节中。

对于手册页的良好示例，请记住，有些手册页是使用 groff 的特定细节编写的和/或使用并非真正可移植的特定宏。

手册页的可移植性总是存在一些陷阱，因为某些系统可能（或可能不）使用特殊功能。例如，在记录dialog，我必须记住（并解决）各种系统中显示示例的差异（这是不合理的）。

开始于阅读man man提到标准宏的相关部分，以及比较这些针对 FreeBSD 和 Linux 的描述。

您是选择为库编写一个手册页，还是为函数（或函数组）编写单独的手册页，取决于函数描述的复杂程度：

• 恩诅咒在几十个手册页中拥有数百个功能。
• 对话一页手册页中有几十个功能。其他人肯定会展示更多的例子。

进一步阅读：

• man -- 显示在线手册文档页面（自由BSD）
• man-pages - 编写 Linux 手册页的约定
• groff_mdoc -- groff 的 mdoc 实现的参考
• 操作方法：从头开始创建联机帮助页。（自由BSD）
• 什么是“自行车棚”？

Answer 2

我用罗恩。您只需编写 Markdown，它就会将其变成手册页。还有一个（能力稍差）js它的克隆称为标记者。

我一直通过使用END_MAN分隔的heredocs 来记录我的脚本，并使用相同的END_MAN分隔heredocs 来记录我的C/C++ 代码（除了在/* */.两者都可以使用 sed 轻松提取，然后可呈现到联机帮助页中。 （通过一点 UNIX 信号黑客技术和 inotifywait，您可以实时提取和查看您的手册页部分，并在源更新时重新加载手册页浏览器。）

至于该部分，那么对于用户级 C 库来说，3 就是它。您可以阅读有关章节编号（以及其他内容）的信息男人(1)。

如果您想查看一些可读的、结构良好的示例手册页，我会看一下 Plan9https://swtch.com/plan9port/unix/库，您可以在其中了解其创建者及其文档系统可能如何c让UNIX这些东西发挥作用。

Answer 3

为了补充其他答案，另一种可用于简化编写手册页的 Markdown 语言是重构文本和rst2man命令是的一部分python-docutils包裹。

这种 Markdown 语言已被 Python 采用它的文档，并且比 rst2man 将从 reStructuredText 为您生成的老式 troff man 宏更容易学习、编写和维护。

Answer 4

您可以使用以下方式记录 API强力氧以 HTML 形式提供参考，并生成手册页和其他格式以供离线阅读。

doxygen 的优点在于它是一种“内联”文档，如 JavaDoc 或 PythonDoc，兼作界面注释（或 vv.，注释兼作文档文本）；您将文档文本添加到源文件/头文件中，然后从那里提取文档文本，这提高了保持最新状态的机会。