[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 10/15: doc/groff.texi, groff_diff(7): Resynchronize.
From: |
G. Branden Robinson |
Subject: |
[groff] 10/15: doc/groff.texi, groff_diff(7): Resynchronize. |
Date: |
Tue, 20 Oct 2020 14:00:31 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit ea0dfae690f849c348419ebf2b7cefde8c896e34
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 19 04:34:22 2020 +1100
doc/groff.texi, groff_diff(7): Resynchronize.
The descriptions of .asciify, .unformat, and .char had diverged in the
two documents. Parallelize them, taking the clearer language from each
(and doing some light recasting of my own).
---
doc/groff.texi | 77 ++++++++++++++++++++++---------------------
man/groff_diff.7.man | 93 ++++++++++++++++++++++++++++++++++------------------
2 files changed, 102 insertions(+), 68 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 944225f..7a29ce6 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9505,31 +9505,31 @@ on the right doesn't get examined.
@cindex @code{\&}, and glyph definitions
@cindex @code{\e}, and glyph definitions
@cindex @code{hcode} request, and glyph definitions
-Define a new glyph@tie{}@var{g} to be @var{string} (which can be
-empty).@footnote{@code{char} is a misnomer since an output glyph is
-defined.} Every time glyph@tie{}@var{g} needs to be printed,
-@var{string} is processed in a temporary environment and the result is
-wrapped up into a single object. Compatibility mode is turned off and
-the escape character is set to @samp{\} while @var{string} is being
-processed. Any emboldening, constant spacing or track kerning is
-applied to this object rather than to individual characters in
-@var{string}.
-
-A glyph defined by these requests can be used just like a normal glyph
+Define a new character or glyph@tie{}@var{g} to be @var{string}, which
+can be empty. More precisely, @code{char} defines (or redefines an
+existing) @code{groff} object that is accessed with the
+name@tie{}@var{g} on input, and produces @var{string} on output. Every
+time glyph@tie{}@var{g} needs to be printed, @var{string} is processed
+in a temporary environment and the result is wrapped up into a single
+object. Compatibility mode is turned off and the escape character is
+set to@tie{}@code{\} while @var{string} is processed. Any emboldening,
+constant spacing, or track kerning is applied to this object rather than
+to individual glyphs in @var{string}.
+
+An object defined by these requests can be used just like a normal glyph
provided by the output device. In particular, other characters can be
translated to it with the @code{tr} or @code{trin} requests; it can be
-made the leader character by the @code{lc} request; repeated patterns
-can be drawn with the glyph using the @code{\l} and @code{\L} escape
-sequences; words containing the glyph can be hyphenated correctly if the
-@code{hcode} request is used to give the glyph's symbol a hyphenation
-code.
+made the leader character with the @code{lc} request; repeated patterns
+can be drawn with it using the @code{\l} and @code{\L} escape sequences;
+and words containing@tie{}@var{g} can be hyphenated correctly if the
+@code{hcode} request is used to give the object a hyphenation code.
-There is a special anti-recursion feature: Use of @code{g} within the
-glyph's definition is handled like normal characters and symbols not
-defined with @code{char}.
+There is a special anti-recursion feature: use of the object within its
+own definition is handled like a normal character (not
+defined with @code{char}).
-Note that the @code{tr} and @code{trin} requests take precedence if
-@code{char} accesses the same symbol.
+The @code{tr} and @code{trin} requests take precedence if @code{char}
+accesses the same symbol.
@Example
.tr XY
@@ -13003,12 +13003,14 @@ the output device, filtering out @var{string} again.
@cindex unformatting diversions (@code{asciify})
@cindex diversion, unformatting (@code{asciify})
@cindex @code{trin} request, and @code{asciify}
-@dfn{Unformat} the diversion specified by @var{div} in such a way that
-@acronym{ASCII} characters, characters translated with the @code{trin}
-request, space characters, and some escape sequences that were formatted
-and diverted are treated like ordinary input characters when the
-diversion is reread. It can be also used for gross hacks; for example,
-the following sets register@tie{}@code{n} to@tie{}1.
+@dfn{Unformat} the diversion @var{div} in a way such that Unicode basic
+Latin (@acronym{ASCII}) characters, characters translated with the
+@code{trin} request, space characters, and some escape sequences, that
+were formatted and diverted into @var{div} are treated like ordinary
+input characters when @var{div} is reread. Doing so can be useful in
+conjunction with the @code{writem} request. @code{asciify} can be also
+used for gross hacks; for example, the following sets
+register@tie{}@code{n} to@tie{}1.
@Example
.tr @@.
@@ -13021,21 +13023,22 @@ the following sets register@tie{}@code{n} to@tie{}1.
.x
@endExample
-Note that @code{asciify} cannot return all items in a diversion back
-to their source equivalent, nodes such as @code{\N[...]} will still
-remain as nodes, so the result cannot be guaranteed to be a pure string.
+@code{asciify} cannot return all items in a diversion back to their
+source equivalent; nodes such as those produced by @code{\N[...]} will
+remain nodes, so the result cannot be guaranteed to be a pure string.
@xref{Copy-in Mode}.
@endDefreq
@Defreq {unformat, div}
-Like @code{asciify}, unformat the specified diversion. However,
-@code{unformat} only unformats spaces and tabs between words.
-Unformatted tabs are treated as input tokens, and spaces are stretchable
-again.
-
-The vertical size of lines is not preserved; glyph information (font,
-font size, space width, etc.)@: is retained.
+Like @code{asciify}, unformat the diversion @var{div}. However,
+@code{unformat} handles only tabs and spaces between words, the latter
+usually arising from spaces or newlines in the input. Tabs are treated
+as input tokens, and spaces become stretchable again.
+
+The vertical sizes of lines are not preserved, but glyph information
+(font, font size, space width, etc.)@: is retained. @code{unformat} can
+be useful in conjunction with the @code{box} and @code{boxa} requests.
@endDefreq
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 4f07514..3f5a664 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1065,21 +1065,33 @@ and
.
.
.TP
-.BI .asciify\~ xx
-This request \[oq]unformats\[cq] the diversion
-.I xx
-in such a way that ASCII and space characters (and some escape
-sequences) that were formatted
-and diverted into
-.I xx
+.BI .asciify\~ div
+.I Unformat
+the diversion
+.I div
+in a way such that Unicode basic Latin (ASCI) characters,
+characters translated with the
+.B .trin
+request,
+space characters,
+and some escape sequences,
+that were formatted and diverted into
+.I div
are treated like ordinary input characters when
-.I xx
+.I div
is reread.
-Useful for diversions in conjunction with the
-.B writem
+.
+Doing so can be useful in conjunction with the
+.B .writem
request.
.
-It can be also used for gross hacks; for example, this
+.B .asciify
+can be also used for gross hacks;
+for example,
+the following sets
+.RB register\~ n
+to\~1.
+.
.
.RS
.IP
@@ -1096,15 +1108,26 @@ It can be also used for gross hacks; for example, this
.EE
.RE
.
+.
.IP
-sets register\~\c
-.B n
-to\~1.
+.B .asciify
+cannot return all items in a diversion back to their source equivalent;
+nodes such as those produced by
+.BR \[rs]N[ .\|.\|.\& ]
+will remain nodes,
+so the result cannot be guaranteed to be a pure string.
+.
.
-Note that glyph information (font, font size, etc.) is not preserved;
+.IP
+Glyph information
+(font,
+point size,
+etc.)
+is not preserved;
use
.B .unformat
-instead.
+instead to achieve that.
+.
.
.TP
.B .backtrace
@@ -3150,32 +3173,40 @@ This undoes the effect of the
.B nroff
request.
.
+.
.TP
-.BI .unformat\~ xx
-This request \[oq]unformats\[cq] the diversion
-.IR xx .
+.BI .unformat\~ div
+\[lq]Unformat\[rq]
+the diversion
+.IR div .
.
-Contrary to the
-.B asciify
-request, which tries to convert formatted elements of the diversion
-back to input tokens as much as possible,
+In contrast to the
+.B .asciify
+request,
+which tries to convert formatted elements of the diversion back to input
+tokens as much as possible,
.B .unformat
-only handles tabs and spaces between words (usually caused by spaces
-or newlines in the input) specially.
+handles only tabs and spaces between words,
+the latter usually arising from spaces or newlines in the input.
.
-The former are treated as if they were input tokens, and the latter
-are stretchable again.
+Tabs are treated as input tokens,
+and spaces become are stretchable again.
.
Note that the vertical size of lines is not preserved.
.
-Glyph information (font, font size, space width, etc.) is retained.
+The vertical sizes of lines are not preserved,
+but glyph information
+(font, font size, space width, etc.\&)
+is retained.
.
-Useful in conjunction with the
-.B box
+.B .unformat
+can be useful in conjunction with the
+.B .box
and
-.B boxa
+.B .boxa
requests.
.
+.
.TP
.BI .vpt\~ n
Enable vertical position traps if
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 10/15: doc/groff.texi, groff_diff(7): Resynchronize.,
G. Branden Robinson <=