explain option name conventions

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

3 files changed, 21 insertions, 13 deletions

diff --git a/Build/source/extra/epstopdf/Makefile b/Build/source/extra/epstopdf/Makefile
index 878b8ee9b94..a8f00f62dd7 100644
--- a/Build/source/extra/epstopdf/Makefile
+++ b/Build/source/extra/epstopdf/Makefile
@@ -92,6 +92,7 @@ check1:
 dist: epstopdf.tar.gz epstopdf.html
 epstopdf.tar.gz: README epstopdf.pl epstopdf.1 repstopdf.1 epstopdf.man1.pdf
 	tar czf epstopdf.tar.gz $^
+	# upload .tar.gz to ctan.org/upload, move .html to ~www/epstopdf.
 
 groff = groff
 groff_opts = -man -t
@@ -102,5 +103,3 @@ epstopdf.man1.pdf: epstopdf.1
 	$(groff) $(pdfopts) $< | $(pspdf) - $@
 epstopdf.html: epstopdf.1
 	$(groff) $(htmlopts) $< >$@
-
-# upload .tar.gz to ctan.org/upload, move .html to ~www/epstopdf.
diff --git a/Build/source/extra/epstopdf/epstopdf.1 b/Build/source/extra/epstopdf/epstopdf.1
index 019548a26f4..fd0f9e0eb40 100644
--- a/Build/source/extra/epstopdf/epstopdf.1
+++ b/Build/source/extra/epstopdf/epstopdf.1
@@ -1,4 +1,4 @@
-.TH EPSTOPDF 1 "18 March 2010"
+.TH EPSTOPDF 1 "12 May 2013"
 .\" $Id$
 .SH NAME
 epstopdf, repstopdf \- convert an EPS file to PDF
@@ -14,6 +14,11 @@ result is piped to Ghostscript and a PDF version written.
 .P
 If the bounding box is not right, of course, there are problems.
 .SH OPTIONS
+Options may start with either "\fB-\fP" or "\fB--\fP", and may be
+unambiguously abbreviated.  (It is best to use the full option name in
+scripts, though, to avoid possible collisions with new options in the
+future.)
+.PP
 .IP "\fB--outfile\fP=\fIfile\fP"
 write result to \fIfile\fP.  If this option is not given, and
 \fB--nogs\fP or \fB--filter\fP is specified, write to standard output;
@@ -53,13 +58,13 @@ display help message and exit
 .IP "\fB--version\fP
 display version information and exit
 .SH EXAMPLES
-Examples which produce "test.pdf":
+Examples all equivalently producing "test.pdf":
 .nf
 epstopdf test.eps
-produce postscript | epstopdf --filter >test.pdf
-produce postscript | epstopdf -f -d -o=test.pdf
+cat test.eps | epstopdf --filter >test.pdf
+cat test.eps | epstopdf -f -d -o=test.pdf
 .fi
-Example: look for HiresBoundingBox and produce corrected PostScript:
+Example to look for HiResBoundingBox and produce corrected PostScript:
 .nf
 epstopdf -d --nogs --hires test.ps >testcorr.ps 
 .fi
diff --git a/Build/source/extra/epstopdf/epstopdf.pl b/Build/source/extra/epstopdf/epstopdf.pl
index 0e3c5510089..c3496958187 100755
--- a/Build/source/extra/epstopdf/epstopdf.pl
+++ b/Build/source/extra/epstopdf/epstopdf.pl
@@ -215,18 +215,22 @@ Options:
   --gscmd=VAL        pipe output to VAL    (default: $GS)
   --res=DPI          set image resolution  (default: $resmsg)
   --autorotate=VAL   set AutoRotatePages   (default: $rotmsg)
-                      Recognized VAL choices: None, All, PageByPage
-                      For EPS files, PageByPage is equivalent to All
+                      Recognized VAL choices: None, All, PageByPage;
+                      for EPS files, PageByPage is equivalent to All.
   --restricted       use restricted mode   (default: $bool[$restricted])
 
-Examples producing test.pdf:
+Examples all equivalently producing test.pdf:
   * $program test.eps
-  * produce postscript | $program --filter >test.pdf
-  * produce postscript | $program -f -d -o=test.pdf
+  * cat test.eps | $program --filter >test.pdf
+  * cat test.eps | $program -f -o=test.pdf
 
-Example: look for HiResBoundingBox and produce corrected PostScript:
+Example to look for HiResBoundingBox and produce corrected PostScript:
   * $program -d --nogs --hires test.ps >testcorr.ps
 
+Options may start with either - or --, and may be unambiguously
+abbreviated.  It is best to use the full option name in scripts, though,
+to avoid possible collisions with new options in the future.
+
 When reporting bugs, please include an input file and command line
 options so the problem can be reproduced.