From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-4.sys.kth.se (smtp-4.sys.kth.se [130.237.48.193]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id sACESeQ3012436 for ; Wed, 12 Nov 2014 09:28:44 -0500 (EST) Received: from smtp-4.sys.kth.se (localhost.localdomain [127.0.0.1]) by smtp-4.sys.kth.se (Postfix) with ESMTP id 3F1C01D9C for ; Wed, 12 Nov 2014 15:28:39 +0100 (CET) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-4.sys.kth.se ([127.0.0.1]) by smtp-4.sys.kth.se (smtp-4.sys.kth.se [127.0.0.1]) (amavisd-new, port 10024) with LMTP id YVcUs_g5rxE4 for ; Wed, 12 Nov 2014 15:28:38 +0100 (CET) X-KTH-Auth: kristaps [82.239.22.94] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: discuss@mdocml.bsd.lv Received: from skins.local (jau31-3-82-239-22-94.fbx.proxad.net [82.239.22.94]) by smtp-4.sys.kth.se (Postfix) with ESMTPSA id 78454F3C for ; Wed, 12 Nov 2014 15:28:31 +0100 (CET) Message-ID: <54636E8E.3010007@bsd.lv> Date: Wed, 12 Nov 2014 15:28:30 +0100 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:24.0) Gecko/20100101 Thunderbird/24.6.0 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 To: discuss@mdocml.bsd.lv Subject: Library manpages per-function or per-library? Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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