discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Svyatoslav Mishyn <juef@openmailbox.org>
Cc: discuss@mdocml.bsd.lv
Subject: Re: library name inside 'Lb' macro
Date: Tue, 22 Mar 2016 16:00:05 +0100	[thread overview]
Message-ID: <20160322150005.GJ10862@athene.usta.de> (raw)
In-Reply-To: <20160314141328.GA1353@k8>

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

  reply	other threads:[~2016-03-22 15:00 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 [this message]
2016-03-23 13:23   ` Kristaps Dzonsons

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=20160322150005.GJ10862@athene.usta.de \
    --to=schwarze@usta.de \
    --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).