branch: elpa/dirvish
commit 2f7887d270e99f974d334e0dc59dc0d4021a633c
Author: Alex Lu <hellosimon1...@hotmail.com>
Commit: Alex Lu <hellosimon1...@hotmail.com>
refactor: rename `pdf-preface` to `pdf` and use it by default
`pdf-tools` freezes Emacs for a while because of its loading, making it a
less
desirable default pdf viewer.
---
dirvish-widgets.el | 11 +++++-----
dirvish.el | 2 +-
docs/CUSTOMIZING.org | 61 ++++++++++++++++++++++++++--------------------------
3 files changed, 37 insertions(+), 37 deletions(-)
diff --git a/dirvish-widgets.el b/dirvish-widgets.el
index 71489b2bde..7d806dd33d 100644
--- a/dirvish-widgets.el
+++ b/dirvish-widgets.el
@@ -31,10 +31,9 @@
;; - `audio': preview audio files with metadata, requires `mediainfo'
;; - `epub': preview epub documents, requires `epub-thumbnail'
;; - `font': preview font files, requires `magick'
-;; - `pdf': preview pdf documents via `pdf-tools'
+;; - `pdf': preview pdf documents with thumbnail image, require
`pdftoppm'
+;; - `pdf-tools': preview pdf documents via `pdf-tools'
;; - `archive': preview archive files, requires `tar' and `unzip'
-;; - `dired': preview directories using `dired' (asynchronously)
-;; - `pdf-preface': preview pdf documents with thumbnail image, require
`pdftoppm'
;; - `image-dired' NOT implemented yet | TODO
;;; Code:
@@ -711,7 +710,7 @@ Require: `epub-thumbnailer' (executable)"
`(img . ,(create-image cache nil nil :max-width width :max-height
height))
`(cache . (,dirvish-epub-thumbnailer-program ,file ,cache
,(number-to-string width)))))))
-(dirvish-define-preview pdf (file ext)
+(dirvish-define-preview pdf-tools (file ext)
"Preview pdf files.
Require: `pdf-tools' (Emacs package)"
(when (equal ext "pdf")
@@ -721,8 +720,8 @@ Require: `pdf-tools' (Emacs package)"
(dirvish--find-file-temporarily file)
'(info . "`epdfinfo' program required to preview pdfs; run `M-x
pdf-tools-install'"))))
-(dirvish-define-preview pdf-preface (file ext preview-window)
- "Display the preface image as preview for pdf files."
+(dirvish-define-preview pdf (file ext preview-window)
+ "Display thumbnail for pdf files."
:require (dirvish-pdftoppm-program)
(when (equal ext "pdf")
(let* ((width (dirvish-media--img-size preview-window))
diff --git a/dirvish.el b/dirvish.el
index 2a3df05e81..45e79ef5f4 100644
--- a/dirvish.el
+++ b/dirvish.el
@@ -56,7 +56,7 @@ The default value contains:
requires `ffmpegthumbnailer' on Linux/macOS | `mtn' on Windows
- audio: preview audio files with metadata, requires `mediainfo'.
- epub: preview epub documents, requires `epub-thumbnailer'.
-- pdf: preview pdf documents via `pdf-tools'.
+- pdf: preview pdf with thumbnail generated by `pdftoppm'.
- font: preview font files, requires `magick'.
- archive: preview archives such as .tar, .zip, requires `7z' (`7zz' on
macOS)."
:group 'dirvish :type '(repeat (symbol :tag "Dirvish preview methods")))
diff --git a/docs/CUSTOMIZING.org b/docs/CUSTOMIZING.org
index ae84e32322..391487eb2c 100644
--- a/docs/CUSTOMIZING.org
+++ b/docs/CUSTOMIZING.org
@@ -202,17 +202,6 @@ A quick demo:
https://github.com/user-attachments/assets/b0d93a4e-92a4-4c17-9f82-6e5206ece9bf
-* Multile layout recipies
-
-In Dirvish, a Dirvish window with an associated layout includes a preview
window
-and, optionally, one or more parent windows. You can toggle the visibility of
-the session layout (preview and parent windows) using ~dirvish-layout-toggle~.
-
-You can define multiple layouts in ~dirvish-layout-recipes~ and cycle through
them
-with ~dirvish-layout-switch~. This allows you to have different pane ratios
for
-various tasks. For example, use a 1:3 ratio for image previews or a 1:3:5
ratio
-for general file previews.
-
* Mode line | Header line
Dirvish displays information about the current directory or session in the mode
@@ -267,18 +256,33 @@ header-line are displayed in separate buffers and their
corresponding
windows. These buffers are initialized with ~dirvish-misc-mode~. To customize
the
settings of these buffers, append your configuration to
~dirvish-misc-mode-hook~.
-* File preview
+* File preview in multiple window layouts
-Dirvish offers out-of-the-box file previews for text files and directories.
-Furthermore, it provides interfaces and extensive user options to customize and
-expand its preview capabilities.
+~M-x dirvish~ creates a full-frame window *layout* consists of a central file
+listing window accompanied by an preview window and 0 or more additional parent
+windows denoted by ~dirvish-default-layout~. The command
~dirvish-layout-toggle~
+toggles between the working layout (see ~dirvish-layout-recipes~ below) and the
+original window configuration before entering the full-frame layout, it can
also
+be called on buffers created by ~dired~ and alike commands.
+
+You can define multiple layouts tailored to different tasks within the variable
+~dirvish-layout-recipes~, and cycle through them using
~dirvish-layout-switch~. This
+enables you to configure different pane ratios as needed. For instance, you
+might use a 1:3 ratio for image previews or a 1:3:5 ratio for more detailed
file
+previews.
+
+When a layout is active, you can use ~M-x other-window~ to switch focus between
+the main file listing window and the preview window. Note that the contents of
+the preview buffers are generally read-only.
** Install dependencies for an enhanced preview experience
-Dirvish offers file preview presets that depend on specific binaries. If you
-don't require these extra preview features, you can remove the corresponding
-entries from ~dirvish-preview-dispatchers~ (documented below). Dirvish will
then
-no longer prompt you to install the associated programs.
+Dirvish offers out-of-the-box file previews for text files and directories and
a
+few presets for other common file types that expects specific binaries
installed
+in your operating system. If you don't want these extra preview features, you
+can remove the corresponding entries from ~dirvish-preview-dispatchers~
+(documented below). Dirvish will then no longer prompt you to install the
+associated programs.
+ [[https://github.com/libvips][vipsthumbnail]] for image preview
+ [[https://poppler.freedesktop.org/][poppler]] |
[[https://github.com/vedang/pdf-tools][pdf-tools]] for pdf preview
@@ -400,22 +404,19 @@ info display, image and metadata and etc.
Here are several examples on how to extend the preview capabilities of Dirvish.
-*** Preview PDF files with generated thumbnail
-
-The default ~pdf~ preview method uses =pdf-tools= to open the document, which
works
-fine for most of the pdf documents, but it feels sluggish for some documents
-especially those big ones.
+*** Preview PDF files with ~pdf-tools~
-Dirvish provided an alternative PDF preview dispatcher ~pdf-preface~ which
-generates preface image for pdf files and use those preface images as the
-preview. This allows the user to preview big pdf files in a non-blocking
-fashion.
+By default, PDF previews display a thumbnail and metadata generated by the
+=pdftoppm= and =pdfinfo= utilities, enabling quick, non-blocking previews,
even for
+large files.
-Note: this dispatcher requires the =pdftoppm= executable.
+Alternatively, Dirvish offers a ~pdf-tools~ dispatcher that utilizes
[[https://github.com/vedang/pdf-tools][pdf-tools]] to
+open a fully functional PDF buffer in the preview window. However, this
approach
+can be slower for large documents, as they are loaded synchronously.
#+begin_src emacs-lisp
(setq dirvish-preview-dispatchers
- (cl-substitute 'pdf-preface 'pdf dirvish-preview-dispatchers))
+ (cl-substitute 'pdf-tools 'pdf dirvish-preview-dispatchers))
#+end_src
*** Preview directory using ~eza~ command
