Re: Why does man(7) have 3 paragraph macros for the same thing?

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 4380 bytes --]

Hi Ingo,

On Thu, Oct 26, 2023 at 07:52:13PM +0200, Ingo Schwarze wrote:
> 
> I consider this a bikeshed discussion.

Sure.  But someone has to design the bike parkings.  I find a lot awful
bike parkings that harm bike's wheels, and have to park it in a sign or
tree nearby.

> 
> Given that Branden apparently wants to
>  * promote .P and deprecate .PP
>  * i don't want mandoc_man(7) to gratuitiously spread any more bad
>    man(7) style advice than is unavoidable by the fundamental decision
>    of declaring the whole man(7) language as obsolete,
> i briefly considered changing mandoc_man(7).
> 
> Currently it says:
> 
>   PP  Begin an undecorated paragraph.  The scope of a paragraph is closed
>       by a subsequent paragraph, sub-section, section, or end of file.
>       The saved paragraph left-margin width is reset to the default.
> 
>   LP  A synonym for PP.
> 
>   P   This synonym for PP is an AT&T System III UNIX extension later
>       adopted by 4.3BSD.
> 
> and it declares LP and P deprecated by including only PP in the
> MACRO OVERVIEW.
> 
> All the arguments feel weak in either direction:
> 
>  * In theory, .PP is more portable than .P, but that is extremely
>    unlikely to ever matter in practice.
>  * As seen above, the similarities and subtle differences
>    when comparing to ms(7) can be employed as arguments in either
>    direction.
>  * The arguably more important similarity that HTML defines a <p>
>    but not a <pp> element can be regarded as a learning aid,
>    but it's still a weak argument because HTML and roff(7) are
>    very different domains and not similar in most other respects.
>  * The similarity of .P and <P> can also be turned around to be
>    levied as an argument for .PP:  .P and <P> are *very different*
>    in so far as <P> is a block element, whereas .P is an in-line
>    macro that cannot participate in block nesting.  In particular,
>    it can neither nest inside a list item, nor can anything be
>    contained inside a .P syntax tree node.  In contrast to <p>,
>    .P does not represent a *paragraph*, but only a paragraph *break*.
>  * .PP is more similar to mdoc(7) .Pp.  Again, a weak argument because
>    macro naming is totally different in both languages even in most
>    of the few cases where functionality matches, with the exception
>    of only .SH and .SS.
> 
> Consequently, i tend to leave mandoc_man(7) just as it is and not
> repaint the bikeshed.  That way, the original .PP macro - with which
> nothing is really wrong, except for the fundamental design mistake
> of not being a block macro, a mistake it shares with mdoc(7) .Pp -
> gets the full description, while the slighly younger .P gets the
> compat info, even though that now is only of historical but not
> of practical interest.  Maybe still nice to keep both apart - gee,
> yet another weak argument.
> 
> If, for some reason, you feel strongly about it and think it is
> important which one to promote, it might be possible to convince me to
> deprecate .PP and list .P as the non-deprecated form even though it
> is theoretically less portable.  I must admit i don't particularly
> like the idea, though.  It feels like taking a gratuitious risk,
> which does not feel ideal even if both the magnitude of the risk
> and the benefit reaped are almost exactly zero.

I don't think there's any urgent need to change mandoc_man(7), since
good quality man(7) pages should not even read that page.  I see it as
a quick guide if you're in a mandoc(1) system and need to fix a man(7)
bug or something.  If you're going to write new man(7) pages, you
probably want to read groff_man(7).

But I think having 3 ways of spelling PP is bad, and I think deprecating
at least LP, and possibly one of P or PP would be a good move.

For making sure pages are fixed, we could an a warning that gets
triggered always, so that projects have time to catch the change.

As for chosing P or PP: I don't mind very much which, but P seems
slightly better.  Since both are relatively widespread, and I can help
turn the balance in favour of any of them, I'll side with groff(1)
using and recommending P.  But yeah, it's a very arbitrary decission
between P and PP.

Cheers,
Alex

> 
> Yours,
>   Ingo

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]