0

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)

Herdsman
  • 799
  • 1
  • 7
  • 24
  • read your `man troff` carefully. I'm pretty sure there used to be an `--man` option (or similar). Good luck. – shellter Apr 28 '20 at 23:47
  • 1
    The output you show is some form of *markdown* format, perhaps reStructuredText. You need to look for further scripts to handle this, perhaps`sphinx`, before you can pass it to groff. – meuh Apr 29 '20 at 07:17

2 Answers2

0

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 -

enter image description here

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

mjmcull
  • 60
  • 5
0

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

Herdsman
  • 799
  • 1
  • 7
  • 24
  • What makes it better than pandoc, especially if there is markdown or reStructuredText contents? – mjmcull May 02 '20 at 00:12
  • I'm still getting familiar with stackexchange; but doesn't your answer to your own question not appropriately address the question? Is this a situation warranting an edit to the question itself? – mjmcull May 02 '20 at 00:32