2.21: help message improvements per dek

git-svn-id: svn://tug.org/texlive/trunk@32701 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 64 insertions, 36 deletions

diff --git a/Build/source/extra/epstopdf/Makefile b/Build/source/extra/epstopdf/Makefile
index 226d1206c4e..8e188e18c48 100644
--- a/Build/source/extra/epstopdf/Makefile
+++ b/Build/source/extra/epstopdf/Makefile
@@ -1,9 +1,10 @@
 # $Id$
 # This file is public domain.  (Originally written by Karl Berry, 2009.)
 
-e2p = ./epstopdf.pl #--debug
-re2p = ./repstopdf --restricted
-re2p_script = ./repstopdf
+prg = epstopdf
+e2p = ./$(prg).pl #--debug
+re2p = ./r$(prg) --restricted
+re2p_script = ./r$(prg)
 
 default: check
 
@@ -17,7 +18,7 @@ check: check-help check-version \
        check-filter check-filter-outfile check-write-error check-gscmd \
        check-simple check-atend check-binary check-bin2 \
        check-binhdr-lf check-binhdr-cr check-binhdr-crlf \
-       check-tn5002 check-floral
+       check-tn5002 #check-floral
 
 # needs new kpsewhich: check-restricted-safe-in check-restricted-safe-out
 check-help:
@@ -35,7 +36,7 @@ check-nogs:
 	cmp -s test-simple.eps test-simple.out || exit 0
 	
 $(re2p_script):
-	ln -s epstopdf.pl $@
+	ln -s $(prg).pl $@
 
 check-restricted-gscmd:
 	! $(re2p) --gscmd=/bin/unsafe test-simple.eps
@@ -112,20 +113,23 @@ check1:
 	pdfinfo $(file).pdf | grep "Page size"
 
 # put tar contents in a directory for CTAN.
-dist: epstopdf.tar.gz epstopdf.html
-epstopdf.tar.gz: README epstopdf.pl epstopdf.1 repstopdf.1 epstopdf.man1.pdf
-	rm -rf epstopdf; mkdir epstopdf
-	cp $^ epstopdf
-	tar czf epstopdf.tar.gz epstopdf
-	rm -rf epstopdf
-	# upload .tar.gz to ctan.org/upload, move .html to ~www/epstopdf.
+dist: $(prg).tar.gz $(prg).html
+.PHONY: dist
+$(prg).tar.gz: README $(prg).pl $(prg).1 r$(prg).1 $(prg).man1.pdf
+	rm -rf $(prg); mkdir $(prg)
+	cp $^ $(prg)
+	tar cvzf $(prg).tar.gz $(prg)
+	rm -rf $(prg)
+	# upload .tar.gz to ctan.org/upload, move .html to ~www/$(prg).
 
 groff = groff
 groff_opts = -man -t
-pdfopts = $(groff_opts)
-htmlopts = $(groff_opts) -Thtml
 pspdf = ps2pdf -sPAPERSIZE=a4
-epstopdf.man1.pdf: epstopdf.1
-	$(groff) $(pdfopts) $< | $(pspdf) - $@
-epstopdf.html: epstopdf.1
-	$(groff) $(htmlopts) $< >$@
+$(prg).man1.pdf: $(prg).1
+	$(groff) $(groff_opts) $< | $(pspdf) - $@
+$(prg).html: $(prg).1
+	$(groff) $(groff_opts) -Thtml $< >$@
+show-man:
+	man ./$(prg).1 | col -b
+#	$(groff) $(groff_opts) -Tascii -M. -mraggedright -P-cbouU $(prg).1
+# -P-c... avoids ANSI color sequences and backspaces in the output.
diff --git a/Build/source/extra/epstopdf/README b/Build/source/extra/epstopdf/README
index 8d8eb583288..18ca6aff779 100644
--- a/Build/source/extra/epstopdf/README
+++ b/Build/source/extra/epstopdf/README
@@ -8,6 +8,8 @@ Primary distribution point: http://mirror.ctan.org/support/epstopdf/
 
 Home page: http://tug.org/epstopdf/
 
+Run epstopdf --help for the usual list of options, examples, etc.
+
 Mailing list for bugs and discussion: http://lists.tug.org/tex-k
 When reporting bugs, please include an input file and command line
 options, so the problem can be reproduced.
diff --git a/Build/source/extra/epstopdf/epstopdf.1 b/Build/source/extra/epstopdf/epstopdf.1
index bac45ea9e5f..492e77520c4 100644
--- a/Build/source/extra/epstopdf/epstopdf.1
+++ b/Build/source/extra/epstopdf/epstopdf.1
@@ -1,20 +1,23 @@
-.TH EPSTOPDF 1 "28 September 2013"
+.TH EPSTOPDF 1 "17 January 2014"
 .\" $Id$
 .SH NAME
 epstopdf, repstopdf \- convert an EPS file to PDF
 .SH SYNOPSIS
 \fBepstopdf\fP [\fIoptions\fP] [\fIepsfile\fP]
 .SH DESCRIPTION
-\fBepstopdf\fP transforms the Encapsulated PostScript file \fIepsfile\fP
+By default, \fBepstopdf\fP converts the input PostScript file to PDF,
+using Ghostscript.
+.PP
+\fBEpstopdf\fP transforms the Encapsulated PostScript file \fIepsfile\fP
 (or standard input) so that it is guaranteed to start at the 0,0
 coordinate, and it sets a page size exactly corresponding to the
 BoundingBox.  Thus, the result needs no cropping, and the PDF MediaBox
-is correct.  By default, the input is converted to PDF using Ghostscript.
+is correct.  
 .PP
 PJL commands at the start of a file are removed.  DOS EPS binary files
 (TN 5002) are supported.
 .PP
