是否可以从 troff 格式制作手册页？答案

【问题标题】：Is it possible to make man page from troff format?是否可以从 troff 格式制作手册页？
【发布时间】：2020-04-28 23:21:10
【问题描述】：

我有一个 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 file.txt | man -l - 时，我不太了解 groff 的输出。

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

怎么做？

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

【问题讨论】：

仔细阅读您的man troff。我很确定曾经有一个--man 选项（或类似选项）。祝你好运。
您显示的输出是某种形式的 markdown 格式，可能是 reStructuredText。您需要寻找更多的脚本来处理这个问题，也许是sphinx，然后才能将它传递给 groff。

标签： shell document manpage troff

【解决方案1】：

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

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

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

【讨论】：

【解决方案2】：

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

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

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

rst2man是python脚本

【讨论】：

是什么让它比 pandoc 更好，尤其是在有 markdown 或 reStructuredText 内容的情况下？
我还在熟悉stackexchange；但是您对自己问题的回答不是没有恰当地解决这个问题吗？这种情况是否需要对问题本身进行编辑？