branch: externals/blist
commit 8956fae6514e14b10dbc2b4bb41f3a61af55a813
Author: JSDurand <mmem...@gmail.com>
Commit: JSDurand <mmem...@gmail.com>
Update docs
* README.org:
* blist.info:
* blist.pdf
* blist.texinfo: Documentation updated.
* ChangeLog: Record the change.
---
ChangeLog | 4 ++++
README.org | 23 ++++++++++++++++++-----
blist.info | Bin 36197 -> 36875 bytes
blist.pdf | Bin 447187 -> 448798 bytes
blist.texinfo | 36 ++++++++++++++++++++++++++----------
5 files changed, 48 insertions(+), 15 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 7c3d6e572c..519965ba59 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2021-12-23 Durand <mmem...@gmail.com>
+
+ Update documentation.
+
2021-12-22 李俊緯 <mmem...@gmail.com>
New user option: blist-use-header-p. Now the user can choose to
diff --git a/README.org b/README.org
index 25030a7b82..f59516a92d 100644
--- a/README.org
+++ b/README.org
@@ -42,6 +42,9 @@ configuring the package.
(cons "Info" #'blist-info-p)
(cons "Default" #'blist-default-p)))
+ ;; Whether one wants to use the header line or not
+ (setq blist-use-header-p nil)
+
;; Eshell and Default are defined in the package by default
(blist-define-criterion "elisp" "ELisp"
@@ -60,6 +63,15 @@ configuring the package.
See the following subsections for more details.
+** Header
+
+Some users prefer to display the names of columns in the /header
+line/. It has the advantage that it will always be visible, even
+though the user scrolls the buffer. This package has an option
+=blist-use-header-p= for this purpose. If that customizable variable
+is non-nil, then blist will display the names of columns in the header
+line.
+
** Columns
As one can see, the display has two columns: a name column and a
@@ -102,11 +114,12 @@ 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.
+Note that the default filter group, which always returns =t= for every
+bookmark, is not needed. If =blist-filter-groups= does not include a
+filter group whose filter function is =blist-default-p=, then a
+default group will be added automatically. This is to avoid surprises
+to the users. This is a feature of "blist", and not of "ilist": you
+can display a list without default groups.
** Calling convention(s)
diff --git a/blist.info b/blist.info
index 22a9b8758f..bbf1bab005 100644
Binary files a/blist.info and b/blist.info differ
diff --git a/blist.pdf b/blist.pdf
index 4c0fb3965f..c426fb0109 100644
Binary files a/blist.pdf and b/blist.pdf differ
diff --git a/blist.texinfo b/blist.texinfo
index c25f0bee20..bd41564a14 100644
--- a/blist.texinfo
+++ b/blist.texinfo
@@ -79,13 +79,14 @@ package.
@comment node-name, next, previous, up
@chapter Usage
-After installing, one can call the function @code{blist-list-bookmarks}
-to display the list of bookmarks. Of course, one can bind a key to that
-function for easier invocations.
+After installing, one can call the function @code{blist-list-bookmarks},
+or simply @code{blist}, to display the list of bookmarks. Of course,
+one can bind a key to that function for easier invocations.
@menu
* Screenshot::
* Example configuration::
+* Header::
* Columns::
* Groups::
* Calling convention(s)::
@@ -105,7 +106,7 @@ how the list of bookmarks looks like on my end:
@image{scaled-screenshot1}
-@node Example configuration, Columns, Screenshot, Usage
+@node Example configuration, Header, Screenshot, Usage
@comment node-name, next, previous, up
@section Example configuration
@@ -121,6 +122,9 @@ configuring the package.
(cons "Info" #'blist-info-p)
(cons "Default" #'blist-default-p)))
+;; Whether one wants to use the header line or not
+(setq blist-use-header-p nil)
+
;; Eshell and Default are defined in the package by default
(blist-define-criterion "elisp" "ELisp"
@@ -139,7 +143,18 @@ configuring the package.
See the following subsections for more details.
-@node Columns, Groups, Example configuration, Usage
+@node Header, Columns, Example configuration, Usage
+@comment node-name, next, previous, up
+@section Header
+
+Some users prefer to display the names of columns in the @emph{header
+line}. It has the advantage that it will always be visible, even though
+the user scrolls the buffer. This package has an option
+@code{blist-use-header-p} for this purpose. If that customizable
+variable is non-nil, then blist will display the names of columns in the
+header line.
+
+@node Columns, Groups, Header, Usage
@comment node-name, next, previous, up
@section Columns
@@ -187,11 +202,12 @@ 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 @code{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 @file{ilist} can display
-the lists more flexibly.
+Note that the default filter group, which always returns @code{t} for
+every bookmark, is not needed. If @code{blist-filter-groups} does not
+include a filter group whose filter function is @code{blist-default-p},
+then a default group will be added automatically. This is to avoid
+surprises to the users. This is a feature of ``blist'', and not of
+``ilist'': you can display a list without default groups.
@node Calling convention(s), Navigations, Groups, Usage
@comment node-name, next, previous, up
