diff options
author | G. Branden Robinson <g.branden.robinson@gmail.com> | 2022-12-03 22:58:26 -0600 |
---|---|---|
committer | G. Branden Robinson <g.branden.robinson@gmail.com> | 2022-12-07 02:51:57 -0600 |
commit | e6904b4bad23302e4168c1307a70805478798b59 (patch) | |
tree | 57b0252c8edfbb09d2d5db9b4a8ed09ff7cc416c | |
parent | 230ad718f67621c02143c6f18031978d1f98c63a (diff) | |
download | groff-git-e6904b4bad23302e4168c1307a70805478798b59.tar.gz |
[docs]: Fix content, style, and markup nits.
First, Dave Kemper rightly pointed out some fractured grammar in our
Texinfo manual <https://lists.gnu.org/archive/html/groff/2022-12/\
msg00002.html>. I went to fix that, found that some tightening and
terminology correction could be done, did it, synced with groff(7),
and then found that my precious dead-tree page breaks were thrown off,
producing widows and orphans through the remainder of the page.
This is what happens when man(7) doesn't have keep macros...
Content:
* Fix "value"/"mode" confusion in hyphenation discussion.
* Use (now-)standard terminology when discussing underlining. Say
"escape sequence" instead of "escape". Say "underrule" instead of
"underline character" (there is a difference, now explained). Make
example of \z and \(ul use slightly more realistic.
Style:
* Drop word "explicitly" in hyphenation discussion since we have already
used "explicit" as a term for "literal" hyphens (e.g., "big-nosed").
* Fix grammar gaffe.
* Tighten wording.
* Recast discussion of underlining. (I continue to question the worth
of having this material where it is.)
Markup:
* groff(7): Break input lines after commas.
-rw-r--r-- | doc/groff.texi | 14 | ||||
-rw-r--r-- | man/groff.7.man | 111 |
2 files changed, 58 insertions, 67 deletions
diff --git a/doc/groff.texi b/doc/groff.texi index dcfbe0c7c..9a9de097e 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -8381,9 +8381,9 @@ automatically determined hyphenation points are permissible. The places within a word that are eligible for hyphenation are determined by language-specific data and lettercase relationships. Furthermore, hyphenation of a word might be suppressed due to a limit on -consecutive hyphenated lines (@code{hlm}), the line has not reached a -certain minimum length (@code{hym}), or the line can instead be adjusted -with up to a certain amount of additional inter-word space (@code{hys}). +consecutive hyphenated lines (@code{hlm}), a minimum line length +threshold, certain minimum length (@code{hym}), or because the line can +instead be adjusted with additional inter-word space (@code{hys}). @cindex hyphenation mode register (@code{.hy}) @DefreqList {hy, [@Var{mode}]} @@ -8452,11 +8452,11 @@ enables hyphenation after the first character of a word. Apart from value@tie{}2, restrictions imposed by the hyphenation mode are @emph{not} respected for words whose hyphenations have been -explicitly specified with the hyphenation character (@samp{\%} by -default) or the @code{hw} request. +specified with the hyphenation character (@samp{\%} by default) or the +@code{hw} request. -The nonzero values in the previous table are additive. For example, -value@tie{}12 causes GNU @code{troff} to hyphenate neither the last two +Nonzero values in the previous table are additive. For example, +mode@tie{}12 causes GNU @code{troff} to hyphenate neither the last two nor the first two characters of a word. Some values cannot be used together because they contradict; for instance, values 4 and@tie{}16, and values 8 and@tie{}32. As noted, it is superfluous to add 1 to any diff --git a/man/groff.7.man b/man/groff.7.man index 5aebe5ff5..4334d00b4 100644 --- a/man/groff.7.man +++ b/man/groff.7.man @@ -6002,8 +6002,8 @@ enables hyphenation after the first character of a word. Apart from value\~2, restrictions imposed by the hyphenation mode are .I not -respected for words whose hyphenations have been explicitly specified -with the hyphenation character +respected for words whose hyphenations have been specified with the +hyphenation character .RB (\[lq] \|\[rs]% \[rq] by default) or the @@ -6012,10 +6012,10 @@ request. . . .P -The nonzero values above are additive. +Nonzero values are additive. . For example, -value\~12 causes +mode\~12 causes .I groff to hyphenate neither the last two nor the first two characters of a word. @@ -6045,10 +6045,10 @@ Furthermore, hyphenation of a word might be suppressed due to a limit on consecutive hyphenated lines .RB ( .hlm ), -the line has not reached a certain minimum length +a minimum line length threshold .RB ( .hym ), -or the line can instead be adjusted with up to a certain amount of -additional inter-word space +or because the line can instead be adjusted with additional inter-word +space .RB ( .hys ). . . @@ -6599,9 +6599,12 @@ to .SS "Underlining without macro definitions" .\" ==================================================================== . -If one does not want to use macro definitions, e.g., when -.B doclifter -gets lost, use the following: +If one does not want to use macro definitions, +e.g., +when +.I doclifter +gets lost, +use the following. . .RS .EX @@ -6616,7 +6619,7 @@ gets lost, use the following: .RE . When using -.BR doclifter , +.IR doclifter , it might be necessary to change syntax forms such as .B \e[xy] and @@ -6656,75 +6659,63 @@ after . . .\" ==================================================================== -.SS "Underlining with overstriking \ez and \e(ul" +.SS "Underlining by overstriking with \e(ul" .\" ==================================================================== . -There is another possibility for underlining by using overstriking -with -.BI \ez c -(print -.I c -with zero width without spacing) and -.B \e(ul -(underline character). -. -This produces the underlining of 1 character, both in -.B nroff -and in -.BR troff . +You can use the +.B \[rs]z +escape sequence to format a glyph while suppressing advancement of its +drawing position; +this is another form of overstriking. . +Thus, +.BI \[rs]z c \[rs](ul +formats +.I c +without advancement, +then draws the underrule glyph on top of it. . -.P -For example the underlining of a character say -.B t -looks like -.B \ez\e[ul]t -or -.B \ez\e(ult +Because video terminals implement the underrule glyph by setting the +underline attribute on the character cell, +this works in both +.I nroff \" mode +and +.I troff \" mode +modes. . . .P -Longer words look then a bit strange, but a useful mode is to write -each character into a whole own line. +Long words may then look intimidating in the input; +a clarifying approach might be to use the input line continuation escape +sequence +.BI \[rs] newline +to place each underlined character on its own input line. . -To underlines the 3 character part "tar" of the word "start": +Thus, . .RS .EX -.br -before s\[rs] -\[rs]z\[rs][ul]t\[rs] -\[rs]z\[rs][ul]a\[rs] -\[rs]z\[rs][ul]r\[rs] -t after +\&.nf +\[rs]&\[rs]fB: ${\[rs]fIvar\[rs]fR\[rs]c +\[rs]zo\[rs](ul\[rs] +\[rs]zp\[rs](ul\[rs]c +\[rs]&\[rs]fIvalue\[rs]fB} +\&.fi .EE .RE . -or +produces . .RS .EX -.br -before s\[rs] -\[rs]z\[rs](ult\[rs] -\[rs]z\[rs](ula\[rs] -\[rs]z\[rs](ulr\[rs] -t after +.BI ": ${" var \c +\zo\(ul\ +\zp\(ul\c +.IB value } .EE .RE . -. -.P -The result looks like -.RS -.ft CR -before s\ -\z\[ul]t\ -\z\[ul]a\ -\z\[ul]r\ -t after -.ft R -.RE +as output. . . .\" ==================================================================== |