Можно ли сделать справочную страницу из формата troff?

Question

У меня есть файл в формате troff, и я хотел бы переписать страницу man

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, когда я сделать groff file.txt | man -l -.

Как видите, я никогда не делал man-страниц, просто хочу использовать формат troff и сделал его удобочитаемой man-страницей.

Как это сделать?

PS: вывод поступает из perl script kernel-doc из предоставленного дерева исходных текстов. Я знаю, является ли это формат troff, но сценарий говорит так (Output troff manual page format)

Answer 1

Я случайно натолкнулся на сценарий rst2man, написанный на python, который выполняет преобразование работы. Это не идеальный, но лучший вариант, чем pandoc. Если кто-то пытается, например, прочитать документацию ядра. Вы можете сделать с

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

kernel-doc is perl скрипт в дереве исходных текстов

rst2man is python script

Answer 2

Если необходимо использовать формат troff и создать читаемую справочную страницу, необязательно использовать groff - я бы рекомендовал использовать pando c. Приведенные ниже команды приводят к гораздо более удобочитаемому выводу, чем использование groff.

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

Если в вашем файле есть какое-либо значение markdown или reStructuredText как @meuh предполагает, что это не должно быть проблемой для пандо c.