-If the bounding box in the input file is not right, of course there will
+If the bounding box in the input is incorrect, of course there will
 be resulting problems.
 .SH OPTIONS
 Options may start with either "\fB-\fP" or "\fB--\fP", and may be
@@ -98,17 +101,25 @@ known to be safe; some options taking booleans, integers or fixed
 names are allowed, those taking general strings are not.
 
 .SH EXAMPLES
-Examples all equivalently producing `test.pdf':
+Examples all equivalently converting `test.eps' to `test.pdf':
 .nf
 epstopdf test.eps
 cat test.eps | epstopdf --filter >test.pdf
-cat test.eps | epstopdf -f -d -o=test.pdf
+cat test.eps | epstopdf -f -o=test.pdf
 .fi
 .PP
-Example to look for HiResBoundingBox and produce corrected PostScript:
+Example for using HiResBoundingBox instead of BoundingBox:
 .nf
-epstopdf -d --nogs --hires test.ps >testcorr.ps 
+epstopdf --hires test.eps
 .fi
+.PP
+Example for producing \fBepstopdf\fP's attempt at corrected PostScript:
+.nf
+$program --nogs test.ps >testcorr.ps
+.fi
+.PP
+In all cases, you can add \fB--debug\fP (\fB-d\fP) to see more about
+what \fBepstopdf\fP is doing.
 .SH BUGS
 The case of "%%BoundingBox: (atend)" when input is not seekable (e.g.,
 from a pipe) is not supported.
diff --git a/Build/source/extra/epstopdf/epstopdf.pl b/Build/source/extra/epstopdf/epstopdf.pl
index c09219c0fc4..97d0109ddc7 100755
--- a/Build/source/extra/epstopdf/epstopdf.pl
+++ b/Build/source/extra/epstopdf/epstopdf.pl
@@ -34,7 +34,11 @@
 # "%%BoundingBox: (atend)" when input is not seekable (e.g., from a pipe),
 #
 # emacs-page
+my $ver = "2.21";
+
 # History
+#  2014/01/17 v2.21 (Karl Berry)
+#    * tweaks to help message, per reports from Knuth.
 #  2013/09/28 v2.20 (Heiko Oberdiek, and (a little) Karl Berry)
 #    * New command line argument --(no)safer which allows setting
 #      -dNOSAFER instead of -dSAFER (only for non-restricted).
@@ -161,9 +165,9 @@
 ### emacs-page
 ### program identification
 my $program = "epstopdf";
-my $ident = '($Id$) 2.18';
+my $ident = '($Id$)' . " $ver";
 my $copyright = <<END_COPYRIGHT ;
-Copyright 2009-2013 Karl Berry et al.
+Copyright 2009-2014 Karl Berry et al.
 Copyright 2002-2009 Gerben Wierda et al.
 Copyright 1998-2001 Sebastian Rahtz et al.
 License RBSD: Revised BSD <http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5>
@@ -340,7 +344,7 @@ The resulting output is guaranteed to start at the 0,0 coordinate, and
 sets a page size exactly corresponding to the BoundingBox.  Thus, the
 result does not need any cropping, and the PDF MediaBox is correct.
 
-If the bounding box in the input EPS is not right, of course there will
+If the bounding box in the input is incorrect, of course there will
 be resulting problems.
 
 Options:
@@ -348,12 +352,13 @@ Options:
   --version          display version information and exit
 
   --outfile=FILE     write result to FILE   (default based on input name)
-  --(no)debug        write debugging info   (default: $bool[$::opt_debug])
+  --restricted       use restricted mode    (default: $bool[$restricted])
+
+  --(no)debug        output debugging info  (default: $bool[$::opt_debug])
   --(no)exact        scan ExactBoundingBox  (default: $bool[$::opt_exact])
   --(no)filter       read standard input    (default: $bool[$::opt_filter])
   --(no)gs           run ghostscript        (default: $bool[$::opt_gs])
   --(no)hires        scan HiResBoundingBox  (default: $bool[$::opt_hires])
-  --restricted       use restricted mode    (default: $bool[$restricted])
 
 Options for Ghostscript:
   --gscmd=VAL        pipe output to VAL     (default: $GS)
@@ -373,13 +378,19 @@ Options for Ghostscript:
                        ignored if option --debug is set.
   --(no)safer        use -d(NO)SAFER        (default: $bool[$::opt_safer])
 
-Examples producing test.pdf:
+Examples all equivalently converting test.eps to test.pdf:
   \$ $program test.eps
   \$ cat test.eps | $program --filter >test.pdf
   \$ cat test.eps | $program -f -o=test.pdf
 
-Example to look for HiResBoundingBox and produce corrected PostScript:
-  \$ $program -d --nogs --hires test.ps >testcorr.ps
+Example for using HiResBoundingBox instead of BoundingBox:
+  \$ $program --hires test.eps
+
+Example for producing epstopdf's attempt at corrected PostScript:
+  \$ $program --nogs test.ps >testcorr.ps
+
+In all cases, you can add --debug (-d) to see more about what epstopdf
+is doing.
 
 More about the options for Ghostscript:
   Additional options to be used with gs can be specified
@@ -419,7 +430,7 @@ GetOptions (
   "gscmd=s",              # \ref{val_gscmd}
   "gsopt=s@",             # \ref{val_gsopt}
   "gsopts=s" => \&gsopts, # \ref{val_gsopts}
-  "help",
+  "help|h",
   "hires!",
   "outfile=s",            # \ref{openout_any}
   "pdfsettings=s",
@@ -428,7 +439,7 @@ GetOptions (
   "restricted",
   "safer!",
   "version",
-) or die $usage;
+) or die "Try $0 --help for more information\n";
 
 ### disable --quiet if option --debug is given
 $::opt_quiet = 0 if $::opt_debug;