library name inside 'Lb' macro

library name inside 'Lb' macro

[Svyatoslav Mishyn]

Hello everybody,

should a library name start with 'lib' or not ?


because,
from http://manpages.bsd.lv/part1-3.html :
  In general, a function library should have its name not include the
  leading "lib".

but mdoc(7)'s examples are:
  .Lb libz
  .Lb libmandoc


as discussed previously with Kristaps,
variant from part1-3.html is wrong and needs fixing.


-- 
https://www.juef.tk/
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: library name inside 'Lb' macro

[Ingo Schwarze]

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

Re: library name inside 'Lb' macro

[Kristaps Dzonsons]

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