Debian Codegraph @

texmf-dist/doc/man/man1/pdfopen.1

raw
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.