summaryrefslogtreecommitdiff
path: root/Build/source/utils/xpdfopen/pdfopen.1
blob: 82239785469f49847251468e6ee8650db3286815 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
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).