[bug #64202] [man-pages]: groff_man(7) inconsistently (and redundantly) guards some .MR references with '\%'

[G. Branden Robinson]

Update of bug #64202 (project groff):

                Category:               Macro man => General                
              Item Group:                    None => Documentation          
                  Status:                    None => Need Info              
             Assigned to:                    None => gbranden               

    _______________________________________________________

Follow-up Comment #1:

Hi Keith,

I'm aware of this.  It's deliberate insofar as it's a consequence of other
decisions.

The main facts are these:

1.  The new `MR` macro unconditionally prefixes its first argument with a `\%`
escape sequence to suppress hyphenation.

2.  All of _groff_'s man pages (.[157]) files are produced in the build tree
from from .man inputs.

3.  The reason for that is that man page content is partially dynamic.  The
redundancy you're observing is the result of the "@g@" character sequence
being replaced by the ./configure-d command prefix in use by the build.  By
default, and in many build scenarios (of those I've seen personally, all
except for Solaris), this prefix is empty.

4.  @g@ is expanded in several contexts, not just the first argument of `MR`. 
Wherever it occurs, it is part of a literal to which we do not want automatic
hyphenation to apply.

5.  Therefore in some cases you get doubled `\%`s.

In the short term (that is, groff 1.23.0 final), I don't think there is
anything that can be done to correct this without frustrating the objective in
#4 above, or without increasing the number of magic character sequences that
get replaced in man pages ("@g@" and "@gmr@"?).  I'm not sanguine about the
latter as a solution because I think it will increase the man page maintenance
burden.  People will forget or fail to learn which sequence to use, and use
the wrong one.  (I include myself in that set, because when confronted with
complex systems, I forget things.)

> specifying such a guard in the macro call imposes an unnecessary burden on
any macro implementation which constructs, for example, a PDF external
reference based on the MR macro arguments, because the generated reference
address must be passed through a sanitizer routine -- an unnecessary overhead,
when MR already prepends the '\%' in running text.

There are two things to note with respect to the above challenge.

A.  You do not _need_ to sanitize content destined for device control escape
sequences (or the `device` request) of the `\%` escape sequence.  The
formatter will ignore this escape sequence in that context, skipping over it
without diagnostic, and it will not appear in the "x X" commands that GNU
_troff_ produces.  This is already the case in groff 1.22.4 and therefore I
suspect it's been true for many years.

$ printf '\\X@ps: foo\\%%bar@\n' | troff | grep 'x X'
x X ps: foobar

B.  I've noticed that operations like sanitizing a string (/macro/diversion),
or iterating over one for any reason, is hell on wheels.  (I got my taste of
this when implementing ellipsis-ification of man page headers and footers to
resolve bug #43532 and bug #62257.)

Therefore I have proposed (and
[https://lists.gnu.org/archive/html/groff/2022-12/msg00133.html I've mentioned
this on the _groff_ list], to no response so far), adding a request to do
exactly this: iterate over strings (macros, diversions).  To do this right,
especially for diversions, will likely require additional
conditional-expression predicates, because an item in a diversion can be
something that does not exist in the formatter's input language (namely, a
"node", but I do not yet know if there are other such ineffable data types one
can encounter--I expect to find out upon attempting an implementation).

See bug #62264.

What do you think?


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?64202>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/