diff options
Diffstat (limited to 'elpa/pdf-tools-20200512.1524/README')
| -rw-r--r-- | elpa/pdf-tools-20200512.1524/README | 381 |
1 files changed, 381 insertions, 0 deletions
diff --git a/elpa/pdf-tools-20200512.1524/README b/elpa/pdf-tools-20200512.1524/README new file mode 100644 index 0000000..6738261 --- /dev/null +++ b/elpa/pdf-tools-20200512.1524/README @@ -0,0 +1,381 @@ +#+TITLE: PDF Tools README +#+AUTHOR: Andreas Politz +#+EMAIL: politza@fh-trier.de + +[[https://travis-ci.org/politza/pdf-tools.svg?branch%3Dmaster][https://travis-ci.org/politza/pdf-tools.svg?branch=master]] +[[http://stable.melpa.org/#/pdf-tools][http://stable.melpa.org/packages/pdf-tools-badge.svg]] +[[http://melpa.org/#/pdf-tools][http://melpa.org/packages/pdf-tools-badge.svg]] + + + +** About this package + PDF Tools is, among other things, a replacement of DocView for PDF + files. The key difference is that pages are not pre-rendered by + e.g. ghostscript and stored in the file-system, but rather created + on-demand and stored in memory. + + This rendering is performed by a special library named, for + whatever reason, poppler, running inside a server program. This + program is called ~epdfinfo~ and its job is to successively + read requests from Emacs and produce the proper results, i.e. the + PNG image of a PDF page. + + Actually, displaying PDF files is just one part of PDF Tools. + Since poppler can provide us with all kinds of information about a + document and is also able to modify it, there is a lot more we can + do with it. [[http://www.dailymotion.com/video/x2bc1is_pdf-tools-tourdeforce_tech?forcedQuality%3Dhd720][Watch]] + + Please read also about [[#known-problems][known problems.]] + +** Features + + View :: View PDF documents in a buffer with DocView-like + bindings. + + Isearch :: Interactively search PDF documents like any other + buffer, either for a string or a PCRE. + + Occur :: List lines matching a string or regexp in one or more + PDF documents. + + Follow :: + Click on highlighted links, moving to some part of a different + page, some external file, a website or any other URI. Links may + also be followed by keyboard commands. + + Annotations :: Display and list text and markup annotations (like + underline), edit their contents and attributes + (e.g. color), move them around, delete them or + create new ones and then save the modifications + back to the PDF file. + + Attachments :: Save files attached to the PDF-file or list them + in a dired buffer. + + Outline :: Use imenu or a special buffer to examine and navigate + the PDF's outline. + + SyncTeX :: Jump from a position on a page directly to the TeX + source and vice versa. + + Virtual :: + Use a collection of documents as if it were one, big single PDF. + + + Misc :: + - Display PDF's metadata. + - Mark a region and kill the text from the PDF. + - Keep track of visited pages via a history. + - Apply a color filter for reading in low light conditions. + +** Installation + The package may be installed via melpa and it will try to build the + server part when it is activated the first time. Though the next + section regarding build-prerequisites is still relevant, the rest + of the installation instructions assume a build from within a git + repository. (The melpa package has a different directory + structure.) + +*** Server Prerequisites + You'll need GNU Emacs \ge 24.3 and some form of a GNU/Linux OS. + Other operating systems are currently not supported (patches + welcome). The following instructions assume a Debian-based + system. (The prerequisites may be installed automatically on this + kind of systems, see [[#compilation][Compilation]] .) + + First make sure a suitable build-system is installed. We need at + least a C/C++ compiler (both ~gcc~ and ~g++~), ~make~, ~automake~ + and ~autoconf~. + + Next we need to install a few libraries PDF Tools depends on, some + of which are probably already on your system. +#+begin_src sh + $ sudo aptitude install libpng-dev zlib1g-dev + $ sudo aptitude install libpoppler-glib-dev + $ sudo aptitude install libpoppler-private-dev +#+end_src + On some older Ubuntu systems, the final command will possibly give + an error. This should be no problem, since in some versions this + package was contained in the main package ~libpoppler-dev~. Also + note, that ~zlib1g-dev~ was for a long time called ~libz-dev~, + which it still may be on your system. + + Debian wheezy comes with libpoppler version 0.18, which is pretty + old. The minimally required version is 0.16, but some features of + PDF Tools depend on a more recent version of this library. See + the following table for what they are and what version they + require. + + | You want to ... | Required version | + |-------------------------------------------+------------------| + | ... create and modify text annotations. | \ge 0.19.4 | + | ... search case-sensitive. | \ge 0.22 | + | ... create and modify markup annotations. | \ge 0.26 | + |-------------------------------------------+------------------| + + In case you decide to install libpoppler from source, make sure + to run its configure script with the ~--enable-xpdf-headers~ + option. + + Finally there is one feature (following links of a PDF document by + plain keystrokes) which requires imagemagick's convert utility. + This requirement is optional and you may install it like so: +#+begin_src sh + $ sudo aptitude install imagemagick +#+end_src +**** Compiling on OS X + Although OS X is not officially supported, it has been reported + to have been successfully compiled. You will need to install + poppler which you can get with homebrew via +#+BEGIN_SRC sh + $ brew install poppler automake +#+END_SRC + + You will also have to help ~pkg-config~ find some libraries by + setting ~PKG_CONFIG_PATH~, e.g. +#+BEGIN_SRC sh + $ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig +#+END_SRC + or likewise within Emacs using `setenv`. + + After that, compilation should proceed as normal. +**** FreeBSD + Although not officially supported, it has been reported that + pdf-tools work well on FreeBSD. Instead of building pdf-tools, you + can install one of the OS packages with, e.g. +#+BEGIN_SRC sh + $ pkg install pdf-tools-emacs26 +#+END_SRC + To see the current list of pdf-tools packages for FreeBSD visit + [[https://repology.org/metapackages/?search=pdf-tools&inrepo=freebsd][the Repology list]]. + + To build pdf-tools from either melpa or directly from the source + repository, install the dependencies with +#+BEGIN_SRC sh + $ pkg install autotools gmake poppler-glib +#+END_SRC + + If you choose not to install from melpa, you must substitute + ~gmake~ for ~make~ in the instructions below. +**** Compiling on Centos + It is possible to compile pdf-tools on Centos. Install poppler the dependencies with: +#+BEGIN_SRC sh + $ yum install poppler-devel poppler-glib-devel +#+END_SRC + +**** Compiling on Fedora +#+BEGIN_SRC sh + $ sudo dnf install make automake autoconf gcc gcc-c++ ImageMagick libpng-devel zlib-devel poppler-glib-devel +#+END_SRC + +**** Compiling on Alpine Linux +#+BEGIN_SRC sh + $ apk add build-base g++ gcc automake autoconf libpng-dev glib-dev poppler-dev +#+END_SRC + +**** Compiling on Windows + PDF Tools can be built and used on Windows using the MSYS2 + compiler. This will work with native (not cygwin) Windows builds of + emacs. This includes the standard binaries provided by the GNU + project, those available as MSYS2 packages and numerous third-party + binaries. It has been tested with emacs 25.1. Instructions are + provided under [[#compilation-and-installation-on-windows][Compilation and installation on Windows]], below. + PDF Tools will successfully compile using Cygwin, but it will not be + able to open PDFs properly due to the way binaries compiled with Cygwin + handle file paths. + +*** Compilation + :PROPERTIES: + :CUSTOM_ID: compilation + :END: + Now it's time to compile the source. +#+begin_src sh + $ cd /path/to/pdf-tools + $ make install-server-deps # optional + $ make -s +#+end_src + The ~make install-server-deps~ command will try to install all + necessary programs and libraries to build the package, though + it'll only work, if ~sudo~ and ~apt-get~ are available. + + This should compile the source code and create a Emacs Lisp + Package in the root directory of the project. The configure script + also tells you at the very end, which features, depending on the + libpoppler version, will be available. These commands should give + no error, otherwise you are in trouble. +**** Compilation and installation on Windows + If using the GNU binaries for Windows, support for PNG and zlib + must first be installed by copying the appropriate dlls into + emacs' ~bin/~ directory. Most third-party binaries come with this + already done. + + First, install [[http://www.msys2.org/][install MSYS2]] and update + the package database and core packages using the instructions + provided. Then, to compile PDF tools itself: + + 1. Open msys2 shell + + 2. Update and install dependencies, skipping any you already have + #+BEGIN_SRC sh + $ pacman -Syu + $ pacman -S base-devel + $ pacman -S mingw-w64-x86_64-toolchain + $ pacman -S mingw-w64-x86_64-zlib + $ pacman -S mingw-w64-x86_64-libpng + $ pacman -S mingw-w64-x86_64-poppler + $ pacman -S mingw-w64-x86_64-imagemagick + #+END_SRC + + 3. Install PDF tools in Emacs, but do not try to compile the + server. Instead, get a separate copy of the source somewhere + else. + #+BEGIN_SRC sh + $ git clone https://github.com/politza/pdf-tools + #+END_SRC + + 4. Open mingw64 shell (*Note:* You must use mingw64.exe and not msys2.exe) + + 5. Compile pdf-tools + #+BEGIN_SRC sh + $ cd /path/to/pdf-tools + $ make -s + #+END_SRC + + 6. This should produce a file ~server/epdfinfo.exe~. Copy this file + into the ~pdf-tools/~ installation directory in your Emacs. + + 7. Start Emacs and activate the package. + #+BEGIN_SRC + M-x pdf-tools-install RET + #+END_SRC + + 8. Test. + #+BEGIN_SRC + M-x pdf-info-check-epdfinfo RET + #+END_SRC + + If this is successful, ~(pdf-tools-install)~ can be added to Emacs' + config. Note that libraries from other GNU utilities, such as Git + for Windows, may interfere with those needed by PDF Tools. + ~pdf-info-check-epdinfo~ will succeed, but errors occur when trying + to view a PDF file. This can be fixed by ensuring that the MSYS + libraries are always preferred in emacs: + + #+BEGIN_SRC emacs-lisp + (setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH"))) + #+END_SRC + +*** ELisp Prerequisites + This package depends on the following Elisp packages, which should + be installed before installing the Pdf Tools package. + + | Package | Required version | + |-----------+----------------------------------| + | [[https://elpa.gnu.org/packages/let-alist.html][let-alist]] | >= 1.0.4 (comes with Emacs 25.2) | + | [[http://melpa.org/#/tablist][tablist]] | >= 0.70 | + |-----------+----------------------------------| + +*** Installing + If ~make~ produced the ELP file ~pdf-tools-${VERSION}.tar~ you are + fine. This package contains all the necessary files for Emacs + and may be installed by either using +#+begin_src sh + $ make install-package +#+end_src + or executing the Emacs command +#+begin_src elisp + M-x package-install-file RET pdf-tools-${VERSION}.tar RET +#+end_src + + To complete the installation process, you need to activate the + package by putting +#+begin_src elisp + (pdf-tools-install) +#+end_src + somewhere in your ~.emacs~. Alternatively, and if you care about + start-up time, you may want to use +#+begin_src elisp + (pdf-loader-install) +#+end_src + instead. Next you probably want to take a look at the various + features of what you've just installed. The following two commands + might be of help for doing so. +#+begin_src elisp + M-x pdf-tools-help RET + M-x pdf-tools-customize RET +#+end_src + +*** Updating + Some day you might want to update this package via ~git pull~ and + then reinstall it. Sometimes this may fail, especially if + Lisp-Macros are involved and the version hasn't changed. To avoid + this kind of problems, you should delete the old package via + ~list-packages~, restart Emacs and then reinstall the package. + + This also applies when updating via package and melpa. + +** Known problems + :PROPERTIES: + :CUSTOM_ID: known-problems + :END: + +*** linum-mode + PDF Tools does not work well together with ~linum-mode~ and + activating it in a ~pdf-view-mode~, e.g. via ~global-linum-mode~, + might make Emacs choke. + +*** auto-revert + Autorevert works by polling the file-system every + ~auto-revert-interval~ seconds, optionally combined with some + event-based reverting via [[https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html][file notification]]. But this currently + does not work reliably, such that Emacs may revert the PDF-buffer + while the corresponding file is still being written to (e.g. by + LaTeX), leading to a potential error. + + With a recent [[https://www.gnu.org/software/auctex/][auctex]] installation, you might want to put the + following somewhere in your dotemacs, which will revert the PDF-buffer + *after* the TeX compilation has finished. +#+BEGIN_SRC emacs-lisp + (add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer) +#+END_SRC +** Some keybindings + +| Navigation | | +|--------------------------------------------+-----------------------| +| Scroll Up / Down by page-full | ~space~ / ~backspace~ | +| Scroll Up / Down by line | ~C-n~ / ~C-p~ | +| Scroll Right / Left | ~C-f~ / ~C-b~ | +| Top of Page / Bottom of Page | ~<~ / ~>~ | +| Next Page / Previous Page | ~n~ / ~p~ | +| First Page / Last Page | ~M-<~ / ~M->~ | +| Incremental Search Forward / Backward | ~C-s~ / ~C-r~ | +| Occur (list all lines containing a phrase) | ~M-s o~ | +| Jump to Occur Line | ~RETURN~ | +| Pick a Link and Jump | ~F~ | +| Incremental Search in Links | ~f~ | +| History Back / Forwards | ~B~ / ~N~ | +| Display Outline | ~o~ | +| Jump to Section from Outline | ~RETURN~ | +| Jump to Page | ~M-g g~ | + +| Display | | +|------------------------------------------+-----------------| +| Zoom in / Zoom out | ~+~ / ~-~ | +| Fit Height / Fit Width / Fit Page | ~H~ / ~W~ / ~P~ | +| Trim margins (set slice to bounding box) | ~s b~ | +| Reset margins | ~s r~ | +| Reset Zoom | 0 | + +| Annotations | | +|-------------------------------+-------------------------------------------------| +| List Annotations | ~C-c C-a l~ | +| Jump to Annotations from List | ~SPACE~ | +| Mark Annotation for Deletion | ~d~ | +| Delete Marked Annotations | ~x~ | +| Unmark Annotations | ~u~ | +| Close Annotation List | ~q~ | +| Add and edit annotations | via Mouse selection and left-click context menu | + +| Syncing with Auctex | | +|----------------------------------+-------------| +| jump to PDF location from source | ~C-c C-g~ | +| jump source location from PDF | ~C-mouse-1~ | + +| Miscellaneous | | +|-----------------------------------------------+-----------| +| Refresh File (e.g., after recompiling source) | ~g~ | +| Print File | ~C-c C-p~ | + +# Local Variables: +# mode: org +# End: |