Is it possible to make man page from troff format?

Question

I have a file with troff format and would like to recast to man page

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

I don't really understand the output of groff, when I do groff file.txt | man -l -.

As you can see, I have never done man pages, just want to use a troff format and made it a readable man page.

How to do so?

PS: the output comes from perl script kernel-doc from source tree provided. I do know whether it is troff format, but the script says so (Output troff manual page format)

Answer 1

I hit by chance to a script called rst2man written in python which does to converting job. It is not perfect, but better option then pandoc. If anyone is trying to for example read kernel documentation. You can do with

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

kernel-doc is perl script in source tree

rst2man is python script

Answer 2

If the requirement is to use troff format and create a readable man page, not necessarily using groff—I'd recommend using pandoc. The below commands result in a much more readable output than using groff.

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

If your file has any markdown or reStructuredText content as @meuh suggests, that shouldn't be a problem for pandoc.