| 1 |
.\" This manpage is licensed under the GNU Public License |
| 2 |
.TH PDFOPEN 1 2014-05-24 "pdfopen 0.86" "" |
| 3 |
. |
| 4 |
.SH NAME |
| 5 |
pdfopen, pdfclose \- open or close a PDF file viewer |
| 6 |
. |
| 7 |
.SH SYNOPSIS |
| 8 |
.B pdfopen |
| 9 |
[ \fIoptions\fP ]\ |
| 10 |
[ |
| 11 |
.B --file |
| 12 |
]\ |
| 13 |
\fIfile.pdf\fP |
| 14 |
.br |
| 15 |
.B pdfclose |
| 16 |
[ |
| 17 |
.B --file |
| 18 |
]\ |
| 19 |
\fIfile.pdf\fP |
| 20 |
. |
| 21 |
.SH OPTIONS |
| 22 |
.TP 8 |
| 23 |
.B -h, --help, -? |
| 24 |
output help and exit. |
| 25 |
.TP |
| 26 |
.B -v, --version, -V |
| 27 |
output the version number and exit. |
| 28 |
.TP |
| 29 |
.B -p <n>, --page <n> |
| 30 |
when starting the viewer, display page <n> of the document (notes: not |
| 31 |
all viewers support this feature, and even in those cases this option |
| 32 |
only has effect when the document is initially loaded). This option |
| 33 |
is over-ridden by \fB-g\fP. |
| 34 |
.TP |
| 35 |
.B -g <named destination>, --goto <named destination> |
| 36 |
when starting the viewer, display the page of the document containing |
| 37 |
the named destination (notes: not all viewers support this feature, |
| 38 |
and even in those cases this option only has effect when the document |
| 39 |
is initially loaded). |
| 40 |
.TP |
| 41 |
.B -r, --reset_focus |
| 42 |
after sending commands to the PDF viewer, attempt to reset the input focus to |
| 43 |
the window which had focus before the commands were sent. |
| 44 |
.TP |
| 45 |
.B -viewer, --viewer <\fIar9\fP|\fIar9-tab\fP|\fIar8\fP|\fIar7\fP|\fIar5\fP|\fIxpdf\fP|\fIevince\fP> |
| 46 |
use (respectively) Adobe Reader 9 (in a new window), Adobe Reader 9 |
| 47 |
(in a new tab of a running AR9, if any), |
| 48 |
Adobe Reader 8, Adobe Reader 7, Adobe Reader 5, xpdf or evince as the |
| 49 |
PDF viewer program. |
| 50 |
Adobe Reader 9 (in a new window) is the default. |
| 51 |
. |
| 52 |
.SH RATIONALE |
| 53 |
At certain points of TeX document preparation, many people repeat a |
| 54 |
"edit-compile-view" cycle. Since PDF viewers such as Adobe's Acrobat |
| 55 |
Reader ("\fBacroread\fP") do not automatically refresh the display when the |
| 56 |
PDF file changes, this cycle can be more cumbersome than desired. |
| 57 |
The |
| 58 |
.B pdfopen |
| 59 |
program provides the ability to automate the reloading of the PDF |
| 60 |
document when it is changed. |
| 61 |
|
| 62 |
Note: there seems to be little need for |
| 63 |
.B pdfclose |
| 64 |
under GNU/Linux, since (unlike the situation for MS windows) |
| 65 |
.B acroread |
| 66 |
does not lock the PDF file, which would prevent |
| 67 |
.B pdftex |
| 68 |
(or a DVI to PDF converter) from creating a new version of the PDF |
| 69 |
output file. However, |
| 70 |
.B pdfclose |
| 71 |
is provided in case someone finds it useful. |
| 72 |
. |
| 73 |
.SH DESCRIPTION |
| 74 |
.B pdfopen |
| 75 |
searches for an instance of the specified (or default) PDF viewer |
| 76 |
displaying the specified PDF file. |
| 77 |
If there is already an instance of the given viewer displaying the |
| 78 |
given file, the viewer is instructed to reload the file. If no such |
| 79 |
instance is found, \fBpdfopen\fP attempts to run the specified viewer |
| 80 |
on the specified document. |
| 81 |
|
| 82 |
The default viewer is "\fBacroread\fP", which could start any one |
| 83 |
of a number of versions of Acrobat Reader, depending on what is |
| 84 |
installed on your system. However, the commands to reload the current |
| 85 |
document vary from one version of \fBacroread\fP to another; |
| 86 |
consequently, if you are using a version of \fBacroread\fP other than |
| 87 |
AR9, you should explicitly specify the viewer program. |
| 88 |
|
| 89 |
This version of \fBpdfopen\fP accepts the following viewer options: |
| 90 |
.br |
| 91 |
\fIar9\fP, \fIar9-tab\fP, \fIar8\fP, \fIar7\fP, \fIar5\fP, \fIxpdf\fP, |
| 92 |
and \fIevince\fP. |
| 93 |
.br |
| 94 |
The difference between \fIar9\fP and \fIar9-tab\fP is significant |
| 95 |
when there is no instance of AR9 already displaying the requested |
| 96 |
document. In this situation, while \fIar9\fP will |
| 97 |
request \fBacroread\fP to create a new instance of \fBacroread\fP |
| 98 |
(and thus open a new window) by using the \fB-openInNewInstance\fP |
| 99 |
argument, \fIar9-tab\fP starts \fBacroread\fP without this argument; |
| 100 |
if there is already an instance of \fBacroread\fP running, a new |
| 101 |
tab will be opened in an existing window. |
| 102 |
|
| 103 |
.B pdfclose |
| 104 |
searches for one of the above PDF viewers displaying the given file |
| 105 |
and instructs the viewer to "close" the window. In most cases, the |
| 106 |
PDF viewer continues to run, possibly now displaying just a blank |
| 107 |
window. (This behaviour varies somewhat from one PDF viewer to another.) |
| 108 |
. |
| 109 |
.SH PORTABILITY AND AVAILABILITY |
| 110 |
These programs have been tested on Slackware64 Version 14.1 and a few |
| 111 |
other versions / distributions of GNU/Linux. The code is reasonably |
| 112 |
generic and should work out of the box using most recent X11 |
| 113 |
implementations. (Reports to the contrary are welcome, particularly |
| 114 |
if they come with robust fixes.) |
| 115 |
|
| 116 |
These programs are designed for X11-based systems. If you somehow |
| 117 |
find compiled versions of these programs on a system using another |
| 118 |
window system, they are very unlikely to be of any use to you. |
| 119 |
|
| 120 |
Source and binaries of the programs can be downloaded from |
| 121 |
\f(CWCTAN://support/xpdfopen/\fR |
| 122 |
(e.g., \f(CWhttp://mirror.ctan.org/support/xpdfopen\fR). |
| 123 |
. |
| 124 |
.SH CAVEATS |
| 125 |
If you use |
| 126 |
.I ar9-tab |
| 127 |
to reload the PDF document and the instance |
| 128 |
of |
| 129 |
.B acroread |
| 130 |
with the given document is currently displaying some other document, |
| 131 |
the command causes your document to be displayed, but not reloaded. |
| 132 |
|
| 133 |
.B pdfopen |
| 134 |
works by looking for a window with a name (window title) matching that |
| 135 |
expected for the given viewer and document. If for some reason your |
| 136 |
viewer's window name is not as expected, |
| 137 |
.B pdfopen |
| 138 |
may not work for you. |
| 139 |
|
| 140 |
With at least AR9 and some window managers, using |
| 141 |
.B pdfopen |
| 142 |
to reload the document gives focus to the |
| 143 |
.B acroread |
| 144 |
window, even though the mouse cursor is not necessarily in that |
| 145 |
window. This can be annoying. The \fB-reset_focus\fP option can be |
| 146 |
used to deal with this problem. |
| 147 |
. |
| 148 |
.SH AUTHOR |
| 149 |
This manual page was written by Jim Diamond <\f([email protected]\fP>. |
| 150 |
I am the current maintainer of the X11 versions of |
| 151 |
.B pdfopen |
| 152 |
and |
| 153 |
\fBpdfclose\fP. |
| 154 |
Report any bugs you find to me. Feature enhancement requests are |
| 155 |
welcome, coded enhancements even more so. |
| 156 |
|
| 157 |
Past authors: |
| 158 |
Fabrice Popineau wrote the MS-windows versions of |
| 159 |
.B pdfopen |
| 160 |
and |
| 161 |
.B pdfclose |
| 162 |
upon which these programs were originally based. |
| 163 |
Taco Hoekwater created the GNU/Linux versions, up to Version 0.61 |
| 164 |
(including some documentation which inspired parts of this man page). |
| 165 |
Peter Breitenlohner has contributed both code and suggestions to |
| 166 |
versions later than 0.61. |