Re: [PATCH v2 2/9] regex.3: improve REG_STARTEND

[G. Branden Robinson]

Hi Alex,

At 2023-04-21T00:29:12+0200, Alejandro Colomar wrote:
> On 4/20/23 20:33, G. Branden Robinson wrote:
> > [Note for non-mdoc(7) speakers: `Sx` is its macro for (sub)section
> > heading cross references.  man(7) doesn't have an equivalent, though
> > if there is demand, I'm happy to implement one.  :D]
> 
> I've been delaying my global switch to non-shouting sexion headings,
> due to not having a clear idea of how to refer to them.

Fair.

> Having a macro that does that for me, and ensures that the appropriate
> formatting is applied might be a good solution.

Well, I have three ideas.

1.  Mark them up the way the groff man pages do, in typographer's
    quotes.

See \[lq]Match offsets\[rq] in
.MR regex 3 .

2.  I could implement the `Q` quotation macro for man(7) that I've been
    making noise about for a while.[1]  Of course, you'd be waiting for
    the next release _after_ groff 1.23.0 for it...

See
.Q "Match offsets"
in
.MR regex 3 .

3.  I could implement a macro explicitly tuned to the problem of
    (sub)section cross references.  I didn't see anybody come up with a
    good way to shoehorn this functionality into `MR`, so I suggest the
    following.

.SR section-or-subsection-title [page-topic page-section [trailing-punct]

See
.SR "Match offsets" regex 3 .
.
Also see
.SR Bugs
below.

In this design, if argument 2 is present, argument 3 is mandatory.

The foregoing would render as

       See “Match offsets” (regex(3)).  Also see “Bugs” below.

On devices supporting hyperlinks, "Match offsets" would be a hyperlink
with a to-be-determined anchor reference.  "regex(3)" would be a
hyperlink as with the `MR` macro today.  "Bugs" would be a hyperlink
with a to-be-determined anchor reference within the current document.
(OSC 8 support for this may require some thought, or maybe we'd just
handle them like external page references.)

I trust the tradeoffs involved with each of the above solutions are
readily apparent.

> It would also please the info(1) people, so that the few references we
> have to those would be linked.

What's the URL format for hyperlinks into Info documents?  How is the
existing .UR/.UE inadequate?

Regards,
Branden

[1] https://mail.gnu.org/archive/html/groff/2022-12/msg00078.html

signature.asc
Description: PGP signature