Do I need to write man pages for C library?

Question

I wrote a small C library for Linux and FreeBSD, and I'm going to write the documentation for it. I tried to learn more about creating man pages and not found the instructions or descriptions of best practices making man pages for libraries. In particular I'm interested in what section to put man pages of the functions? 3? Maybe there good examples or manuals? Create man pages for each function from the library a bad idea?

Answer 1

Manual pages for a library would go in section 3.

For good examples of manual pages, bear in mind that some are written using specific details of groff and/or use specific macros which are not really portable.

There are always some pitfalls in portability of man-pages, since some systems may (or may not) use special features. For instance, in documenting dialog, I have had to keep in mind (and work around) differences in various systems for displaying examples (which are not justified).

Start by reading the relevant sections of man man where it mentions the standard macros, and compare those descriptions for FreeBSD and Linux.

Whether you choose to write one manual page for the library, or separate manual pages for the functions (or groups of functions) depends on how complicated the descriptions of the functions would be:

• ncurses has a few hundred functions across several dozen manual pages.
• dialog has several dozen functions in one manual page. Others will be sure to show many more examples.

Further reading:

• man -- display online manual documentation pages (FreeBSD)
• man-pages - conventions for writing Linux man pages
• groff_mdoc -- reference for groff's mdoc implementation
• HowTo: Create a manpage from scratch. (FreeBSD)
• What Is A "Bikeshed"?

Answer 2

I use ronn. You simply write markdown, and it'll turn it into a manpage. There's also a (somewhat less capable) js clone of it called marked-man.

I've been documenting my scripts with it by using END_MAN delimited heredocs and my C/C++ code by using the same END_MAN delimited heredocs except within /* */. Either is easily extractible with sed and then renderable into a manpage. (With a little bit of UNIX signal hackery along with inotifywait, you can extract and view your manpage sections live and have the manpage browser reload as the source updates. )

As for the section, then 3 would be it for a user-level C library. You can read about the section numbers (among other things) in man(1).

If you want to see some readable, well-structured example man pages, I'd take a look at the Plan9 https://swtch.com/plan9port/unix/ libraries where you can see how the very creators of c and UNIX and its documentation system probably intended for these things to work.

Answer 3

To supplement the other answers, another markdown language that can be used to simplify writing man pages is reStructuredText and the rst2man command which is part of the python-docutils package.

This markdown language has been adopted by python for its documentation, and is much easier to learn, write and maintain, than the good old troff man macros which rst2man will generate for you from your reStructuredText.

Answer 4

You could document the API using doxygen to provide the reference as HTML, and also generate man pages and other formats for offline reading.

The advantage of doxygen is that it's sort of "inline" documentation like JavaDoc or PythonDoc, doubling as interface comments (or vv., comments doubling as doc text); you add the doc texts to your source/header files, and it's extracted from there, which improves the chances of being held up to date.