From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 015bf0a0 for ; Tue, 22 Mar 2016 10:00:13 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1aiNn0-0000No-1n; Tue, 22 Mar 2016 16:00:12 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1aiNmv-0003ms-VV; Tue, 22 Mar 2016 16:00:05 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84) (envelope-from ) id 1aiNmn-0006i4-7a; Tue, 22 Mar 2016 15:59:57 +0100 Received: from localhost (1031@localhost [local]); by localhost (OpenSMTPD) with ESMTPA id 98bd9165; Tue, 22 Mar 2016 16:00:05 +0100 (CET) Date: Tue, 22 Mar 2016 16:00:05 +0100 From: Ingo Schwarze To: Svyatoslav Mishyn Cc: discuss@mdocml.bsd.lv Subject: Re: library name inside 'Lb' macro Message-ID: <20160322150005.GJ10862@athene.usta.de> References: <20160314141328.GA1353@k8> 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: <20160314141328.GA1353@k8> User-Agent: Mutt/1.5.23 (2014-03-12) Hi Svyatoslav, Svyatoslav Mishyn wrote on Mon, Mar 14, 2016 at 04:13:29PM +0200: > should a library name start with 'lib' or not ? you mean, in .Lb? It should start with 'lib'. But avoid using .Lb in the first place if you can. > because, > from http://manpages.bsd.lv/part1-3.html : > In general, a function library should have its name not include the > leading "lib". That refers to .Dt, not to .Lb. That is bogus advice, too, by the way. Manual pages should be named after functions. They should not have fantasy names. But i left that untouched for now. > but mdoc(7)'s examples are: > .Lb libz > .Lb libmandoc That's correct. > as discussed previously with Kristaps, > variant from part1-3.html is wrong and needs fixing. Indeed, but only further down, not at the place you quoted above. I just committed a fix for the wrong syntax and added minimal changes to make it clear that ".Sh LIBRARY" and ".Lb" are bad ideas. Unfortunately, manpages.bsd.lv is full of bogus advice in general. Just as an example, just on this individual page: - libraries are not usually in /usr/local, but in /usr[/*]/lib - filenames rarely end in .so, libraries are usually versioned - bogus name in .Dt - .Nd should not be "generic", but concise and precise; if more functions are added, .Nd can be adjusted as well - the first .Nm wins, not the last one - alphabetic order in NAME is one acceptable option, but it is often better to list functions in the order they are usually called or list the most important one first and less common variants afterwards - as the list is short in any good page, alphabetic order is not important - wrong order in the SYNOPSIS; the correct order would be .In hello .Fo hello .In hi .Fn hi - it goes without saying that C strings are NUL-terminated (besides, in the exceptional case that you need to say it, don't say "nil-terminated" in manuals) - it's obvious that a void function does not return a value - hello()'s return values are ill-designed - missed opportunity to show .Rv I'm not sure what to do about it. It would need a major rewrite. On the one hand, that's a considerable amount of work. On the other hand, the style isn't bad, and it's Kristaps' personal style. If i would do the rewrite, my changes probably wouldn't match the style. We might end up with an inconsistent style, which might make the tutorial awkward to read. For a tutorial, that might be even worse than for a reference document. Besides, i'm not sure Kristaps would like me to do more than fixing severe bugs in his text. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv