可以从troff格式制作手册页吗？

Question

我有一个troff格式的文件，并希望重新转换为手册页

file.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 file.txt | man -l -时，我并不真正理解groff的输出。

正如您所看到的，我从来没有做过手册页，我只是想使用troff格式，使它成为一个可读的手册页。

该怎么做呢？

PS:输出来自所提供的源码树中的perl script kernel-doc。我确实知道它是否是troff格式，但脚本是这样说的(Output troff manual page format)

Answer 1

如果需要使用troff格式并创建一个可读的手册页，不一定要使用groff-我推荐使用pandoc。下面的命令产生了比使用groff更具可读性的输出。

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

​

​

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

Answer 2

我偶然发现了一个用python编写的名为rst2man的脚本，它负责转换作业。它并不完美，但比pandoc更好的选择。例如，如果有人想要阅读内核文档。您可以使用

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

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

rst2man是python脚本