Follow-up Comment #6, bug #68890 (group groff):

[comment #3 comment #3:]
> Doug McIlroy was also recently bitten by the current behavior, and
> additionally points out a disparity between documentation and behavior that
> should be addressed even if the search path is not changed:
> http://lists.gnu.org/r/bug-groff/2026-11/msg00085.html

In that message, Doug said:

> The GROFF_TMAC_PATH description in troff(1) groff 1.25.0.rc4 says the
home directory is searched only in unsafe mode. Would that this were
true!

The man page doesn't actually say that, but only a comma stands between the
text and misinterpretation.

_troff_(1):

     GROFF_TMAC_PATH
            A list of directories in which to search for macro files.
            troff will scan directories given as arguments to any
            specified -M options before these, then the current
            directory (only if in unsafe mode), the user’s home
            directory, a site‐specific directory (/home/branden/
            groff-HEAD/share/groff/site-tmac), and a standard location
            (/home/branden/groff-HEAD/share/groff/1.25.0/tmac) after
            them.


"(only if in unsafe mode)" _precedes_ a comma, then "the user's home
directory" follows.  Thus "(only if in unsafe mode)" binds to "then the
current directory".

I do not wish to defend the comprehensibility of the sentence beyond that.
"Technically correct" is not necessarily good enough for user-facing
documentation.  (Maybe not for develoer-facing docs, either.)

I'm a strident anti-monarchist, but an inconsistent one because I also hold
that Clarity is King.

Resolving this ticket means I can drop ", the user's home directory" from this
paragraph, and I will do that.  That will bring the complexity of the sentence
housing it down, and, perhaps, it will be clear enough.

If not, we can further recast it, perhaps to use a bulleted list.  My
nefarious `LS` and `LE` _man_(7) macros are mounted on the wall under track
lighting, waiting to be seized and deployed in household combat.


    _______________________________________________________

Reply to this item at:

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

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

Attachment: signature.asc
Description: PGP signature

Reply via email to