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
Attachment:
signature.asc
Description: PGP signature
