Re: library name inside 'Lb' macro

[Ingo Schwarze <schwarze@usta.de>]

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