[groff] 04/04: pic2graph(1): Make editorial/style changes.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit fc7903ad23654589472b890b3bf23fef6a377591
Author: G. Branden Robinson <address@hidden>
Date:   Mon Apr 23 04:48:55 2018 -0400

    pic2graph(1): Make editorial/style changes.
    
    Synopsis:
    * Use groff_man(7)'s synopsis macros for the synopsis.
    * Document the presence of --help and --version flags.
    * Make option argument descriptions more descriptive.
    
    Description:
    * Don't start the discussion with sentence fragments.
    * Make clear that this tool reads standard input and writes to standard
      output.
    * Present PNG abbreviation on the first occurrence of its expansion.
    * Render work titles (like the names of software programs) in italics,
      except on the first mention of a program which has a supporting man
      page.  The manual section does not need to be stated every time the
      program is mentioned.
    * Remove material singing the praises of the PIC language from this
      man page.  Maybe we can move some of it into pic(1)?
    * The groff convention regarding name of the language appears to be PIC
      (full capitalization).  "pic" is the name of a Unix tool implementing
      the language.  If you want consistency from an authoritative source, I
      advise you _not_ to look at CSTR #116--Kernighan is all over the map,
      using "PIC" in the article title, and "pic" itself (susceptible to
      beginning-of-sentence-capitaliztion) interchangeably to refer to the
      tool and the language specification.  But when you put it in a box,
      it's in full caps again.  :-|
    * Set references to *roff macros in bold.
    * FIXME comment some stuff about old versions of convert using white
      backgrounds by default instead of transparent ones.  This language
      hasn't been touched since 2008 and was probably old even then.
    * Also drop language about passing an argument to convert to force the
      background transparent, since that's the default these days anyway.
    * Note availability of "convert" program from GraphicsMagick as well,
      which has been around a mere 16 years (and is still making releases).
    * Clarify what tool is doing the work of cropping the image.
    * Drop paragraph calling out which tools are invoked, and advising the
      user that the programs have to be installed and in the $PATH to work.
      The cross-references do the work of the former and the latter is Unix
      101 knowledge that does not need to be recapitulated here.
    * Drop references to gs; whether GhostScript is called is up to groff.
      pic2graph does not call it directly.
    
    Options:
    * Set the term "unsafe" (regarding groff's -U flag) in italics, not
      scare quotes.  The term deserves emphasis and is warranted without
      irony.  Running a PIC file with "sh {>$HOME/PWN3D}" (or worse) in it
      through this tool with the -unsafe option set could be upsetting.
    * Tighten description of -format.
    * Expand description of -eqn since a "delimeter" in the Unix world is
      usually an unpaired single character.  eqn and m4 are exceptions.
    * Document --help and --version flags.
    
    Files:
    * Delete section.  This script does not read the eqnrc file, and it's up
      to eqn to do so itself.
    
    Environment:
    * Tighten by using groff_man(7)'s .TQ macro to list the variable names
      attempted for a temp directory.
    * Set filespec literals in italics, not bold.  (This is supposed to be
      the convention, but you'll find a lot of man pages not honoring it,
      including some in our own project.)
    * Speaking of conventions, italics are supposed to be used for
      environment variables, too, as I recall, but there's even more chaos
      on that front than there is with filespecs.  So I left these alone.
    
    See also:
    * A simple list of man page cross-references is not a sentence; lose the
      period.
    * Add citation of W. Richard Stevens's "Turning PIC into HTML" article,
      as it seems to be the source of the recipe Raymond mentions.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 contrib/pic2graph/pic2graph.1.man | 221 +++++++++++++++++++-------------------
 1 file changed, 108 insertions(+), 113 deletions(-)

diff --git a/contrib/pic2graph/pic2graph.1.man 
b/contrib/pic2graph/pic2graph.1.man
index b9ea5c3..df3cac1 100644
--- a/contrib/pic2graph/pic2graph.1.man
+++ b/contrib/pic2graph/pic2graph.1.man
@@ -14,89 +14,75 @@ pic2graph \- convert a PIC diagram into a cropped image
 .SH SYNOPSIS
 .\" ====================================================================
 .
-.B pic2graph
-[
-.B \-unsafe
-]
-[
-.BI "\-format " fmt
-]
-[
-.BI "\-eqn " delim
-]
+.SY pic2graph
+.OP \-unsafe
+.OP \-format output-format
+.OP \-eqn delimeters
+.RI [ \%convert-arguments ]
+.YS
+.
+.SY "pic2graph \-\-help"
+.SY "pic2graph \-\-version"
+.YS
 .
 .
 .\" ====================================================================
 .SH DESCRIPTION
 .\" ====================================================================
 .
-Reads a PIC program as input; produces an image file (by default in
-Portable Network Graphics format) suitable for the Web as output.
+.I pic2graph
+reads a
+.BR @address@hidden (@MAN1EXT@)
+program from the standard input and and writes an image file,
+by default in Portable Network Graphics (PNG) format,
+to the standard output.
 .
-Also translates
+It furthermore translates
 .BR @address@hidden (@MAN1EXT@)
 constructs, so it can be used for generating images of mathematical
 formulae.
 .
 .
-.P
-PIC is a rather expressive graphics minilanguage suitable for
-producing box-and-arrow diagrams of the kind frequently used in
-technical papers and textbooks.
-.
-The language is sufficiently flexible to be quite useful for state
-charts, Petri-net diagrams, flow charts, simple circuit schematics,
-jumper layouts, and other kinds of illustration involving repetitive
-uses of simple geometric forms and splines.
-.
-Because PIC descriptions are procedural and object-based, they are
-both compact and easy to modify.
-.
-.
-.P
-The PIC language is fully documented in
-.IR "Making Pictures With GNU PIC" ,
-a document which is part of the
-.BR groff (@MAN1EXT@)
-distribution.
-.
-.
-.P
-Your input PIC code should
+.PP
+The input
+.I PIC
+code should
 .I not
-be wrapped with the \&.PS and \&.PE macros that normally guard it within
+be wrapped with the
+.B \&.PS
+and
+.B \&.PE
+macros that normally guard it within
 .BR groff (@MAN1EXT@)
-macros.
+documents.
 .
 .
-.P
-The output image will be clipped to the smallest possible bounding box
-that contains all the black pixels.
+.\" FIXME: How old?  This text hasn't been touched since 2008 at latest.
+.\" Older versions of
+.\" .I \%convert
+.\" will produce a black-on-white graphic; newer ones may produce a
+.\" black-on-transparent graphic.
 .
-Older versions of
-.BR \%convert (1)
-will produce a black-on-white graphic; newer ones may produce a
-black-on-transparent graphic.
+.PP
+Arguments not recognized by
+.I pic2graph
+are passed to the ImageMagick or GraphicsMagick program
+.BR \%convert (1).
 .
-By specifying command-line options to be passed to
-.BR \%convert (1)
-you can give it a border, force the background transparent, set the
-image's pixel density, or perform other useful transformations.
 .
+By specifying these, you can give your image a border,
+.\" Transparent backgrounds are the default in 2018.
+.\" force the background transparent,
+set the image's pixel density,
+or perform other useful transformations.
 .
-.P
-This program uses
-.BR @address@hidden (@MAN1EXT@),
-.BR @address@hidden (@MAN1EXT@),
-.BR groff (@MAN1EXT@),
-.BR gs (1),
-and the ImageMagick
-.BR \%convert (1)
-program.
-These programs must be installed on your system and accessible on your
-$PATH for
-.B pic2graph
-to work.
+.
+.PP
+The output image is clipped using
+.IR convert 's
+.B \-trim
+option to the smallest possible bounding box that contains all the black
+pixels.
 .
 .
 .\" ====================================================================
@@ -106,53 +92,57 @@ to work.
 .TP
 .B \-unsafe
 Run
-.BR @address@hidden (@MAN1EXT@)
-and
-.BR groff (@MAN1EXT@)
-in the \(oqunsafe\(cq mode enabling the PIC macro
+.I groff
+in
+.I unsafe
+mode, enabling the
+.I PIC
+command
 .B sh
-to execute arbitrary commands.
+to execute arbitrary Unix shell commands.
+.
+The
+.I groff
+default is to forbid this.
 .
-The default is to forbid this.
 .
 .TP
-.BI "\-format " fmt
-Specify an output format; the default is PNG (Portable Network Graphics).
+.BI "\-format " output-format
+Write the image in
+.IR output-format ,
+which must be understood by
+.IR convert ;
+the default is PNG.
 .
-Any format that
-.BR \%convert (1)
-can emit is supported.
 .
 .TP
-.BI "\-eqn " delim
-Change the fencepost characters that delimit
-.BR @address@hidden (@MAN1EXT@)
-directives
-.RB ( $
-and
-.BR $ ,
-by default).
-.
-This option requires an argument, but an empty string is accepted as a
-directive to disable
-.BR @address@hidden (@MAN1EXT@)
+.BI "\-eqn " delimeters
+Use
+.I delimeters
+as the opening and closing
+characters that delimit
+.I @address@hidden
+directives;
+the default is \(lq$$\(rq.
+.
+The option argument
+.I delimeters
+should be a two-character string,
+but an empty string (\(dq\(dq) is accepted as a directive to disable
+.I @address@hidden
 processing.
 .
 .
-.PP
-Command-line switches and arguments not listed above are passed to
-.BR \%convert (1).
-.
+.TP
+.B \-\-help
+Display a brief usage message and exit.
 .
-.\" ====================================================================
-.SH FILES
-.\" ====================================================================
 .
 .TP
-.B @MACRODIR@/eqnrc
-The
-.BR @address@hidden (@MAN1EXT@)
-initialization file.
+.B \-\-version
+Display
+.IR pic2graph 's
+version string and exit.
 .
 .
 .\" ====================================================================
@@ -160,26 +150,25 @@ initialization file.
 .\" ====================================================================
 .
 .TP
-.B GROFF_TMPDIR
-The directory in which temporary files will be created.
-.
-If this is not set
-.B pic2graph
-searches the environment variables
-.BR \%TMPDIR ,
-.BR TMP ,
-and
-.B TEMP
-(in that order).
+.B \%GROFF_TMPDIR
+.TQ
+.B \%TMPDIR
+.TQ
+.B \%TMP
+.TQ
+.B \%TEMP
+These environment variables are searched in the given order to determine
+the directory where temporary files will be created.
 .
-Otherwise, temporary files will be created in
-.BR /tmp .
+If none are set,
+.I /tmp
+is used.
 .
 .
 .\" ====================================================================
 .SH AUTHORS
 .\" ====================================================================
-.B pic2graph
+.I pic2graph
 was written by
 .MT address@hidden:thyrsus.com
 Eric S.\& Raymond
@@ -196,8 +185,14 @@ based on a recipe by W.\& Richard Stevens.
 .BR @address@hidden (@MAN1EXT@),
 .BR @address@hidden (@MAN1EXT@),
 .BR groff (@MAN1EXT@),
-.BR gs (1),
-.BR \%convert (1).
+.BR \%convert (1)
+.
+.
+.PP
+W.\& Richard Stevens,
+.UR http://\:www.kohala.com/\:start/\:troff/\:pic2html.html
+.I Turning PIC into HTML
+.UE
 .
 .
 .\" Local Variables: