tctest.1 man page hyphenation comments

[G. Branden Robinson]

Hi Thomas,

There being no mailing list for tctest (as far as I know), I thought I'd
send some comments about its man page here.

commit 31bdd510398664cc0acbd3c4bf451ffececbfd3d
Author: Thomas E. Dickey <dickey@invisible-island.net>
Date:   Mon Apr 29 19:14:00 2024 +0000

    snapshot of project "tctest", label t20240429

diff --git a/CHANGES b/CHANGES
index 59e8b99..10a5a16 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,32 @@
+2024-04-29  Thomas E. Dickey  <dickey@invisible-island.net>
+
+       * tctest.1: workaround for groff mis-hyphenating

I was curious about this remark so I looked into it.

-\fBtctest\fP exercises the termcap library (or emulation of termcap)
+\fBtctest\fP exercises the \%termcap library (or emulation of \%termcap)

groff does not mis-hyphenate this word for me, neither using the default
hyphenation mode (1) nor a correct one for English (4).[1]

$ cat ~/bin/hyphen
#!/bin/sh

: ${HY:=4}

for W
do
    printf ".hy $HY\n.ll 1u\n%s\n" "$W" | nroff -Wbreak | sed '/^$/d' \
        | tr -d '\n'
    echo
done

# vim:set ai et sw=4 ts=4 tw=80:
$ PATH=$HOME/groff-stable/bin:/usr/bin:$HOME/bin nroff -v | head -n 1
GNU nroff (groff) version 1.23.0
$ PATH=$HOME/groff-stable/bin:/usr/bin:$HOME/bin HY=1 hyphen termcap
term‐cap
$ PATH=$HOME/groff-stable/bin:/usr/bin:$HOME/bin hyphen termcap
term‐cap
$ PATH=/usr/bin:$HOME/bin nroff -v
GNU nroff (groff) version 1.22.4
$ PATH=/usr/bin:$HOME/bin HY=1 hyphen termcap
term‐cap
$ PATH=/usr/bin:$HOME/bin hyphen termcap
term‐cap
$ PATH=$HOME/groff-1.22.3/bin:/usr/bin:$HOME/bin nroff -v
GNU nroff (groff) version 1.22.3
$ PATH=$HOME/groff-1.22.3/bin:/usr/bin:$HOME/bin HY=1 hyphen termcap
term‐cap
$ PATH=$HOME/groff-1.22.3/bin:/usr/bin:$HOME/bin hyphen termcap
term‐cap

That covers groff versions going back nearly 10 years.  What
mis-hyphenation did you observe?

-use $TERMCAP variable if it exists.
+use $\%TERMCAP variable if it exists.

This will not work as you intend.

$ hyphen '$\%TERMCAP'
$‐TERM‐CAP

In *roff, punctuation marks are word-constituent.  (They aren't normally
hyphenation points, but they're "part of a word".

"To GNU troff, a word is any sequence of one or more characters that
aren’t spaces or newlines. The exceptions separate words."

https://www.gnu.org/software/groff/manual/groff.html.node/Filling.html

The manual speaks only of GNU troff since its purpose at that point is
not to comprehensively cover all known *roff implementation, but the
principle nevertheless holds broadly.

I would move the hyphenation control escape sequence to the beginning of
the word.

+use \%$TERMCAP variable if it exists.

Also, personally, I would suppress the hyphenation of "termcap" only
when using it as a literal; that is, as part of a file name, a man
page cross reference, or similar.  That is the practice I (try to)
follow in my revisions to ncurses man pages.

Regards,
Branden

[1] Version 7 Unix man(7) used hyphenation mode 14.
    https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/lib/tmac/tmac.an

signature.asc
Description: PGP signature