Hi Ralph, At 2022-05-02T09:42:12+0100, Ralph Corderoy wrote: > Hi Branden, > > > At any rate, groff_man(7) in groff 1.22.4 does in fact cover this. > ... > > \& Zero-width space. Append to an input line to prevent > > an end-of-sentence punctuation sequence from being > > recognized as such, or insert at the beginning of an > > input line to prevent a dot or apostrophe from being > > interpreted as the beginning of a roff request. > > This is from the notes on portability.
That's correct. This change is about five years old.
commit 428b822f36474d334778d8f3f745ba4dea0d47cf
Author: Ingo Schwarze <schwa...@usta.de>
Date: Mon Aug 28 23:40:56 2017 +0200
groff_man(7) manual page: recommendations for escape sequences.
See bug at https://savannah.gnu.org/bugs/?51021.
[...]
.TP
.B \e&
Zero-width space.
.
Used for different kinds of escaping, for example after abbreviations
that occur at the end of an input line to prevent misinterpretation
of the final dot as a full stop ending a sentence, or before an
apostroph or dot at the beginning of a text input line to prevent
misinterpretation as a macro line, for example:
.sp
.EX
The
\&.B .gcolor
request supports several color names, e.g.\e&
\e&'green', by default.
.EE
I've edited this material since then. Given your remarks quoted below,
you may wish to perform a comparative word count[1].
> It seems odd have yet more definitions of the escape sequences here
> rather than just listing the sequences and leaving them to be
> explained elsewhere.
The motivation was spelled out in the NEWS file for groff 1.22.4,
released in December 2018.
[[
o Much work has been done, and is ongoing, to make groff's man pages
better examples for man page writers to follow. groff_man(7) itself
has been expanded and largely rewritten to more precisely document the
macro package's behavior and to be more helpful and accessible to man
page writers who may never read any other groff documentation.
]]
Experience has shown that "never reading any other groff documentation"
is something that man page authors are particularly likely to do. On
the one hand, we're lucky if they peruse groff_man(7) at all, and on the
other, the limited feature set exposed by the man(7) macro package means
that there is much about the *roff language that a man page author need
never acquire--if they aim never to turn it to any other purpose.
> > In groff 1.23.0, this material will move to groff_man_style(7),
> > since groff_man(7) is meant to slim itself down to a reference for
> > the macro package proper, and not cover *roff language fundamentals.
>
> groff_man_style doesn't sound like it should be covering ‘language
> fundamentals’ either.
See above. In fact I still have it on my to-do list to add--in as terse
a form as I can manage--an introductory subsection explaining terms like
"filling" and "break" since novice man page authors often have not been
exposed to them. I haven't yet done it because the same material is
now covered in our Texinfo manual and in roff(7); I'm torn between
adhering to my rigid principle of groff_man_style(7) being a one-stop
shop even for readers lacking knowledge of typesetting fundamentals, and
avoiding duplication of material and extension of an existing page.
> > Our Texinfo manual is similarly expanded.
>
> Expansion is not necessarily good as it can easily worsen the
> noise-to- signal ratio.
Does it here? If you have a concrete example to name, please do so.
Otherwise your comment is merely hectoring, as is...
> Over the years, repeated advice from Bell Labs on good technical
> writing has been to first absorb Strunk and White.
Over the years, the tenor of your feedback to my contributions to groff
has been uniformly negative. As you are an outlier in this regard[2],
perhaps you'd care to characterize your problem with my work in a manner
more "direct and vigorous" than you've shown to date.
A fortiori, to non-specifically cite a well-known work as an implicit
derogation of a person's efforts is unproductive, and encourages them to
waste time second-guessing their output with hazy notions rather than
focussed revision, applying concrete goals.
I invite you to review groff's Git history (or subscribe to the
groff-commit list), note the number of times the phrase "tighten
wording" has appeared in one of my commit messages, and see for yourself
whether I have in fact done so. Where I add documentary material, I
present the rationale for its presence--if I fail to do so, I welcome
correction on that point.
Gesturing vaguely at S&W does no one else any good. I could just as
well say:
"Many people have found their way to a better life through the gospels."
...see how condescending that is?
Regards,
Branden
[1] ...though I don't think it would hurt to restore Ingo's example or a
similar one; the new groff_man_style(7) page allows itself room for
such things.
[2] For instance, Ingo and I occasionally argue fiercely (to the
entertainment of some list subscribers), but that's no barrier to
our mutual respect and collaborative efforts[3]. What prevents you
from working with me in a similar way?
[3] groff 1.23's doc/doc.am will be better organized and more
comprehensible than 1.22.4's, and the build process overall is going
to be more parallelizable due to our recent and pending work.
signature.asc
Description: PGP signature
