summaryrefslogtreecommitdiff
path: root/elpa/pdf-tools-20200512.1524/README
diff options
context:
space:
mode:
authorBlendoit <blendoit@gmail.com>2020-08-01 15:24:03 -0700
committerBlendoit <blendoit@gmail.com>2020-08-01 15:24:03 -0700
commite47650852b8aa4da6d0b0cea3b5421955795cc64 (patch)
tree2535f7cc4fa4b5c25bbd46f9523da5944b76e201 /elpa/pdf-tools-20200512.1524/README
parent374ae3de24187512adddf01a56e5eb52c79db65f (diff)
Definitely /not/ including elpa/, that would be chaos.
Diffstat (limited to 'elpa/pdf-tools-20200512.1524/README')
-rw-r--r--elpa/pdf-tools-20200512.1524/README381
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:
Copyright 2019--2024 Marius PETER