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

G. Branden Robinson
2022-11-11T04:46:47Z

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

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

[-- Attachment #2: signature.asc --]