GNU bug report logs - #61624
30.0.50; [PATCH] More doc on image-dired-dired-*

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 61624 in the body.
You can then email your comments to 61624 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Manuel Giraud <manuel <at> ledu-giraud.fr>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 12:37:25 +0100

[Message part 1 (text/plain, inline)]

Hi,

Here is more documentation on some image-dired-dired-* commands.

[0001-More-doc-on-image-dired-dired.patch (text/x-patch, attachment)]

[Message part 3 (text/plain, inline)]

In GNU Emacs 30.0.50 (build 1, x86_64-unknown-openbsd7.2, cairo version
 1.17.8) of 2023-02-19 built on computer
Repository revision: ff2109d7202ad2bbad00edd2a2ab21e4917ca7a3
Repository branch: mgi/image-dired-doc
Windowing system distributor 'The X.Org Foundation', version 11.0.12101006
System Description: OpenBSD computer 7.2 GENERIC.MP#1052 amd64

Configured using:
 'configure --prefix=/home/manuel/emacs --bindir=/home/manuel/bin
 --with-x-toolkit=no --without-sound --without-compress-install
 CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib'

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LCMS2 LIBOTF LIBXML2 MODULES NOTIFY KQUEUE OLDXMENU PDUMPER PNG RSVG
SQLITE3 THREADS TIFF TREE_SITTER WEBP X11 XDBE XIM XINPUT2 XPM ZLIB

Important settings:
  value of $LC_ALL: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Dired by name

Minor modes in effect:
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  gnus-dired-mode: t
  display-time-mode: t
  display-battery-mode: t
  server-mode: t
  shell-dirtrack-mode: t
  repeat-mode: t
  desktop-save-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  buffer-read-only: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
/home/manuel/.emacs.d/elpa/ef-themes-0.10.0/theme-loaddefs hides /home/manuel/emacs/share/emacs/30.0.50/lisp/theme-loaddefs
/home/manuel/.emacs.d/elpa/transient-0.3.7/transient hides /home/manuel/emacs/share/emacs/30.0.50/lisp/transient

