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

Question

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

Answer 1

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

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

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

首先阅读man man它提到标准宏的相关部分，并比较FreeBSD 和 Linux 的这些描述。

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

• ncurses在几十个手册页中有几百个函数。
• dialog在一个手册页中有几十个功能。其他人肯定会展示更多的例子。

进一步阅读：

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

Answer 2

我使用ronn。您只需编写 markdown，它就会将其转换为联机帮助页。还有一个（功能稍差）的js克隆，称为标记人。

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

至于部分，则 3 将是用户级 C 库。您可以在man(1) 中阅读有关部分编号（以及其他内容）的信息。

如果你想看到一些可读性强，结构良好的范例手册页，我想看看在的Plan9 https://swtch.com/plan9port/unix/库在这里你可以看到的非常创造者c，并UNIX和它的文档系统可能旨在让这些事情发挥作用。