Hi Branden, On 11/10/22 23:55, G. Branden Robinson wrote:
Hi Alex, At 2022-11-10T19:04:46+0100, Alejandro Colomar wrote:Of course I forgot to rename the title, and to agg groff@. Nice.It gave me time to reply to this one. :)
:) [...]
The big issue is that your MR doesn't support leading text: .MR page‐title manual‐section [trailing‐text] I remember we had this discussion about what to do with it. A 4th argument? There's also conflict with a hypothetical link that we might want to add later. My opinion is that the 4th argument should be the leading text. Asking to use the escape (was it \c?) sequence to workaround that limitation is not very nice. Especially for scripting the change.Here's what I did for groff. commit 2ab0dacb95863a2e347d06cf970676c74c784ce2 Author: G. Branden Robinson <g.branden.robinson@xxxxxxxxx> Date: Fri Oct 8 00:46:41 2021 +1100 [man pages]: Migrate man(7) cross refs to `MR`. # Handle simplest case: ".IR foo (1)". s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\(@MAN[157]EXT@\))$/.MR \2 \3/ s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))$/.MR \2 \3/ # Handle case: trailing puncutation, e.g., ".IR foo (1),". s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\(@MAN[157]EXT@\))\([^[:space:]]\+\)/.MR \2 \3 \4/ s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))\([^[:space:]]\+\)/.MR \2 \3 \4/ # Handle case: 3rd+ arguments or trailing comments. This case is rare # and will require manual fixup if there are 4+ arguments to MR. Use # groff -man -rCHECKSTYLE=1 to have them automatically reported. s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\(@MAN[157]EXT@\))\( .*\)/.MR \2 \3\4/ s/^.[BI]R \(\\%\)*\([@_[:alnum:]\\-]\+\) (\([1-8a-z]\+\))\( .*\)/.MR \2 \3\4/ You can ignore the 'MAN[157]EXT' lines; they are relevant only to within-groff pages (because all of our man pages undergo sed-processing to be prepared for installation).
Hmm, will need to parse that. Anyway, I think now that I have the MR with 4 arguments, moving the 4th to the previous line with sed and N should not be that difficult.
If you want a 5th argument for a URI, you can specify the leading text as "", which is not much of an issue. And you keep the trailing text and the leading one together. What are your thoughts? What should we do?I am reluctant to extend the interface of `MR` at this point because as it is it has two nice properties: it aligns with mdoc(7)'s `Xr` macro and with Plan 9 from User Space troff's `MR`, which did it first.
Well, being a compatible extension to the others is not that bad. How does mdoc(7) solve it with Xr?
(Admittedly, P9US troff's `MR` macro doesn't supply the parentheses. I
don't know if they intend to change that. I'm willing to supply a patch
to change their implementation and their man pages to align with what I
did in groff. As shown above, I believe my sed-fu is in order.)
I think man page authors should learn when the `\c` escape sequence is
appropriate and use it when warranted, and recast their sentences
otherwise. That is why I provided an explicit example in the
groff_man_style(7) page.
.MR page-title manual-section [trailing-text]
(since groff 1.23) Set a man page cross reference as "page-
title(manual-section)". If trailing-text (typically
punctuation) is specified, it follows the closing parenthesis
without intervening space. Hyphenation is disabled while the
cross reference is set. page-title is set in the font specified
by the MF string. The cross reference hyperlinks to a URI of
the form "man:page-title(manual-section)".
The output driver
.MR grops 1
produces PostScript from
.I troff
output.
.
The Ghostscript program (\c
.MR gs 1 )
interprets PostScript and PDF.
One of the biggest issues with this is that it breaks what would otherwise represent a single entity, into two lines, so it hurts readability. See as an extreme example the following change I did with my scripts (from posix_spawn(3), if you're curious):
@@ -129,7 +129,7 @@ .SH DESCRIPTION Below, the functions are described in terms of a three-step process: the .MR fork 3 step, the -.RB pre- exec () +.MR exec 3 "" pre- step (executed in the child), and the .MR exec 3Having 'pre-' as the last part of some random line, separates it from the other part of the word. The \c alternative would be:
step, the pre- .MR exec 3 step ... Not terrible, but I'm not in love with it.
`\c` solves problems that are complicated to solve any other way. As far as I have seen, you don't ever need it in mdoc(7) pages, for example...but you pay a price. You must learn which of mdoc's several dozen macros are "parsed" versus "callable" (and what the heck the package even _means_ by those words); you must learn that `Pf` and `Ns` exist and when to use them; you must learn that certain two-letter words will not behave as you expect; and if you thought using mdoc(7) meant you wouldn't have to type any groff escape sequences, think again--you'll be putting `\&` all over the place. People can use mdoc(7) if they want to (and now that I'm learning it better, I will consult as I am able), but its reputation in some circles as a superior solution to man(7) on all fronts that should have kicked its predecessor into the grave long ago is due solely to irresponsible hype from its exponents. If you need help automating a change to adapt some Linux man-pages documents to use `\c` before an `MR` call on the next line (where you were using `RB` before, for instance), just let know. I am nearly certain that a sed script utilizing its hold space feature can get the job done. (I've used the hold space profitably before, but occasions for it come up seldom enough that I have to review my past solutions before the knowledge comes back. Or maybe it's creeping senescence.)
I hope I can come up with something, but yes, if not, I'll call you ;)BTW, so far I've never found a case where I had to use the hold space. I wonder if I may meet a case where I need it in my life. This week I came up with some script for inserting an element into a JSON array at a specified position, but N is all that was needed:
<http://www.alejandro-colomar.es/src/alx/nginx/unitcli.git/tree/bin/setup-unit#n969>.I've met a few more-complex cases, but not really that much. I always come up with some combination of filters that allows me to avoid the hold space. Sometimes, two scripts run consecutively also helps keep it simple :)
Cheers, Alex
Regards, Branden
-- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
