diff options
Diffstat (limited to 'elpa/pdf-tools-20200512.1524/README')
| -rw-r--r-- | elpa/pdf-tools-20200512.1524/README | 381 |
1 files changed, 0 insertions, 381 deletions
diff --git a/elpa/pdf-tools-20200512.1524/README b/elpa/pdf-tools-20200512.1524/README deleted file mode 100644 index 6738261..0000000 --- a/elpa/pdf-tools-20200512.1524/README +++ /dev/null @@ -1,381 +0,0 @@ -#+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: |