[groff] 07/51: pic(1): Fix content, style, and markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 19c584bd0e6f0c02f8a7abbda7648bd2c5ea5a4f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 3 19:44:52 2022 -0500

    pic(1): Fix content, style, and markup nits.
    
    Content:
    * Migrate terminology: "page position" -> "drawing position".
    * Distinguish groff(1) options from pic(1) options.
    * Clarify.
    
    Style:
    * Set "Name" section's summary-description terms in italics as needed.
    * Say "AT&T troff", not "Unix" troff, since Unices can employ a variety
      of existing troffs these days.  Like ours!
    * Reorganize discussion of TeX mode.
    * Place inlined examples within sentences rather than using them as
      excuses to end sentences without punctuation.
    * Tighten wording.
    
    Markup:
    * Use nonbreaking space between quantity and its units.
    * Set examples using EX/EE macros, not with boldface and `br` requests.
    * Set file name "graphics.sty" in italics, not bold.
---
 src/preproc/pic/pic.1.man | 212 +++++++++++++++++++++-------------------------
 1 file changed, 97 insertions(+), 115 deletions(-)

diff --git a/src/preproc/pic/pic.1.man b/src/preproc/pic/pic.1.man
index c8e4be540..2230d3149 100644
--- a/src/preproc/pic/pic.1.man
+++ b/src/preproc/pic/pic.1.man
@@ -1,6 +1,8 @@
 .TH @g@pic @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-@g@pic \- compile pictures for troff or TeX
+@g@pic \- compile pictures for
+.I troff
+or TeX
 .
 .
 .\" ====================================================================
@@ -106,18 +108,20 @@ and any of
 .BR .PF ,
 or
 .B .PY
-are interpreted as picture descriptions.
+are interpreted as picture descriptions in the
+.I pic
+language.
 .
-Ending a
+End a
 .I @g@pic
 picture with
 .B .PE
-leaves the page position at the bottom of the picture;
-ending it with
+to leave the drawing position at the bottom of the picture,
+and with
 .B .PF
 or
 .B .PY
-leaves the position at the top.
+to leave it at the top.
 .
 Normally,
 .I @g@pic
@@ -149,7 +153,9 @@ and
 macros.
 .
 When a macro package does not supply these,
-appropriate definitions can be obtained with
+obtain simple definitions with the
+.I groff
+option
 .BR \-mpic ;
 these will center each picture.
 .
@@ -188,9 +194,8 @@ all exit afterward.
 .TP
 .B \-c
 Be more compatible with
-.IR tpic .
-.
-Implies
+.IR tpic ;
+implies
 .BR \-t .
 .
 Lines beginning with
@@ -211,7 +216,7 @@ 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.
+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
@@ -240,15 +245,12 @@ extensions to the
 .I troff \" generic
 drawing commands.
 .
-You should use this if you are using a postprocessor that doesn't
-support these extensions.
-.
-The extensions are described in
+Specify this option if a postprocessor you're using doesn't support
+these extensions,
+described in
 .MR groff_out @MAN5EXT@ .
 .
-The
-.B \-n
-option also causes
+This option also causes
 .I @g@pic
 not to use zero-length lines to draw dots in
 .I troff \" generic
@@ -262,14 +264,14 @@ Operate in
 .B sh
 commands are ignored.
 .
-This option,
+This mode,
 enabled by default,
 can be useful when operating on untrustworthy input.
 .
 .
 .TP
 .B \-t
-\*[tx] mode.
+Produce \*[tx] output.
 .
 .
 .TP
@@ -323,122 +325,107 @@ This section describes only the differences between GNU
 and the original version of
 .IR pic . \" AT&T
 .
-Many of these differences also apply to newer versions of Unix
+Many of these differences also apply to newer versions of AT&T
 .BR pic .
 .
-A complete documentation is available in the file
-.
-.
-.LP
-.RS
-.I @DOCDIR@/\:pic.ms
-.RE
-.
 .
 .\" ====================================================================
 .SS "\*[tx] mode"
 .\" ====================================================================
 .
-\*[tx] mode is enabled by the
+\*[tx]-compatible output is produced when the
 .B \-t
+option is specified.
+.
+You must use a \*[tx] driver that supports
+.I tpic
+version 2 specials.
+.
+.RI ( tpic
+was a fork of AT&T
+.I pic \" AT&T
+by Tim Morgan of the University of California at Irvine that diverged
+from its source around 1984.
+.
+It is best known today for lending its name to a group of
+.B \[rs]special
+commands it produced for \*[tx].)
+.\" http://ftp.cs.stanford.edu/tex/texhax/texhax90.019
+.
+.
+.P
+Lines beginning with
+.B \[rs]
+are passed through transparently;
+a
+.B %
+is added to the end of the line to avoid unwanted spaces.
+.
+You can safely use this feature to change fonts or the value of
+.BR \[rs]baselineskip .
+.
+Anything else may well produce undesirable results;
+use at your own risk.
+.
+By default,
+lines beginning with a dot are not treated specially\[em]but see the
+.B \-c
 option.
 .
