[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 06/09: doc/groff.texi: Update filling/adjustment matter.
From: |
G. Branden Robinson |
Subject: |
[groff] 06/09: doc/groff.texi: Update filling/adjustment matter. |
Date: |
Sun, 24 Jan 2021 01:19:31 -0500 (EST) |
gbranden pushed a commit to branch master
in repository groff.
commit e79f5314db2c474d0117e093c9b0abc1de5ced78
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jan 24 16:00:08 2021 +1100
doc/groff.texi: Update filling/adjustment matter.
* doc/groff.texi (Manipulating Filling and Adjustment): Clarify synonymy
of ".na" and ".ad l".
Thanks to Bjarni Ingi Gislason for pointing out the potential for
confusion.
Fixes <https://savannah.gnu.org/bugs/index.php?59795>.
Also:
- Define the concept of a "pending output line", including index
entry. (Some call this a "partially collected line".)
- Use this concept consistently in description of requests (in this
node) that cause breaks.
- Update .br example to illustrate usage with both control characters.
- Use the more idiomatic noun "adjustment" instead of "adjusting".
- Say "GNU troff" instead of "gtroff".
- Clarify "status" of filling and adjustment as "enablement status",
reflecting their boolean state (and in the latter case to
distinguish it from the available "modes" of adjustment).
- Clarify when a change to adjustment mode takes effect (it does _not_
cause a break).
- Supply possible mnemonic for ".ad n"--adjust "normally" (for *roff).
- Tweak '.ad' example to use more suggestive example text.
- Warn people off assuming that values of the .j register are stable
across implementations.
- Add .ll request to "\p" example to ease reproducibility.
- Describe .ce and .rj better, fronting essential information.
- Adjust ".ad c" and ".ce" example to use macro for repeated text,
place typographical quotes (if available) in example output, and
match break locations with actual groff output.
- Describe .rj in its own right, not in terms of .ce.
- Tighten wording.
- Move @codequote* commands to mark this node as reviewed for correct
grave accent and apostrophe glyph usage.
---
ChangeLog | 10 +++
doc/groff.texi | 218 +++++++++++++++++++++++++++++++--------------------------
2 files changed, 127 insertions(+), 101 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index e9c00b1..07741d3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2021-01-24 G. Branden Robinson <g.branden.robinson@gmail.com>
+
+ * doc/groff.texi (Manipulating Filling and Adjustment): Clarify
+ synonymy of ".na" and ".ad l".
+
+ Thanks to Bjarni Ingi Gislason for pointing out the potential
+ for confusion.
+
+ Fixes <https://savannah.gnu.org/bugs/?59795>.
+
2021-01-20 G. Branden Robinson <g.branden.robinson@gmail.com>
* src/roff/grog/grog.pl: Report program name in fatal error
diff --git a/doc/groff.texi b/doc/groff.texi
index e2d0a7f..a40cbaa 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -26,7 +26,7 @@
@copying
This manual documents GNU @code{troff} version 1.23.0.
-Copyright @copyright{} 1994--2020 Free Software Foundation, Inc.
+Copyright @copyright{} 1994--2021 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -6765,11 +6765,14 @@ register @code{.T} is set to@tie{}1, and zero otherwise.
@c =====================================================================
+@codequotebacktick on
+@codequoteundirected on
+
@node Manipulating Filling and Adjustment, Manipulating Hyphenation,
Registers, gtroff Reference
@section Manipulating Filling and Adjustment
-@cindex manipulating filling and adjusting
-@cindex filling and adjusting, manipulating
-@cindex adjusting and filling, manipulating
+@cindex manipulating filling and adjustment
+@cindex filling and adjustment, manipulating
+@cindex adjustment and filling, manipulating
@cindex justifying text
@cindex text, justifying
@@ -6786,28 +6789,37 @@ register @code{.T} is set to@tie{}1, and zero otherwise.
@cindex @code{sp} request, causing implicit linebreak
@cindex @code{ti} request, causing implicit linebreak
@cindex @code{trf} request, causing implicit linebreak
-Various ways of causing @dfn{breaks} were given in @ref{Breaking}. The
+Various ways of causing @dfn{breaks} were shown in @ref{Breaking}. The
@code{br} request likewise causes a break. Several other requests also
-cause breaks, but implicitly. These are @code{bp}, @code{ce},
-@code{cf}, @code{fi}, @code{fl}, @code{in}, @code{nf}, @code{rj},
-@code{sp}, @code{ti}, and @code{trf}.
+cause breaks implicitly. These are @code{bp}, @code{ce}, @code{cf},
+@code{fi}, @code{fl}, @code{in}, @code{nf}, @code{rj}, @code{sp},
+@code{ti}, and @code{trf}. If the no-break control character is used
+with any of these requests, GNU @code{troff} suppresses the break.
+
+@cindex pending output line
+@cindex partially collected line
+An output line is said to be @dfn{pending} if some input has been
+collected but an output line corresponding to it has not yet been
+written. If no output line is pending, it is as if a break has already
+happened; additional breaks, whether explicit or implicit, have no
+effect.
@Defreq {br, }
-Break the current line, i.e., the input collected so far is emitted
-without adjustment.
-
-If the no-break control character is used, @code{gtroff} suppresses the
-break:
+Break the current line: any input collected on the pending output line
+is emitted without adjustment.
@Example
-a
+foo bar
+.br
+baz
'br
-b
- @result{} a b
+qux
+ @result{} foo bar
+ @result{} baz qux
@endExample
@endDefreq
-Initially, @code{gtroff} fills and adjusts text to both margins.
+Initially, GNU @code{troff} fills text and adjusts it to both margins.
Filling can be disabled via the @code{nf} request and re-enabled with
the @code{fi} request.
@@ -6815,11 +6827,10 @@ the @code{fi} request.
@DefregListEndx {.u}
@cindex fill mode (@code{fi})
@cindex mode, fill (@code{fi})
-Activate fill mode (which is the default). This request implicitly
-enables adjusting; it also inserts a break in the text currently being
-filled. The read-only register @code{.u} is set to@tie{}1.
+Activate fill mode; a pending output line is broken. The read-only
+register @code{.u} is set to@tie{}1.
-The fill mode status is associated with the current environment
+Fill mode enablement status is associated with the current environment
(@pxref{Environments}).
See @ref{Line Control}, for interaction with the @code{\c} escape.
@@ -6828,12 +6839,12 @@ See @ref{Line Control}, for interaction with the
@code{\c} escape.
@Defreq {nf, }
@cindex no-fill mode (@code{nf})
@cindex mode, no-fill (@code{nf})
-Activate no-fill mode. Input lines are output as-is, retaining line
-breaks and ignoring the current line length. This request implicitly
-disables adjusting; it also causes a break. The register @code{.u} is
-set to@tie{}0.
+Activate no-fill mode: the output line length (@pxref{Line Layout}) is
+ignored and output lines are broken where the input lines are. A
+pending output line is broken and adjustment is suppressed. The
+register @code{.u} is set to@tie{}0.
-The fill mode status is associated with the current environment
+Fill mode enablement status is associated with the current environment
(@pxref{Environments}).
See @ref{Line Control}, for interaction with the @code{\c} escape.
@@ -6841,41 +6852,43 @@ See @ref{Line Control}, for interaction with the
@code{\c} escape.
@DefreqList {ad, [@Var{mode}]}
@DefregListEndx {.j}
-Set adjusting mode.
+Set adjustment mode to @var{mode}, taking effect when the pending (or
+next) output line is broken. Adjustment is suppressed in no-fill mode.
-Activation and deactivation of adjusting is done implicitly with calls
-to the @code{fi} or @code{nf} requests.
-
-@var{mode} can have one of the following values:
+@var{mode} can have one of the following values.
@table @code
@item l
-@cindex ragged-right
-Adjust text to the left margin. This produces what is traditionally
-called ragged-right text.
+@cindex ragged-right text
+Adjust text to the left margin, producing what is sometimes called
+ragged-right text. Due to the way @code{roff} systems traditionally
+implement adjustment, it can be helpful to think of @w{@samp{.ad l}} as
+``no adjustment'', or as a synonym for the @code{na} request (see
+below).
@item r
-@cindex ragged-left
+@cindex ragged-left text
Adjust text to the right margin, producing ragged-left text.
@item c
@cindex centered text
-@cindex @code{ce} request, difference to @samp{.ad@tie{}c}
-Center filled text. This is different to the @code{ce} request, which
-only centers text without filling.
+@cindex @code{ce} request, difference from @w{@samp{.ad c}}
+Center filled text. Contrast with the @code{ce} request, which centers
+text without filling.
@item b
@itemx n
-Justify to both margins. This is the default used by @code{gtroff}.
+Adjust ``normally'': to both margins. This is the GNU @code{troff}
+default.
@end table
Finally, @var{mode} can be the numeric argument returned by the
@code{.j} register.
-Using @code{ad} without argument is the same as saying
-@samp{.ad \n[.j]}. In particular, @code{gtroff} adjusts lines in the
-same way it did before adjusting was deactivated (with a call to
-@code{na}, say). For example, this input code
+Using @code{ad} without an argument is the same as @samp{.ad \n[.j]}.
+In particular, GNU @code{troff} adjusts lines in the same way it did
+before adjustment was deactivated (with a call to @code{na}, say). For
+example, this input code
@Example
.de AD
@@ -6888,76 +6901,79 @@ same way it did before adjusting was deactivated (with
a call to
. na
..
.
-textA
+left
.AD r
.nr ad \n[.j]
-textB
+right
.AD c
-textC
+center
.NA
-textD
-.AD \" back to centering
-textE
-.AD \n[ad] \" back to right justifying
-textF
+left
+.AD
+center
+.AD \n[ad]
+right
@endExample
@noindent
produces the following output:
@Example
-textA
- textB
- textC
-textD
- textE
- textF
+left
+ right
+ center
+left
+ center
+ right
@endExample
@cindex adjustment mode register (@code{.j})
-As just demonstrated, the current adjustment mode is available in the
-read-only register @code{.j}; it can be stored and subsequently used to
-set adjustment.
+The current adjustment mode is available in the read-only register
+@code{.j}; it can be stored and subsequently used to set adjustment.
-The adjustment mode status is associated with the current environment
-(@pxref{Environments}).
+The adjustment mode and enablement status are associated with the
+current environment (@pxref{Environments}).
+
+The value of @code{.j} for any adjustment mode is an implementation
+detail and should not be relied upon as a programmer's interface.
@endDefreq
@Defreq {na, }
-Disable adjusting. This request won't change the current adjustment
-mode: A subsequent call to @code{ad} uses the previous adjustment
-setting.
+Disable adjustment. This is synonymous with the request
+@w{@samp{.ad l}}; the value of the adjustment mode register @code{.j}
+is not changed.
-The adjustment mode status is associated with the current environment
-(@pxref{Environments}).
+The adjustment mode and enablement status are associated with the
+current environment (@pxref{Environments}).
@endDefreq
@DefreqList {brp, }
@DefescListEndx {\\p, , , }
-Break, adjusting the current line per the current adjustment mode.
+Break, adjusting the line per the current adjustment mode.
With @code{\p}, this break will happen at the next word boundary. The
@code{\p} itself is removed entirely, adding neither a break nor a space
where it appears in input; it can thus be placed in the middle of a word
to cause a break at the end of that word.
-In most cases this produces very ugly results since @code{gtroff}
-doesn't have a sophisticated paragraph building algorithm (as @TeX{}
-has, for example); instead, @code{gtroff} fills and adjusts a paragraph
-line by line:
+In most cases this produces ugly results since GNU @code{troff} doesn't
+have a sophisticated paragraph-building algorithm (as @TeX{} has, for
+example); instead, GNU @code{troff} fills and adjusts a paragraph line
+by line.
@Example
+.ll 4.5i
This is an uninteresting sentence.
This is an uninteresting sentence.\p
This is an uninteresting sentence.
@endExample
@noindent
-is formatted as
+is formatted as follows.
@Example
-This is an uninteresting sentence. This is an
-uninteresting sentence.
+This is an uninteresting sentence. This is
+an uninteresting sentence.
This is an uninteresting sentence.
@endExample
@endDefreq
@@ -7044,30 +7060,32 @@ If @emph{undiscardable} space is required, use the
@code{\h} escape.
@DefregListEndx {.ce}
@cindex centering lines (@code{ce})
@cindex lines, centering (@code{ce})
-Center text. While the @w{@samp{.ad c}} request also centers text, it
-fills the text as well. @code{ce} does not fill the text it affects.
-This request causes a break. The number of lines still to be centered
+Center the next @var{nnn} input text lines without filling them. A
+pending output line is broken. The number of lines still to be centered
is associated with the current environment (@pxref{Environments}).
-The following example demonstrates the differences.
+While the @w{@samp{.ad c}} request also centers text, it fills the text
+as well. The following example demonstrates the difference.
@Example
+.de FR
+This is a small text fragment that shows the differences
+between the `.ce' and the `.ad c' requests.
+..
.ll 4i
.ce 1000
-This is a small text fragment that shows the differences
-between the `.ce' and the `.ad c' request.
+.FR
.ce 0
.ad c
-This is a small text fragment that shows the differences
-between the `.ce' and the `.ad c' request.
- @result{} This is a small text fragment that
- @result{} shows the differences
- @result{} between the `.ce' and the `.ad c' request.
+.FR
+ @result{} This is a small text fragment that shows
+ @result{} the differences
+ @result{} between the @quoteleft{}.ce@quoteright{} and the @quoteleft{}.ad
c@quoteright{} requests.
@result{}
- @result{} This is a small text fragment that
- @result{} shows the differences between the `.ce'
- @result{} and the `.ad c' request.
+ @result{} This is a small text fragment that shows
+ @result{} the differences between the @quoteleft{}.ce@quoteright{} and
+ @result{} the @quoteleft{}.ad c@quoteright{} requests.
@endExample
With no arguments, @code{ce} centers the next line of text. @var{nnn}
@@ -7078,10 +7096,10 @@ The basic length for centering text is the line length
(as set with the
@code{ll} request) minus the indentation (as set with the @code{in}
request). Temporary indentation is ignored.
-The previous example shows the common idiom of turning on centering for
-a large number of lines, and turning off centering after the text to be
-centered. This is useful for any request that takes a number of lines
-as an argument.
+The previous example illustrates a common idiom of turning centering on
+for a quantity of lines far in excess of what is required, and off again
+after the text to be centered. This pattern is useful for any request
+that takes a count of input lines as an argument.
The @code{.ce} read-only register contains the number of lines remaining
to be centered, as set by the @code{ce} request.
@@ -7092,19 +7110,17 @@ to be centered, as set by the @code{ce} request.
@cindex justifying text (@code{rj})
@cindex text, justifying (@code{rj})
@cindex right-justifying (@code{rj})
-Justify unfilled text to the right margin. Arguments are identical to
-the @code{ce} request. The @code{.rj} read-only register is the number
-of lines to be right-justified as set by the @code{rj} request. This
-request causes a break. The number of lines still to be right-justified
-is associated with the current environment (@pxref{Environments}).
+Align the next @var{nnn} input text lines to the right margin without
+filling them. A pending output line is broken. The @code{.rj}
+read-only register is the number of lines to be right-justified as set
+by the @code{rj} request. The number of lines still to be
+right-justified is associated with the current environment
+(@pxref{Environments}).
@endDefreq
@c =====================================================================
-@codequotebacktick on
-@codequoteundirected on
-
@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and
Adjustment, gtroff Reference
@section Manipulating Hyphenation
@cindex manipulating hyphenation
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 06/09: doc/groff.texi: Update filling/adjustment matter.,
G. Branden Robinson <=