discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Library manpages per-function or per-library?
@ 2014-11-12 14:28 Kristaps Dzonsons
  2014-11-12 14:51 ` Joerg Sonnenberger
  2014-11-20  2:10 ` Guy Harris
  0 siblings, 2 replies; 4+ messages in thread
From: Kristaps Dzonsons @ 2014-11-12 14:28 UTC (permalink / raw)
  To: discuss

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Library manpages per-function or per-library?
  2014-11-12 14:28 Library manpages per-function or per-library? Kristaps Dzonsons
@ 2014-11-12 14:51 ` Joerg Sonnenberger
  2014-11-20  2:02   ` Ingo Schwarze
  2014-11-20  2:10 ` Guy Harris
  1 sibling, 1 reply; 4+ messages in thread
From: Joerg Sonnenberger @ 2014-11-12 14:51 UTC (permalink / raw)
  To: discuss

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Library manpages per-function or per-library?
  2014-11-12 14:51 ` Joerg Sonnenberger
@ 2014-11-20  2:02   ` Ingo Schwarze
  0 siblings, 0 replies; 4+ messages in thread
From: Ingo Schwarze @ 2014-11-20  2:02 UTC (permalink / raw)
  To: discuss

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

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Library manpages per-function or per-library?
  2014-11-12 14:28 Library manpages per-function or per-library? Kristaps Dzonsons
  2014-11-12 14:51 ` Joerg Sonnenberger
@ 2014-11-20  2:10 ` Guy Harris
  1 sibling, 0 replies; 4+ messages in thread
From: Guy Harris @ 2014-11-20  2:10 UTC (permalink / raw)
  To: discuss


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

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2014-11-20  2:10 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-11-12 14:28 Library manpages per-function or per-library? Kristaps Dzonsons
2014-11-12 14:51 ` Joerg Sonnenberger
2014-11-20  2:02   ` Ingo Schwarze
2014-11-20  2:10 ` Guy Harris

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).