summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/pdfopen.1
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/pdfopen.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/pdfopen.1160
1 files changed, 160 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/man/man1/pdfopen.1 b/Master/texmf-dist/doc/man/man1/pdfopen.1
new file mode 100644
index 00000000000..82239785469
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/pdfopen.1
@@ -0,0 +1,160 @@
+.\" This manpage is licensed under the GNU Public License
+.TH PDFOPEN 1 2012-01-28 "pdfopen 0.83" ""
+.
+.SH NAME
+pdfopen, pdfclose \- open or close a PDF file viewer
+.
+.SH SYNOPSIS
+.B pdfopen
+[\fIOPTION\fP]
+\fIFILE.PDF\fP
+.br
+.B pdfclose
+\fIFILE.PDF\fP
+.
+.SH OPTIONS
+.TP 8
+.B -h, --help
+output help and exit
+.TP
+.B -v, --version
+output the version number and exit
+.TP
+.B -r, --reset_focus
+after sending commands to the PDF viewer, attempt to reset the input focus to
+the window which had focus before the commands were sent
+.TP
+.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 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
+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. 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.83 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. 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.
+
+These programs have been tested on Slackware64 Version 13.37 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. The \fB-reset_focus\fP option can be
+used to deal with this problem.
+.
+.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).
+