Features:
(shadow sort mail-extr emacsbug whitespace magit-extras magit-patch
pulse face-remap magit-bookmark magit-submodule magit-obsolete
magit-blame magit-stash magit-reflog magit-bisect magit-push magit-pull
magit-fetch magit-clone magit-remote magit-commit magit-sequence
magit-notes magit-worktree magit-tag magit-merge magit-branch
magit-reset magit-files magit-refs magit-status magit magit-repos
magit-apply magit-wip magit-log which-func magit-diff smerge-mode diff
git-commit log-edit pcvs-util add-log magit-core magit-autorevert
magit-margin magit-transient magit-process with-editor magit-mode
transient magit-git magit-section magit-utils dash org-indent vc-dir
ewoc vc mhtml-mode js c-ts-common reveal pascal vc-hg conf-mode css-mode
sgml-mode facemenu imenu sh-script smie treesit executable oc-basic
ol-eww eww url-queue mm-url ol-rmail ol-mhe ol-irc ol-info ol-gnus
nnselect ol-docview doc-view jka-compr image-mode exif ol-bibtex bibtex
ol-bbdb ol-w3m ol-doi org-link-doi paredit edmacro gnus-dired autorevert
filenotify vc-git diff-mode bug-reference texinfo texinfo-loaddefs time
battery exwm-randr xcb-randr exwm-config ido exwm exwm-input xcb-keysyms
xcb-xkb exwm-manage exwm-floating xcb-cursor xcb-render exwm-layout
exwm-workspace exwm-core xcb-ewmh xcb-icccm xcb xcb-xproto xcb-types
xcb-debug kmacro server stimmung-themes modus-operandi-theme
modus-themes ytdious osm bookmark mingus libmpdee reporter edebug debug
backtrace transmission color calc-bin calc-ext calc calc-loaddefs rect
calc-macs w3m-load supercite regi ebdb-message ebdb-gnus gnus-msg
gnus-art mm-uu mml2015 mm-view mml-smime smime gnutls dig gnus-sum shr
pixel-fill kinsoku url-file svg dom gnus-group gnus-undo gnus-start
gnus-dbus gnus-cloud nnimap nnmail mail-source utf7 nnoo gnus-spec
gnus-int gnus-range message sendmail yank-media puny rfc822 mml mml-sec
epa epg rfc6068 epg-config mm-decode mm-bodies mm-encode mail-parse
rfc2231 rfc2047 rfc2045 ietf-drums gmm-utils mailheader gnus-win gnus
nnheader gnus-util mail-utils range mm-util mail-prsvr ebdb-mua ebdb-com
crm ebdb-format ebdb mailabbrev eieio-opt cl-extra help-mode speedbar
ezimage dframe eieio-base pcase timezone visual-basic-mode cl web-mode
derived disp-table erlang-start smart-tabs-mode skeleton cc-mode
cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars
cc-defs slime-asdf grep slime-tramp tramp tramp-loaddefs trampver
tramp-integration cus-edit cus-load wid-edit files-x tramp-compat shell
parse-time iso8601 ls-lisp slime-fancy slime-indentation slime-cl-indent
cl-indent slime-trace-dialog slime-fontifying-fu slime-package-fu
slime-references slime-compiler-notes-tree advice slime-scratch
slime-presentations bridge slime-macrostep macrostep slime-mdot-fu
slime-enclosing-context slime-fuzzy slime-fancy-trace
slime-fancy-inspector slime-c-p-c slime-editing-commands slime-autodoc
slime-repl slime-parse slime apropos compile text-property-search etags
fileloop xref project arc-mode archive-mode pp hyperspec thingatpt
slime-autoloads org-agenda org-element org-persist xdg org-id avl-tree
generator org-refile org ob ob-tangle ob-ref ob-lob ob-table ob-exp
org-macro org-src ob-comint org-pcomplete pcomplete comint ansi-osc
ansi-color ring org-list org-footnote org-faces org-entities time-date
noutline outline icons ob-emacs-lisp ob-core ob-eval org-cycle org-table
org-keys oc org-loaddefs find-func ol rx org-fold org-fold-core
org-compat org-version org-macs format-spec view mule-util cal-china
lunar solar cal-dst cal-bahai cal-islam cal-hebrew holidays
holiday-loaddefs vc-dispatcher vc-svn appt diary-lib diary-loaddefs
cal-menu calendar cal-loaddefs dired-aux dired-x dired dired-loaddefs
notifications dbus xml repeat easy-mmode desktop frameset
stimmung-themes-autoloads rust-mode-autoloads ebdb-autoloads
magit-autoloads debbugs-autoloads git-commit-autoloads
magit-section-autoloads ef-themes-autoloads with-editor-autoloads
paredit-autoloads dash-autoloads ytdious-autoloads
transmission-autoloads transient-autoloads exwm-autoloads
hyperbole-autoloads detached-autoloads info package browse-url url
url-proxy url-privacy url-expand url-methods url-history url-cookie
generate-lisp-file url-domsuf url-util mailcap url-handlers url-parse
auth-source cl-seq eieio eieio-core cl-macs password-cache json subr-x
map byte-opt gv bytecomp byte-compile url-vars cl-loaddefs cl-lib rmc
iso-transl tooltip cconv eldoc paren electric uniquify ediff-hook
vc-hooks lisp-float-type elisp-mode mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer nadvice seq simple cl-generic indonesian philippine
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite emoji-zwj charscript
charprop case-table epa-hook jka-cmpr-hook help abbrev obarray oclosure
cl-preloaded button loaddefs theme-loaddefs faces cus-face macroexp
files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads dbusbind kqueue lcms2 dynamic-setting system-font-setting
font-render-setting cairo xinput2 x multi-tty make-network-process
emacs)

Memory information:
((conses 16 739117 59159)
 (symbols 48 58769 2)
 (strings 32 193263 13383)
 (string-bytes 1 6191582)
 (vectors 16 112218)
 (vector-slots 8 2243696 120250)
 (floats 8 1056 393)
 (intervals 56 16282 427)
 (buffers 984 104))

-- 
Manuel Giraud

Message #8 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Manuel Giraud <manuel <at> ledu-giraud.fr>
Cc: 61624 <at> debbugs.gnu.org
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 14:05:07 +0200

> Date: Sun, 19 Feb 2023 12:37:25 +0100
> From:  Manuel Giraud via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> Here is more documentation on some image-dired-dired-* commands.

Thanks.  I have a few comments:

> * doc/emacs/dired.texi (Image-Dired): Some fix and more documentation
> about image-dired-dired-* commands.        ^^^

"fixes", I guess?

>  @findex image-dired-display-previous
>    With point in the thumbnail buffer, you can type @key{RET}
>  (@code{image-dired-display-this}) to display the image in another
> -window.  Use the arrow keys to move around in the thumbnail buffer.
> -For easy browsing, use @key{SPC} (@code{image-dired-display-next}) to
> -advance and display the next image.  Typing @key{DEL}
> -(@code{image-dired-display-previous}) backs up to the previous
> -thumbnail and displays that instead.
> +window.  Use the standard Emacs movement shortcuts or the arrow keys
                                            ^^^^^^^^^
We say "key bindings" not "shortcuts".

