From e6946bf5f2c9cb23a7a569d0bf6154110df247c7 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sun, 24 Oct 2021 18:36:09 +0200 Subject: [PATCH] Improve documentation of image-dired thumbnails * lisp/image-dired.el: Fix documentation on thumbnail file format to correctly say that it can be either PNG or JPEG; not just JPEG. Also fix inconsistent formatting in comments. * lisp/image-dired.el (image-dired-thumbnail-storage): Improve docstring. --- lisp/image-dired.el | 87 +++++++++++++++++++++++++++------------------ 1 file changed, 52 insertions(+), 35 deletions(-) diff --git a/lisp/image-dired.el b/lisp/image-dired.el index 13b2e5bc172..0a4db7a0e55 100644 --- a/lisp/image-dired.el +++ b/lisp/image-dired.el @@ -1,7 +1,7 @@ ;;; image-dired.el --- use dired to browse and manipulate your images -*- lexical-binding: t -*- -;; + ;; Copyright (C) 2005-2021 Free Software Foundation, Inc. -;; + ;; Version: 0.4.11 ;; Keywords: multimedia ;; Author: Mathias Dahl @@ -22,7 +22,7 @@ ;; along with GNU Emacs. If not, see . ;;; Commentary: -;; + ;; BACKGROUND ;; ========== ;; @@ -86,10 +86,13 @@ ;; =========== ;; ;; * Supports all image formats that Emacs and convert supports, but -;; the thumbnails are hard-coded to JPEG format. +;; the thumbnails are hard-coded to JPEG or PNG format. It uses +;; JPEG by default, but can optionally follow the Thumbnail Managing +;; Standard, which mandates PNG. See the user option +;; `image-dired-thumbnail-storage'. ;; ;; * WARNING: The "database" format used might be changed so keep a -;; backup of `image-dired-db-file' when testing new versions. +;; backup of `image-dired-db-file' when testing new versions. ;; ;; * `image-dired-display-image-mode' does not support animation ;; @@ -97,13 +100,13 @@ ;; ==== ;; ;; * Support gallery creation when using per-directory thumbnail -;; storage. +;; storage. ;; ;; * Some sort of auto-rotate function based on rotate info in the -;; EXIF data. +;; EXIF data. ;; ;; * Investigate if it is possible to also write the tags to the image -;; files. +;; files. ;; ;; * From thumbs.el: Add an option for clean-up/max-size functionality ;; for thumbnail directory. @@ -116,33 +119,32 @@ ;; * From thumbs.el: Add the "modify" commands (emboss, negate, ;; monochrome etc). ;; -;; * Add `image-dired-display-thumbs-ring' and functions to cycle that. Find -;; out which is best, saving old batch just before inserting new, or -;; saving the current batch in the ring when inserting it. Adding it -;; probably needs rewriting `image-dired-display-thumbs' to be more general. +;; * Add `image-dired-display-thumbs-ring' and functions to cycle that. Find out +;; which is best, saving old batch just before inserting new, or +;; saving the current batch in the ring when inserting it. Adding +;; it probably needs rewriting `image-dired-display-thumbs' to be more general. ;; ;; * Find some way of toggling on and off really nice keybindings in -;; dired (for example, using C-n or instead of C-S-n). Richard -;; suggested that we could keep C-t as prefix for image-dired commands -;; as it is currently not used in dired. He also suggested that -;; `dired-next-line' and `dired-previous-line' figure out if -;; image-dired is enabled in the current buffer and, if it is, call -;; `image-dired-dired-next-line' and -;; `image-dired-dired-previous-line', respectively. Update: This is -;; partly done; some bindings have now been added to dired. +;; dired (for example, using C-n or instead of C-S-n). +;; Richard suggested that we could keep C-t as prefix for +;; image-dired commands as it is currently not used in dired. He +;; also suggested that `dired-next-line' and `dired-previous-line' +;; figure out if image-dired is enabled in the current buffer and, +;; if it is, call `image-dired-dired-next-line' and `image-dired-dired-previous-line', +;; respectively. Update: This is partly done; some bindings have +;; now been added to dired. ;; ;; * Enhanced gallery creation with basic CSS-support and pagination -;; of tag pages with many pictures. +;; of tag pages with many pictures. ;; ;; * Rewrite `image-dired-modify-mark-on-thumb-original-file' to be -;; less ugly. +;; less ugly. ;; ;; * In some way keep track of buffers and windows and stuff so that -;; it works as the user expects. -;; -;; * More/better documentation -;; +;; it works as the user expects. ;; +;; * More/better documentation. + ;;; Code: (require 'dired) @@ -165,15 +167,30 @@ :type 'directory) (defcustom image-dired-thumbnail-storage 'use-image-dired-dir - "How to store image-dired's thumbnail files. -Image-Dired can store thumbnail files in one of two ways and this is -controlled by this variable. \"Use image-dired dir\" means that the -thumbnails are stored in a central directory. \"Per directory\" -means that each thumbnail is stored in a subdirectory called -\".image-dired\" in the same directory where the image file is. -\"Thumbnail Managing Standard\" means that the thumbnails are -stored and generated according to the Thumbnail Managing Standard -that allows sharing of thumbnails across different programs." + "How `image-dired' stores thumbnail files. +There are two ways that Image Dired can store and generate +thumbnails. If you set this variable to one of the two following +values, they will be stored in the JPEG format: + +- `use-image-dired-dir' means that the thumbnails are stored in a + central directory. + +- `per-directory' means that each thumbnail is stored in a + subdirectory called \".image-dired\" in the same directory + where the image file is. + +It can also use the \"Thumbnail Managing Standard\", which allows +sharing of thumbnails across different programs. This method +means that thumbnails are saved in the PNG format, and allows for +use the following file sizes: + +- `standard' means use thumbnails sized 128x128. +- `standard-large' means use thumbnails sized 256x256. + +Note that with this method of storing thumbnails, they will be +saved in subdirectories of `image-dired-dir'. For more +information on the Thumbnail Managing Standard, see: +https://specifications.freedesktop.org/thumbnail-spec/thumbnail-spec-latest.html" :type '(choice :tag "How to store thumbnail files" (const :tag "Use image-dired-dir" use-image-dired-dir) (const :tag "Thumbnail Managing Standard (normal 128x128)" standard) -- 2.39.5