Re: MR macro 4th argument (was: [PATCH] Various pages: SYNOPSIS: Use VLA syntax in function parameters)

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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 3


Having '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


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux