[elpa] externals/blist f1b556af33 12/31: Add README

[ELPA Syncer]

branch: externals/blist
commit f1b556af33ac092bb4a3ce32dd3e5cd5985f63dc
Author: JSDurand <mmemmew@gmail.com>
Commit: JSDurand <mmemmew@gmail.com>

    Add README
---
 README.org      | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 screenshot1.png | Bin 0 -> 515752 bytes
 2 files changed, 149 insertions(+)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..05fcc000a4
--- /dev/null
+++ b/README.org
@@ -0,0 +1,149 @@
+#+TITLE: BList: List Bookmarks in an Ibuffer way
+#+AUTHOR: Durand
+#+DATE: <2021-09-16 Jeu 12:26>
+
+* About
+
+The built-in library "bookmark" is useful for storing information that
+can be retrieved later.  But I find the built-in mechanism to display
+the list of bookmarks not so satisfactory, so I wrote this little
+package to display the list of bookmarks in an Ibuffer way.
+
+* Dependency
+
+This package is driven by another package: 
[[https://gitlab.com/mmemmew/ilist.git][ilist]].  So make sure to
+install that before using this package.  In fact, the package "ilist"
+was written as an abstraction of the mechanisms of this package.
+
+* Usage
+
+After installing, one can call the function =blist-list-bookmarks= to
+display the list of bookmarks.  Of course, one can bind a key to that
+function for easier invocations.
+
+** Screenshot
+
+A picture says more about the package than a thousand words.  Below is
+how the list of bookmarks looks like on my end:
+
+[[file:/Users/durand/elisp_packages/blist/screenshot1.png]]
+
+** Columns
+
+As one can se, the display has two columns: a name column and a
+location column.  The name column shows the names of the bookmarks,
+while the location column shows the /locations/, which are either the
+*filename* or the *location* attributes of the bookmarks.
+
+The variable =blist-display-location-p= controls whether to display
+the locations or not.  Also, one can toggle the display of the
+locations interactively by =blist-toggle-location=.
+
+The variable =blist-maximal-name-len= determines the maximal length of
+the name column.  And the variable =blist-elide-string= determines how
+to elide the name, when it gets too long.
+
+If one feels like so, then one can play with the function
+=blist-name-column= to control the name column.
+
+** Groups
+
+An important feature of this package is the /filter groups/.  They are
+criteria that group bookmarks together under various sections.  So one
+can find all bookmarks of, say, "Eshell buffers" in one section.
+
+The groups are stored in the variable =blist-filter-groups=.  One can
+add or remove filter groups to that variable.  That variable is a list
+of filter groups, while each filter group is a cons cell of the form
+=(NAME . FUN)=, where =NAME= is a string which will be displayed as
+the section header, and =FUN= is a function that accepts a bookmark as
+its argument, and returns non-nil when and only when that bookmark
+belongs to the group.
+
+Since defining the group functions might be tedious, the package also
+provides a convenient macro =blist-define-criterion= for the users to
+define filter groups easily.  See the documentation string of that
+macro for details.
+
+Also, the order of the filter groups matters: the filter groups that
+occur earlier on the list have higher priority.  So if an item belongs
+to multiple groups, it will be classified under the group that is the
+earliest on the list.
+
+In addition, the default filter group simply returns =t= for every
+bookmark.  It is important to have the default group since items that
+belong to no groups will not be shown in the buffer.  This design is
+intentional, so that other packages that use =ilist= can have display
+the lists more flexibly.
+
+** Navigations
+
+The following is a list of default key-bindings to navigate in the
+list of bookmarks.
+
+- =n=/=p=: go to next/previous line.  Whether it treats the top of the
+  buffer as identified with the bottom of the buffer is controlled by
+  the variable =blist-movement-cycle=.
+- =N=/=P=: go to next/previous line that is not a group heading.
+- =M-n=/=M-p=: go to next/previous group heading.
+- =j=, =M-g=: Use =completing-read= to choose a bookmark to go to.
+- =J=, =M-j=, =M-G=: Use =completing-read= to choose a group heading
+  to go to.
+- =M-{=, =(=: go to the previous marked bookmark.
+- =)=, =M-}=: go to the next marked bookmark.
+
+** Marking
+
+The following is a list of default key-bindings to mark bookmarks and
+to operate on the bookmarks.
+
+There is the MRGP convention, that is to say, if there are marked
+bookmarks, they operate on the marked bookmarks.  Otherwise they
+operate on the region, the group at point, the bookmark at point, in
+the order of precedence.
+
+- =m=: Mark the bookmark with the default mark (=blist-default-mark=)
+  and advance.
+- =d=, =k=: Mark for deletion and advance.
+- =C-d=: Mark for deletion and go backwards.
+- =x=: Delete all bookmarks that are marked for deletion.
+- =D=: Delete the bookmark immediately (the MRGP convention).
+- =u=: Unmark the bookmark and advance.
+- =DEL=: Unmark the bookmark and go backwards.
+- =U=: Unmark all bookmarks.
+- =M-DEL=, =* *=: prompt for a mark and unmark all boomarks that are
+  marked with the entered mark.
+- =% n=: Mark bookmarks whose name matches a regular expression.
+- =% l=: Mark bookmarks whose location matches a regular expression.
+- =* c=: Change the marks from OLD to NEW.
+
+** Jump to bookmarks
+
+The following lists the default key-bindings for jumping to, or
+opening bookmarks.
+
+- =RET=: Either open the bookmark in this window or toggle the group
+  at point.
+- =o=: Open the bookmark in another window.
+- =v=: Select the bookmarks (the *MGP* convention).  How multiple
+  bookmarks are opened is controlled by the variable
+  =blist-select-manner=.  See its documentation for details.
+
+** Annotations
+
+The following lists the default key-bindings for operating on the
+annotations of bookmarks.
+
+- =a=: View the annotations of bookmarks: If there are marked
+  bookmarks, show the annotations of the marked bookmarks; otherwise
+  show the annotations of the bookmark at point.  If there is no
+  bookmark at point, use =completing-read= to choose one.
+- =A=: View the annotations of all bookmarks.
+- =e=: edit the annotation of the bookmark at point.  If called with
+  =universal-argument=, prompt for the bookmark to edit with
+  completion.
+
+** Others
+
+Some functions are too minor to record here.  Use =describe-mode= in
+the list of bookmarks to see all available key-bindings.
diff --git a/screenshot1.png b/screenshot1.png
new file mode 100644
index 0000000000..224ef33c08
Binary files /dev/null and b/screenshot1.png differ