[PATCH 7/9] man/clear.1: Revise formatting (3/4).

[G. Branden Robinson]

Protect literals from hyphenation.  I apply a few guidelines.

1.  Words of less than five letters don't need protection, since the
    hyphenation patterns used by groff (adapted from TeX) won't
    hyphenate words of four or fewer letters.

2.  Words that will undergo replacement when the man page is generated,
    like @CLEAR@ and @TSET@, always get protection because we don't know
    how long the resulting expansion will be.

3.  Longer (but still plain English) words get protection only if
    needed.  For example, "LINES" and "clear" don't, and "COLUMNS" does.
    See <https://froude.eu/groff/examples/hyphenation-points.html>.

4a. Literals at the beginning of synopsis lines, or used as paragraph
    tags, don't get protection because they are at no risk of being
    hyphenated anyway (except on insanely narrow terminals where all
    hope is lost anyway).  I don't apply this reasoning to ordinary
    paragraphs because they are more likely to be recast/rearranged.

4b. Literals in the "SEE ALSO" section's list of man page cross
    references override the above rules.  Since ncurses follows a sound
    practice of always setting these one per input line, this results in
    less visual clutter and faster comprehension of the list contents.
---
 man/clear.1 | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/man/clear.1 b/man/clear.1
index 6ce0b4c6..c47a1d88 100644
--- a/man/clear.1
+++ b/man/clear.1
@@ -91,17 +91,17 @@ .SH SYNOPSIS
 .PP
 .B "@CLEAR@ \-V"
 .SH DESCRIPTION
-\fB@CLEAR@\fP clears your terminal's screen if this is possible,
+\fB\%@CLEAR@\fP clears your terminal's screen if this is possible,
 including the terminal's scrollback buffer
 (if the extended \*(``E3\*('' capability is defined).
-\fB@CLEAR@\fP looks in the environment for the terminal type
+\fB\%@CLEAR@\fP looks in the environment for the terminal type
 given by the environment variable \fBTERM\fP,
 and then in the
 \fIterminfo\fP database to determine how to clear the screen.
 .PP
-\fB@CLEAR@\fP writes to the standard output.
+\fB\%@CLEAR@\fP writes to the standard output.
 You can redirect the standard output to a file (which prevents
-\fB@CLEAR@\fP from actually clearing the screen),
+\fB\%@CLEAR@\fP from actually clearing the screen),
 and later \fBcat\fP the file to the screen, clearing it at that point.
 .SH OPTIONS
 .TP 5
@@ -111,7 +111,7 @@ .SH OPTIONS
 unnecessary, because the default is taken from the environment
 variable \fBTERM\fP.
 If \fB\-T\fP is specified, then the shell
-variables \fBLINES\fP and \fBCOLUMNS\fP will also be ignored.
+variables \fBLINES\fP and \fB\%COLUMNS\fP will also be ignored.
 .TP
 .B \-V
 reports the version of \fIncurses\fP which was used in this program, and exits.
@@ -187,21 +187,21 @@ .SH HISTORY
 next relevant step was a change to the \fBclear\fP program in 2013
 to incorporate this extension.
 .IP \(bu
-In 2013, the \fBE3\fP extension was overlooked in \fB@TPUT@\fP with
+In 2013, the \fBE3\fP extension was overlooked in \fB\%@TPUT@\fP with
 the \*(``clear\*('' parameter.
-That was addressed in 2016 by reorganizing \fB@TPUT@\fP to share
-its logic with \fB@CLEAR@\fP and \fB@TSET@\fP.
+That was addressed in 2016 by reorganizing \fB\%@TPUT@\fP to share
+its logic with \fB\%@CLEAR@\fP and \fB\%@TSET@\fP.
 .SH PORTABILITY
 Neither IEEE Std 1003.1/The Open  Group  Base  Specifications  Issue  7
 (POSIX.1-2008) nor X/Open Curses Issue 7 documents @TSET@ or @RESET@.
 .PP
 The latter documents \fBtput\fP, which could be used to replace this utility
 either via a shell script or by an alias (such as a symbolic link) to
-run \fB@TPUT@\fP as \fB@CLEAR@\fP.
+run \fB\%@TPUT@\fP as \fB\%@CLEAR@\fP.
 .SH SEE ALSO
-\fB@TPUT@\fP(1),
-\fBxterm\fP(1),
-\fBterminfo\fP(\*n).
+\fB\%@TPUT@\fP(1),
+\fB\%xterm\fP(1),
+\fB\%terminfo\fP(\*n).
 .PP
 This describes \fIncurses\fP
 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-- 
2.30.2

signature.asc
Description: PGP signature