Re: Why does man(7) have 3 paragraph macros for the same thing? (was: `\c`, mdoc(7), and man(7) extension macros)

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

On Thu, Oct 26, 2023 at 09:51:40AM -0500, G. Branden Robinson wrote:
> At 2023-10-26T16:12:36+0200, Alejandro Colomar wrote:
> > Regarding PP, LP, and P, what's the history of them?  Why do we have
> > the 3?  I'm willing to reduce them to just one.
> 
> I invite Doug McIlroy to go on record, but my surmise is that they were
> introduced as crutches for people already familiar with ms(7).
> 
> Doug's original man(7) (1979) didn't have `P`.  But Unix System III
> added it in 1980, and 4.3BSD followed suit in 1986.  This information is
> in groff_man(7).

Was the original PP?

> 
> In ms(7), `LP` sets a paragraph that is left-aligned, and `PP` sets one
> with a first-line indentation.
> 
> In man(7), all (ordinary) paragraphs behave analogously to ms(7)'s `PP`.
> A first-line indentation is never used.
> 
> My opinion is that one should use `P` exclusively for a few reasons.
> 
> 1.  Its name is short and it is frequently used.  Huffman coding FTW.
> 2.  The existence of both `LP` and `PP` is difficult to rationalize to
>     anyone except a seasoned ms(7) author, of whom there are almost none
>     writing man(7) documents today.

Still, compatibility with ms(7) would make it slightly easier to
trasnfer learning from man(7) to ms(7), would one learn it.  I know many
other macros are incompatible in bad ways, but the less the better, no?

Cheers,
Alex

> 3.  It's been around long enough that everything supports it.  `LP`/`PP`
>     have no measurable advantage in this respect.  Anyone running early
>     BSD in 2023 has more interesting things to do than the composition
>     of legacy man pages.
> 
> Incidentally, mm(7) would have already had a `P` macro as well by 1979.
> Its call syntax is different (it interprets arguments; ms(7)'s and
> man(7)'s "plain" paragraphing macros do not).  Maybe this, and/or some
> friction between Bell Labs Research and the constantly reconfiguring
> series of departments dedicated to deriving revenue from Unix (and
> troff) commercially accounts for man(7)'s omission of it.
> 
> Nowadays, we can be confident that no loon is going to do something
> crazy with mm's `P` macro such that it would trip up man(7) writers.
> 
> <an evil grin spreads slowly across my face>
> 
> Regards,
> Branden



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

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