Merge branch 'pull/186'

1 files changed, 439 insertions, 357 deletions

diff --git a/lisp/pdf-view.el b/lisp/pdf-view.el
index 8e6752c..7aad501 100644
--- a/lisp/pdf-view.el
+++ b/lisp/pdf-view.el
@@ -19,9 +19,10 @@
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ;;; Commentary:
-;;
+
+;;  Functions related to viewing PDF documents.
+
 ;;; Code:
-;;
 
 (require 'image-mode)
 (require 'pdf-util)
@@ -48,9 +49,9 @@ number as a scale factor applied to the document's size.  Any
 other value behaves like `fit-width'."
   :group 'pdf-view
   :type '(choice number
-                 (const fit-height)
-                 (const fit-width)
-                 (const fit-page)))
+		 (const fit-height)
+		 (const fit-width)
+		 (const fit-page)))
 
 (make-variable-buffer-local 'pdf-view-display-size)
 
@@ -111,7 +112,7 @@ dis-/advantages of imagemagick and png."
 This should be a cons \(FOREGROUND . BACKGROUND\) of colors."
   :group 'pdf-view
   :type '(cons (color :tag "Foreground")
-               (color :tag "Background")))
+	       (color :tag "Background")))
 
 (defcustom pdf-view-change-page-hook nil
   "Hook run after changing to another page, but before displaying it.
@@ -194,20 +195,31 @@ regarding display of the region in the later function.")
   "Local, dedicated register for PDF positions.")
 
 (defmacro pdf-view-current-page (&optional window)
+  ;;TODO: write documentation!
   `(image-mode-window-get 'page ,window))
+
 (defmacro pdf-view-current-overlay (&optional window)
+    ;;TODO: write documentation!
   `(image-mode-window-get 'overlay ,window))
+
 (defmacro pdf-view-current-image (&optional window)
+    ;;TODO: write documentation!
   `(image-mode-window-get 'image ,window))
+
 (defmacro pdf-view-current-slice (&optional window)
+    ;;TODO: write documentation!
   `(image-mode-window-get 'slice ,window))
+
 (defmacro pdf-view-current-window-size (&optional window)
+    ;;TODO: write documentation!
   `(image-mode-window-get 'window-size ,window))
 
 (defun pdf-view-active-region-p nil
+  "Return t if there are active regions."
   (not (null pdf-view-active-region)))
 
 (defmacro pdf-view-assert-active-region ()
+  "Signal an error if there are no active regions."
   `(unless (pdf-view-active-region-p)
      (error "The region is not active")))
 
@@ -290,33 +302,33 @@ PNG images in Emacs buffers."
                              (file-readable-p buffer-file-name)))))
              (pdf-tools-pdf-buffer-p))
     (let ((tempfile (pdf-util-make-temp-file
-                     (concat (if buffer-file-name
-                                 (file-name-nondirectory
-                                  buffer-file-name)
-                               (buffer-name))
-                             "-"))))
+		     (concat (if buffer-file-name
+				 (file-name-nondirectory
+				  buffer-file-name)
+			       (buffer-name))
+			     "-"))))
       (write-region nil nil tempfile nil 'no-message)
       (setq-local pdf-view--buffer-file-name tempfile)))
 
   ;; Setup scroll functions
   (if (boundp 'mwheel-scroll-up-function) ; not --without-x build
       (setq-local mwheel-scroll-up-function
-                  #'pdf-view-scroll-up-or-next-page))
+		  #'pdf-view-scroll-up-or-next-page))
   (if (boundp 'mwheel-scroll-down-function)
       (setq-local mwheel-scroll-down-function
-                  #'pdf-view-scroll-down-or-previous-page))
+		  #'pdf-view-scroll-down-or-previous-page))
 
   ;; Clearing overlays
   (add-hook 'change-major-mode-hook
-            (lambda ()
-              (remove-overlays (point-min) (point-max) 'pdf-view t))
-            nil t)
+	    (lambda ()
+	      (remove-overlays (point-min) (point-max) 'pdf-view t))
+	    nil t)
   (remove-overlays (point-min) (point-max) 'pdf-view t) ;Just in case.
 
   ;; Setup other local variables.
   (setq-local mode-line-position
-              '(" P" (:eval (number-to-string (pdf-view-current-page)))
-                "/" (:eval (number-to-string (pdf-cache-number-of-pages)))))
+	      '(" P" (:eval (number-to-string (pdf-view-current-page)))
+		"/" (:eval (number-to-string (pdf-cache-number-of-pages)))))
   (setq-local auto-hscroll-mode nil)
   (setq-local pdf-view--server-file-name (pdf-view-buffer-file-name))
   ;; High values of scroll-conservatively seem to trigger
@@ -326,7 +338,7 @@ PNG images in Emacs buffers."
   (setq-local buffer-read-only t)
   (setq-local view-read-only nil)
   (setq-local bookmark-make-record-function
-              'pdf-view-bookmark-make-record)
+	      'pdf-view-bookmark-make-record)
   (setq-local revert-buffer-function #'pdf-view-revert-buffer)
   ;; No auto-save at the moment.
   (setq-local buffer-auto-save-file-name nil)
@@ -338,17 +350,17 @@ PNG images in Emacs buffers."
   (setq-local transient-mark-mode t)
 
   (add-hook 'window-configuration-change-hook
-            'pdf-view-maybe-redisplay-resized-windows nil t)
+	    'pdf-view-maybe-redisplay-resized-windows nil t)
   (add-hook 'deactivate-mark-hook 'pdf-view-deactivate-region nil t)
   (add-hook 'write-contents-functions
-            'pdf-view--write-contents-function nil t)
+	    'pdf-view--write-contents-function nil t)
   (add-hook 'kill-buffer-hook 'pdf-view-close-document nil t)
   (pdf-view-add-hotspot-function
    'pdf-view-text-regions-hotspots-function -9)
 
   ;; Keep track of display info
   (add-hook 'image-mode-new-window-functions
-            'pdf-view-new-window-function nil t)
+	    'pdf-view-new-window-function nil t)
   (image-mode-setup-winprops)
 
   ;; Decryption needs to be done before any other function calls into
@@ -380,8 +392,8 @@ PNG images in Emacs buffers."
 (defun pdf-view-buffer-file-name ()
   "Return the local filename of the PDF in the current buffer.
 
-This may be different from `buffer-file-name', when operating on
-a local copy of a remote file."
+This may be different from variable `buffer-file-name' when
+operating on a local copy of a remote file."
   (or pdf-view--buffer-file-name
       (buffer-file-name)))
 
@@ -411,7 +423,10 @@ a local copy of a remote file."
           (delete-file tempfile))))))
 
 (defun pdf-view-revert-buffer (&optional ignore-auto noconfirm)
-  "Like `revert-buffer', but preserves the buffer's current modes."
+  "Revert buffer while preseving current modes.
+
+Optional parameters IGNORE-AUTO and NOCONFIRM are defined as in
+`revert-buffer'."
   (interactive (list (not current-prefix-arg)))
   ;; Bind to default so that we can use pdf-view-revert-buffer as
   ;; revert-buffer-function.  A binding of nil is needed in Emacs 24.3, but in
@@ -419,15 +434,17 @@ a local copy of a remote file."
   ;; not relied upon.
   (let ((revert-buffer-function (when (fboundp #'revert-buffer--default)
 				  #'revert-buffer--default))
-        (after-revert-hook
-         (cons #'pdf-info-close
-               after-revert-hook)))
+	(after-revert-hook
+	 (cons #'pdf-info-close
+	       after-revert-hook)))
     (prog1
-        (revert-buffer ignore-auto noconfirm 'preserve-modes)
+	(revert-buffer ignore-auto noconfirm 'preserve-modes)
       (pdf-view-redisplay t))))
 
 (defun pdf-view-close-document ()
-  "Like `pdf-info-close', but returns immediately."
+  "Return immediately after closing document.
+
+See also `pdf-info-close', which does not return immediately."
   (when (pdf-info-running-p)
     (let ((pdf-info-asynchronous 'ignore))
       (pdf-info-close))))
@@ -438,6 +455,10 @@ a local copy of a remote file."
 ;; * ================================================================== *
 
 (defun pdf-view-fit-page-to-window ()
+  "Fit PDF to window.
+
+Choose the larger of PDF's height and width, and fits that
+dimension to window."
   (interactive)
   (setq pdf-view-display-size 'fit-page)
   (image-set-window-vscroll 0)
@@ -445,35 +466,50 @@ a local copy of a remote file."
   (pdf-view-redisplay t))
 
 (defun pdf-view-fit-height-to-window ()
+  "Fit PDF height to window."
   (interactive)
   (setq pdf-view-display-size 'fit-height)
   (image-set-window-vscroll 0)
   (pdf-view-redisplay t))
 
 (defun pdf-view-fit-width-to-window ()
+  "Fit PDF size to window."
   (interactive)
   (setq pdf-view-display-size 'fit-width)
   (image-set-window-hscroll 0)
   (pdf-view-redisplay t))
 
 (defun pdf-view-enlarge (factor)
+  "Enlarge PDF by FACTOR.
+
+When called interactively, uses the value of
+`pdf-view-resize-factor'.
+
+For example, (pdf-view-enlarge 1.25) increases size by 25%."
   (interactive
    (list (float pdf-view-resize-factor)))
   (let* ((size (pdf-view-image-size))
-         (pagesize (pdf-cache-pagesize
-                    (pdf-view-current-page)))
-         (scale (/ (float (car size))
-                   (float (car pagesize)))))
+	 (pagesize (pdf-cache-pagesize
+		    (pdf-view-current-page)))
+	 (scale (/ (float (car size))
+		   (float (car pagesize)))))
     (setq pdf-view-display-size
-          (* factor scale))
+	  (* factor scale))
     (pdf-view-redisplay t)))
 
 (defun pdf-view-shrink (factor)
+  "Shrink PDF by FACTOR.
+
+When called interactively, uses the value of
+`pdf-view-resize-factor'.
+
+For example, (pdf-view-shrink 1.25) decreases size by 20%."
   (interactive
    (list (float pdf-view-resize-factor)))
   (pdf-view-enlarge (/ 1.0 factor)))
 
 (defun pdf-view-scale-reset ()
+  "Reset PDF to its default set."
   (interactive)
   (setq pdf-view-display-size 1.0)
   (pdf-view-redisplay t))
@@ -485,51 +521,67 @@ a local copy of a remote file."
 ;; * ================================================================== *
 
 (defun pdf-view-goto-page (page &optional window)
+  "Go to PAGE in PDF.
+
+If optional parameter WINDOW, go to PAGE in all `pdf-view'
+windows."
   (interactive
    (list (if current-prefix-arg
-             (prefix-numeric-value current-prefix-arg)
-           (read-number "Page: "))))
+	     (prefix-numeric-value current-prefix-arg)
+	   (read-number "Page: "))))
   (unless (and (>= page 1)
-               (<= page (pdf-cache-number-of-pages)))
+	       (<= page (pdf-cache-number-of-pages)))
     (error "No such page: %d" page))
   (unless window
     (setq window
-          (if (pdf-util-pdf-window-p)
-              (selected-window)
-            t)))
+	  (if (pdf-util-pdf-window-p)
+	      (selected-window)
+	    t)))
   (save-selected-window
     ;; Select the window for the hooks below.
     (when (window-live-p window)
       (select-window window))
     (let ((changing-p
-           (not (eq page (pdf-view-current-page window)))))
+	   (not (eq page (pdf-view-current-page window)))))
       (when changing-p
-        (run-hooks 'pdf-view-before-change-page-hook)
-        (setf (pdf-view-current-page window) page)
-        (run-hooks 'pdf-view-change-page-hook))
+	(run-hooks 'pdf-view-before-change-page-hook)
+	(setf (pdf-view-current-page window) page)
+	(run-hooks 'pdf-view-change-page-hook))
       (when (window-live-p window)
-        (pdf-view-redisplay window))
+	(pdf-view-redisplay window))
       (when changing-p
-        (pdf-view-deactivate-region)
-        (force-mode-line-update)
-        (run-hooks 'pdf-view-after-change-page-hook))))
+	(pdf-view-deactivate-region)
+	(force-mode-line-update)
+	(run-hooks 'pdf-view-after-change-page-hook))))
   nil)
 
 (defun pdf-view-next-page (&optional n)
+  "View the next page in the PDF.
+
+Optional parameter N moves N pages forward."
   (interactive "p")
   (pdf-view-goto-page (+ (pdf-view-current-page)
-                         (or n 1))))
+			 (or n 1))))
 
 (defun pdf-view-previous-page (&optional n)
+  "View the previous page in the PDF.
+
+Optional parameter N moves N pages backward."
   (interactive "p")
   (pdf-view-next-page (- (or n 1))))
 
 (defun pdf-view-next-page-command (&optional n)
+  "View the next page in the PDF.
+
+Optional parameter N moves N pages forward.
+
+This command is a wrapper for `pdf-view-next-page' that will
+indicate to the user if they are on the last page and more."
   (declare (interactive-only pdf-view-next-page))
   (interactive "p")
   (unless n (setq n 1))
   (when (> (+ (pdf-view-current-page) n)
-           (pdf-cache-number-of-pages))
+	   (pdf-cache-number-of-pages))
     (user-error "Last page"))
   (when (< (+ (pdf-view-current-page) n) 1)
     (user-error "First page"))
@@ -542,16 +594,21 @@ a local copy of a remote file."
     (cancel-timer pdf-view--next-page-timer)
     (setq pdf-view--next-page-timer nil))
   (if (or (not (input-pending-p))
-          (and (> n 0)
-               (= (pdf-view-current-page)
-                  (pdf-cache-number-of-pages)))
-          (and (< n 0)
-               (= (pdf-view-current-page) 1)))
+	  (and (> n 0)
+	       (= (pdf-view-current-page)
+		  (pdf-cache-number-of-pages)))
+	  (and (< n 0)
+	       (= (pdf-view-current-page) 1)))
       (pdf-view-redisplay)
     (setq pdf-view--next-page-timer
-          (run-with-idle-timer 0.001 nil 'pdf-view-redisplay (selected-window)))))
+	  (run-with-idle-timer 0.001 nil 'pdf-view-redisplay (selected-window)))))
 
 (defun pdf-view-previous-page-command (&optional n)
+  "View the previous page in the PDF.
+
+Optional parameter N moves N pages backward.
+
+This command is a wrapper for `pdf-view-previous-page'."
   (declare (interactive-only pdf-view-previous-page))
   (interactive "p")
   (with-no-warnings
@@ -568,18 +625,19 @@ a local copy of a remote file."
   (pdf-view-goto-page (pdf-cache-number-of-pages)))
 
 (defun pdf-view-scroll-up-or-next-page (&optional arg)
-  "Scroll page up ARG lines if possible, else goto next page.
-When `pdf-view-continuous' is non-nil, scrolling upward
-at the bottom edge of the page moves to the next page.
-Otherwise, goto next page only on typing SPC (ARG is nil)."
+  "Scroll page up ARG lines if possible, else go to the next page.
+
+When `pdf-view-continuous' is non-nil, scrolling upward at the
+bottom edge of the page moves to the next page.  Otherwise, go to
+next page only on typing SPC (ARG is nil)."
   (interactive "P")
   (if (or pdf-view-continuous (null arg))
       (let ((hscroll (window-hscroll))
 	    (cur-page (pdf-view-current-page)))
 	(when (or (= (window-vscroll) (image-scroll-up arg))
-                  ;; Workaround rounding/off-by-one issues.
-                  (memq pdf-view-display-size
-                        '(fit-height fit-page)))
+		  ;; Workaround rounding/off-by-one issues.
+		  (memq pdf-view-display-size
+			'(fit-height fit-page)))
 	  (pdf-view-next-page)
 	  (when (/= cur-page (pdf-view-current-page))
 	    (image-bob)
@@ -588,18 +646,19 @@ Otherwise, goto next page only on typing SPC (ARG is nil)."
     (image-scroll-up arg)))
 
 (defun pdf-view-scroll-down-or-previous-page (&optional arg)
-  "Scroll page down ARG lines if possible, else goto previous page.
-When `pdf-view-continuous' is non-nil, scrolling downward
-at the top edge of the page moves to the previous page.
-Otherwise, goto previous page only on typing DEL (ARG is nil)."
+  "Scroll page down ARG lines if possible, else go to the previous page.
+
+When `pdf-view-continuous' is non-nil, scrolling downward at the
+top edge of the page moves to the previous page.  Otherwise, go
+to previous page only on typing DEL (ARG is nil)."
   (interactive "P")
   (if (or pdf-view-continuous (null arg))
       (let ((hscroll (window-hscroll))
 	    (cur-page (pdf-view-current-page)))
 	(when (or (= (window-vscroll) (image-scroll-down arg))
-                  ;; Workaround rounding/off-by-one issues.
-                  (memq pdf-view-display-size
-                        '(fit-height fit-page)))
+		  ;; Workaround rounding/off-by-one issues.
+		  (memq pdf-view-display-size
+			'(fit-height fit-page)))
 	  (pdf-view-previous-page)
 	  (when (/= cur-page (pdf-view-current-page))
 	    (image-eob)
@@ -608,7 +667,8 @@ Otherwise, goto previous page only on typing DEL (ARG is nil)."
     (image-scroll-down arg)))
 
 (defun pdf-view-next-line-or-next-page (&optional arg)
-  "Scroll upward by ARG lines if possible, else goto next page.
+  "Scroll upward by ARG lines if possible, else go to the next page.
+
 When `pdf-view-continuous' is non-nil, scrolling a line upward
 at the bottom edge of the page moves to the next page."
   (interactive "p")
@@ -624,7 +684,8 @@ at the bottom edge of the page moves to the next page."
     (image-next-line 1)))
 
 (defun pdf-view-previous-line-or-previous-page (&optional arg)
-  "Scroll downward by ARG lines if possible, else goto previous page.
+  "Scroll downward by ARG lines if possible, else go to the previous page.
+
 When `pdf-view-continuous' is non-nil, scrolling a line downward
 at the top edge of the page moves to the previous page."
   (interactive "p")
@@ -640,13 +701,13 @@ at the top edge of the page moves to the previous page."
     (image-previous-line arg)))
 
 (defun pdf-view-goto-label (label)
-  "Goto the page corresponding to LABEL.
+  "Go to the page corresponding to LABEL.
 
-Usually the label of a document's page is the same as its
+Usually, the label of a document's page is the same as its
 displayed page number."
   (interactive
    (list (let ((labels (pdf-info-pagelabels)))
-           (completing-read "Goto label: " labels nil t))))
+	   (completing-read "Goto label: " labels nil t))))
   (let ((index (cl-position label (pdf-info-pagelabels) :test 'equal)))
     (unless index
       (error "No such label: %s" label))
@@ -658,26 +719,28 @@ displayed page number."
 ;; * ================================================================== *
 
 (defun pdf-view-set-slice (x y width height &optional window)
+  ;; TODO: add WINDOW to docstring.
   "Set the slice of the pages that should be displayed.
 
 X, Y, WIDTH and HEIGHT should be relative coordinates, i.e. in
 \[0;1\].  To reset the slice use `pdf-view-reset-slice'."
   (unless (equal (pdf-view-current-slice window)
-                 (list x y width height))
+		 (list x y width height))
     (setf (pdf-view-current-slice window)
-          (mapcar (lambda (v)
-                    (max 0 (min 1 v)))
-                  (list x y width height)))
+	  (mapcar (lambda (v)
+		    (max 0 (min 1 v)))
+		  (list x y width height)))
     (pdf-view-redisplay window)))
 
 (defun pdf-view-set-slice-using-mouse ()
   "Set the slice of the images that should be displayed.
-You set the slice by pressing mouse-1 at its top-left corner and
+
+Set the slice by pressing `mouse-1' at its top-left corner and
 dragging it to its bottom-right corner.  See also
 `pdf-view-set-slice' and `pdf-view-reset-slice'."
   (interactive)
   (let ((size (pdf-view-image-size))
-        x y w h done)
+	x y w h done)
     (while (not done)
       (let ((e (read-event
 		(concat "Press mouse-1 at the top-left corner and "
@@ -689,12 +752,13 @@ dragging it to its bottom-right corner.  See also
 	  (setq h (- (cdr (posn-object-x-y (event-end e))) y))
 	  (setq done t))))
     (apply 'pdf-view-set-slice
-           (pdf-util-scale
-            (list x y w h)
-            (cons (/ 1.0 (float (car size)))
-                  (/ 1.0 (float (cdr size))))))))
+	   (pdf-util-scale
+	    (list x y w h)
+	    (cons (/ 1.0 (float (car size)))
+		  (/ 1.0 (float (cdr size))))))))
 
 (defun pdf-view-set-slice-from-bounding-box (&optional window)
+  ;; TODO: add WINDOW to docstring.
   "Set the slice from the page's bounding-box.
 
 The result is that the margins are almost completely cropped,
@@ -704,19 +768,20 @@ much more accurate than could be done manually using
 See also `pdf-view-bounding-box-margin'."
   (interactive)
   (let* ((bb (pdf-cache-boundingbox (pdf-view-current-page window)))
-         (margin (max 0 (or pdf-view-bounding-box-margin 0)))
-         (slice (list (- (nth 0 bb)
-                         (/ margin 2.0))
-                      (- (nth 1 bb)
-                         (/ margin 2.0))
-                      (+ (- (nth 2 bb) (nth 0 bb))
-                         margin)
-                      (+ (- (nth 3 bb) (nth 1 bb))
-                         margin))))
+	 (margin (max 0 (or pdf-view-bounding-box-margin 0)))
+	 (slice (list (- (nth 0 bb)
+			 (/ margin 2.0))
+		      (- (nth 1 bb)
+			 (/ margin 2.0))
+		      (+ (- (nth 2 bb) (nth 0 bb))
+			 margin)
+		      (+ (- (nth 3 bb) (nth 1 bb))
+			 margin))))
     (apply 'pdf-view-set-slice
-           (append slice (and window (list window))))))
+	   (append slice (and window (list window))))))
 
 (defun pdf-view-reset-slice (&optional window)
+  ;; TODO: add WINDOW to doctring.
   "Reset the current slice.
 
 After calling this function the whole page will be visible
@@ -737,12 +802,12 @@ See also `pdf-view-set-slice-from-bounding-box'."
    (pdf-view-auto-slice-minor-mode
     (dolist (win (get-buffer-window-list nil nil t))
       (when (pdf-util-pdf-window-p win)
-        (pdf-view-set-slice-from-bounding-box win)))
+	(pdf-view-set-slice-from-bounding-box win)))
     (add-hook 'pdf-view-change-page-hook
-              'pdf-view-set-slice-from-bounding-box nil t))
+	      'pdf-view-set-slice-from-bounding-box nil t))
    (t
     (remove-hook 'pdf-view-change-page-hook
-                 'pdf-view-set-slice-from-bounding-box t))))
+		 'pdf-view-set-slice-from-bounding-box t))))
 
 
 ;; * ================================================================== *
@@ -753,34 +818,36 @@ See also `pdf-view-set-slice-from-bounding-box'."
 (defvar pdf-view-inhibit-hotspots nil)
 
 (defun pdf-view-image-type ()
-  "Return the image-type which should be used.
+  "Return the image type that should be used.
 
-The return value is either imagemagick (if available and wanted
-or if png is not available) or png.
+The return value is either `imagemagick' (if available and wanted
+or if png is not available) or `png'.
 
-Signal an error, if neither imagemagick nor png is available.
+Signal an error, if neither `imagemagick' nor `png' is available.
 
 See also `pdf-view-use-imagemagick'."
   (cond ((and pdf-view-use-imagemagick
-              (fboundp 'imagemagick-types))
-         'imagemagick)
-        ((image-type-available-p 'png)
-         'png)
-        ((fboundp 'imagemagick-types)
-         'imagemagick)
-        (t
-         (error "PNG image supported not compiled into Emacs"))))
+	      (fboundp 'imagemagick-types))
+	 'imagemagick)
+	((image-type-available-p 'png)
+	 'png)
+	((fboundp 'imagemagick-types)
+	 'imagemagick)
+	(t
+	 (error "PNG image supported not compiled into Emacs"))))
 
 (defun pdf-view-use-scaling-p ()
+  "Return t if scaling should be used."
   (and (eq 'imagemagick
-           (pdf-view-image-type))
+	   (pdf-view-image-type))
        pdf-view-use-scaling))
 
 (defmacro pdf-view-create-image (data &rest props)
+  ;; TODO: add DATA and PROPS to docstring.
   "Like `create-image', but with set DATA-P and TYPE arguments."
   (declare (indent 1) (debug t))
   `(create-image ,data (pdf-view-image-type) t ,@props
-                 :relief (or pdf-view-image-relief 0)))
+		 :relief (or pdf-view-image-relief 0)))
 
 (defun pdf-view-create-page (page &optional window)
   "Create an image of PAGE for display on WINDOW."
@@ -798,21 +865,22 @@ See also `pdf-view-use-imagemagick'."
       :pointer 'arrow)))
 
 (defun pdf-view-image-size (&optional displayed-p window)
+  ;; TODO: add WINDOW to docstring.
   "Return the size in pixel of the current image.
 
 If DISPLAYED-P is non-nil, return the size of the displayed
 image.  These values may be different, if slicing is used."
   (if displayed-p
       (with-selected-window (or window (selected-window))
-        (image-display-size
-         (image-get-display-property) t))
+	(image-display-size
+	 (image-get-display-property) t))
     (image-size (pdf-view-current-image window) t)))
 
 (defun pdf-view-image-offset (&optional window)
+  ;; TODO: add WINDOW to docstring.
   "Return the offset of the current image.
 
 It is equal to \(LEFT . TOP\) of the current slice in pixel."
-
   (let* ((slice (pdf-view-current-slice window)))
     (cond
      (slice
@@ -829,39 +897,40 @@ It is equal to \(LEFT . TOP\) of the current slice in pixel."
    window))
 
 (defun pdf-view-display-image (image &optional window inhibit-slice-p)
+  ;; TODO: write documentation!
   (let ((ol (pdf-view-current-overlay window)))
     (when (window-live-p (overlay-get ol 'window))
       (let* ((size (image-size image t))
-             (slice (if (not inhibit-slice-p)
-                        (pdf-view-current-slice window)))
-             (displayed-width (floor
-                               (if slice
-                                   (* (nth 2 slice)
-                                      (car (image-size image)))
-                                 (car (image-size image))))))
-        (setf (pdf-view-current-image window) image)
-        (move-overlay ol (point-min) (point-max))
-        ;; In case the window is wider than the image, center the image
-        ;; horizontally.
-        (overlay-put ol 'before-string
-                     (when (> (window-width window)
-                              displayed-width)
-                       (propertize " " 'display
-                                   `(space :align-to
-                                           ,(/ (- (window-width window)
-                                                  displayed-width) 2)))))
-        (overlay-put ol 'display
-                     (if slice
-                         (list (cons 'slice
-                                     (pdf-util-scale slice size 'round))
-                               image)
-                       image))
-        (let* ((win (overlay-get ol 'window))
-               (hscroll (image-mode-window-get 'hscroll win))
-               (vscroll (image-mode-window-get 'vscroll win)))
-          ;; Reset scroll settings, in case they were changed.
-          (if hscroll (set-window-hscroll win hscroll))
-          (if vscroll (set-window-vscroll win vscroll)))))))
+	     (slice (if (not inhibit-slice-p)
+			(pdf-view-current-slice window)))
+	     (displayed-width (floor
+			       (if slice
+				   (* (nth 2 slice)
+				      (car (image-size image)))
+				 (car (image-size image))))))
+	(setf (pdf-view-current-image window) image)
+	(move-overlay ol (point-min) (point-max))
+	;; In case the window is wider than the image, center the image
+	;; horizontally.
+	(overlay-put ol 'before-string
+		     (when (> (window-width window)
+			      displayed-width)
+		       (propertize " " 'display
+				   `(space :align-to
+					   ,(/ (- (window-width window)
+						  displayed-width) 2)))))
+	(overlay-put ol 'display
+		     (if slice
+			 (list (cons 'slice
+				     (pdf-util-scale slice size 'round))
+			       image)
+		       image))
+	(let* ((win (overlay-get ol 'window))
+	       (hscroll (image-mode-window-get 'hscroll win))
+	       (vscroll (image-mode-window-get 'vscroll win)))
+	  ;; Reset scroll settings, in case they were changed.
+	  (if hscroll (set-window-hscroll win hscroll))
+	  (if vscroll (set-window-vscroll win vscroll)))))))
 
 (defun pdf-view-redisplay (&optional window)
   "Redisplay page in WINDOW.
@@ -869,50 +938,52 @@ It is equal to \(LEFT . TOP\) of the current slice in pixel."
 If WINDOW is t, redisplay pages in all windows."
   (unless pdf-view-inhibit-redisplay
     (if (not (eq t window))
-        (pdf-view-display-page
-         (pdf-view-current-page window)
-         window)
+	(pdf-view-display-page
+	 (pdf-view-current-page window)
+	 window)
       (dolist (win (get-buffer-window-list nil nil t))
-        (pdf-view-display-page
-         (pdf-view-current-page win)
-         win)))
+	(pdf-view-display-page
+	 (pdf-view-current-page win)
+	 win)))
     (force-mode-line-update)))
 
 (defun pdf-view-redisplay-pages (&rest pages)
+  "Redisplay PAGES in all windows."
   (pdf-util-assert-pdf-buffer)
   (dolist (window (get-buffer-window-list nil nil t))
     (when (memq (pdf-view-current-page window)
-                pages)
+		pages)
       (pdf-view-redisplay window))))
 
 (defun pdf-view-maybe-redisplay-resized-windows ()
   "Redisplay some windows needing redisplay."
   (unless (or (numberp pdf-view-display-size)
-              (pdf-view-active-region-p)
-              (> (minibuffer-depth) 0))
+	      (pdf-view-active-region-p)
+	      (> (minibuffer-depth) 0))
     (dolist (window (get-buffer-window-list nil nil t))
       (let ((stored (pdf-view-current-window-size window))
-            (size (cons (window-width window)
-                        (window-height window))))
-        (unless (equal size stored)
-          (setf (pdf-view-current-window-size window) size)
-          (unless (or (null stored)
-                      (and (eq pdf-view-display-size 'fit-width)
-                           (eq (car size) (car stored)))
-                      (and (eq pdf-view-display-size 'fit-height)
-                           (eq (cdr size) (cdr stored))))
-            (pdf-view-redisplay window)))))))
+	    (size (cons (window-width window)
+			(window-height window))))
+	(unless (equal size stored)
+	  (setf (pdf-view-current-window-size window) size)
+	  (unless (or (null stored)
+		      (and (eq pdf-view-display-size 'fit-width)
+			   (eq (car size) (car stored)))
+		      (and (eq pdf-view-display-size 'fit-height)
+			   (eq (cdr size) (cdr stored))))
+	    (pdf-view-redisplay window)))))))
 
 (defun pdf-view-new-window-function (winprops)
+  ;; TODO: write documentation!
   ;; (message "New window %s for buf %s" (car winprops) (current-buffer))
   (cl-assert (or (eq t (car winprops))
-                 (eq (window-buffer (car winprops)) (current-buffer))))
+		 (eq (window-buffer (car winprops)) (current-buffer))))
   (let ((ol (image-mode-window-get 'overlay winprops)))
     (if ol
-        (progn
-          (setq ol (copy-overlay ol))
-          ;; `ol' might actually be dead.
-          (move-overlay ol (point-min) (point-max)))
+	(progn
+	  (setq ol (copy-overlay ol))
+	  ;; `ol' might actually be dead.
+	  (move-overlay ol (point-min) (point-max)))
       (setq ol (make-overlay (point-min) (point-max) nil t))
       (overlay-put ol 'pdf-view t))
     (overlay-put ol 'window (car winprops))
@@ -925,39 +996,40 @@ If WINDOW is t, redisplay pages in all windows."
     ;; Clean up some overlays.
     (dolist (ov (overlays-in (point-min) (point-max)))
       (when (and (windowp (overlay-get ov 'window))
-                 (not (window-live-p (overlay-get ov 'window))))
-        (delete-overlay ov)))
+		 (not (window-live-p (overlay-get ov 'window))))
+	(delete-overlay ov)))
     (when (and (windowp (car winprops))
-               (null (image-mode-window-get 'image winprops)))
+	       (null (image-mode-window-get 'image winprops)))
       ;; We're not displaying an image yet, so let's do so.  This
       ;; happens when the buffer is displayed for the first time.
       (with-selected-window (car winprops)
-        (pdf-view-goto-page
-         (or (image-mode-window-get 'page t) 1))))))
+	(pdf-view-goto-page
+	 (or (image-mode-window-get 'page t) 1))))))
 
 (defun pdf-view-desired-image-size (&optional page window)
+  ;; TODO: write documentation!
   (let* ((pagesize (pdf-cache-pagesize
-                    (or page (pdf-view-current-page window))))
-         (slice (pdf-view-current-slice window))
-         (width-scale (/ (/ (float (pdf-util-window-pixel-width window))
-                            (or (nth 2 slice) 1.0))
-                         (float (car pagesize))))
-         (height (- (nth 3 (window-inside-pixel-edges window))
-                    (nth 1 (window-inside-pixel-edges window))
-                    1))
-         (height-scale (/ (/ (float height)
-                             (or (nth 3 slice) 1.0))
-                          (float (cdr pagesize))))
-         (scale width-scale))
+		    (or page (pdf-view-current-page window))))
+	 (slice (pdf-view-current-slice window))
+	 (width-scale (/ (/ (float (pdf-util-window-pixel-width window))
+			    (or (nth 2 slice) 1.0))
+			 (float (car pagesize))))
+	 (height (- (nth 3 (window-inside-pixel-edges window))
+		    (nth 1 (window-inside-pixel-edges window))
+		    1))
+	 (height-scale (/ (/ (float height)
+			     (or (nth 3 slice) 1.0))
+			  (float (cdr pagesize))))
+	 (scale width-scale))
     (if (numberp pdf-view-display-size)
-        (setq scale (float pdf-view-display-size))
+	(setq scale (float pdf-view-display-size))
       (cl-case pdf-view-display-size
-        (fit-page
-         (setq scale (min height-scale width-scale)))
-        (fit-height
-         (setq scale height-scale))
-        (t
-         (setq scale width-scale))))
+	(fit-page
+	 (setq scale (min height-scale width-scale)))
+	(fit-height
+	 (setq scale height-scale))
+	(t
+	 (setq scale width-scale))))
     (let ((width (floor (* (car pagesize) scale)))
 	  (height (floor (* (cdr pagesize) scale))))
       (when (> width (max 1 (or pdf-view-max-image-width width)))
@@ -970,14 +1042,14 @@ If WINDOW is t, redisplay pages in all windows."
 
 This will display a text cursor, when hovering over them."
   (local-set-key [pdf-view-text-region t]
-                 'pdf-util-image-map-mouse-event-proxy)
+		 'pdf-util-image-map-mouse-event-proxy)
   (mapcar (lambda (region)
-            (let ((e (pdf-util-scale region size 'round)))
-              `((rect . ((,(nth 0 e) . ,(nth 1 e))
-                         . (,(nth 2 e) . ,(nth 3 e))))
-                pdf-view-text-region
-                (pointer text))))
-          (pdf-cache-textregions page)))
+	    (let ((e (pdf-util-scale region size 'round)))
+	      `((rect . ((,(nth 0 e) . ,(nth 1 e))
+			 . (,(nth 2 e) . ,(nth 3 e))))
+		pdf-view-text-region
+		(pointer text))))
+	  (pdf-cache-textregions page)))
 
 (define-minor-mode pdf-view-dark-minor-mode
   "Mode for PDF documents with dark background.
@@ -997,7 +1069,7 @@ This tells the various modes to use their face's dark colors."
   nil " Prn" nil
   (pdf-util-assert-pdf-buffer)
   (let ((enable (lambda ()
-                  (pdf-info-setoptions :render/printed t))))
+		  (pdf-info-setoptions :render/printed t))))
     (cond
      (pdf-view-printer-minor-mode
       (add-hook 'after-save-hook enable nil t)
@@ -1019,10 +1091,10 @@ The colors are determined by the variable
   (pdf-util-assert-pdf-buffer)
   ;; FIXME: Maybe these options should be passed stateless to pdf-info-renderpage ?
   (let ((enable (lambda ()
-                  (pdf-info-setoptions
-                   :render/foreground (or (car pdf-view-midnight-colors) "black")
-                   :render/background (or (cdr pdf-view-midnight-colors) "white")
-                   :render/usecolors t))))
+		  (pdf-info-setoptions
+		   :render/foreground (or (car pdf-view-midnight-colors) "black")
+		   :render/background (or (cdr pdf-view-midnight-colors) "white")
+		   :render/usecolors t))))
     (cond
      (pdf-view-midnight-minor-mode
       (add-hook 'after-save-hook enable nil t)
@@ -1042,7 +1114,7 @@ The colors are determined by the variable
              (list " ⎙" )))
 (and (fontp (char-displayable-p ?🌙))
      (setcdr (assq 'pdf-view-midnight-minor-mode minor-mode-alist)
-             (list  " 🌙" )))
+	     (list  " 🌙" )))
 
 
 ;; * ================================================================== *
@@ -1059,26 +1131,28 @@ list of hotspots applicable to the the :map image-property.
 LAYER determines the order: Functions in a higher LAYER will
 supercede hotspots in lower ones."
   (push (cons (or layer 0) fn)
-        pdf-view--hotspot-functions))
+	pdf-view--hotspot-functions))
 
 (defun pdf-view-remove-hotspot-function (fn)
   "Unregister FN as a hotspot function in the current buffer."
   (setq pdf-view--hotspot-functions
-        (cl-remove fn pdf-view--hotspot-functions
-                   :key 'cdr)))
+	(cl-remove fn pdf-view--hotspot-functions
+		   :key 'cdr)))
 
 (defun pdf-view-sorted-hotspot-functions ()
+  ;; TODO: write documentation!
   (mapcar 'cdr (cl-sort (copy-sequence pdf-view--hotspot-functions)
-                        '> :key 'car)))
+			'> :key 'car)))
 
 (defun pdf-view-apply-hotspot-functions (window page image-size)
+  ;; TODO: write documentation!
   (unless pdf-view-inhibit-hotspots
     (save-selected-window
       (when window (select-window window))
       (apply 'nconc
-             (mapcar (lambda (fn)
-                       (funcall fn page image-size))
-                     (pdf-view-sorted-hotspot-functions))))))
+	     (mapcar (lambda (fn)
+		       (funcall fn page image-size))
+		     (pdf-view-sorted-hotspot-functions))))))
 
 
 ;; * ================================================================== *
@@ -1086,6 +1160,7 @@ supercede hotspots in lower ones."
 ;; * ================================================================== *
 
 (defun pdf-view--push-mark ()
+  ;; TODO: write documentation!
   (let (mark-ring)
     (push-mark-command nil))
   (setq deactivate-mark nil))
@@ -1094,7 +1169,6 @@ supercede hotspots in lower ones."
   "Return the active region, a list of edges.
 
 Deactivate the region if DEACTIVATE-P is non-nil."
-
   (pdf-view-assert-active-region)
   (prog1
       pdf-view-active-region
@@ -1110,8 +1184,8 @@ Deactivate the region if DEACTIVATE-P is non-nil."
     (pdf-view-redisplay t)))
 
 (defun pdf-view-mouse-set-region (event &optional allow-extend-p
-                                        rectangle-p)
-  "Selects a region of text using the mouse.
+					rectangle-p)
+  "Select a region of text using the mouse with mouse event EVENT.
 
 Allow for stacking of regions, if ALLOW-EXTEND-P is non-nil.
 
@@ -1121,84 +1195,84 @@ Stores the region in `pdf-view-active-region'."
   (interactive "@e")
   (setq pdf-view--have-rectangle-region rectangle-p)
   (unless (and (eventp event)
-               (mouse-event-p event))
+	       (mouse-event-p event))
     (signal 'wrong-type-argument (list 'mouse-event-p event)))
   (unless (and allow-extend-p
-               (or (null (get this-command 'pdf-view-region-window))
-                   (equal (get this-command 'pdf-view-region-window)
-                          (selected-window))))
+	       (or (null (get this-command 'pdf-view-region-window))
+		   (equal (get this-command 'pdf-view-region-window)
+			  (selected-window))))
     (pdf-view-deactivate-region))
   (put this-command 'pdf-view-region-window
        (selected-window))
   (let* ((window (selected-window))
-         (pos (event-start event))
-         (begin-inside-image-p t)
-         (begin (if (posn-image pos)
-                    (posn-object-x-y pos)
-                  (setq begin-inside-image-p nil)
-                  (posn-x-y pos)))
-         (abs-begin (posn-x-y pos))
-         pdf-view-continuous
-         region)
+	 (pos (event-start event))
+	 (begin-inside-image-p t)
+	 (begin (if (posn-image pos)
+		    (posn-object-x-y pos)
+		  (setq begin-inside-image-p nil)
+		  (posn-x-y pos)))
+	 (abs-begin (posn-x-y pos))
+	 pdf-view-continuous
+	 region)
     (when (pdf-util-track-mouse-dragging (event 0.15)
-            (let* ((pos (event-start event))
-                   (end (posn-object-x-y pos))
-                   (end-inside-image-p
-                    (and (eq window (posn-window pos))
-                         (posn-image pos))))
-              (when (or end-inside-image-p
-                        begin-inside-image-p)
-                (cond
-                 ((and end-inside-image-p
-                       (not begin-inside-image-p))
-                  ;; Started selection ouside the image, setup begin.
-                  (let* ((xy (posn-x-y pos))
-                         (dxy (cons (- (car xy) (car begin))
-                                    (- (cdr xy) (cdr begin))))
-                         (size (pdf-view-image-size t)))
-                    (setq begin (cons (max 0 (min (car size)
-                                                  (- (car end) (car dxy))))
-                                      (max 0 (min (cdr size)
-                                                  (- (cdr end) (cdr dxy)))))
-                          ;; Store absolute position for later.
-                          abs-begin (cons (- (car xy)
-                                             (- (car end)
-                                                (car begin)))
-                                          (- (cdr xy)
-                                             (- (cdr end)
-                                                (cdr begin))))
-                          begin-inside-image-p t)))
-                 ((and begin-inside-image-p
-                       (not end-inside-image-p))
-                  ;; Moved outside the image, setup end.
-                  (let* ((xy (posn-x-y pos))
-                         (dxy (cons (- (car xy) (car abs-begin))
-                                    (- (cdr xy) (cdr abs-begin))))
-                         (size (pdf-view-image-size t)))
-                    (setq end (cons (max 0 (min (car size)
-                                                (+ (car begin) (car dxy))))
-                                    (max 0 (min (cdr size)
-                                                (+ (cdr begin) (cdr dxy)))))))))
-                (let ((iregion (if rectangle-p
+	    (let* ((pos (event-start event))
+		   (end (posn-object-x-y pos))
+		   (end-inside-image-p
+		    (and (eq window (posn-window pos))
+			 (posn-image pos))))
+	      (when (or end-inside-image-p
+			begin-inside-image-p)
+		(cond
+		 ((and end-inside-image-p
+		       (not begin-inside-image-p))
+		  ;; Started selection ouside the image, setup begin.
+		  (let* ((xy (posn-x-y pos))
+			 (dxy (cons (- (car xy) (car begin))
+				    (- (cdr xy) (cdr begin))))
+			 (size (pdf-view-image-size t)))
+		    (setq begin (cons (max 0 (min (car size)
+						  (- (car end) (car dxy))))
+				      (max 0 (min (cdr size)
+						  (- (cdr end) (cdr dxy)))))
+			  ;; Store absolute position for later.
+			  abs-begin (cons (- (car xy)
+					     (- (car end)
+						(car begin)))
+					  (- (cdr xy)
+					     (- (cdr end)
+						(cdr begin))))
+			  begin-inside-image-p t)))
+		 ((and begin-inside-image-p
+		       (not end-inside-image-p))
+		  ;; Moved outside the image, setup end.
+		  (let* ((xy (posn-x-y pos))
+			 (dxy (cons (- (car xy) (car abs-begin))
+				    (- (cdr xy) (cdr abs-begin))))
+			 (size (pdf-view-image-size t)))
+		    (setq end (cons (max 0 (min (car size)
+						(+ (car begin) (car dxy))))
+				    (max 0 (min (cdr size)
+						(+ (cdr begin) (cdr dxy)))))))))
+		(let ((iregion (if rectangle-p
 				   (list (min (car begin) (car end))
 					 (min (cdr begin) (cdr end))
 					 (max (car begin) (car end))
 					 (max (cdr begin) (cdr end)))
 				 (list (car begin) (cdr begin)
 				       (car end) (cdr end)))))
-                  (setq region
-                        (pdf-util-scale-pixel-to-relative iregion))
-                  (pdf-view-display-region
-                   (cons region pdf-view-active-region)
-                   rectangle-p)
-                  (pdf-util-scroll-to-edges iregion)))))
+		  (setq region
+			(pdf-util-scale-pixel-to-relative iregion))
+		  (pdf-view-display-region
+		   (cons region pdf-view-active-region)
+		   rectangle-p)
+		  (pdf-util-scroll-to-edges iregion)))))
       (setq pdf-view-active-region
-            (append pdf-view-active-region
-                    (list region)))
+	    (append pdf-view-active-region
+		    (list region)))
       (pdf-view--push-mark))))
 
 (defun pdf-view-mouse-extend-region (event)
-  "Extend the currently active region."
+  "Extend the currently active region with mouse event EVENT."
   (interactive "@e")
   (pdf-view-mouse-set-region
    event t pdf-view--have-rectangle-region))
@@ -1206,20 +1280,23 @@ Stores the region in `pdf-view-active-region'."
 (defun pdf-view-mouse-set-region-rectangle (event)
   "Like `pdf-view-mouse-set-region' but displays as a rectangle.
 
+EVENT is the mouse event.
+
 This is more useful for commands like
 `pdf-view-extract-region-image'."
   (interactive "@e")
   (pdf-view-mouse-set-region event nil t))
 
 (defun pdf-view-display-region (&optional region rectangle-p)
+  ;; TODO: write documentation!
   (unless region
     (pdf-view-assert-active-region)
     (setq region pdf-view-active-region))
   (let ((colors (pdf-util-face-colors
-                 (if rectangle-p 'pdf-view-rectangle 'pdf-view-region)
-                 (bound-and-true-p pdf-view-dark-minor-mode)))
-        (page (pdf-view-current-page))
-        (width (car (pdf-view-image-size))))
+		 (if rectangle-p 'pdf-view-rectangle 'pdf-view-region)
+		 (bound-and-true-p pdf-view-dark-minor-mode)))
+	(page (pdf-view-current-page))
+	(width (car (pdf-view-image-size))))
     (pdf-view-display-image
      (pdf-view-create-image
          (if rectangle-p
@@ -1243,7 +1320,7 @@ This is more useful for commands like
   (interactive)
   (pdf-view-deactivate-region)
   (setq pdf-view-active-region
-        (list (list 0 0 1 1)))
+	(list (list 0 0 1 1)))
   (pdf-view--push-mark)
   (pdf-view-display-region))
 
@@ -1255,11 +1332,12 @@ This is more useful for commands like
    pdf-view-active-region))
 
 (defun pdf-view-extract-region-image (regions &optional page size
-                                              output-buffer no-display-p)
+					      output-buffer no-display-p)
+  ;; TODO: what is "resp."? Avoid contractions.
   "Create a PNG image of REGIONS.
 
 REGIONS should have the same form as `pdf-view-active-region',
-which see.  PAGE and size are the page resp. base-size of the
+which see.  PAGE and SIZE are the page resp. base-size of the
 image from which the image-regions will be created; they default
 to `pdf-view-current-page' resp. `pdf-view-image-size'.
 
@@ -1268,12 +1346,12 @@ image*\" and display it, unless NO-DISPLAY-P is non-nil.
 
 In case of multiple regions, the resulting image is constructed
 by joining them horizontally.  For this operation (and this only)
-the `convert' programm is used. "
+the `convert' programm is used."
 
   (interactive
    (list (if (pdf-view-active-region-p)
-             (pdf-view-active-region t)
-           '((0 0 1 1)))))
+	     (pdf-view-active-region t)
+	   '((0 0 1 1)))))
   (unless page
     (setq page (pdf-view-current-page)))
   (unless size
@@ -1281,16 +1359,16 @@ the `convert' programm is used. "
   (unless output-buffer
     (setq output-buffer (get-buffer-create "*PDF image*")))
   (let* ((images (mapcar (lambda (edges)
-                           (let ((file (make-temp-file "pdf-view"))
-                                 (coding-system-for-write 'binary))
-                             (write-region
-                              (pdf-info-renderpage
-                               page (car size)
-                               :crop-to edges)
-                              nil file nil 'no-message)
-                             file))
-                         regions))
-         result)
+			   (let ((file (make-temp-file "pdf-view"))
+				 (coding-system-for-write 'binary))
+			     (write-region
+			      (pdf-info-renderpage
+			       page (car size)
+			       :crop-to edges)
+			      nil file nil 'no-message)
+			     file))
+			 regions))
+	 result)
     (unwind-protect
         (progn
           (if (= (length images) 1)
@@ -1319,45 +1397,46 @@ the `convert' programm is used. "
             (unless no-display-p
               (pop-to-buffer (current-buffer)))))
       (dolist (f (cons result images))
-        (when (file-exists-p f)
-          (delete-file f))))))
+	(when (file-exists-p f)
+	  (delete-file f))))))
 
 ;; * ================================================================== *
 ;; * Bookmark + Register Integration
 ;; * ================================================================== *
 
 (defun pdf-view-bookmark-make-record  (&optional no-page no-slice no-size no-origin)
+  ;; TODO: add NO-PAGE, NO-SLICE, NO-SIZE, NO-ORIGIN to the docstring.
   "Create a bookmark PDF record.
 
 The optional, boolean args exclude certain attributes."
   (let ((displayed-p (eq (current-buffer)
-                         (window-buffer))))
+			 (window-buffer))))
     (cons (buffer-name)
-          (append (bookmark-make-record-default nil t 1)
-                  `(,(unless no-page
-                       (cons 'page (pdf-view-current-page)))
-                    ,(unless no-slice
-                       (cons 'slice (and displayed-p
-                                         (pdf-view-current-slice))))
-                    ,(unless no-size
-                       (cons 'size pdf-view-display-size))
-                    ,(unless no-origin
-                       (cons 'origin
-                             (and displayed-p
-                                  (let ((edges (pdf-util-image-displayed-edges nil t)))
-                                    (pdf-util-scale-pixel-to-relative
-                                     (cons (car edges) (cadr edges)) nil t)))))
-                    (handler . pdf-view-bookmark-jump-handler))))))
+	  (append (bookmark-make-record-default nil t 1)
+		  `(,(unless no-page
+		       (cons 'page (pdf-view-current-page)))
+		    ,(unless no-slice
+		       (cons 'slice (and displayed-p
+					 (pdf-view-current-slice))))
+		    ,(unless no-size
+		       (cons 'size pdf-view-display-size))
+		    ,(unless no-origin
+		       (cons 'origin
+			     (and displayed-p
+				  (let ((edges (pdf-util-image-displayed-edges nil t)))
+				    (pdf-util-scale-pixel-to-relative
+				     (cons (car edges) (cadr edges)) nil t)))))
+		    (handler . pdf-view-bookmark-jump-handler))))))
 
 ;;;###autoload
 (defun pdf-view-bookmark-jump-handler (bmk)
-  "The bookmark handler-function interface for PDF bookmarks.
+  "The bookmark handler-function interface for bookmark BMK.
 
 See also `pdf-view-bookmark-make-record'."
   (let ((page (bookmark-prop-get bmk 'page))
 	(slice (bookmark-prop-get bmk 'slice))
-        (size (bookmark-prop-get bmk 'size))
-        (origin (bookmark-prop-get bmk 'origin))
+	(size (bookmark-prop-get bmk 'size))
+	(origin (bookmark-prop-get bmk 'origin))
 	(file (bookmark-prop-get bmk 'filename))
 	(show-fn-sym (make-symbol "pdf-view-bookmark-after-jump-hook")))
     (fset show-fn-sym
@@ -1369,22 +1448,22 @@ See also `pdf-view-bookmark-make-record'."
 		(or (get-buffer-window (current-buffer) 0)
 		    (selected-window))
 	      (when size
-                (setq-local pdf-view-display-size size))
-              (when slice
-                (apply 'pdf-view-set-slice slice))
+		(setq-local pdf-view-display-size size))
+	      (when slice
+		(apply 'pdf-view-set-slice slice))
 	      (when (numberp page)
-                (pdf-view-goto-page page))
-              (when origin
-                (let ((size (pdf-view-image-size t)))
-                  (image-set-window-hscroll
-                   (round (/ (* (car origin) (car size))
-                             (frame-char-width))))
-                  (image-set-window-vscroll
-                   (round (/ (* (cdr origin) (cdr size))
-                             (frame-char-height)))))))))
+		(pdf-view-goto-page page))
+	      (when origin
+		(let ((size (pdf-view-image-size t)))
+		  (image-set-window-hscroll
+		   (round (/ (* (car origin) (car size))
+			     (frame-char-width))))
+		  (image-set-window-vscroll
+		   (round (/ (* (cdr origin) (cdr size))
+			     (frame-char-height)))))))))
     (add-hook 'bookmark-after-jump-hook show-fn-sym)
     (set-buffer (or (find-buffer-visiting file)
-                    (find-file-noselect file)))))
+		    (find-file-noselect file)))))
 
 (defun pdf-view-bookmark-jump (bmk)
   "Switch to bookmark BMK.
@@ -1395,8 +1474,8 @@ works only with bookmarks created by
 `pdf-view-bookmark-make-record'."
 
   (let* ((file (bookmark-prop-get bmk 'filename))
-         (buffer (or (find-buffer-visiting file)
-                     (find-file-noselect file))))
+	 (buffer (or (find-buffer-visiting file)
+		     (find-file-noselect file))))
     (switch-to-buffer buffer)
     (let (bookmark-after-jump-hook)
       (pdf-view-bookmark-jump-handler bmk)
@@ -1409,7 +1488,7 @@ works only with bookmarks created by
    :print-func 'pdf-view-registerv-print-func
    :jump-func 'pdf-view-bookmark-jump
    :insert-func (lambda (bmk)
-                  (insert (format "%S" bmk)))))
+		  (insert (format "%S" bmk)))))
 
 (defun pdf-view-registerv-print-func (bmk)
   "Print a textual representation of bookmark BMK.
@@ -1417,30 +1496,30 @@ works only with bookmarks created by
 This function is used as the `:print-func' property with
 `registerv-make'."
   (let* ((file (bookmark-prop-get bmk 'filename))
-         (buffer (find-buffer-visiting file))
-         (page (bookmark-prop-get bmk 'page))
-         (origin (bookmark-prop-get bmk 'origin)))
+	 (buffer (find-buffer-visiting file))
+	 (page (bookmark-prop-get bmk 'page))
+	 (origin (bookmark-prop-get bmk 'origin)))
     (princ (format "PDF position: %s, page %d, %d%%"
-                   (if buffer
-                       (buffer-name buffer)
-                     file)
-                   (or page 1)
-                   (if origin
-                       (round (* 100 (cdr origin)))
-                     0)))))
+		   (if buffer
+		       (buffer-name buffer)
+		     file)
+		   (or page 1)
+		   (if origin
+		       (round (* 100 (cdr origin)))
+		     0)))))
 
 (defmacro pdf-view-with-register-alist (&rest body)
-  "Setup the proper binding for `register-alist' in body.
+  "Setup the proper binding for `register-alist' in BODY.
 
 This macro may not work as desired when it is nested.  See also
 `pdf-view-use-dedicated-register'."
   (declare (debug t) (indent 0))
   (let ((dedicated-p (make-symbol "dedicated-p")))
     `(let* ((,dedicated-p pdf-view-use-dedicated-register)
-            (register-alist
-             (if ,dedicated-p
-                 pdf-view-register-alist
-               register-alist)))
+	    (register-alist
+	     (if ,dedicated-p
+		 pdf-view-register-alist
+	       register-alist)))
        (unwind-protect
            (progn ,@body)
          (when ,dedicated-p
@@ -1452,27 +1531,30 @@ This macro may not work as desired when it is nested.  See also
 See also `point-to-register'."
   (interactive
    (list (pdf-view-with-register-alist
-           (register-read-with-preview "Position to register: "))))
+	   (register-read-with-preview "Position to register: "))))
   (pdf-view-with-register-alist
     (set-register register (pdf-view-registerv-make))))
 
 (defun pdf-view-jump-to-register (register &optional delete return-register)
-  "Move point to a position stored in a REGISTER."
+  ;; TODO: add RETURN-REGISTER to the docstring.
+  "Move point to a position stored in a REGISTER.
+
+Optional parameter DELETE is defined as in `jump-to-register'."
   (interactive
    (pdf-view-with-register-alist
      (list
       (register-read-with-preview "Jump to register: ")
       current-prefix-arg
       (and (or pdf-view-use-dedicated-register
-               (local-variable-p 'register-alist))
-           (characterp last-command-event)
-           last-command-event))))
+	       (local-variable-p 'register-alist))
+	   (characterp last-command-event)
+	   last-command-event))))
   (pdf-view-with-register-alist
     (let ((return-pos (and return-register
-                           (pdf-view-registerv-make))))
+			   (pdf-view-registerv-make))))
       (jump-to-register register delete)
       (when return-register
-        (set-register return-register return-pos)))))
+	(set-register return-register return-pos)))))
 
 (provide 'pdf-view)