shell - 是否可以从 troff 格式制作手册页？

Question

我有一个 troff 格式的文件，想重铸到手册页

文件.txt：

.. c:function:: bool is_module_percpu_address (unsigned long addr)

   test whether address is from module static percpu

**Parameters**

``unsigned long addr``
  address to test

**Description**

Test whether **addr** belongs to module static percpu area.

**Return**

``true`` if **addr** is from module static percpu area


.. c:function:: int module_refcount (struct module * mod)

   return the refcount or -1 if unloading

**Parameters**

``struct module * mod``
  the module we're checking

**Return**

     -1 if the module is in the process of unloading
     otherwise the number of references in the kernel to the module

当我这样做时，我并不真正了解 groff 的输出groff file.txt | man -l -。

如您所见，我从未做过手册页，只是想使用 troff 格式并使其成为可读的手册页。

怎么做？

PS：输出来自kernel-doc提供的源代码树的 perl 脚本。我确实知道它是否是 troff 格式，但脚本是这样说的（Output troff manual page format）

Answer 1

如果需要使用 troff 格式并创建可读的手册页，不一定使用 groff——我建议使用 pandoc。与使用 groff 相比，以下命令产生的输出更具可读性。

pandoc file.txt -s -t man | man -l -

如果您的文件像@meuh 建议的那样有任何降价或 reStructuredText 内容，那对于 pandoc 来说应该不是问题。

Answer 2

我偶然发现了一个rst2man用 python 编写的脚本，它可以转换工作。它并不完美，但更好的选择pandoc。例如，如果有人试图阅读内核文档。你可以做

 kernel-doc path/to/kernel/source.{c,h} | rst2man -q - | man -l -

kernel-doc是源代码树中的 perl 脚本

rst2man是python脚本