[groff] 13/30: [docs]: Note annoying portability land mine.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5d746e5747d8025b403666c88385740facde4779
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Mar 30 23:23:51 2024 -0500

    [docs]: Note annoying portability land mine.
---
 doc/groff.texi.in    | 17 +++++++++++++++++
 man/groff_diff.7.man | 26 ++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 02e1a2f1e..40943f0f8 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -17737,6 +17737,23 @@ automatic hyphenation mode to the value of the 
@code{.hydefault}
 register; the @acronym{AT&T} implementation sets it to @samp{1}, which
 is not suitable for some languages, including English.
 
+GNU @command{troff} handles the dummy character @code{\&} differently
+from @acronym{AT&T} @command{troff} when it is followed by the
+hyphenation control escape sequence @code{\%} at the beginning of a
+word.  GNU @command{troff} does not regard the dummy character as
+``starting'' the word;@acronym{AT&T} @command{troff}
+does.  Further, Heirloom Doctools @command{troff} does not honor an
+explicit hyphenation point marked with @code{\%} after a word-initial
+one.@footnote{Thus,
+@Example
+.ll 10n
+\%antidisestablishmen\%tarianism
+.br
+\&\%antidisestablishmen\%tarianism
+.pl \n(nlu
+@endExample
+produces different results with each of the three formatters.}
+
 @cindex output device name string (@code{.T}), in other implementations
 GNU @code{troff} predefines a string @code{.T} containing the argument
 given to the @option{-T} command-line option, namely the current output
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 0694ea24c..839ed4017 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -5418,6 +5418,32 @@ GNU
 has no such restriction.
 .
 .
+.P
+GNU
+.I troff \" GNU
+handles the dummy character
+.B \[rs]&
+differently from AT&T
+.I troff \" AT&T
+when it is followed by the hyphenation control escape sequence
+.B \[rs]%
+at the beginning of a word.
+.
+GNU
+.I troff \" GNU
+does not regard the dummy character as \[lq]starting\[rq] the word;
+AT&T
+.I troff \" AT&T
+does.
+.
+Further,
+Heirloom Doctools
+.I troff \" Heirloom
+does not honor an explicit hyphenation point marked with
+.B \[rs]%
+after a word-initial one.
+.
+.
 .\" ====================================================================
 .SH "Compatibility mode"
 .\" ====================================================================