PDFOPEN(1)

💖 PDFOPEN(1) ✨ NAME

okay so bestie, the manual name is pdfopen and its sidekick is pdfclose 🎀. Both are tiny programs that open or close a PDF file viewer. Iconic duo, no cap 💅.

🧾 SYNOPSIS

pdfopen [ options ]  [ --file ]  file.pdf
pdfclose [ --file ]  file.pdf

🌸 OPTIONS

• -h, --help, -? — asks for the help text and then exits. Literally the "I'm lost" button 🙈.
• -v, --version, -V — prints the version number and exits ✨.
• -p <n>, --page <n> — when the viewer starts up, it jumps to page n of the document 📄. Heads up: not every viewer knows this trick, and even the ones that do only respect it when the document first loads. This one gets overruled by -g if you use both, so it's giving second place energy 🥈.
• -g <named destination>, --goto <named destination> — when the viewer starts, it opens the page holding that named destination 🧚. Same catch as above: not every viewer supports it, and it only kicks in on the initial load.
• -r, --reset_focus — after the commands go to the PDF viewer, it tries to give the cursor focus back to whichever window had it before. This is the fix for when the viewer keeps stealing your focus and it's lowkey so annoying 😭.
• -viewer <ar9|ar9-tab|ar8|ar7|ar5|xpdf|evince>, --viewer <ar9|ar9-tab|ar8|ar7|ar5|xpdf|evince> — picks your viewer: Adobe Reader 9 in a new window, Adobe Reader 9 in a new tab of an already running AR9 (if there is one), Adobe Reader 8, Adobe Reader 7, Adobe Reader 5, xpdf, or evince 🦋. Adobe Reader 9 in a new window is the default, so if you don't pick, that's what you get 👑.

🎀 RATIONALE

okay so picture this: you're in the middle of TeX document prep and you're stuck in an "edit-compile-view" loop 🔁. The problem is that PDF viewers like Adobe's Acrobat Reader (acroread) don't refresh on their own when the PDF changes, so the loop gets super clunky. That's where pdfopen comes in, automating the reload whenever the document changes ✨.

Note: honestly, pdfclose is basically unnecessary on GNU/Linux 💀. Unlike MS windows, acroread doesn't lock the PDF file, so pdftex (or a DVI to PDF converter) can happily write a new version of the output. It's still included in case someone finds it useful, so no judgment 🫶.

🦋 DESCRIPTION

pdfopen goes hunting for a running copy of the chosen (or default) PDF viewer that's showing the given PDF file 🔍. If it finds one, it tells that viewer to reload the file. If there's no such instance, pdfopen starts the viewer with that document instead.

The default viewer is acroread, which could launch any of several Acrobat Reader versions depending on what's installed on your system 🌈. The reload commands are different from one version to the next, though, so if you're on something other than AR9, you should explicitly name the viewer program bestie 💜.

This version of pdfopen accepts these viewer options: ar9, ar9-tab, ar8, ar7, ar5, xpdf, and evince.

The difference between ar9 and ar9-tab matters when no AR9 is already showing the document. With ar9, acroread gets told to open a brand new instance (and therefore a new window) using the -openInNewInstance argument 🪟. With ar9-tab, acroread starts without that argument, so if an acroread is already running, the document pops up as a new tab in an existing window 🗂️.

pdfclose searches for one of the viewers above that's displaying the given file, then tells it to "close" the window 🚪. Most of the time the viewer keeps running, maybe just sitting there with a blank window. (This behaviour varies a bit between PDF viewers, fyi.)

🌍 PORTABILITY AND AVAILABILITY

These programs have been tested on Slackware64 Version 14.1 and a few other versions and distributions of GNU/Linux 🐧. The code is pretty generic and should work out of the box with most recent X11 implementations. If it doesn't, reports are welcome, especially if they come with robust fixes 🛠️.

These programs are built for X11-based systems. If you somehow stumble upon compiled versions on a system running a different window system, they're very unlikely to be useful to you 🙈.

Source and binaries can be downloaded from CTAN://support/xpdfopen/ (e.g., http://mirror.ctan.org/support/xpdfopen) 📦.

⚠️ CAVEATS

Heads up: if you use ar9-tab to reload the document and the acroread instance that has it is currently showing a different document, the command will display your document but won't reload it 😬.

pdfopen works by searching for a window whose name (window title) matches what's expected for the given viewer and document 🔎. If your viewer's window name for some reason isn't what's expected, pdfopen might not work for you.

With at least AR9 and some window managers, using pdfopen to reload the document gives focus to the acroread window, even if your mouse cursor isn't in that window 😤. It can be super annoying. The -reset_focus option is there to deal with exactly this problem 💅.

👩‍💻 AUTHOR

This manual page was written by Jim Diamond <Jim.Diamond@acadiau.ca>. He's the current maintainer of the X11 versions of pdfopen and pdfclose, so report any bugs you find to him 🐛. Feature enhancement requests are welcome, and coded enhancements even more so 💜.

Past authors: Fabrice Popineau wrote the MS windows versions of pdfopen and pdfclose, which these programs were originally based on 🌷. Taco Hoekwater created the GNU/Linux versions, up to Version 0.61 (including some documentation that inspired parts of this man page) 🍓. Peter Breitenlohner has contributed both code and suggestions to versions later than 0.61 🌈.

✨ bestie, that's the whole page: pdfopen version 0.86, last updated 2014-05-24 🎀. Now go reload your PDFs and slay the edit-compile-view loop 💖💅🦋