>    You can delete images through Image-Dired also.  Type @kbd{d}
>  (@code{image-dired-flag-thumb-original-file}) to flag the image file
> -for deletion in the Dired buffer.  You can also delete the thumbnail
> +for deletion in the Dired buffer.  You can also remove the thumbnail
>  image from the thumbnail buffer with @kbd{C-d}
>  (@code{image-dired-delete-char}).

Not sure I understand the reason for this.  "Deletion" goes together
with "delete", so why use "remove" instead?

> +@findex image-dired-dired-toggle-marked-thumbs
> +@findex image-dired-dired-display-external
> +@findex image-dired-dired-display-image
> +  You could also use Image-Dired for @dfn{inline} operations (i.e.,
                                        ^^^^^^^^^^^^^^^^^^^^^^^
As a general rule, whenever you use @dfn to introduce new terminology,
you should have a suitable @cindex entry, so that readers could easily
find the description of the term if they see it later in the manual.

> +right into the Dired buffer).  Type @kbd{C-t C-t} and the thumbnails
                                                    ^
Comma is missing there.

> +(@code{image-dired-dired-toggle-marked-thumbs}).  @kbd{C-t i} and
> +@kbd{C-t x} will display the image under the point into Emacs or with
> +the external viewer, respectively.

"Display the image ... into Emacs" sounds awkward.  I'd say "in Emacs"
instead.

> -@kbd{C-t t} (@code{image-dired-tag-files}).  This reads the tag name
> +@kbd{C- tt} (@code{image-dired-tag-files}).  This reads the tag name
        ^^^^^
Is that a typo?

> +@findex image-dired-dired-comment-files
> +@findex image-dired-dired-edit-comment-and-tags
>    You can also tag a file directly from the thumbnail buffer by typing
>  @kbd{t t} and you can remove a tag by typing @kbd{t r}.  There is also
            ^
A comma missing there.

> -a special tag called ``comment'' for each file (it is not a tag in
> -the exact same sense as the other tags, it is handled slightly
> -differently).  That is used to enter a comment or description about the
> -image.  You comment a file from the thumbnail buffer by typing
> +a special tag called ``comment'' for each file (it is not a tag in the
> +exact same sense as the other tags, it is handled slightly
> +differently).  That is used to enter a comment or description about
> +the image.  You comment a file from the thumbnail buffer by typing

Is this part just a refill of the same text?

Message #11 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Manuel Giraud <manuel <at> ledu-giraud.fr>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61624 <at> debbugs.gnu.org
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 14:16:34 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

> Thanks.  I have a few comments:

Hi Eli,

Here is a new version that adresses most of your comments.

[0001-More-doc-on-image-dired-dired-bug-61624.patch (text/x-patch, attachment)]

[Message part 3 (text/plain, inline)]

[...]

>>    You can delete images through Image-Dired also.  Type @kbd{d}
>>  (@code{image-dired-flag-thumb-original-file}) to flag the image file
>> -for deletion in the Dired buffer.  You can also delete the thumbnail
>> +for deletion in the Dired buffer.  You can also remove the thumbnail
>>  image from the thumbnail buffer with @kbd{C-d}
>>  (@code{image-dired-delete-char}).
>
> Not sure I understand the reason for this.  "Deletion" goes together
> with "delete", so why use "remove" instead?

You're right that it goes with "delete" from the command name but I
thought that "remove" is better because no file is deleted from this
operation.  Only the thumbnail is removed from the thumbnails buffer.
Maybe my english is a bit off here.
-- 
Manuel Giraud

Message #14 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Manuel Giraud <manuel <at> ledu-giraud.fr>
Cc: 61624 <at> debbugs.gnu.org
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 15:36:44 +0200

> From: Manuel Giraud <manuel <at> ledu-giraud.fr>
> Cc: 61624 <at> debbugs.gnu.org
> Date: Sun, 19 Feb 2023 14:16:34 +0100
> 
> Here is a new version that adresses most of your comments.

LGTM, thanks.

> >>    You can delete images through Image-Dired also.  Type @kbd{d}
> >>  (@code{image-dired-flag-thumb-original-file}) to flag the image file
> >> -for deletion in the Dired buffer.  You can also delete the thumbnail
> >> +for deletion in the Dired buffer.  You can also remove the thumbnail
> >>  image from the thumbnail buffer with @kbd{C-d}
> >>  (@code{image-dired-delete-char}).
> >
> > Not sure I understand the reason for this.  "Deletion" goes together
> > with "delete", so why use "remove" instead?
> 
> You're right that it goes with "delete" from the command name but I
> thought that "remove" is better because no file is deleted from this
> operation.  Only the thumbnail is removed from the thumbnails buffer.

Then I suggest to reword:

  Alternatively, you can remove an image's thumbnail from the
  thumbnail buffer without flagging the image for deletion, by typing
  @kbd{C-d}.

