On Monday, 11 May 2026 17:38:03 BST G. Branden Robinson wrote: > 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
Hi Branden, It makes a lot of sense. Just remember that link-text is not compulsory either, here's the calls in the new Groff-PDF-Features.ms:- [derij@pip build (master)]$ grep "^\.XR " ../doc/Groff-PDF-Features.ms .XR naming ). ( .XR naming ). ( .XR XR "" "" "\&.XR command" .XR bookmarks "" "" bookmarks .XR hotspot ). ( .XR hotspot ). ( .XR hotspot ). ( .XR external "" "" external .XR naming . "" * .XR naming ). ( .XR expandochars "" "" * .XR expandochars "" "" expandos .XR intro ), ( .XR external ), ( .XR prefix ). ( .XR expandochars "" "" Expandos .XR hdexample ) ( .XR hotspot "" "" * .XR naming "" "" * .XR bookmarks "" "" \fB.pdfbookmark\fP .XR naming . "" + .XR hotspot . "" + .XR external . "" + (which has 10 examples where link-text is not given (using the default), and 8 where neither after or before are given). If link-text is missing the value of \*[spdf:txt_default] is used, which defaults to "see: +" (so the expansion character will receive the text from the named section). So you could replicate the texinfo style of link (minus the page number) by setting the register to "See section: +" and using calls:- .XR name ] [ I can see advantages with both parameter orders. Cheers Deri
