From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from c.mail.sonic.net (c.mail.sonic.net [64.142.111.80]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id sAK2AWGo017203 for ; Wed, 19 Nov 2014 21:10:32 -0500 (EST) Received: from [10.0.1.2] ([66.201.46.179]) (authenticated bits=0) by c.mail.sonic.net (8.14.9/8.14.9) with ESMTP id sAK2AL4i015552 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT) for ; Wed, 19 Nov 2014 18:10:25 -0800 Content-Type: text/plain; charset=iso-8859-1 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv Mime-Version: 1.0 (Mac OS X Mail 6.6 \(1510\)) Subject: Re: Library manpages per-function or per-library? From: Guy Harris In-Reply-To: <54636E8E.3010007@bsd.lv> Date: Wed, 19 Nov 2014 18:10:23 -0800 Message-Id: <9541F379-44DD-4DCD-9E3B-A6A450874746@alum.mit.edu> References: <54636E8E.3010007@bsd.lv> To: discuss@mdocml.bsd.lv X-Mailer: Apple Mail (2.1510) X-Sonic-CAuth: UmFuZG9tSVYGSkWb3zo1B5FwKeu9zSX7lOvQ1OaOWPGePmGQ3EJmL5bX775h68AXp3pDn95OWgF6oOieQYaavkFUQmrK8VHz X-Sonic-ID: C;BgeLYVpw5BGNH1Zegs/dsg== M;lOj3YVpw5BGNH1Zegs/dsg== X-Spam-Flag: No X-Sonic-Spam-Details: 0.0/5.0 by cerberusd Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by krisdoz.my.domain id sAK2AWGo017203 On Nov 12, 2014, at 6:28 AM, 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? > > 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