Proposed: resequence arguments of groff ms(7)'s new `XR` macro

"G. Branden Robinson" <[email protected]> Mon, 11 May 2026 11:38:03 -0500

Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20260511163803.joak5nvsiwbdxrgk@illithid>

Subscribers to groff-commit and rabid Git pullers will have already
noticed that the long-desired integration of PDF support features into
groff ms(7) has landed in the master branch.

This was Deri's work--terrific stuff!

As often happens, I see adjustments I'd like to make.

Here's the synopsis of the new `XR` macro for internal document
hyperlinks (the references/hotspots, not the destinations/anchors).

.XR name [after [before [hotlink-text]]]

I find this ordering of arguments a bit surprising.

Can I propose this instead?

.XR name [link-text [after [before]]]

I think this ordering is (1) more consistent with existing ms(7) macros,
including the admittedly awkward "after before" sequencing arising from
Lesk lacking a crystal ball in the late 1970s, and (2) loads the more
frequently used arguments toward the "front" of the call.

For example, here are the occurrences of `XR` calls in our own
"doc/ms.ms.in", which Deri updated alongside his code changes.

doc/ms.ms.in:463:.XR RP "" "" "(see below)"
doc/ms.ms.in:488:.XR doc-control "" "" "See section \*[Q]Document control settings\\*[U]"
doc/ms.ms.in:499:.XR doc-desc "" "" "See section \\*[Q]Document description macros\\*[U]"
doc/ms.ms.in:520:.XR body-text "" "" "See section \\*[Q]Body text\\*[U]"
doc/ms.ms.in:546:.XR RP "" "" RP
doc/ms.ms.in:576:.XR RP . "" "\f[CR]RP\f[]"
doc/ms.ms.in:1186:.XR lists "" "" +
doc/ms.ms.in:1361:.XR XR "" "" \f[CR].XR\f[]
doc/ms.ms.in:1514:.XR XR "" "" \f[CR].XR\f[]
doc/ms.ms.in:4111:.XR RP ) "" \f[CR]RP\f[]
doc/ms.ms.in:4130:.XR NH "" "" NH
doc/ms.ms.in:4132:.XR SH "" "" SH
doc/ms.ms.in:4135:.XR head ")." "" Headings

We see that the (hot)link-text argument is used in _every_ case, yet is
stuck way out at the right end as the fourth parameter.

The "after" argument is used 2/13 times.

The "before" argument is not used at all.

I think we can improve the user experience by resequencing the
arguments as suggested above.

Thoughts?  Objections?

Regards,
Branden

signature.asc (application/pgp-signature, 833 B)