manpage update

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

6 files changed, 143 insertions, 27 deletions

diff --git a/Master/texmf/doc/man/man1/ebb.man1.pdf b/Master/texmf/doc/man/man1/ebb.man1.pdf
index 9e7a8b9a346..96cfad1f854 100644
--- a/Master/texmf/doc/man/man1/ebb.man1.pdf
+++ b/Master/texmf/doc/man/man1/ebb.man1.pdf
diff --git a/Master/texmf/doc/man/man1/extractbb.1 b/Master/texmf/doc/man/man1/extractbb.1
index d6d98af5d8c..82c9715e681 100644
--- a/Master/texmf/doc/man/man1/extractbb.1
+++ b/Master/texmf/doc/man/man1/extractbb.1
@@ -1,4 +1,4 @@
-.TH "EXTRACTBB" "1" "28 April 2011" "20110311" "DVIPDFMx"
+.TH "EXTRACTBB" "1" "6 May 2011" "20110311" "DVIPDFMx"
 .PP 
 .SH "NAME" 
 extractbb, ebb \- extract bounding box information from graphics files
@@ -60,9 +60,21 @@ Write output in dvipdfm's ``bb'' format.
 .TP
 .B -x
 Write output in dvipdfmx's ``xbb'' format (default), which is the same
-as that used by the PDF format.
+as that used by pdfTeX.
 .PD
 .PP
+.SH "OUTPUT FORMATS"
+.PP
+Here are more details about the bb and xbb formats:
+.PP
+The original ebb (from dvipdfm) ignored density information in bitmap
+images, and generated bounding boxes with 100px = 72bp = 1in.
+Unfortunately, screenshots (especially) tend to look bad with this
+approach.
+.PP
+So, extractbb (from dvipdfmx) uses density information if present.
+Otherwise, it generates bounding box with 100px = 100bp.  This is what
+pdfTeX does.
 .SH "BUGS"
 .PP
 There is currently no way to specify which bounding box is taken
diff --git a/Master/texmf/doc/man/man1/extractbb.man1.pdf b/Master/texmf/doc/man/man1/extractbb.man1.pdf
index 49edf3de5fd..4dbd0027e28 100644
--- a/Master/texmf/doc/man/man1/extractbb.man1.pdf
+++ b/Master/texmf/doc/man/man1/extractbb.man1.pdf
diff --git a/Master/texmf/doc/man/man1/pdfclose.man1.pdf b/Master/texmf/doc/man/man1/pdfclose.man1.pdf
index 79da000ea35..99a02a1aa5e 100644
--- a/Master/texmf/doc/man/man1/pdfclose.man1.pdf
+++ b/Master/texmf/doc/man/man1/pdfclose.man1.pdf
diff --git a/Master/texmf/doc/man/man1/pdfopen.1 b/Master/texmf/doc/man/man1/pdfopen.1
index a98a623a95b..9531dfadd56 100644
--- a/Master/texmf/doc/man/man1/pdfopen.1
+++ b/Master/texmf/doc/man/man1/pdfopen.1
@@ -1,53 +1,157 @@
 .\" This manpage is licensed under the GNU Public License
-.TH PDFOPEN 1 2011-05-17  "pdfopen version 0.81" ""
-
+.TH PDFOPEN 1 2011-05-17  "pdfopen 0.82" ""
+.
 .SH NAME
-pdfopen \- open or close a PDF file viewer
-
+pdfopen, pdfclose \- open or close a PDF file viewer
+.
 .SH SYNOPSIS
-pdfopen 
-[
-.IR option
-] 
-<file.pdf>
+.B pdfopen 
+[\fIOPTION\fP] 
+\fIFILE.PDF\fP
 .br
-pdfclose <file.pdf>
-
+.B pdfclose
+\fIFILE.PDF\fP
+.
 .SH OPTIONS
 .TP 8
-.B -h
-output help
+.B -h, --help
+output help and exit
 .TP
-.B --help
-output help
+.B -v, --version
+output the version number and exit
 .TP
-.B -viewer <ar9|ar9tab|ar8|ar7|ar5|xpdf|evince>
+.B -viewer
+<\fIar9\fP|\fIar9-tab\fP|\fIar8\fP|\fIar7\fP|\fIar5\fP|\fIxpdf\fP|\fIevince\fP>
 use (respectively) Adobe Reader 9 (in a new window), Adobe Reader 9
 (in a new tab of a running AR9, if any),
 Adobe Reader 8, Adobe Reader 7, Adobe Reader 5, xpdf or evince as the
 PDF viewer program.
-Adobe Reader (in a new window) is the default.
+Adobe Reader 9 (in a new window) is the default.
+.
+.SH RATIONALE
+At certain points of TeX document preparation, many people repeat a
+"edit-compile-view" cycle.  Since PDF viewers such as Adobe's Acrobat
+Reader ("\fBacroread\fP") do not automatically refresh the display when the
+PDF file changes, this cycle can be more cumbersome than desired.
+The
+.B pdfopen
+program provides the ability to automate the reloading of the PDF
+document when it is changed.
 
