Generate man pages using help2man (fix #13)

Also use say instead of print where possible in scripts.

Change to output --help and usage messages on stdout rather than stderr.

.gitignore

@@ -1,4 +1,5 @@
 *.o
+*.1
 *~
 psutils*.tar.gz
 /.deps/

.travis.yml

@@ -1,13 +1,20 @@
 # Use language: c because perl builds are not available on macOS
 language: c
 
+addons:
+  homebrew:
+    packages:
+    - help2man
+    update: true
+
 matrix:
   include:
     - os: linux
       addons:
         apt:
           packages:
             - libipc-run3-perl
+            - help2man
     - os: osx
 
 env:

Makefile.am

@@ -71,6 +71,15 @@ install-exec-hook:
 	  mv $(DESTDIR)$(bindir)/paper $(DESTDIR)$(bindir)/paper$(PERL_EXEEXT); \
 	fi
 
+%.1: % %-include.man man-include.man
+## Exit gracefully if $@ is not writeable, such as during distcheck!
+	$(AM_V_GEN)if ( touch $@.w && rm -f $@.w; ) >/dev/null 2>&1; then \
+	  $(srcdir)/pre-inst-env $(top_srcdir)/build-aux/missing --run $(HELP2MAN) --no-info \
+		--include=$(srcdir)/man-include.man \
+		--include=$(srcdir)/$*-include.man \
+		--output=$@ ./$*; \
+	fi
+
 include tests/Makefile.am
 
 loc:

configure.ac

@@ -3,12 +3,19 @@
 
 AC_INIT(psutils, 1.92, rrt@sc3d.org)
 AC_CONFIG_AUX_DIR([build-aux])
-AM_INIT_AUTOMAKE([-Wall -Werror foreign 1.11])
+AM_INIT_AUTOMAKE([-Wall foreign 1.11])
 
 gl_EARLY
 gl_INIT
 AC_PATH_PROG(PERL, perl)
 
+# Require GNU Make
+AX_CHECK_GNU_MAKE([], [AC_MSG_ERROR([make must be GNU Make])])
+
+# help2man
+# Set a value even if not found, so that an invocation via build-aux/missing works
+AC_PATH_PROG([HELP2MAN], [help2man], [help2man])
+
 # Generate output files
 AC_CONFIG_FILES([
   Makefile

epsffit-include.man

@@ -0,0 +1,7 @@
+[NAME]
+epsffit - fit an Encapsulated PostScript file to a given bounding box
+
+/reads from standard input/
+See
+.BR psutils (1)
+for the available units.

epsffit.in.in

@@ -2,7 +2,7 @@
 # -*- perl -*-
 my $version_banner = <<END;
 epsffit @VERSION@
-Copyright (c) Reuben Thomas 2016
+Copyright (c) Reuben Thomas 2016.
 Released under the GPL version 3, or (at your option) any later version.
 END
 
@@ -48,9 +48,9 @@ my ($help_flag, $version_flag, $center, $rotate, $aspect, $maximize, $showpage);
 
 sub usage {
   my ($exit_code) = @_;
-  print STDERR <<END;
-$prog [OPTION...] LLX LLY URX URY [INFILE [OUTFILE]]
-Fit EPSF file into constrained size.
+  print STDOUT <<END;
+Usage: $prog [OPTION...] LLX LLY URX URY [INFILE [OUTFILE]]
+Fit an Encapsulated PostScript file to a given bounding box.
 
   -c, --center         center the image in the given bounding box
   -r, --rotate         rotate the image by 90 degrees counter-clockwise
@@ -59,6 +59,12 @@ Fit EPSF file into constrained size.
   -s, --showpage       append a /showpage to the file to force printing
       --help           display this help and exit
       --version        display version information and exit
+
+(LLX, LLY) are the coordinates of the lower left corner of the box, and
+(URX, URY) the upper right.
+
+If OUTFILE is not specified, writes to standard output.
+If INFILE is not specified, reads from standard input.
 END
   exit $exit_code;
 }
@@ -76,7 +82,7 @@ my $opts = GetOptions(
   "version" => \$version_flag,
  ) or usage(1);
 if ($version_flag) {
-  print STDERR $version_banner;
+  print STDOUT $version_banner;
   exit 0;
 }
 usage(0) if $help_flag;

extractres.1 → extractres-include.man

@@ -1,12 +1,8 @@
-.TH EXTRACTRES 1 "PSUtils"
-.SH NAME
-extractres \- filter to extract resources from a PostScript document
-.SH SYNOPSIS
-.B extractres 
-.RB [ \-m ]
-.RI < document.ps
-.RI > output.ps
-.SH DESCRIPTION
+[NAME]
+extractres - filter to extract resources from a PostScript document
+
+[>DESCRIPTION]
+.PP
 .B Extractres
 extracts resources (fonts, procsets, patterns, files, etc) appearing in a
 PostScript document, and puts appropriate
@@ -27,18 +23,8 @@ The output file can then be put through page re-arrangement filters such as
 or 
 .B pstops
 safely.
-.PP
-The
-.B \-m
-option combines the resources of the same name into one file; this must be
-used for some programs which download fonts a bit at a time.
-.SH AUTHOR
-Written by Angus J. C. Duggan.
-.SH "SEE ALSO"
-.BR psutils (1)
-.SH TRADEMARKS
-.B PostScript
-is a trademark of Adobe Systems Incorporated.
+
+[>AUTHOR]
 .SH BUGS
 .B extractres
 does not alter the

extractres.in.in

@@ -71,11 +71,12 @@ my ($help_flag, $version_flag, $merge);
 
 sub usage {
   my ($exit_code) = @_;
-  print STDERR <<END;
-$prog [OPTION...] [INFILE [OUTFILE]]
+  print STDOUT <<END;
+Usage: $prog [OPTION...] [INFILE [OUTFILE]]
 Filter to extract resources from a PostScript document.
 
   -m, --merge          merge resources of the same name into one file
+                       (needed e.g. for fonts output in multiple blocks)
       --help           display this help and exit
       --version        display version information and exit
 END
@@ -91,7 +92,7 @@ my $opts = GetOptions(
   "version" => \$version_flag,
  ) or usage(1);
 if ($version_flag) {
-  print STDERR $version_banner;
+  print STDOUT $version_banner;
   exit 0;
 }
 usage(0) if $help_flag;

includeres.1 → includeres-include.man

@@ -1,11 +1,8 @@
-.TH INCLUDERES 1 "PSUtils"
-.SH NAME
-includeres \- filter to include resources in a PostScript document
-.SH SYNOPSIS
-.B includeres 
-.RI < document.ps
-.RI > output.ps
-.SH DESCRIPTION
+[NAME]
+includeres - filter to include resources in a PostScript document
+
+[>DESCRIPTION]
+.PP
 .B Includeres
 includes resources (fonts, procsets, patterns, files, etc.) in place of
 .B %%IncludeResource
@@ -24,13 +21,8 @@ The output file can then be put through page re-arrangement filters such as
 or 
 .B pstops
 safely.
-.SH AUTHOR
-Written by Angus J. C. Duggan.
-.SH "SEE ALSO"
-.BR psutils (1)
-.SH TRADEMARKS
-.B PostScript
-is a trademark of Adobe Systems Incorporated.
+
+[>AUTHOR]
 .SH BUGS
 .B includeres
 does not alter the

includeres.in.in

@@ -31,6 +31,7 @@ END
 #
 #                                                                 AJCD 4/4/95
 
+use v5.10;
 use strict;
 use warnings;
 
@@ -71,8 +72,8 @@ my ($help_flag, $version_flag);
 
 sub usage {
   my ($exit_code) = @_;
-  print STDERR <<END;
-$prog [OPTION...] [INFILE [OUTFILE]]
+  print STDOUT <<END;
+Usage: $prog [OPTION...] [INFILE [OUTFILE]]
 Filter to include resources in a PostScript document.
 
       --help           display this help and exit
@@ -89,7 +90,7 @@ my $opts = GetOptions(
   "version" => \$version_flag,
  ) or usage(1);
 if ($version_flag) {
-  print STDERR $version_banner;
+  print STDOUT $version_banner;
   exit 0;
 }
 usage(0) if $help_flag;
@@ -107,8 +108,8 @@ while (<$infile>) {
       print $outfile do { local $/; <RES> };
       close(RES);
     } else {
-      print $outfile "%%IncludeResource: ", join(" ", $type, @res), "\n";
-      print STDERR "$prog: resource `$name' not found\n";
+      say $outfile "%%IncludeResource: ", join(" ", $type, @res);
+      say STDERR "$prog: resource `$name' not found";
     }
   } else {
     print $outfile $_;

m4/ax_check_gnu_make.m4

@@ -0,0 +1,95 @@
+# ===========================================================================
+#    https://www.gnu.org/software/autoconf-archive/ax_check_gnu_make.html
+# ===========================================================================
+#
+# SYNOPSIS
+#
+#   AX_CHECK_GNU_MAKE([run-if-true],[run-if-false])
+#
+# DESCRIPTION
+#
+#   This macro searches for a GNU version of make. If a match is found:
+#
+#     * The makefile variable `ifGNUmake' is set to the empty string, otherwise
+#       it is set to "#". This is useful for including a special features in a
+#       Makefile, which cannot be handled by other versions of make.
+#     * The makefile variable `ifnGNUmake' is set to #, otherwise
+#       it is set to the empty string. This is useful for including a special
+#       features in a Makefile, which can be handled
+#       by other versions of make or to specify else like clause.
+#     * The variable `_cv_gnu_make_command` is set to the command to invoke
+#       GNU make if it exists, the empty string otherwise.
+#     * The variable `ax_cv_gnu_make_command` is set to the command to invoke
+#       GNU make by copying `_cv_gnu_make_command`, otherwise it is unset.
+#     * If GNU Make is found, its version is extracted from the output of
+#       `make --version` as the last field of a record of space-separated
+#       columns and saved into the variable `ax_check_gnu_make_version`.
+#     * Additionally if GNU Make is found, run shell code run-if-true
+#       else run shell code run-if-false.
+#
+#   Here is an example of its use:
+#
+#   Makefile.in might contain:
+#
+#     # A failsafe way of putting a dependency rule into a makefile
+#     $(DEPEND):
+#             $(CC) -MM $(srcdir)/*.c > $(DEPEND)
+#
+#     @ifGNUmake@ ifeq ($(DEPEND),$(wildcard $(DEPEND)))
+#     @ifGNUmake@ include $(DEPEND)
+#     @ifGNUmake@ else
+#     fallback code
+#     @ifGNUmake@ endif
+#
+#   Then configure.in would normally contain:
+#
+#     AX_CHECK_GNU_MAKE()
+#     AC_OUTPUT(Makefile)
+#
+#   Then perhaps to cause gnu make to override any other make, we could do
+#   something like this (note that GNU make always looks for GNUmakefile
+#   first):
+#
+#     if  ! test x$_cv_gnu_make_command = x ; then
+#             mv Makefile GNUmakefile
+#             echo .DEFAULT: > Makefile ;
+#             echo \  $_cv_gnu_make_command \$@ >> Makefile;
+#     fi
+#
+#   Then, if any (well almost any) other make is called, and GNU make also
+#   exists, then the other make wraps the GNU make.
+#
+# LICENSE
+#
+#   Copyright (c) 2008 John Darrington <j.darrington@elvis.murdoch.edu.au>
+#   Copyright (c) 2015 Enrico M. Crisostomo <enrico.m.crisostomo@gmail.com>
+#
+#   Copying and distribution of this file, with or without modification, are
+#   permitted in any medium without royalty provided the copyright notice
+#   and this notice are preserved. This file is offered as-is, without any
+#   warranty.
+
+#serial 12
+
+AC_DEFUN([AX_CHECK_GNU_MAKE],dnl
+  [AC_PROG_AWK
+  AC_CACHE_CHECK([for GNU make],[_cv_gnu_make_command],[dnl
+    _cv_gnu_make_command="" ;
+dnl Search all the common names for GNU make
+    for a in "$MAKE" make gmake gnumake ; do
+      if test -z "$a" ; then continue ; fi ;
+      if "$a" --version 2> /dev/null | grep GNU 2>&1 > /dev/null ; then
+        _cv_gnu_make_command=$a ;
+        AX_CHECK_GNU_MAKE_HEADLINE=$("$a" --version 2> /dev/null | grep "GNU Make")
+        ax_check_gnu_make_version=$(echo ${AX_CHECK_GNU_MAKE_HEADLINE} | ${AWK} -F " " '{ print $(NF); }')
+        break ;
+      fi
+    done ;])
+dnl If there was a GNU version, then set @ifGNUmake@ to the empty string, '#' otherwise
+  AS_VAR_IF([_cv_gnu_make_command], [""], [AS_VAR_SET([ifGNUmake], ["#"])],   [AS_VAR_SET([ifGNUmake], [""])])
+  AS_VAR_IF([_cv_gnu_make_command], [""], [AS_VAR_SET([ifnGNUmake], [""])],   [AS_VAR_SET([ifnGNUmake], ["#"])])
+  AS_VAR_IF([_cv_gnu_make_command], [""], [AS_UNSET(ax_cv_gnu_make_command)], [AS_VAR_SET([ax_cv_gnu_make_command], [${_cv_gnu_make_command}])])
+  AS_VAR_IF([_cv_gnu_make_command], [""],[$2],[$1])
+  AC_SUBST([ifGNUmake])
+  AC_SUBST([ifnGNUmake])
+])