[elpa] externals/blist 8956fae651 29/31: Update docs

[ELPA Syncer]

branch: externals/blist
commit 8956fae6514e14b10dbc2b4bb41f3a61af55a813
Author: JSDurand <mmemmew@gmail.com>
Commit: JSDurand <mmemmew@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  <mmemmew@gmail.com>
+
+       Update documentation.
+
 2021-12-22  李俊緯  <mmemmew@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