+Note: there seems to be little need for
+.B pdfclose
+under GNU/Linux, since (unlike the situation for MS windows)
+.B acroread
+does not lock the PDF file, which would prevent
+.B pdftex
+(or a DVI to PDF converter) from creating a new version of the PDF
+output file.  However,
+.B pdfclose
+is provided in case someone finds it useful.
+.
 .SH DESCRIPTION
 .B pdfopen
-displays the specified PDF file using the given (or default) viewer.
+searches for an instance of the specified (or default) PDF viewer
+displaying the specified PDF file.
 If there is already an instance of the given viewer displaying the
-given file, the viewer is instructed to reload the file.
+given file, the viewer is instructed to reload the file.  If no such
+instance is found, \fBpdfopen\fP attempts to run the specified viewer
+on the specified document.
+
+The default viewer is "\fBacroread\fP", which could start any one
+of a number of versions of Acrobat Reader, depending on what is
+installed on your system.  However, the commands to reload the current
+document vary from one version of \fBacroread\fP to another;
+consequently, if you are using a version of \fBacroread\fP other than
+AR9, you should explicitly specify the viewer program.
+
+Version 0.81 of \fBpdfopen\fP accepts the following viewer options:
+.br
+\fIar9\fP, \fIar9-tab\fP, \fIar8\fP, \fIar7\fP, \fIar5\fP, \fIxpdf\fP,
+and \fIevince\fP.
+.br
+The difference between \fIar9\fP and \fIar9-tab\fP is significant
+when there is no instance of AR9 already displaying the requested
+document.  In this situation, while \fIar9\fP will
+request \fBacroread\fP to create a new instance of \fBacroread\fP
+(and thus open a new window) by using the \fB-openInNewInstance\fP
+argument, \fIar9-tab\fP starts \fBacroread\fP without this argument;
+if there is already an instance of \fBacroread\fP running, a new
+tab will be opened in an existing window.
 
 .B pdfclose
 searches for one of the above PDF viewers displaying the given file
-and instructs the viewer to close the window.
+and instructs the viewer to "close" the window.  In most cases, the
+PDF viewer continues to run, possibly now displaying just a blank
+window.  (This behaviour varies somewhat from one PDF viewer to another.)
+.
+.SH PORTABILITY AND AVAILABILITY
+Users familiar with the Windows version of
+.B pdfopen
+might wonder about the lack of a
+.B --page
+.IR <pagenumber>
+option.  Unfortunately, to date no GNU/Linux versions of
+.B acroread
+support this feature.  Anyone having a friend at Adobe is encouraged
+to ask them to implement a
+"\fB-page \fP\fI<pagenumber>\fP"
+command line option for \fBacroread\fP.
 
-.SH NOTES
-If the file argument to
-.B pdfclose
-is shown in a tab-capable viewer (such as Adobe Reader 9), the tab
-displaying the file is closed, but the window itself is not closed.
+These programs have been tested on Slackware64 Version 13.1 and a few
+other versions / distributions of GNU/Linux.  The code is reasonably
+generic and should work out of the box using most recent X11
+implementations.  (Reports to the contrary are welcome, particularly
+if they come with robust fixes.)
 
 These programs are designed for X11-based systems.  If you somehow
 find compiled versions of these programs on a system using another
 window system, they are very unlikely to be of any use to you.
 
+Source and binaries of the programs can be downloaded from 
+CTAN://support/xpdfopen/
+(e.g., http://mirror.ctan.org/support/xpdfopen).
+.
+.SH CAVEATS
+If you use
+.I ar9-tab
+to reload the PDF document and the instance
+of
+.B acroread
+with the given document is currently displaying some other document,
+the command causes your document to be displayed, but not reloaded.
+
+.B pdfopen
+works by looking for a window with a name (window title) matching that
+expected for the given viewer and document.  If for some reason your
+viewer's window name is not as expected,
+.B pdfopen
+may not work for you.
 
+With at least AR9 and some window managers, using
+.B pdfopen
+to reload the document gives focus to the
+.B acroread
+window, even though the mouse cursor is not necessarily in that
+window.  This can be annoying.  A contribution from an X11 wizard to
+retain focus in the current window (or to restore focus to that
+window after reloading the PDF document) would be cheerily accepted.
+.
 .SH AUTHOR 
 This manual page was written by Jim Diamond <Jim.Diamond@acadiau.ca>.
+I am the current maintainer of the X11 versions of
+.B pdfopen
+and
+\fBpdfclose\fP.
+Report any bugs you find to me.  Feature enhancement requests are
+welcome, coded enhancements even more so.
+
+Past authors:
+Fabrice Popineau wrote the MS-windows versions of
+.B pdfopen
+and
+.B pdfclose
+upon which these programs were originally based.
+Taco Hoekwater created the GNU/Linux versions, up to Version 0.61
+(including some documentation which inspired parts of this man page).
+
diff --git a/Master/texmf/doc/man/man1/pdfopen.man1.pdf b/Master/texmf/doc/man/man1/pdfopen.man1.pdf
index 522377e4de4..bdcee4ec1e5 100644
--- a/Master/texmf/doc/man/man1/pdfopen.man1.pdf
+++ b/Master/texmf/doc/man/man1/pdfopen.man1.pdf