discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Kristaps Dzonsons <kristaps@bsd.lv>
To: discuss@mdocml.bsd.lv, Svyatoslav Mishyn <juef@openmailbox.org>
Subject: Re: library name inside 'Lb' macro
Date: Wed, 23 Mar 2016 14:23:22 +0100	[thread overview]
Message-ID: <56F298CA.7040501@bsd.lv> (raw)
In-Reply-To: <20160322150005.GJ10862@athene.usta.de>


[-- Attachment #1.1: Type: text/plain, Size: 3798 bytes --]

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 functions.

>  - 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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 842 bytes --]

      reply	other threads:[~2016-03-23 13:23 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-03-14 14:13 Svyatoslav Mishyn
2016-03-22 15:00 ` Ingo Schwarze
2016-03-23 13:23   ` Kristaps Dzonsons [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=56F298CA.7040501@bsd.lv \
    --to=kristaps@bsd.lv \
    --cc=discuss@mdocml.bsd.lv \
    --cc=juef@openmailbox.org \
    --subject='Re: library name inside '\''Lb'\'' macro' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).