Re: tctest.1 man page hyphenation comments

[Thomas Dickey]

On Sun, Jun 02, 2024 at 06:58:33PM -0500, G. Branden Robinson wrote:
> 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.

Here's what I see with the 1.8 revision:

DESCRIPTION
       tctest  exercises  the  termcap  library (or emulation of termcap) with
       which it is linked.  It provides several command-line  options,  making
       it  simple  to construct test-cases to compare implementations of term-
       cap.

Call that overly-aggressive, then: it's predictable but reduces readability :-)

I was probably also grumbling about nroff hyphenating "error" and "Repeat",
i.e., 
        "er-" "ror"
        "Re-" "peat"
It also split
        "parameters" as "pa-" "rameters"
        "obsolete" as "ob-" "solete"
        "default" as "de-" "fault"

In a quick check, it hyphenated 11 lines out of the 84 non-blank lines,
and of those 11, 6 have 2 characters before the hyphen.  8 of the 11
lines do have at least one place where there's a double-space.

Preventing it from splitting termcap reduced that to 10 lines.

(I'd rather the feature was configurable so that I could force it to
keep at least 3 characters before/after the split)

> -\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



-- 
Thomas E. Dickey <dickey@invisible-island.net>
https://invisible-island.net

signature.asc
Description: PGP signature