a straw-man `SR` man(7) macro for (sub)section cross references (was: [PATCH v2 2/9] regex.3: improve REG_STARTEND)

[G. Branden Robinson]

[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:

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

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.

Regards,
Branden

signature.asc
Description: PGP signature