[groff] 02/04: eqn2graph: Parallelize changes with pic2graph.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c100633a9f6be3d65c2566eea894109026f8ae64
Author: G. Branden Robinson <address@hidden>
Date:   Thu Apr 26 03:58:27 2018 -0400

    eqn2graph: Parallelize changes with pic2graph.
    
    contrib/eqn2graph/eqn2graph.sh:
    contrib/eqn2graph/eqn2graph.1.man:
    * Refactor temp directory handling.
    * Handle embedded whitespace in temp dir.
    * Adapt to old convert(1) programs.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 ChangeLog                         |  10 ++
 NEWS                              |  13 +--
 contrib/eqn2graph/eqn2graph.1.man | 207 ++++++++++++++++++--------------------
 contrib/eqn2graph/eqn2graph.sh    |  57 ++++++++---
 4 files changed, 155 insertions(+), 132 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 29564d9..9b9d7c9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2018-04-26  G. Branden Robinson <address@hidden>
+
+       eqn2graph: Parallelize changes with pic2graph.
+
+       contrib/eqn2graph/eqn2graph.sh:
+       contrib/eqn2graph/eqn2graph.1.man:
+       * Refactor temp directory handling.
+       * Handle embedded whitespace in temp dir.
+       * Adapt to old convert(1) programs.
+
 2018-04-25  G. Branden Robinson <address@hidden>
 
        pic2graph: Refactor temp directory handling.
diff --git a/NEWS b/NEWS
index 559f9d6..4d9ad17 100644
--- a/NEWS
+++ b/NEWS
@@ -53,12 +53,13 @@ o New 'configure' option --with-compatibility-wrappers to 
control how groff
   compatibility wrappers for vendor-provided non-GNU macro sets are
   installed (See: ./configure --help).
 
-o pic2graph now attempts to adapt to very old installed versions of the
-  ImageMagick and GraphicsMagick programs "convert".  pic2graph searches the
-  output of convert's "-help" option, and uses "-trim" if that string is
-  found; otherwise, the old "-crop 0x0" method (which produces incompatible
-  results on versions that _do_ support "-trim") is used.  pic2graph emits a
-  warning to standard error if the search fails and the old method is used.
+o eqn2graph and pic2graph now attempt to adapt to very old installed
+  versions of the ImageMagick and GraphicsMagick programs "convert".  They
+  search the output of convert(1)'s "-help" option, and use "-trim" if that
+  string is found; otherwise, the old "-crop 0x0" method (which produces
+  incompatible results on versions that _do_ support "-trim") is used.  The
+  programs emit a warning to standard error if the search fails and the old
+  method is used.
 
 o groffer now supports the output of XHTML.  Use the "--xhtml" or
   "--mode=xhtml" command-line options to generate it.
diff --git a/contrib/eqn2graph/eqn2graph.1.man 
b/contrib/eqn2graph/eqn2graph.1.man
index 47d8492..cd27ced 100644
--- a/contrib/eqn2graph/eqn2graph.1.man
+++ b/contrib/eqn2graph/eqn2graph.1.man
@@ -3,74 +3,82 @@
 eqn2graph \- convert an EQN equation into a cropped image
 .
 .
+.\" ====================================================================
+.\" Legalese
+.\" ====================================================================
+.\"
 .\" This documentation is released to the public domain.
 .
 .
-.\" Like TP, but if specified indent is more than half
-.\" the current line-length - indent, use the default indent.
-.de Tp
-.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
-.el .TP "\\$1"
-..
-.
 .\" ====================================================================
 .SH SYNOPSIS
 .\" ====================================================================
 .
-.B eqn2graph
-[
-.B \-unsafe
-]
-[
-.BI \-format\  fmt
-]
+.SY eqn2graph
+.OP \-unsafe
+.OP \-format output-format
+.RI [ \%convert-arguments ]
+.YS
+.
+.SY eqn2graph
+.B \-\-help
+.SY eqn2graph
+.RB { \-v | \-\-version }
+.YS
 .
 .
 .\" ====================================================================
 .SH DESCRIPTION
 .\" ====================================================================
 .
