Re: MR macro 4th argument (was: [PATCH] Various pages: SYNOPSIS: Use VLA syntax in function parameters)

[G. Branden Robinson]

At 2022-11-11T00:55:18+0100, Alejandro Colomar wrote:
> Hmm, will need to parse that.  Anyway, I think now that I have the MR
> with 4 arguments, moving the 4th to the previous line with sed and N
> should not be that difficult.

Okay.

> Well, being a compatible extension to the others is not that bad.  How
> does mdoc(7) solve it with Xr?

I alluded to it: the `Pf` ("prefix") macro.

man(7):
.TH foo 1 2022-11-10 "groff test suite"
.SH Description
pre-\c
.MR exec 3

mdoc(7):
.Dd 2022-11-10
.Dt foo 1
.Os "groff test suite"
.Sh Description
.Pf pre- Xr exec 3

> One of the biggest issues with this is that it breaks what would
> otherwise represent a single entity, into two lines, so it hurts
> readability.  See as an extreme example the following change I did
> with my scripts (from posix_spawn(3), if you're curious):
> 
> @@ -129,7 +129,7 @@ .SH DESCRIPTION
>  Below, the functions are described in terms of a three-step process: the
>  .MR fork 3
>  step, the
> -.RB pre- exec ()
> +.MR exec 3 "" pre-
>  step (executed in the child),
>  and the
>  .MR exec 3
> 
> Having 'pre-' as the last part of some random line, separates it from the
> other part of the word.  The \c alternative would be:
> 
> step, the pre-
> .MR exec 3
> step ...
> 
> Not terrible, but I'm not in love with it.

I personally find the derangement of word ordering more disruptive to my
reading than a mid-word line break...especially after a hyphen, where
years of experience have prepared me to expect a continued word on the
next line anyway.  ;-)

I would also note that I don't think it's necessary to hyperlink every
single occurence of a cross-referenced man page topic, especially if the
same page topic comes up repeatedly in a section (or even paragraph).
IIRC Ingo doesn't agree, and you might too.

> I hope I can come up with something, but yes, if not, I'll call you ;)

My bat-shaped phone is plugged in.

> BTW, so far I've never found a case where I had to use the hold space.
> I wonder if I may meet a case where I need it in my life.  This week I
> came up with some script for inserting an element into a JSON array at
> a specified position, but N is all that was needed:
> <http://www.alejandro-colomar.es/src/alx/nginx/unitcli.git/tree/bin/setup-unit#n969>.

Multi-line patterns solve a lot of problems.  A person knows that they
are no longer a sed(1) beginner when they use those effectively.  :D

> I've met a few more-complex cases, but not really that much.  I always
> come up with some combination of filters that allows me to avoid the
> hold space.  Sometimes, two scripts run consecutively also helps keep
> it simple :)

I've resorted to this too.  It's just that sed is such a small language
(even in its GNU dialect) that it taunts me.  Surely mastering it should
be _easy_...

Regards,
Branden

signature.asc
Description: PGP signature