[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

a straw-man `SR` man(7) macro for (sub)section cross references (was: [P

From: G. Branden Robinson
Subject: a straw-man `SR` man(7) macro for (sub)section cross references (was: [PATCH v2 2/9] regex.3: improve REG_STARTEND)
Date: Fri, 21 Apr 2023 03:06:07 -0500

[self-follow-up; updated subject]

At 2023-04-21T00:07:21-0500, G. Branden Robinson wrote:
> 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]

On second thought, I think it would be better to have matched brackets
here.  And more seriously, to permute the argument order to feel more
parallel to `MR` (as well as `ME` and `UE`).

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

Updating the example:

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

In this design, if argument 3 is present, argument 4 is mandatory.  This
would need to be a pretty hard requirement.  Maybe the default section,
if unspecified, would be "UNKNOWN".  This is rude but doesn't penalize
the user any more than the document author does.  (There is also
precedent in mdoc(7)'s setup macros.)  We don't want to `ab`ort page
rendering for these errors because that will adversely affect innocent
users who are simply trying to read documentation.

The foregoing would render as

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


Attachment: signature.asc
Description: PGP signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]