-Reads an EQN equation (one line) as input; produces an image
-file (by default in Portable Network Graphics format) suitable for the
-Web as output.
+.I eqn2graph
+reads a one-line
+.BR @address@hidden (@MAN1EXT@)
+equation from the standard input and and writes an image file,
+by default in Portable Network Graphics (PNG) format,
+to the standard output.
 .
 .
-.P
-Your input EQN code should
+.PP
+The input
+.I EQN
+code should
 .I not
-have the \&.EQ/.EN preamble that normally precedes it within
+be preceded by the
+.B \&.EQ
+macro that normally precedes it within
 .BR groff (@MAN1EXT@)
-macros; nor do you need to have dollar-sign or other delimiters
-around the equation.
+macros;
+nor do you need to have dollar-sign or other delimiters around the
+equation.
 .
 .
-.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 eqn2graph
+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 groff (@MAN1EXT@),
-and the ImageMagick
-.BR convert (1)
-program.
 .
-These programs must be installed on your system and accessible on your
-$PATH for
-.B eqn2graph
-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.
 .
 .
 .\" ====================================================================
@@ -80,36 +88,41 @@ to work.
 .TP
 .B \-unsafe
 Run
-.BR groff (@MAN1EXT@)
-in the \[lq]unsafe\[rq] 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 default is to forbid this.
+The
+.I groff
+default is to forbid this.
 .
-.TP
-.BI \-format\  fmt
-Specify an output format; the default is PNG (Portable Network Graphics).
 .
-Any format that
-.BR convert (1)
-can emit is supported.
+.TP
+.BI "\-format " output-format
+Write the image in
+.IR output-format ,
+which must be understood by
+.IR convert ;
+the default is PNG.
 .
 .
-.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 \w'address@hidden@/eqnrc'u+2n
-.B @MACRODIR@/eqnrc
-The
-.BR @address@hidden (@MAN1EXT@)
-initialization file.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Display
+.IR pic2graph 's
+version string and exit.
 .
 .
 .\" ====================================================================
@@ -117,58 +130,33 @@ initialization file.
 .\" ====================================================================
 .
 .TP
-.B GROFF_TMPDIR
-The directory in which temporary files will be created.
-.
-If this is not set
-.B eqn2graph
-searches the environment variables
-.BR \%TMPDIR ,
-.BR TMP ,
-and
-.B TEMP
-(in that order).
-.
-Otherwise, temporary files will be created in
-.BR /tmp .
-.
+.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.
 .
-.\" ====================================================================
-.SH BUGS
-.\" ====================================================================
-.
-Due to changes in the behavior of ImageMagick
-.BR convert (1)
-that are both forward and backward-incompatible,
-mismatches between your
-.B eqn2graph
-and
-.BR convert (1)
-versions may produce zero-sized or untrimmed output images.
-.
-For this version of
-.B eqn2graph
-you will need a version of
-.BR convert (1)
-that supports the
-.B \-trim
-option; older versions of
-.B eqn2graph
-used
-.BR \-crop\~0x0 ,
-which no longer has trimming behavior.
+If none are set,
+.I /tmp
+is used.
 .
 .
 .\" ====================================================================
 .SH AUTHORS
 .\" ====================================================================
 .
-
-.B eqn2graph
+.I eqn2graph
 was written by
 .MT address@hidden:thyrsus.com
 Eric S.\& Raymond
-.ME .
+.ME ,
+based on a recipe for
+.BR pic2graph (@MAN1EXT@),
+by W.\& Richard Stevens.
 .
 .
 .\" ====================================================================
@@ -179,8 +167,7 @@ Eric S.\& Raymond
 .BR grap2graph (@MAN1EXT@),
 .BR @address@hidden (@MAN1EXT@),
 .BR groff (@MAN1EXT@),
-.BR gs (1),
-.BR convert (1).
+.BR convert (1)
 .
 .
 .\" Local Variables:
diff --git a/contrib/eqn2graph/eqn2graph.sh b/contrib/eqn2graph/eqn2graph.sh
index ee7cc5f..daa8517 100644
--- a/contrib/eqn2graph/eqn2graph.sh
+++ b/contrib/eqn2graph/eqn2graph.sh
@@ -7,7 +7,7 @@
 # In Unixland, the magic is in knowing what to string together...
 #
 # Take an eqn equation on stdin, emit cropped bitmap on stdout.
