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
On Wed, Nov 12, 2014 at 03:28:30PM +0100, Kristaps Dzonsons wrote:
> 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?
One man page documenting the general API design and one man page per
function group.
Joerg
--
To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
Hi, Kristaps and Joerg, Joerg Sonnenberger wrote on Wed, Nov 12, 2014 at 03:51:27PM +0100: > On Wed, Nov 12, 2014 at 03:28:30PM +0100, Kristaps Dzonsons wrote: >> 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? The usual policy in OpenBSD is one page per function, except when that would cause substantial text duplication, in which case functions get grouped into pages to avoid duplication. Grouping a few closely related functions for other reasons is also widely considered acceptable, in particular if the amount of information per function is low, as long as the number of functions per page doesn't grow too much. > One man page documenting the general API design and one man page > per function group. That sounds like a sound policy, too, even though OpenBSD usually skips the page documenting the general API design, explaining that in whichever of the individual pages fits best. Note that there are many cases where these policies are not followed for various, often historical reasons, and that the policies are not intended to be followed by the letter. If, in a particular case, doing it a bit differently makes the pages easier to use, that's OK. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
On Nov 12, 2014, at 6:28 AM, Kristaps Dzonsons <kristaps@bsd.lv> wrote:
> 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.
That, with possible grouping of related functions into a single man page rather than giving *all* functions their own man pages, is my preference.
Originally, libpcap had a single pcap(3) man page; if you wanted to see a description of a *single* function, you'd have to say "man pcap" and scroll through, hoping you don't miss the function.
This annoyed me enough that I split it up, with pcap(3PCAP) covering the library as a whole, and individual man pages for functions or small groups (for example, pcap_dispatch() and pcap_loop() are similar enough that they're probably best discussed in a common man page, so I put them together in that page).
There should be aliases, so that you can do "man pcap_dispatch" or "man pcap_loop" and get their shared man page. (That's what I did.)
--
To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv