gbranden pushed a commit to branch master
in repository groff.
commit 304720d616850db0918f430343c95cb77eae5e95
Author: G. Branden Robinson <[email protected]>
AuthorDate: Mon Sep 23 12:23:24 2024 -0500
[doc,man]: Fix content and style nits.
* Clarify why certain would-be invalid identifiers never occur.
* Document that groff does not specify handling of polygon filling.
Thanks to Tadziu Hoffman and Doug McIlroy for shedding light on this.
* Relocate material, presenting the 's' scaling unit before caveats
about when certain scaling units (including that one) are valid.
* Favor active voice over passive.
* Favor present tense over future.
* Recast.
---
doc/groff.texi.in | 14 ++++++-----
man/groff_diff.7.man | 66 +++++++++++++++++++++++++++++-----------------------
2 files changed, 45 insertions(+), 35 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 6f1881c59..18fccb448 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -6627,10 +6627,10 @@ preprocessor, which recognizes input lines starting
with @samp{.[} and
@Defesc {\\A, @code{'}, anything, @code{'}}
Interpolate@tie{}1 if @var{anything} is a valid identifier, and@tie{}0
otherwise. The delimiter need not be a neutral apostrophe; see
-@ref{Delimiters}. Because invalid input characters are removed (see
-above), invalid identifiers are empty or contain spaces, tabs, newlines,
-or escape sequences that interpolate something other than a sequence of
-ordinary characters.
+@ref{Delimiters}. Because GNU @command{troff} ignores any input
+character with an invalid code when reading it, invalid identifiers are
+empty or contain spaces, tabs, newlines, or escape sequences that
+interpolate something other than a sequence of ordinary characters.
You can employ @code{\A} to validate a macro argument before using it to
construct another escape sequence or identifier.
@@ -14568,11 +14568,13 @@ Afterward, the drawing position is left at (@var{hn},
@var{vn}).
@cindex polygon, solid, drawing (@samp{\D'P @dots{}'})
@cindex drawing a solid polygon (@samp{\D'P @dots{}'})
@cindex solid polygon, drawing (@samp{\D'P @dots{}'})
-As @samp{\D'P @r{@dots{}}'}, but the polygon is filled.
+As @samp{\D'P @r{@dots{}}'}, but the polygon is filled. @code{groff}
+does not specify how the output device must fill concave or
+self-intersecting polygons.
The following macro is like the @samp{\D'l'} example, but shades the
box. We draw the box before writing the text because colors in GNU
-@code{troff} have no transparency; in the opposite order, the filled
+@command{troff} have no transparency; in the opposite order, the filled
polygon would occlude the text.
@Example
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index daeddd268..8af6217f8 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -271,19 +271,21 @@ or because the line can instead be adjusted with
additional inter-word
space
.RB ( hys ).
.
-A hyphenation language is selected with the
+The
.B hla
-request and hyphenation patterns loaded
-(or appended)
-with
+request selects a hyphenation language,
+whereas
.B hpf
-(or
-.BR hpfa ).
+and
+.B hpfa
+load
+(or append to)
+the language's hyphenation patterns.
.
If no hyphenation language is set or no patterns are loaded,
GNU
.I troff \" GNU
-will not perform automatic hyphenation.
+does not perform automatic hyphenation.
.
.
.P
@@ -419,6 +421,26 @@ both set the type size to 10,500\~scaled points,
or 10.5\~points.
.
.
+.br
+.ne 2v
+.P
+Another new scaling unit,
+.RB \[lq] s \[rq],
+multiplies by the number of basic units in a scaled point.
+.
+Thus,
+.RB \[lq]\^ \[rs]n[.ps]s \[rq]
+is equal to
+.RB \[lq] 1m \[rq]
+by definition.
+.
+Do not confuse the
+.RB \[lq] s \[rq]
+and
+.RB \[lq] z \[rq]
+scaling units.
+.
+.
.P
It makes no sense to use the
.RB \[lq] z \[rq]\~scaling
@@ -446,26 +468,6 @@ disallows those as well.
.br
.ne 2v
.P
-Another new scaling unit,
-.RB \[lq] s \[rq],
-multiplies by the number of basic units in a scaled point.
-.
-Thus,
-.RB \[lq]\^ \[rs]n[.ps]s \[rq]
-is equal to
-.RB \[lq] 1m \[rq]
-by definition.
-.
-Do not confuse the
-.RB \[lq] s \[rq]
-and
-.RB \[lq] z \[rq]
-scaling units.
-.
-.
-.br
-.ne 2v
-.P
Output devices may be limited in the type sizes they can employ.
.
For example,
@@ -738,7 +740,9 @@ Interpolate 1 if
is a valid identifier,
and\~0 otherwise.
.
-Because invalid input characters are removed,
+Because GNU
+.I troff \" GNU
+ignores any input character with an invalid code when reading it,
invalid identifiers are empty or contain spaces,
tabs,
newlines,
@@ -777,7 +781,7 @@ Draw filled ellipse with
.I h
and
.I v
-as the axes and the leftmost point at the drawing position.
+as the axis lengths and its leftmost point at the drawing position.
.
.
.TP
@@ -813,6 +817,10 @@ As
.BR \[rs]D\[aq]p\[aq] ,
but the polygon is filled.
.
+.I groff
+does not specify how the output device must fill concave or
+self-intersecting polygons.
+.
.
.TP
.BI \[rs]D\[aq]t\~ "n" \[aq]
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