-# The pic markup should *not* be wrapped in .EQ/.EN, this script will do that.
+# The eqn markup should *not* be wrapped in .EQ/.EN, this script will do that.
 # A -U option on the command line enables gpic/groff "unsafe" mode.
 # A -format FOO option changes the image output format to any format
 # supported by convert(1).  All other options are passed to convert(1).
@@ -34,6 +34,7 @@
 #
 groff_opts=""
 convert_opts=""
+convert_trim_arg="-trim"
 format="png"
 
 while [ "$1" ]
@@ -58,22 +59,45 @@ done
 
 # create temporary directory
 tmp=
-for d in "$GROFF_TMPDIR" "$TMPDIR" "$TMP" "$TEMP" /tmp; do
-    test -z "$d" && continue
+for d in "$GROFF_TMPDIR" "$TMPDIR" "$TMP" "$TEMP" /tmp
+do
+    test -n "$d" && break
+done
+
+if ! test -d "$d"
+then
+    echo "$0: error: temporary directory \"$d\" does not exist or is" \
+        "not a directory" >&2
+    exit 1
+fi
 
-    tmp=`(umask 077 && mktemp -d -q "$d/eqn2graph-XXXXXX") 2> /dev/null` \
-    && test -n "$tmp" && test -d "$tmp" \
-    && break
+if ! tmp=`(umask 077 && mktemp -d -q "$d/pic2graph-XXXXXX") 2> /dev/null`
+then
+    # mktemp failed--not installed or is a version that doesn't support those
+    # flags?  Fall back to older method which uses more predictable naming.
+    #
+    # $RANDOM is a Bashism.  The fallback of $PPID is not good 
pseudorandomness,
+    # but is supported by the stripped-down dash shell, for instance.
+    tmp="$d/pic2graph$$-${RANDOM:-$PPID}"
+    (umask 077 && mkdir "$tmp") 2> /dev/null
+fi
+
+if ! test -d "$tmp"
+then
+    echo "$0: error: cannot create temporary directory \"$tmp\"" >&2
+    exit 1
+fi
 
-    tmp=$d/eqn2graph$$-$RANDOM
-    (umask 077 && mkdir $tmp) 2> /dev/null && break
-done;
-if test -z "$tmp"; then
-    echo "$0: cannot create temporary directory" >&2
-    { (exit 1); exit 1; }
+# See if the installed version of convert(1) is new enough to support the -trim
+# option.  Versions that didn't were described as "old" as early as 2008.
+is_convert_recent=`convert -help | grep -e -trim`
+if test -z "$is_convert_recent"
+then
+    echo "$0: warning: falling back to old '-crop 0x0' trim method" >&2
+    convert_trim_arg="-crop 0x0"
 fi
 
-trap 'exit_status=$?; rm -rf $tmp && exit $exit_status' EXIT INT TERM
+trap 'exit_status=$?; rm -rf "$tmp" && exit $exit_status' EXIT INT TERM
 
 # Here goes:
 # 1. Add .EQ/.EN.
@@ -82,8 +106,9 @@ trap 'exit_status=$?; rm -rf $tmp && exit $exit_status' EXIT 
INT TERM
 # 4. Use convert(1) to crop the Postscript and turn it into a bitmap.
 read equation
 (echo ".EQ"; echo 'delim $$'; echo ".EN"; echo '$'"$equation"'$') | \
-       groff -e $groff_opts -Tps -P-pletter > $tmp/eqn2graph.ps \
-       && convert -trim $convert_opts $tmp/eqn2graph.ps $tmp/eqn2graph.$format 
\
-       && cat $tmp/eqn2graph.$format
+       groff -e $groff_opts -Tps -P-pletter > "$tmp"/eqn2graph.ps \
+       && convert $convert_trim_arg $convert_opts "$tmp"/eqn2graph.ps \
+          "$tmp"/eqn2graph.$format \
+       && cat "$tmp"/eqn2graph.$format
 
 # End