Re: library name inside 'Lb' macro

[Kristaps Dzonsons <kristaps@bsd.lv>]

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