The only man page we have that doesn't enter compatibility mode (neqn)
also doesn't use any sed-substituted patters where characters replaced
by a \[] special character escape form are likely to be used.
The @g@ command prefix is the main avenue for intrusion, but I think it
improbable that many people are going to include apostrophes, double
quotes, carets, grave accents, or tildes in the command prefix; some or
all of these will pick fights with the shell and require quoting that we
don't represent in man page text anyway.
On top of that, neqn is largely a stub page.
If it's a problem, the better fix is to simply make neqn switch out of
compatibility mode like all our other man pages.
...and rename "hyphenless [discretionary] break" to "non-printing break
point" in documentation.
In spite of my discomfort at learning this fact, I decided not to try to
change groff's behavior because (1) frankly, doing so looked challenging
in the implementation and (2) it occurred to me that, for those
circumstances in which the present behavior is desired by the user, the
mechanism of recovering it would be _even more_ challenging. Keeping in
mind that requests and escapes are "assembly language for typesetting",
I'm leaving the language alone and adapting to it. The pattern '\:\%'
will be unambiguous to locate and easy to change later if someone has a
brighter idea.
* doc/groff.texi (Manipulating Hyphenation): Rename "hyphenless break"
to "non-printing break point". Clarify that it is the soft hyphen
glyph, not necessarily a hyphen, that is ordinarily written to the
output on hyphenation breaks. Note that the remainder of a word after
\: is subject to hyphenation as normal. Note (new) '\:\%' idiom for
getting what people will want at least some of the time. Update
example to use it.
* makevarescape.sed: Insert \% after we insert \: to rewrite slashes in
filenames, to protect later portions of the filename from hyphenation.
* man/groff.7.man (Escape Sequences/Escape short reference): Rename
"hyphenless break" to "non-printing break point".
* man/groff_diff.7.man (Language/Escape sequences): Resync with our
Texinfo manual.
* tmac/groff_man.7.man.in (Description/Hyperlink and email macros):
Rename "hyphenless break" to "non-printing break point". (The
examples did not need updating because the macros already disable
hyphenation--too aggressively as it turns out, but that's a different
change set...)
* makevarescape.sed:
+ Escape plain spaces and double-quotes (ASCII 32 and 34) so
that bad things don't happen if they are embedded in a Make
variable expanded in a man page @THUS@ _and_ given as an
argument to a macro that distinguishes its parameters, such
as .IR.
+ Add discretionary breaks after groups of slashes not
preceded by a space; e.g., transform "/usr/bin/groff" into
"/usr/\:bin/\:groff". Will also work on URLs
("https://\:example.com/\:page.html") in case we need that.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
* makevarescape.sed: Transform - to \-, ~ to \(ti, and so forth,
(with an extra layer of backslashes--see below) so that Makefile
variables containing ASCII characters that do not represent
themselves literally in *roff (see groff_char(7)) are correctly
interpolated into man page text.
* Makefile.am (.man): Transform Makefile variables with the
above script when interpolating them into man page text.
Note that while the script, combined with this target, will
transform ` to \(ga, including grave accents in Makefile
variables is likely to fail when the shell lexes the argument to
echo within the old-style command substitution ``. Testing
shows that grave accents should work[1] if POSIX-style command
substitution $() is done instead. However, $() is less
portable. (Triple-escaping grave accents \\\` inside the
interpolated Makefile variable will work, but is not attempted
at present.)
Note also that the amount of backslash-escaping in the sed
script is excessive (and incorrect) for normal purposes, but
required here because a command substitution is being nested
inside yet another invocation of sed.
[1] For this target; no assurances about the good behavior of
unusual characters in Makefile variables in other aspects of the
groff build are offered.
Fixes <https://savannah.gnu.org/bugs/index.php?55004>.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
