Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

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?

share|improve this question
1  
Frankly speaking, I never use man for programming except standard library and syscalls. – el.pescado Feb 28 at 11:07
up vote 25 down vote accepted

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:

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
1  
It's worth noting that Doxygen can export manpages! – el.pescado Feb 28 at 10:50
    
@el.pescado Thanks for reminding me, I incorporated that into my text. – Murphy Feb 28 at 11:48

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.