Re: `\c`, mdoc(7), and man(7) extension macros (was: [PATCH 1/2] man*/: srcfix)

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

On Thu, Oct 26, 2023 at 07:58:35AM -0500, G. Branden Robinson wrote:
[...]
> 
> And mdoc _does_ manage to make `\c`
> almost(?) totally unnecessary--at the cost of a weighty internal
> recursive macro reprocessing system that no other *roff package is known
> to implement.
> 
> (This is what that "parsed"/"callable" stuff in groff_mdoc(7) (and
> mandoc_mdoc(7)) is all about.  Also, by "weighty", I mean it--back in
> ~1990, when mdoc was implemented, its documentation warned the reader of
> its slowness.  Fortunately, on modern systems, the rendering latency
> relative to man(7) is no longer noticeable.)
> 
> Even with performance considerations out of the picture, I think such a
> system is a point against adoption of mdoc; one can observe that,
> nowadays, both man(7) and mdoc require a person to acquire knowledge
> that they will "never" transfer anywhere else, assuming no resurgence in
> *roff popularity.  But the point is _even more true_ of mdoc than it is
> of man(7), by dint of the recursive macro reprocessing feature and the
> funny requirements that become necessary as a consequence (you have to
> use `\&` in more places; you have to break up individual punctuation
> characters when using them as macro arguments if you want them to work
> right).  In other words, learning mdoc doesn't help you learn *roff all
> that much.  Not as much as man(7) does.  And it doesn't help you learn
> any other programming/documentation system anywhere.
> 
> Plus, in mdoc, there is a much larger lexicon of macros to learn in the
> first place.  I count 115.

Yup.  I have similar feelings about C++, BTW.  I have a hard time
understanding complex languages.  I prefer simpler languages.  Most
features can be implemented as library code, without complicating the
language.

[...]

> > 
> > For consistency with the above two cases, I think you should move that
> > (\c to a new line.  It also reduces the diff (semantic newlines any?)
> > :)
> 
> Well, okay.  I'll roll a v5.
> 
> By the way, even the diffless version of 2/2 (the actual `MR` migration)
> got canned by vger.  Even just the diff --stat blows past the 100,000
> byte limit.  But you should have a copy in your inbox, and the sed
> script is what does the real work of 2/2 anyway.

Yep, I have 2/2 locally.  Maybe reply to the mail CCing vger, keeping
only the commit message, so that readers of the list can get a notice of
what MR.sed is.

> 
> Regards,
> Branden
> 
> [1] It _would_ be nice if these all ended in `S` and `E`, respectively,
>     for "start" and "end".  Alas, there is historical baggage here,
>     which Doug McIlroy, author of the original man(7) macros and of the
>     latter Ninth Edition Unix `EX`/`EE` extension, recently lamented.
> 
>     https://lists.gnu.org/archive/html/groff/2023-09/msg00058.html
> 
>     We _could_ fix all the outliers, save one, without collision.
> 
> 	EX -> ES (example start)
> 	MT -> MS (mail-to start)
> 	UR -> US (URL start)
> 	YS -> SE (synopsis end)

I always make the mistake of writing MS instead of MT, out of inertia of
having an 'S' for the start!  :D

The others have nicer mnemonics that work for me; I wouldn't change
them.  And well, just for changing MT, I wouldn't do it.

> 
>     The oddball is `SY`.  We can't rename that to `SS`, which is already
>     a subsection heading macro.  But we could rename _both_ synopsis
>     macros.
> 
> 	SY -> NS (syNopsis start)
> 	YS -> NE (syNopsis end)

Hmmm, no; I don't like it.

> 
>     I'm game for any of these reforms, if people think it's worth it.
>     The old names can be kept for backward compatibility for as long as
>     necessary (but de-documented).  I _assume_ there's too much inertia
>     for this.

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.


Cheers,
Alex

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

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