Library manpages per-function or per-library?

[Kristaps Dzonsons <kristaps@bsd.lv>]

Hi folks,

I thought I'd put this question up for future searches, as it confuses 
me and no doubt confuses others, as well.  In short, when writing a 
library, does one document each function in a separate mdoc(7) page, or 
all functions in one big one?  Or perhaps, grouped by utility?  Or 
grouped by header file?

Longer story: I'm writing a library for plotting using cairo.  I use it 
for my own affairs and it has one big manpage.  However, I'm getting 
really tired of jumping around in that manpage.

What I think I'd like to do is break it down like pthread(3) or MPI(3), 
where there's a page roughly describing the whole library, then each 
function gets its own page.  (I'd put synonyms on the same page.)  This, 
to me, makes a lot of sense.  One has a general walk-through of all 
functions, perhaps grouped in some way, then each function has its own 
manpage for later usage.

Any thoughts?

Best,

Kristaps
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv