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