+.
+.P
 In \*[tx] mode,
 .I @g@pic
 will define a vbox called
 .B \[rs]graph
 for each picture.
 .
-Use the
+Use GNU
+.IR pic 's \" GNU
 .B figname
 command to change the name of the vbox.
 .
-You must yourself print that vbox using,
-for example,
-the command
-.
+You must print that vbox yourself using the command
 .
 .RS
-.LP
 .EX
 \[rs]centerline{\[rs]box\[rs]graph}
 .EE
 .RE
 .
+for instance.
 .
-.LP
-Actually,
-since the vbox has a height of zero
-(it is defined with \[rs]vtop)
+Since the vbox has a height of zero
+(it is defined with
+.BR \[rs]vtop )
 this will produce slightly more vertical space above the picture than
 below it;
 .
-.
 .RS
-.LP
-.B
+.EX
 \[rs]centerline{\[rs]raise 1em\[rs]box\[rs]graph}
+.EE
 .RE
 .
-.
-.LP
 would avoid this.
 .
-.
-.LP
-To make the vbox having a positive height and a depth of zero
-(as used e.g., by \*[lx]'s
-.BR \%graphics.sty ),
-define the following macro in your document:
-.
+To give the vbox a positive height and a depth of zero
+(as used by \*[lx]'s
+.IR \%graphics.sty ,
+for example)
+define the following macro in your document.
 .
 .RS
-.LP
-.B \[rs]def\[rs]gpicbox#1{%
-.br
-.B "   \[rs]vbox{\[rs]unvbox\[rs]csname #1\[rs]endcsname\[rs]kern 0pt}}
+.EX
+\[rs]def\[rs]gpicbox#1{%
+  \[rs]vbox{\[rs]unvbox\[rs]csname #1\[rs]endcsname\[rs]kern 0pt}}
+.EE
 .RE
 .
-.
-.LP
-Now you can simply say
+You can then simply say
 .B \[rs]gpicbox{graph}
-instead of \[rs]box\[rs]graph.
-.
-.
-.LP
-You must use a \*[tx] driver that supports
-.I tpic
-version 2 specials.
-.
-.RI ( tpic
-was a fork of AT&T
-.I pic \" AT&T
-by Tim Morgan of the University of California at Irvine that diverged
-from its source around 1984.
-.
-It is best known today for lending its name to a group of
-.B \[rs]special
-commands it produced for \*[tx].)
-.\" http://ftp.cs.stanford.edu/tex/texhax/texhax90.019
-.
-.
-.LP
-Lines beginning with
-.B \[rs]
-are passed through transparently;
-a
-.B %
-is added to the end of the line to avoid unwanted spaces.
-.
-You can safely use this feature to change fonts or to
-change the value of
-.BR \[rs]baselineskip .
-.
-Anything else may well produce undesirable results;
-use at your own risk.
-.
-Lines beginning with a period are not given any special treatment.
+instead of
+.BR \[rs]box\[rs]graph .
 .
 .
 .\" ====================================================================
@@ -530,6 +517,8 @@ This is useful for debugging.
 .
 .TP
 \fBcommand\fR \fIarg\fR\|.\|.\|.
+.\" Move right margin to indentation since we must indent more later.
+.RS
 Concatenate the arguments
 and pass them through as a line to
 .I troff
@@ -545,13 +534,13 @@ This has a similar effect to a line beginning with
 .B .\&
 or
 .BR \[rs] ,
-but allows the values of variables to be passed through.
+but allows the values of
+.I pic
+variables to be passed to the formatter.
 .
 For example,
 .
-.
 .RS
-.IP
 .EX
 \&.PS
 x = 14
@@ -561,17 +550,14 @@ command ".ds string x is " x "."
 .EE
 .RE
 .
-.
-.IP
-prints
-.
+produces
 .
 .RS
-.IP
 .EX
 x is 14.
 .EE
 .RE
+.RE
 .
 .
 .TP
@@ -608,6 +594,8 @@ at this point in the file.
 .RB [ until\~ \[dq]\c
 .IB word \[dq]\c
 ]
+.\" Move right margin to indentation since we must indent more later.
+.RS
 This construct does
 .I body
 once for each line of
@@ -643,9 +631,7 @@ can be any character not occurring in
 .
 For example,
 .
-.
-.RS
-.IP
+.RS \" now move further
 .EX
 \&.PS
 copy thru % circle at ($1,$2) % until "END"
@@ -658,13 +644,9 @@ box
 .EE
 .RE
 .
-.
-.IP
-is equivalent to
-.
+and
 .
 .RS
-.IP
 .EX
 \&.PS
 circle at (1,2)
@@ -675,12 +657,12 @@ box
 .EE
 .RE
 .
+are equivalent.
 .
-.IP
-The commands to be performed for each line can also be taken
-from a macro defined earlier by giving the name of the macro
-as the argument to
+The commands to be performed for each line can also be taken from a
+macro defined earlier by giving the name of the macro as the argument to
 .BR thru .
+.RE
 .
 .
 .LP