Update packages/ Add org-ref
This commit is contained in:
Mateus Pinto Rodrigues
371
elpa/pdf-tools-20180428.827/README
Normal file
371
elpa/pdf-tools-20180428.827/README
Normal file
@@ -0,0 +1,371 @@
|
||||
#+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-emacs25
|
||||
#+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 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~. 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-b~ |
|
||||
| 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~ / ~F~ |
|
||||
| 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:
|
||||
Reference in New Issue
Block a user