Message #17 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Manuel Giraud <manuel <at> ledu-giraud.fr>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 61624 <at> debbugs.gnu.org
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 05:45:47 -0800

Manuel Giraud via "Bug reports for GNU Emacs, the Swiss army knife of
text editors" <bug-gnu-emacs <at> gnu.org> writes:

> +@findex image-dired-dired-comment-files
> +@findex image-dired-dired-edit-comment-and-tags
>    You can also tag a file directly from the thumbnail buffer by typing
> -@kbd{t t} and you can remove a tag by typing @kbd{t r}.  There is also
> -a special tag called ``comment'' for each file (it is not a tag in
> -the exact same sense as the other tags, it is handled slightly
> -differently).  That is used to enter a comment or description about the
> -image.  You comment a file from the thumbnail buffer by typing
> +@kbd{t t}, and you can remove a tag by typing @kbd{t r}.  There is
> +also a special tag called ``comment'' for each file (it is not a tag
> +in the exact same sense as the other tags, it is handled slightly
> +differently).  That is used to enter a comment or description about
> +the image.  You comment a file from the thumbnail buffer by typing
>  @kbd{c}.  You will be prompted for a comment.  Type @kbd{C-t c} to add
>  a comment from Dired (@code{image-dired-dired-comment-files}).
> +@kbd{C-t e} will bring a buffer to edit comment and tags
> +(@code{image-dired-dired-edit-comment-and-tags}).

I'm not sure that the comment/tag features are worth the space in the
Emacs manual, but I won't protest if there's a demand for it.  (I don't
use them myself, so I might be biased here.)

> You're right that it goes with "delete" from the command name but I
> thought that "remove" is better because no file is deleted from this
> operation.  Only the thumbnail is removed from the thumbnails buffer.
> Maybe my english is a bit off here.

To my mind, it makes sense to use two different words, because it
clarifies the difference between the two types of operations slightly.

Message #20 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Manuel Giraud <manuel <at> ledu-giraud.fr>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61624 <at> debbugs.gnu.org
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 14:59:25 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

[...]

> Then I suggest to reword:
>
>   Alternatively, you can remove an image's thumbnail from the
>   thumbnail buffer without flagging the image for deletion, by typing
>   @kbd{C-d}.

Yes LGTM.  Do you want an updated patch?
-- 
Manuel Giraud

Message #23 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Manuel Giraud <manuel <at> ledu-giraud.fr>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 61624 <at> debbugs.gnu.org
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 15:01:34 +0100

Stefan Kangas <stefankangas <at> gmail.com> writes:

[...]

> I'm not sure that the comment/tag features are worth the space in the
> Emacs manual, but I won't protest if there's a demand for it.  (I don't
> use them myself, so I might be biased here.)

I'm not using them myself too.  But OTOH, reading about them in the
manual got me interested.
-- 
Manuel Giraud

Message #28 received at 61624-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Manuel Giraud <manuel <at> ledu-giraud.fr>
Cc: 61624-done <at> debbugs.gnu.org
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 17:10:08 +0200

> From: Manuel Giraud <manuel <at> ledu-giraud.fr>
> Cc: 61624 <at> debbugs.gnu.org
> Date: Sun, 19 Feb 2023 14:59:25 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> [...]
> 
> > Then I suggest to reword:
> >
> >   Alternatively, you can remove an image's thumbnail from the
> >   thumbnail buffer without flagging the image for deletion, by typing
> >   @kbd{C-d}.
> 
> Yes LGTM.  Do you want an updated patch?

No need.  Installed on the emacs-29 branch, and closing the bug.

Message #31 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 61624 <at> debbugs.gnu.org, manuel <at> ledu-giraud.fr
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 17:15:01 +0200

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sun, 19 Feb 2023 05:45:47 -0800
> Cc: 61624 <at> debbugs.gnu.org
> 
> > You're right that it goes with "delete" from the command name but I
> > thought that "remove" is better because no file is deleted from this
> > operation.  Only the thumbnail is removed from the thumbnails buffer.
> > Maybe my english is a bit off here.
> 
> To my mind, it makes sense to use two different words, because it
> clarifies the difference between the two types of operations slightly.

My point was that the text didn't make it clear those were two
different operations, so I suggested a modified wording to make that
crystal clear.

Message #34 received at 61624 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 61624 <at> debbugs.gnu.org, manuel <at> ledu-giraud.fr
Subject: Re: bug#61624: 30.0.50; [PATCH] More doc on image-dired-dired-*
Date: Sun, 19 Feb 2023 08:29:49 -0800

Eli Zaretskii <eliz <at> gnu.org> writes:

> My point was that the text didn't make it clear those were two
> different operations, so I suggested a modified wording to make that
> crystal clear.

Yes, your text was better.  Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.