[groff] 15/37: pic(1): Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d11ae59c1b7148a593e986f532848848ab75039d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Sep 25 10:36:17 2024 -0500

    pic(1): Fix content and style nits.
    
    * Document that the "sh" command is implemented using the C standard
      library's system(3) function; the user needs to know that to construct
      proper syntax for nontrivial cases.  Reiterate in "sh" description
      that to function, it requires the `-U` ("unsafe") option.
    
    * Clarify pronoun antecedent.
    * Use "this" as a relative adjective, not a demonstrative pronoun.
    * Use commas instead of semicolons in list.
    * Fix grammar nit (missing "and").
    * Favor active voice over passive.
    * Favor present tense over future.
---
 src/preproc/pic/pic.1.man | 74 ++++++++++++++++++++++++++---------------------
 1 file changed, 41 insertions(+), 33 deletions(-)

diff --git a/src/preproc/pic/pic.1.man b/src/preproc/pic/pic.1.man
index e61bd55b5..1b61bd3f5 100644
--- a/src/preproc/pic/pic.1.man
+++ b/src/preproc/pic/pic.1.man
@@ -9,7 +9,7 @@ or TeX
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -229,14 +229,16 @@ are passed through with the initial
 changed to
 .BR \[rs] .
 .
-A line beginning with
+GNU
+.I pic \" GNU
+gives a line beginning with
 .B .ps
-is given special treatment:
+special treatment:
 it takes an optional integer argument specifying the line thickness
 (pen size)
-in milliinches;
-a missing argument restores the previous line thickness;
-the default line thickness is 8\~milliinches.
+in milliinches,
+a missing argument restores the previous line thickness,
+and the default line thickness is 8\~milliinches.
 .
 The line thickness thus specified takes effect only when a
 non-negative line thickness has not been specified by use of the
@@ -329,12 +331,11 @@ Generate output for the
 device
 .IR dev .
 .
-This is unnecessary because the
-.I troff \" generic
-output generated by
-GNU
+This option is unnecessary in GNU
 .I pic \" GNU
-is device-independent.
+because the
+.I troff \" generic
+it generates is device-independent.
 .
 .
 .\" ====================================================================
@@ -397,7 +398,7 @@ option.
 .P
 In \*[tx] mode,
 .I @g@pic
-will define a vbox called
+defines a vbox called
 .B \[rs]graph
 for each picture.
 .
@@ -418,7 +419,7 @@ for instance.
 .
 Since the vbox has a height of zero\[em]it is defined with
 .BR \[rs]vtop \[em]\c
-this will produce slightly more vertical space above the picture than
+this produces slightly more vertical space above the picture than
 below it;
 .
 .RS
@@ -468,8 +469,10 @@ or newline)
 may be used as alternative delimiters,
 in which case the members of a given pair must be identical.
 .
-Strings are recognized within delimiters of either kind;
-they may contain the delimiter character or unbalanced braces.
+GNU
+.I pic \" GNU
+recognizes double-quoted strings within delimiters of either kind;
+such strings may contain the delimiter character or unbalanced braces.
 .
 .
 .TP
@@ -516,7 +519,7 @@ at each iteration rather than incrementing it.
 If the range constraint on
 .I expr3
 isn't met,
-the loop will not execute.
+the loop does not execute.
 .
 .I X
 can be any character not in
@@ -603,7 +606,12 @@ when formatted with
 \fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR
 Pass
 .I command
-to a shell.
+to a shell via
+.MR system 3 .
+.
+Ignored if
+.B \-U
+option not specified.
 .
 .
 .TP
@@ -656,9 +664,11 @@ lines are taken from the current input up to
 If an
 .B until
 clause is specified,
-lines will be read only until a line the first word of which is
+GNU
+.I pic \" GNU
+reads lines only until encountering one beginning with
 .IR word ;
-that line will then be discarded.
+which it then discards.
 .
 .I X
 can be any character not in
@@ -767,7 +777,7 @@ Update an existing variable.
 must already be defined,
 and
 .I expr
-will be assigned to
+is assigned to
 .I var
 without creating a variable local to the current block.
 .
@@ -1007,17 +1017,15 @@ line accepts a second argument specifying a maximum 
height for the
 picture.
 .
 If a width of zero is specified,
-it will be ignored when computing the scaling factor for the picture.
+it is ignored when computing the scaling factor for the picture.
 .
 GNU
 .I pic \" GNU
-will always scale a picture by the same amount vertically as well as
-horizontally.
+always scales a picture by the same amount vertically and horizontally.
 .
-This is different from DWB 2.0
+This differs from DWB 2.0
 .IR pic , \" foreign
-which may scale a picture by a different amount vertically than
-horizontally if a height is specified.
+which may change the picture's aspect ratio if a height is specified.
 .
 .
 .LP
@@ -1033,7 +1041,7 @@ the value of
 is assumed.
 .
 If the height attribute is not supplied,
-the height will default to the number of text strings associated with
+the height defaults to the number of text strings associated with
 the object times
 .BR textht .
 .
@@ -1058,7 +1066,7 @@ an expression of the form
 .
 .P
 can be used instead;
-this will produce the arguments per the
+it transforms its arguments per
 .IR format ,
 which should be a string as described in
 .MR printf 3 ,
@@ -1140,14 +1148,14 @@ and ellipses can be filled by giving them an attribute 
of
 .BR fill [ ed ],
 which takes an optional expression argument with a value between
 0 and 1;
-0 will fill it with white,
+0 fills it with white,
 1 with black,
-values in between with a proportionally gray shade.
+and values in between with a proportionally gray shade.
 .
 A value greater than 1 is interpreted as the shade of gray that is
 being used for text and lines.
 .
-Normally this will be black,
+Normally this is black,
 but output devices may provide a mechanism for changing this.
 .
 Without an argument,
@@ -1349,7 +1357,7 @@ with
 .RB \[lq] "groff \-T ps" \[rq].
 .
 However,
-such a PostScript file will lack bounding box information;
+such a PostScript file lacks bounding box information;
 .I roff
 formatters produce page-sized output.
 .
@@ -1373,7 +1381,7 @@ produce a PDF with
 .RB \[lq] "groff \-T pdf" \[rq];
 .MR gropdf @MAN1EXT@ 's
 .B \-p
-option will set the MediaBox of the file.
+option sets the MediaBox of the file.
 .
 .
 .P