branch: externals/dired-preview
commit 6673bb1cd3f130ecb63641ea2510b38748bfcec3
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Update to version 0.1.0
---
CHANGELOG.org | 151 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.org | 2 +-
dired-preview.el | 2 +-
3 files changed, 153 insertions(+), 2 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
new file mode 100644
index 0000000000..b89caa5378
--- /dev/null
+++ b/CHANGELOG.org
@@ -0,0 +1,151 @@
+#+TITLE: Change log of dired-preview.el
+#+AUTHOR: Protesilaos Stavrou
+#+EMAIL: i...@protesilaos.com
+#+OPTIONS: ':nil toc:nil num:nil author:nil email:nil
+
+This document contains the release notes for each tagged commit on the
+project's main git repository: <https://git.sr.ht/~protesilaos/dired-preview>.
+
+The newest release is at the top. For further details, please consult
+the manual: <https://protesilaos.com/emacs/dired-preview>.
+
+* 0.1.0
+:PROPERTIES:
+:CUSTOM_ID: h:99cbb3dd-a0f1-4d2b-a945-58531f4ab189
+:END:
+
+The ~dired-preview~ package was in a public testing phase from DATE
+until today. In the meantime, lots of changes have been made in the
+interest of usability and robustness.
+
+** Global and buffer-local modes
+:PROPERTIES:
+:CUSTOM_ID: h:598de101-5c1f-4fbd-8f27-709375d8950b
+:END:
+
+The ~dired-preview-mode~ is a local minor mode, while
+~dired-preview-global-mode~ is its global counterpart. Both only take
+effect in Dired buffers.
+
+The idea for a global and a local mode is to empower the user to
+toggle the functionality on demand, such as when they are in a meeting
+and want to disable/enable previews in a given context.
+
+During the development phase, I had made an error regarding the scope
+of what should be a local minor mode. Thanks to Christian Tietze for
+pointing it out:
<https://lists.sr.ht/~protesilaos/general-issues/%3Cm1zg4noej2.fsf%40christiantietze.de%3E>.
+
+** Preview delay runs on an idle timer
+:PROPERTIES:
+:CUSTOM_ID: h:b80cc550-24ee-4817-be8c-c24c5e98e4c2
+:END:
+
+Originally, previews would run on a timer that would block Emacs.
+Whereas we now arrange to only trigger a preview when Emacs is idle
+for a customisable amount of seconds. Refer to the user option
+~dired-preview-delay~.
+
+** Trigger a preview in the post-command phase
+:PROPERTIES:
+:CUSTOM_ID: h:c298121a-5ba4-408b-b063-14022c307c47
+:END:
+
+In the original design, previews were triggered by bespoke
+~dired-preview~ commands that were remapped to =n= and =p= in Dired
+buffers. This had several downsides, namely, (i) the other motions
+would not pick up the trigger, (ii) we would have to remap all
+possible motions, and (iii) the code was needlessly complex.
+
+Currently, we install a local hook in the post-command phase, which
+will trigger a preview if the previous command was a Dired motion. In
+future versions, we may expand the list of commands that we check for.
+
+Thanks to Peter Prevos for reporting this in issue 1 on the GitHub
+mirror: <https://github.com/protesilaos/dired-preview/issues/1>.
+
+Thanks to Christian Tietze and Ed Hamilton for discussing this topic
+with me on the mailing list:
+<https://lists.sr.ht/~protesilaos/general-issues/%3Cm1zg4noej2.fsf%40christiantietze.de%3E>.
+Commit ae93720 by Christian Tietze is based on this discussion,
+although the implementation details have since been redone.
+
+During the development phase, I had made the mistake of checking the
+~last-command~, whereas I should be testing against the
+~this-command~. Thanks to Karthik Chikmagalur for pointing out my
+error:
+<https://lists.sr.ht/~protesilaos/general-issues/%3C87sfab8ixn.fsf%40gmail.com%3E>.
+
+** The placement of the preview window is customisable
+:PROPERTIES:
+:CUSTOM_ID: h:3033401f-878d-4298-9256-228d6c249b3a
+:END:
+
+We arrange to display previews in a side window. Due to the inherent
+complexity of the ~display-buffer~ function and its accoutrements, a
+user option is necessarily reserved for experienced users. To this
+end, we provide the ~dired-preview-display-action-alist-function~.
+Refer to the ~dired-preview-display-action-alist-dwim~ function for
+the implementation details.
+
+Thanks to Karthik Chikmagalur for making an initial suggestion about
+such a feature:
+<https://lists.sr.ht/~protesilaos/general-issues/%3C87jzvp484n.fsf%40gmail.com%3E>
+
+Thanks to Bruno Boal for discussing the user option and concomitant
+function with me and for checking the relevant definitions. This was
+done via a private channel and the information is shared with
+permission.
+
+** Window placement and deletion is more robust
+:PROPERTIES:
+:CUSTOM_ID: h:06e6249d-8755-450e-b65e-b8f999d982a4
+:END:
+
+The idea of "preview" windows is that they are not ordinary windows
+that the user can interact with. As such, they are to be deleted when
+some non-preview mode of action is taken.
+
+Testing for such cases was extensive and required lots of changes to
+the code base. Thanks to Bruno Boal for performing the tests with me,
+for brainstorming possible solutions, and for inspecting the
+implementation details. This was done via a private channel and the
+information is shared with permission.
+
+** We no longer try to preview irregular files
+:PROPERTIES:
+:CUSTOM_ID: h:a2ee3d09-7356-465c-8627-bdc56e9ec303
+:END:
+
+Before, ~dired-preview~ would attempt to produce a preview of named
+pipes and sockets. This was not intended and has since been
+addressed. Use 'file-regular-p' instead of 'file-exists-p'
+
+Thanks to Karthik Chikmagalur for bringing this matter to my attention
+and for recommending the use of ~file-regular-p~ instead of
+~file-exists-p~:
+<https://lists.sr.ht/~protesilaos/general-issues/%3C87pm5cnpaf.fsf%40gmail.com%3E>.
+
+** Preview buffers are killed up to a cumulative size threshold
+:PROPERTIES:
+:CUSTOM_ID: h:d8ba0949-76b0-4d3a-b0f3-1bfb62280483
+:END:
+
+In the original design, we were killing preview buffers all at once.
+This was wasteful because all the work we were doing in the background
+to, for example, fetch a large file was discarded even though the user
+could theoretically request another preview of it.
+
+The current approach is to keep around the newer buffers in order to
+speed up potential requests for another preview. Older buffers are
+discarded starting from the oldest. The clearance of older buffers is
+done until we reach a cumulative size of what is specified as the
+value of the variable ~dired-preview--buffers-threshold~.
+
+Note that the symbol includes double dashes, meaning that it is
+intended for "private" (internal) purposes. I am mentioning it here,
+because this seems like a good candidate for a future user option,
+subject to further refinements.
+
+Thanks to Bruno Boal for suggesting this idea and checking its
+implementation with me. This was done via a private channel and the
+information is shared with permission.
diff --git a/README.org b/README.org
index 3613a76d20..b6459f283d 100644
--- a/README.org
+++ b/README.org
@@ -5,7 +5,7 @@
#+options: ':t toc:nil author:t email:t num:t
#+startup: content
#+macro: stable-version 0.1.0
-#+macro: release-date N/A
+#+macro: release-date 2023-07-08
#+macro: development-version 0.2.0-dev
#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@
#+macro: space @@texinfo:@: @@
diff --git a/dired-preview.el b/dired-preview.el
index 3e03d6da20..460434f131 100644
--- a/dired-preview.el
+++ b/dired-preview.el
@@ -5,7 +5,7 @@
;; Author: Protesilaos Stavrou <i...@protesilaos.com>
;; URL: https://git.sr.ht/~protesilaos/dired-preview
;; Mailing-List: https://lists.sr.ht/~protesilaos/general-issues
-;; Version: 0.0.0
+;; Version: 0.1.0
;; Package-Requires: ((emacs "27.1"))
;; Keywords: files, convenience
