branch: externals/calibre
commit a3007c20e10ac88640fc4da446fa38fc59735161
Author: Kjartan Oli Agustsson <[email protected]>
Commit: Kjartan Oli Agustsson <[email protected]>
Add ability to mark books
* calibre.el (calibre-mark-marker): New constant.
(calibre-marked): New face.
(calibre-marked-face): New variable.
* calibre-library.el (calibre-library-mark): New command.
(calibre-library-get-marked): New function.
(calibre-library-mode-map): Add binding for calibre-library-mark.
* doc/calibre.texi (Modifying books): Split into three subsections.
(Modifying a single book): New subsection.
(Modifying multiple books): New subsection.
(Committing and reverting modifications): New subsection.
* etc/NEWS: Add entry for marking books.
There is no natural place in the current manual to document
calibre-library-mark and this subsectioning makes sense for the
upcoming set of multiple book editing commands anyway so there's no
reason not to put it in place already.
---
calibre-library.el | 21 +++++++++++++++++++++
calibre.el | 13 +++++++++++++
doc/calibre.texi | 42 +++++++++++++++++++++++++++++++++++++++---
etc/NEWS | 5 +++++
4 files changed, 78 insertions(+), 3 deletions(-)
diff --git a/calibre-library.el b/calibre-library.el
index 8cac3d1017..606ccee43f 100644
--- a/calibre-library.el
+++ b/calibre-library.el
@@ -66,6 +66,11 @@ opening books in that format."
(let ((ids (mapcar #'int-to-string (mapcar #'calibre-book-id books))))
(calibre-exec--queue-command `("remove" ,(string-join ids ",")))))
+(defun calibre-library-mark (&optional _num)
+ "Mark a book for further operations and move to the next line."
+ (interactive "p" calibre-library-mode)
+ (tabulated-list-put-tag (char-to-string calibre-mark-marker) t))
+
(defun calibre-library-mark-remove (&optional _num)
"Mark a book for removal and move to the next line."
(interactive "p" calibre-library-mode)
@@ -81,6 +86,21 @@ opening books in that format."
(calibre-library--find-book book)
(tabulated-list-put-tag " " t)))
+(defun calibre-library-get-marked (&optional mark)
+ "Return books marked with MARK.
+
+If MARK is not specified it defaults to `calibre-mod-marker'."
+ (let ((mark (or mark calibre-mark-marker))
+ books)
+ (save-excursion
+ (goto-char (point-min))
+ (while (not (eobp))
+ (let ((book (tabulated-list-get-id))
+ (book-mark (char-after)))
+ (when (eql mark book-mark) (push book books)))
+ (forward-line))
+ (nreverse books))))
+
(defun calibre-library-execute ()
"Performed marked Library actions."
(interactive nil calibre-library-mode)
@@ -155,6 +175,7 @@ If called with a prefix argument prompt the user for the
format."
(defvar-keymap calibre-library-mode-map
:doc "Local keymap for Calibre Library buffers."
:parent tabulated-list-mode-map
+ "m" #'calibre-library-mark
"d" #'calibre-library-mark-remove
"u" #'calibre-library-mark-unmark
"e" #'calibre-edit-book
diff --git a/calibre.el b/calibre.el
index fa6ac90bcc..09a823deba 100644
--- a/calibre.el
+++ b/calibre.el
@@ -50,6 +50,8 @@
"Return a list of the names of defined libraries."
(mapcar #'car calibre-libraries))
+(defconst calibre-mark-marker ?*
+ "Character used to flag books for further operations.")
(defconst calibre-del-marker ?D
"Character used to flag books for deletion.")
(defconst calibre-mod-marker ?M
@@ -81,12 +83,23 @@
(defvar calibre-flagged-face 'calibre-flagged
"Face used for books flagged for deletion.")
+(defface calibre-marked
+ '((t (:inherit dired-marked)))
+ "Face used for books flagged for further operations."
+ :group 'calibre-faces
+ :package-version '("calibre" . "1.5.0"))
+
+(defvar calibre-marked-face 'calibre-marked
+ "Face used for books flagged for further operations.")
+
(defvar calibre-font-lock-keywords
(list
(list (rx-to-string `(seq line-start ,calibre-del-marker))
'(".+" (beginning-of-line) nil (0 calibre-flagged-face)))
(list (rx-to-string `(seq line-start ,calibre-mod-marker))
'(".+" (beginning-of-line) nil (0 calibre-modified-face)))
+ (list (rx-to-string `(seq line-start ,calibre-mark-marker))
+ '(".+" (beginning-of-line) nil (0 calibre-marked-face)))))
(provide 'calibre)
;;; calibre.el ends here
diff --git a/doc/calibre.texi b/doc/calibre.texi
index fb148d0d9e..7cebd956f9 100644
--- a/doc/calibre.texi
+++ b/doc/calibre.texi
@@ -312,16 +312,52 @@ library.
@node Modifying books
@section Modifying books
+calibre.el provides two methods of modifying book metadata. A dedicated
+editing buffer providing full access to the metadata of a single book,
+and a set of commands to make simple changes to a set of books directly
+from the @file{*Library*} buffer.
+
+@menu
+* Modifying a single book::
+* Modifying multiple books::
+* Committing and reverting modifications::
+@end menu
+
+@node Modifying a single book
+@subsection Modifying a single book
@findex calibre-edit-book
-calibre.el allows you to modify the metadata of the books in your
-library. To do this bring point to the line representing that book in
-the @file{*Library*} buffer and press @kbd{e}
+To edit a single book in your library, bring point to the line
+representing that book in the @file{*Library*} buffer and press @kbd{e}
(@code{calibre-edit-book}). This will open a customisation buffer which
you can use to edit the metadata of the book. Once you are satisfied
with your edits press the Accept or Apply buttons. You will see your
changes reflected in the @file{*Library*} buffer, and the book will be
marked as modified.
+@node Modifying multiple books
+@subsection Modifying multiple books
+@findex calibre-library-mark
+@findex calibre-library-mark-unmark
+To edit multiple books at once you must mark them with
+@code{calibre-library-mark} (bound to @kbd{m} by default). A book can
+be removed from the selection by calling @code{calibre-library-mark-unmark}
+(bound to @kbd{u} by default). Once you are satisfied with your selection
+simply call any of the commands in this section.
+
+Be careful when marking already modified books with
+@code{calibre-library-mark}. calibre.el uses the mark applied by the
+modification commands to identify changes that have not been committed
+(@pxref{Committing and reverting modifications}) and the mark applied by
+@code{calibre-library-mark} overwrites that mark (but not the
+modifications themselves), this is fine as long as you subsequently
+perform some modification on the book since the two sets of
+modifications will merge together and the book will again be marked as
+modified. However, if you unmark the book with
+@code{calibre-library-mark-unmark} the modification mark will not be
+restored and any modifications will be lost.
+
+@node Committing and reverting modifications
+@subsection Committing and reverting modifications
@findex calibre-library-execute
@findex calibre-library-mark-unmark
Modifications are not immediately applied to the underlying Calibre
diff --git a/etc/NEWS b/etc/NEWS
index e853a4be1f..e9136f2be1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -6,6 +6,11 @@ See the end of the file for license conditions.
This file is about changes in calibre.el, the Emacs client for
Calibre.
+* Changes in calibre.el 1.5.0
+** Add ability to mark books
+It is now possible to mark books in the Library buffer.
+
+
* Changes in calibre.el 1.4.1
** Fix sorting by series
Sorting by series did not sort series names correctly.
