From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-3.sys.kth.se (smtp-3.sys.kth.se [130.237.48.192]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 29e18974 for ; Wed, 23 Mar 2016 08:23:32 -0500 (EST) Received: from smtp-3.sys.kth.se (localhost.localdomain [127.0.0.1]) by smtp-3.sys.kth.se (Postfix) with ESMTP id D4A1C27AE; Wed, 23 Mar 2016 14:23:31 +0100 (CET) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-3.sys.kth.se ([127.0.0.1]) by smtp-3.sys.kth.se (smtp-3.sys.kth.se [127.0.0.1]) (amavisd-new, port 10024) with LMTP id Un3uewreyVMI; Wed, 23 Mar 2016 14:23:30 +0100 (CET) X-KTH-Auth: kristaps [2a01:cb19:8253:1100:f0c6:656:87c2:efba] X-KTH-mail-from: kristaps@bsd.lv Received: from skins.home (unknown [IPv6:2a01:cb19:8253:1100:f0c6:656:87c2:efba]) by smtp-3.sys.kth.se (Postfix) with ESMTPSA id 8A55CB0E; Wed, 23 Mar 2016 14:23:25 +0100 (CET) Subject: Re: library name inside 'Lb' macro To: discuss@mdocml.bsd.lv, Svyatoslav Mishyn References: <20160314141328.GA1353@k8> <20160322150005.GJ10862@athene.usta.de> From: Kristaps Dzonsons Message-ID: <56F298CA.7040501@bsd.lv> Date: Wed, 23 Mar 2016 14:23:22 +0100 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:38.0) Gecko/20100101 Thunderbird/38.5.1 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 In-Reply-To: <20160322150005.GJ10862@athene.usta.de> Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="mSgi006hrpnwPjiXVBsET6Hmq6EVL37hk" This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --mSgi006hrpnwPjiXVBsET6Hmq6EVL37hk Content-Type: multipart/mixed; boundary="tjTkp2I09TTKhXqNNqCp51Oe9wK71JSpD" From: Kristaps Dzonsons To: discuss@mdocml.bsd.lv, Svyatoslav Mishyn Message-ID: <56F298CA.7040501@bsd.lv> Subject: Re: library name inside 'Lb' macro References: <20160314141328.GA1353@k8> <20160322150005.GJ10862@athene.usta.de> In-Reply-To: <20160322150005.GJ10862@athene.usta.de> --tjTkp2I09TTKhXqNNqCp51Oe9wK71JSpD Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: quoted-printable Ingo, Svyatoslav, > That is bogus advice, too, by the way. > Manual pages should be named after functions. > They should not have fantasy names. man 3 crypto, ssl, ncurses, gsl, pthread, etc. all do this. Even mandoc(3)! If documenting an entire library (either as an `index' to other manpages or standalone), do you propose arbitrarily choosing a function to stick into `Dt'? I completely agree that having a single manpage for an entire library isn't the best form, but it happens. Plenty of other systems (see above) do something similar for an index style page. The point of the book is to be practical with what people tend to do while encouraging `good usage'. I'm guilty of doing this with systems when the API changes and it's too much work to chase down adding, removing, or renaming associated manpages. All that said, I have added a paragraph that warns against the trade-off of easier manpages (one file) and having a user grep through the page to find their function. Which sucks. > Unfortunately, manpages.bsd.lv is full of bogus advice in general. > Just as an example, just on this individual page: Ok, `bogus' is kinda harsh--but regardless, if it's wrong, it needs to be fixed. That said, I'm more than happy to pick this up and give it a fat update. > - libraries are not usually in /usr/local, but in /usr[/*]/lib Fixed. > - filenames rarely end in .so, libraries are usually versioned Fixed and also mentioned .dylib and .la. > - bogus name in .Dt Ok, see above. What's an appropriate Dt for a manpage documenting a library: the library name or an arbitrary function? > - .Nd should not be "generic", but concise and precise; Changed to note that the description was changed to describe both functio= ns. > - the first .Nm wins, not the last one Fixed. > - 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 I added these possibilities--though again, the point of the book is to lay out some practical guidelines, not act as a survey. > - wrong order in the SYNOPSIS; the correct order would be > .In hello .Fo hello .In hi .Fn hi Fixed! > - 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) Fixed simply to say "which may be NULL". > - it's obvious that a void function does not return a value Fixed, and noted that void returns need not be mentioned. > - hello()'s return values are ill-designed Eh... it was just an example. > - missed opportunity to show .Rv Nope. The function returns 0, not -1, and does not set errno. But I've noted it. > 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. If you post errors in the document to here, I can fix them as done above.= I also fixed the links to manpages on mdocml.bsd.lv, which have changed since writing the book. I'll get these pushed to the main site soon! Best, and thanks for looking this over, Kristaps --tjTkp2I09TTKhXqNNqCp51Oe9wK71JSpD-- --mSgi006hrpnwPjiXVBsET6Hmq6EVL37hk Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Comment: GPGTools - https://gpgtools.org iQIcBAEBCgAGBQJW8pjKAAoJEMT2SUY9XBES4BoP/0Y3ELKyN4oMXg7jNm6d9kEZ 4eb8zyCsgxTh/h5DH6Qb6Vj2mz2xXGB04w5U0Hpo+4dg/D7lU/kHlBrROEDXxVTu 09a6kjt+YQjFwm3E2unDrUkYIoEcAvORopz8YWSFU6Y3fMNAicwEQhfThDeV2QiB frSlQx0e33YAfqKH+xAS50t2xubPRPUHvD/23OVSAv3/Dps6B31TeM02G6YkinEr Y/ZkCBJ5dsiJrvBiQ2SgnEutwSgdyi5wihOs2BrQVS45/XgiGohyC8LdatmTxGXT bEYGNfsht3VMl9pExyoM7fFeNCZcOxGRE3O/xXMU34RFbNdx+7P7B5N8rF+axLE2 nA3xfu8rWQP/MsUa0RDMOL02cvJLi5ySiMou5i/5wPn1BgpiV0vi2MryOdBLM1fh wMU6wrGLtbI0FpK0bVXUlUtBGiTgmFGU4mNfBVWqtSaXVGxuMc0iqKFcDUch2mXK gZMC1ioqKkJ9lYajnZW+ld0LM4onzPUnCOa1qkfj8mLR9jn3K2wI1lSrTINShPQm EfM0pDSREuX8v7hKNYm+EJrU7C6iPpP+wXP+AYnEXE3O9blNdcqfjo0Ym0onDN2w FFJR5qZg4N6Vb++c+LAwqB9zflbnz+Hsy1MPP1u5rYTgUT0w72iq1QSJy2NJIzM2 w1o5Dr+7fq5c63hgBbUZ =kAXr -----END PGP SIGNATURE----- --mSgi006hrpnwPjiXVBsET6Hmq6EVL37hk-- -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv