gbranden pushed a commit to branch master
in repository groff.
commit 4449a4f061949c4db6c216288e8530d34bdb691c
Author: G. Branden Robinson <[email protected]>
AuthorDate: Tue Jul 30 21:14:56 2024 -0500
[docs]: Correct discussion of hyphenation codes.
* doc/groff.texi.in (Manipulating Hyphenation): Fix incorrect claim and
expand discussion. A special character _can_ be an argument to the
`hcode` request, and this has been true for over 20 years (for
example, in "tmac/ps.tmac"). Problem dates back to commit bd66717ef7,
16 April 2001.
* man/groff.7.man (Request short reference):
* man/groff_diff.7.man (New requests): Sync language with our Texinfo
manual, and clarify.
---
ChangeLog | 12 ++++++++++++
doc/groff.texi.in | 46 +++++++++++++++++++++++++++++-----------------
man/groff.7.man | 12 ++++--------
man/groff_diff.7.man | 34 ++++++++++++++++++++++------------
4 files changed, 67 insertions(+), 37 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index c456c0b92..fec31e24d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2024-07-30 G. Branden Robinson <[email protected]>
+
+ * doc/groff.texi.in (Manipulating Hyphenation): Fix incorrect
+ claim and expand discussion. A special character _can_ be an
+ argument to the `hcode` request, and this has been true for over
+ 20 years (for example, in "tmac/ps.tmac"). Problem dates back
+ to commit bd66717ef7, 16 April 2001.
+
+ * man/groff.7.man (Request short reference):
+ * man/groff_diff.7.man (New requests): Sync language with our
+ Texinfo manual, and clarify.
+
2024-07-29 G. Branden Robinson <[email protected]>
* src/roff/troff/input.cpp (set_hyphenation_code): Restore
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 0d3051532..78fe349d6 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -8964,25 +8964,32 @@ loaded at startup, or in a macro package), GNU
@code{troff} won't
automatically hyphenate at all.
@endDefreq
-@Defreq {hcode, c1 code1 [c2 code2] @dots{}}
+For automatic hyphenation to work, the formatter must know which letters
+are equivalent; for example, the letter @samp{E} behaves like @samp{e};
+only the latter typically appears in hyphenation pattern files. GNU
+@code{troff} expects characters that participate in automatic
+hyphenation to be assigned @dfn{hyphenation codes} that define these
+equivalence classes. At startup, GNU @code{troff} assigns hyphenation
+codes to the letters @samp{a}--@samp{z}, applies the same codes to
+@samp{A}--@samp{Z} in one-to-one correspondence, and assigns a code of
+zero to all other characters.
+
+The @code{hcode} request extends this principle to letters outside the
+Unicode basic Latin alphabet; without it, words containing such letters
+won't be hyphenated properly even if the corresponding hyphenation
+patterns contain them.
+
+@Defreq {hcode, dst1 src1 [dst2 src2] @dots{}}
@cindex hyphenation code (@code{hcode})
@cindex code, hyphenation (@code{hcode})
-Set the hyphenation code of character @var{c1} to @var{code1}, that of
-@var{c2} to @var{code2}, and so on. A hyphenation code must be an
-ordinary character (not a special character escape sequence) other than
-a digit or a space. The request is ignored if given no arguments.
-
-For automatic hyphenation to work, hyphenation codes must be set up. At
-startup, GNU @code{troff} assigns hyphenation codes to the letters
-@samp{a}--@samp{z} (mapped to themselves), to the letters
-@samp{A}--@samp{Z} (mapped to @samp{a}--@samp{z}), and zero to all other
-characters. Normally, hyphenation patterns contain only lowercase
-letters which should be applied regardless of case. In other words,
-they assume that the words `FOO' and `Foo' should be hyphenated exactly
-as `foo' is. The @code{hcode} request extends this principle to letters
-outside the Unicode basic Latin alphabet; without it, words containing
-such letters won't be hyphenated properly even if the corresponding
-hyphenation patterns contain them.
+Set the hyphenation code of ordinary or special character @var{dst1} to
+that of @var{src1}, and so on. @var{dst1} must be an ordinary character
+(other than a numeral) or a special character, and @var{src1} must be an
+ordinary character (other than a numeral) or a special character to
+which a hyphenation code has already been applied. Assigning the code
+of an ordinary character code to itself effectively creates a unique
+hyphenation code (which can then be copied to others). @code{hcode}
+ignores spaces between arguments.
For example, the following @code{hcode} requests are necessary to assign
hyphenation codes to the letters @samp{�������}, needed for German.
@@ -9001,6 +9008,11 @@ umlaut@tie{}a is zero by default, just like a space.
There is a German
hyphenation pattern that covers @w{`kinder'}, so GNU @code{troff} finds
the hyphenation `kin-der'. The other two hyphenation points
(`kin-der-g�r-ten') are missed.
+
+If for some reason you desire to remove a character's hyphenation code,
+use @code{hcode} to copy the code of a punctuation character to it; for
+example, @samp{.hcode � $} assigns a hyphenation code of zero to
+@samp{�} (unless @samp{$} has already been assigned a different one).
@endDefreq
@DefreqList {hla, [@Var{lang}]}
diff --git a/man/groff.7.man b/man/groff.7.man
index 674842321..f8721ea66 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3369,15 +3369,11 @@ Change the hyphenation character
.RI to\~ c .
.
.TPx
-.REQ .hcode "c1 code1 \fR[\fPc2 code2\fR] .\|.\|.\fP"
+.REQ .hcode "dst1 src1 \fR[\fPdst2 src2\fR] .\|.\|.\fP"
Set the hyphenation code of character
-.I c1
-to
-.IR code1 ,
-that of
-.I c2
-to
-.IR code2 ,
+.I dst1
+to that of
+.IR src1 ,
and so on.
.
.TPx
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index b7d331a66..cba5e1f3f 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2604,21 +2604,31 @@ or the default if there is none.
.
.
.TP
-.BI .hcode\~ "c1 code1\~"\c
-.RI [ "c2 code2" "] .\|.\|."
+.BI .hcode\~ "dst1 src1\~"\c
+.RI [ "dst2 src2" "] .\|.\|."
Set the hyphenation code of character
-.I c1
-to
-.IR code1 ,
-that of
-.I c2
-to
-.IR code2 ,
+.I dst1
+to that of
+.IR src1 ,
and so on.
.
-A hyphenation code must be an ordinary character
-(not a special character escape sequence)
-other than a digit.
+.I dst1
+must be an ordinary character
+(other than a numeral)
+or a special character,
+and
+.I src1
+must be an ordinary character
+(other than a numeral)
+or a special character
+to which a hyphenation code has already been applied.
+.
+Assigning the code of an ordinary character code to itself
+effectively creates a unique hyphenation code
+(which can then be copied to others).
+.
+.B hcode
+ignores spaces between arguments.
.
.
.IP
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
