From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailout.scc.kit.edu (mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id sAK22gti029833 for ; Wed, 19 Nov 2014 21:02:42 -0500 (EST) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1XrH4x-0002FO-LK; Thu, 20 Nov 2014 03:02:39 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1XrH4x-0003k9-Jk for discuss@mdocml.bsd.lv; Thu, 20 Nov 2014 03:02:39 +0100 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1XrH4x-0004uQ-0c for discuss@mdocml.bsd.lv; Thu, 20 Nov 2014 03:02:39 +0100 Received: from schwarze by usta.de with local (Exim 4.77) (envelope-from ) id 1XrH4w-0008Qs-W9 for discuss@mdocml.bsd.lv; Thu, 20 Nov 2014 03:02:38 +0100 Date: Thu, 20 Nov 2014 03:02:38 +0100 From: Ingo Schwarze To: discuss@mdocml.bsd.lv Subject: Re: Library manpages per-function or per-library? Message-ID: <20141120020238.GL28366@iris.usta.de> References: <54636E8E.3010007@bsd.lv> <20141112145127.GA28857@britannica.bec.de> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20141112145127.GA28857@britannica.bec.de> User-Agent: Mutt/1.5.21 (2010-09-15) 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