[elpa] externals/ilist b2bf67c5d8 24/24: Add changelog, and update documentation

[ELPA Syncer]

branch: externals/ilist
commit b2bf67c5d86914d9139e89945e57e78cde5d205b
Author: JSDurand <mmemmew@gmail.com>
Commit: JSDurand <mmemmew@gmail.com>

    Add changelog, and update documentation
    
    * README.org:
    * ilist.texinfo: Update documentation files.
    
    * .gitignore: Ignore some files produced whie making documentation
      files.
    
    * ChangeLog: A change log is now present, yay!
---
 .gitignore    |   5 ++
 ChangeLog     |   7 +++
 README.org    |  98 +++++++++++++++++++++---------
 ilist.info    | 188 +++++++++++++++++++++++++++++++++++++++++++-------------
 ilist.pdf     | Bin 167330 -> 185921 bytes
 ilist.texinfo | 192 +++++++++++++++++++++++++++++++++++++++++++++++-----------
 6 files changed, 386 insertions(+), 104 deletions(-)

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000..355f8ae924
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+*.aux
+*.cp
+*.cps
+*.log
+*.toc
\ No newline at end of file
diff --git a/ChangeLog b/ChangeLog
new file mode 100644
index 0000000000..4d48b89d02
--- /dev/null
+++ b/ChangeLog
@@ -0,0 +1,7 @@
+2021-12-28  李俊緯  <mmemmew@gmail.com>
+
+       Update documentation.
+
+       Also add the options to skip invisible lines to some primitive
+       commands.
+
diff --git a/README.org b/README.org
index a75ab71ab1..8c0ecfb30b 100644
--- a/README.org
+++ b/README.org
@@ -15,8 +15,8 @@ The one main function this package provides is 
=ilist-string=.  It is
 called as follows.
 
 #+begin_src emacs-lisp :eval no :exports code
-  (ilist-string LIST COLUMNS GROUPS DISCARD-EMPTY-P
-                SORTER NO-TRAILING-SPACE)
+  (ilist-string LIST COLUMNS GROUPS
+      &optional DISCARD-EMPTY-P SORTER NO-TRAILING-SPACE)
 #+end_src
 
 - LIST is the list that the user wants to display
@@ -24,13 +24,15 @@ called as follows.
 - DISCARD-EMPTY-P determines whether to display empty groups or not
 - SORTER is either nil, or a function with two arguments which returns
   non-nil if and only if the first argument should be sorted before
-  the second argument
-- NO-TRAILING-SPACE is non-nil if the function should not produce
-  trailing whitespaces
+  the second argument.  This is used to sort the elements in the list,
+  before grouping happens.  To sort groups, see the section on
+  groups.
+- NO-TRAILING-SPACE is non-nil if there should be no trailing
+  whitespaces in the resulting string.
 
 ** Columns
 
-Like in ibuffer, the user can specify columns to display.  Each column
+Like in Ibuffer, the user can specify columns to display.  Each column
 comprises the following specifications:
 
 - NAME: The name to display in the header.
@@ -49,8 +51,8 @@ comprises the following specifications:
 
 *** Fixed groups
 
-Like in ibuffer, we can group elements together in the display.  One
-difference with ibuffer is that elements that are not in any group are
+Like in Ibuffer, we can group elements together in the display.  One
+difference with Ibuffer is that elements that are not in any group are
 ignored.  If one wants a "default" group, specify that explicitly.
 The specifications of GROUPS are as follows.
 
@@ -65,28 +67,70 @@ put at the end of the list GROUPS.
 Empty groups might or might not be displayed, depending on the value
 of DISCARD-EMPTY-P.
 
-*** Automatic groups (planned)
+*** Automatic groups
 
-I plan to add support for automatic groups.  This means that, instead
-of providing a list of groups, one provides a function with one
-argument.  That argument will be fed the list of elements.  Then the
-function is supposed to return a list of the following form:
+An automatic filter group is a function that can give labels to
+elements in a list.  These labels will be used to group elements
+automatically: the elements with the same label will be grouped
+together, automagically.  Besides, an automatic filter group is also
+responsible for sorting group labels, and for giving a default label,
+if no labels are specified for some element.
 
-#+begin_src emacs-lisp :eval no :exports code
-  (list
-   (NAME
-    (INDEX1 . ELEMENT1)
-    (INDEX2 . ELEMENT2)
-    ...)
-   ...)
+To be precise, an automatic filter group is a function with the
+signature: =(ELEMENT &optional TYPE)=.  The optional argument =TYPE=
+says what the caller wants from the function:
+
+- nil: If it is omitted or nil, the function should just return the
+  label for =ELEMENT=.
+- default: If it is the symbol =default=, the function should return a
+  default label.
+- sorter: If it is the symbol =sorter=, the function should return a
+  function with two arguments, =X= and =Y=.  This returned function
+  should return a non-nil value if and only if group =X= should be
+  placed earlier than group =Y=.
+
+So, for example, the call =(FUN t 'default)= should produce the
+default label, =(FUN t 'sorter)= should return the function used to
+sort groups, and =(FUN ELEMENT)= should return the label for
+=ELEMENT=, where =FUN= is an automatic filter group.
+
+*** Define automatic filter groups
+
+If one wants to define ones own automatic filter group, then the macro
+=ilist-define-automatic-group=, or the shorter alias
+=ilist-dag=, might come in handy.
+
+In case you wonder, this /dag/ has nothing to do with an /directed
+acyclic graph/; it is just an abbreviation to save some typing.  The
+coincidence of the names is a misfortune.
+
+This macro is called as follows.
+
+#+begin_src emacs-lisp
+  (ilist-dag NAME DEFAULT SORTER &rest BODY)
 #+end_src
 
-That is, it should return cons cells of indices and elements, where
-the indices mean the indices of the corresponding element, in the
-original list.
+- NAME: This is a string.  The resulting function defined by this
+  macro will be named as =ilist-automatic-group-NAME=.
+- DEFAULT: This is also a string.  It is used to label elements for
+  which this automatic group returns nil as its label.
+
+  Why not just let the automatic group function give the default label
+  instead of nil, then?  Well, people make mistakes all the time, at
+  least I do.  So I think this mechanism can help people to remember
+  give a default label for elements. 
+- SORTER: This can be a symbol, or an s-expression.
+
+  If it is a symbol, it will be used as the sorting function of the
+  group labels.  Note that one does not have to quote this symbol,
+  though you can still quote it.
 
-Then the user can provide functions to automatically group elements
-based on the criteria that fit the domain of application.
+  If it is an s-expression., it will be used to define a function
+  =ilist-automatic-group-NAME-sorter=, which then becomes the sorting
+  function.  The variables =X= and =Y= are bound to the labels to sort
+  in this expression.  The sorter function should return a non-nil
+  value if and only if the group labelled =X= should be displayed
+  before the group labelled =Y=.
 
 * Mapping over lines
 
@@ -110,8 +154,8 @@ auxiliary functions to operate on the displayed list.  One 
is
 It might be desired to move between the displayed list items in a
 /cyclic/ manner, that is, assuming the top of the buffer is identified
 with the bottom of the buffer.  So the package provides four functions
-for moving.  If the argument =NO-SKIP-INVISIBLE= is non-nil, then we
-don’t skip invisible lines.
+for moving.  These functions all have an argument =NO-SKIP-INVISIBLE=;
+if that argument is non-nil, then invisible lines won't skipped.
 
 - =ilist-backward-line=
 - =ilist-forward-line=: Move between lines.  One can control whether
diff --git a/ilist.info b/ilist.info
index 2cb4056abb..9d17879cad 100644
--- a/ilist.info
+++ b/ilist.info
@@ -69,22 +69,24 @@ File: ilist.info,  Node: Entry point,  Next: Mapping over 
lines,  Prev: About,
 The one main function this package provides is 'ilist-string'.  It is
 called as follows.
 
-     (ilist-string LIST COLUMNS GROUPS DISCARD-EMPTY-P)
+     (ilist-string LIST COLUMNS GROUPS
+         &optional DISCARD-EMPTY-P SORTER NO-TRAILING-SPACE)
 
 'LIST'
      This denotes the list that the user wants to display.
 'COLUMNS'
 'GROUPS'
-     They are described in the following sections.
+     See *note Columns:: and *note Groups::.
 'DISCARD-EMPTY-P'
      This determines whether to display empty groups or not.
 'SORTER'
      This is either nil, or a function with two arguments which returns
      non-nil if and only if the first argument should be sorted before
-     the second argument.
+     the second argument.  This is used to sort the elements in the
+     list, before grouping happens.  To sort groups, see *note Groups::.
 'NO-TRAILING-SPACE'
-     This is non-nil if the function should not produce trailing
-     whitespaces.
+     If this is non-nil then there will be no trailing whitespaces in
+     the resulting string.
 
 * Menu:
 
@@ -124,17 +126,17 @@ File: ilist.info,  Node: Groups,  Prev: Columns,  Up: 
Entry point
 2.2 Groups
 ==========
 
-The first subsection of this section describes the specifications of
-groups.  And the second describes a planned feature that is not yet
-implemented.
+There are two types of filter groups: the fixed and the automatic filter
+groups.
 
 * Menu:
 
 * Fixed groups::
-* Automatic groups (planned)::
+* Automatic groups::
+* Define automatic filter groups::
 
 
-File: ilist.info,  Node: Fixed groups,  Next: Automatic groups (planned),  
Prev: Groups,  Up: Groups
+File: ilist.info,  Node: Fixed groups,  Next: Automatic groups,  Prev: Groups, 
 Up: Groups
 
 2.2.1 Fixed groups
 ------------------
@@ -158,29 +160,81 @@ is put at the end of the list 'GROUPS'.
 of 'DISCARD-EMPTY-P'.
 
 
-File: ilist.info,  Node: Automatic groups (planned),  Prev: Fixed groups,  Up: 
Groups
+File: ilist.info,  Node: Automatic groups,  Next: Define automatic filter 
groups,  Prev: Fixed groups,  Up: Groups
+
+2.2.2 Automatic groups
+----------------------
+
+An automatic filter group is a function that can give labels to elements
+in a list.  These labels will be used to group elements automatically:
+the elements with the same label will be grouped together,
+automagically.  Besides, an automatic filter group is also responsible
+for sorting group labels, and for giving a default label, if no labels
+are specified for some element.
+
+   To be precise, an automatic filter group is a function with the
+signature: '(ELEMENT &optional TYPE)'.  The optional argument 'TYPE'
+says what the caller wants from the function:
+
+'nil'
+     If it is omitted or nil, the function should just return the label
+     for 'ELEMENT'.
+'default'
+     If it is the symbol 'default', the function should return a default
+     label.
+'sorter'
+     If it is the symbol 'sorter', the function should return a function
+     with two arguments, 'X' and 'Y'.  This returned function should
+     return a non-nil value if and only if group 'X' should be placed
+     earlier than group 'Y'.
+
+   So, for example, the call '(FUN t 'default)' should produce the
+default label, '(FUN t 'sorter)' should return the function used to sort
+groups, and '(FUN ELEMENT)' should return the label for 'ELEMENT', where
+'FUN' is an automatic filter group.
 
-2.2.2 Automatic groups (planned)
---------------------------------
+
+File: ilist.info,  Node: Define automatic filter groups,  Prev: Automatic 
groups,  Up: Groups
+
+2.2.3 Define automatic filter groups
+------------------------------------
+
+If one wants to define ones own automatic filter group, then the macro
+'ilist-define-automatic-group', or the shorter alias 'ilist-dag', might
+come in handy.
 
-I plan to add support for automatic groups.  This means that, instead of
-providing a list of groups, one provides a function with one argument.
-That argument will be fed the list of elements.  Then the function is
-supposed to return a list of the following form:
+   In case you wonder, this _dag_ has nothing to do with an _directed
+acyclic graph_; it is just an abbreviation to save some typing.  The
+coincidence of the names is a misfortune.
 
-     (list
-      (NAME
-       (INDEX1 . ELEMENT1)
-       (INDEX2 . ELEMENT2)
-       ...)
-      ...)
+   This macro is called as follows.
+
+     (ilist-dag NAME DEFAULT SORTER &rest BODY)
+
+'NAME'
+     This is a string.  The resulting function defined by this macro
+     will be named as 'ilist-automatic-group-NAME'.
+'DEFAULT'
+     This is also a string.  It is used to label elements for which this
+     automatic group returns nil as its label.
+
+     Why not just let the automatic group function give the default
+     label instead of nil, then?  Well, people make mistakes all the
+     time, at least I do.  So I think this mechanism can help people to
+     remember give a default label for elements.
+'SORTER'
+     This can be a symbol, or an s-expression.
 
-   That is, it should return cons cells of indices and elements, where
-the indices mean the indices of the corresponding element, in the
-original list.
+     If it is a symbol, it will be used as the sorting function of the
+     group labels.  Note that one does not have to quote this symbol,
+     though you can still quote it.
 
-   Then the user can provide functions to automatically group elements
-based on the criteria that fit the domain of application.
+     If it is an s-expression., it will be used to define a function
+     'ilist-automatic-group-NAME-sorter', which then becomes the sorting
+     function.  The variables 'X' and 'Y' are bound to the labels to
+     sort in this expression.  The sorter function should return a
+     non-nil value if and only if the group labelled 'X' should be
+     displayed before the group labelled 'Y'.
 
 
 File: ilist.info,  Node: Mapping over lines,  Next: Moving,  Prev: Entry 
point,  Up: Top
@@ -190,7 +244,11 @@ File: ilist.info,  Node: Mapping over lines,  Next: 
Moving,  Prev: Entry point,
 
 For the convenience of package-users, this package also provides some
 auxiliary functions to operate on the displayed list.  One is
-'ilist-map-lines'.  It is called as follows.
+'ilist-map-lines'.  Its return value is the list of execution results on
+the lines over which the function is executed.  By default it skips
+invisible lines, but this behaviour can be alterred.
+
+   It is called as follows.
 
      (ilist-map-lines FUN &optional PREDICATE START END NO-SKIP-INVISIBLE)
 
@@ -215,8 +273,8 @@ File: ilist.info,  Node: Moving,  Next: Copying This 
Manual,  Prev: Mapping over
 It might be desired to move between the displayed list items in a
 _cyclic_ manner, that is, assuming the top of the buffer is identified
 with the bottom of the buffer.  So the package provides four functions
-for moving.  If the argument 'NO-SKIP-INVISIBLE' is non-nil, then we
-don’t skip invisible lines.
+for moving.  These functions all have an argument 'NO-SKIP-INVISIBLE';
+if that argument is non-nil, then invisible lines won't skipped.
 
 'ilist-backward-line'
 'ilist-forward-line'
@@ -711,8 +769,55 @@ their use in free software.
 
 File: ilist.info,  Node: Index,  Prev: Copying This Manual,  Up: Top
 
-Index
-*****
+Appendix B Index
+****************
+
+[index]
+* Menu:
+
+* automatic filter groups, example call: Automatic groups.     (line 29)
+* automatic filter groups, mechanism:    Automatic groups.     (line  6)
+* automatic filter groups, types:        Automatic groups.     (line 17)
+* column, specification:                 Columns.              (line  6)
+* columns of the display:                Columns.              (line  6)
+* custom automatic filter groups:        Define automatic filter groups.
+                                                               (line  6)
+* define automatic filter groups:        Define automatic filter groups.
+                                                               (line  6)
+* description:                           About.                (line  6)
+* eliding string:                        Columns.              (line 22)
+* entry point:                           Entry point.          (line  6)
+* filter groups:                         Groups.               (line  6)
+* fixed filter groups:                   Fixed groups.         (line  6)
+* fixed filter groups, default group:    Fixed groups.         (line 18)
+* fixed filter groups, specification:    Fixed groups.         (line 11)
+* functionality:                         About.                (line  6)
+* how to call:                           Entry point.          (line  9)
+* ilist-backward-group-header:           Moving.               (line 12)
+* ilist-backward-line:                   Moving.               (line 12)
+* ilist-dag:                             Define automatic filter groups.
+                                                               (line  6)
+* ilist-dag sorter convention:           Define automatic filter groups.
+                                                               (line 36)
+* ilist-define-automatic-group:          Define automatic filter groups.
+                                                               (line  6)
+* ilist-forward-group-header:            Moving.               (line 12)
+* ilist-forward-line:                    Moving.               (line 12)
+* ilist-map-lines:                       Mapping over lines.   (line  6)
+* ilist-string:                          Entry point.          (line  6)
+* loop through display:                  Mapping over lines.   (line  6)
+* mapping:                               Mapping over lines.   (line  6)
+* moving around:                         Moving.               (line  6)
+* navigations:                           Moving.               (line  6)
+* reason for using default in automatic groups: Define automatic filter groups.
+                                                               (line 25)
+* round buffer:                          Moving.               (line  6)
+* signature of ilist-define-automatic-group: Define automatic filter groups.
+                                                               (line 14)
+* signature of ilist-map-lines:          Mapping over lines.   (line 14)
+* signature of ilist-string:             Entry point.          (line  9)
+* sorting elements:                      Entry point.          (line 20)
+* use:                                   About.                (line  6)
 
 
 
@@ -720,14 +825,15 @@ Tag Table:
 Node: Top764
 Node: About1643
 Node: Entry point2012
-Node: Columns2809
-Node: Groups3694
-Node: Fixed groups3995
-Node: Automatic groups (planned)4856
-Node: Mapping over lines5660
-Node: Moving6409
-Node: Copying This Manual7103
-Node: Index32211
+Node: Columns2976
+Node: Groups3861
+Node: Fixed groups4118
+Node: Automatic groups4969
+Node: Define automatic filter groups6389
+Node: Mapping over lines8132
+Node: Moving9059
+Node: Copying This Manual9790
+Node: Index34898
 
 End Tag Table
 
diff --git a/ilist.pdf b/ilist.pdf
index 6249f32d58..dcddbdd210 100644
Binary files a/ilist.pdf and b/ilist.pdf differ
diff --git a/ilist.texinfo b/ilist.texinfo
index 62f77d20db..e9cb4af1e8 100644
--- a/ilist.texinfo
+++ b/ilist.texinfo
@@ -55,42 +55,59 @@ The document was typeset with
 * Index::
 @end menu
 
+@syncodeindex fn cp
+@syncodeindex vr cp
+
 @c Update all node entries with `C-c C-u C-n'.
 @c Insert new nodes with `C-c C-c n'.
 @node About, Entry point, Top, Top
 @chapter About
 
+@cindex description
+@cindex functionality
+@cindex use
+
 This is a little library package that can @emph{display a list in an
-Ibuffer fashion}.  The core functionality it provides is a function that
-can accept a list, and produce a string showing the contents of the list
-according to the specifications of columns, groups, and sorters.
+Ibuffer fashion}.  The core functionality it provides is a function
+that can accept a list, and produce a string showing the contents of
+the list according to the specifications of columns, groups, and
+sorters.
 
 @node Entry point, Mapping over lines, About, Top
 @comment  node-name,  next,  previous,  up
 @chapter Entry point
 
+@cindex entry point
+@findex ilist-string
+
 The one main function this package provides is @code{ilist-string}.
 It is called as follows.
 
+@cindex signature of ilist-string
+@cindex how to call
+
 @lisp
-(ilist-string LIST COLUMNS GROUPS DISCARD-EMPTY-P)
+(ilist-string LIST COLUMNS GROUPS
+    &optional DISCARD-EMPTY-P SORTER NO-TRAILING-SPACE)
 @end lisp
 
-@table @code
+@table@code
 @item LIST
 This denotes the list that the user wants to display.
 @item COLUMNS
 @itemx GROUPS
-They are described in the following sections.
+See @ref{Columns} and @ref{Groups}.
 @item DISCARD-EMPTY-P
 This determines whether to display empty groups or not.
 @item SORTER
+@cindex sorting elements
 This is either nil, or a function with two arguments which returns
 non-nil if and only if the first argument should be sorted before the
-second argument.
+second argument.  This is used to sort the elements in the list,
+before grouping happens.  To sort groups, see @ref{Groups}.
 @item NO-TRAILING-SPACE
-This is non-nil if the function should not produce trailing
-whitespaces.
+If this is non-nil then there will be no trailing whitespaces in the
+resulting string.
 @end table
 
 @menu
@@ -102,10 +119,13 @@ whitespaces.
 @comment  node-name,  next,  previous,  up
 @section Columns
 
+@cindex columns of the display
+@cindex column, specification
+
 Like in Ibuffer, the user can specify columns to display.  Each column
 comprises the following specifications:
 
-@table @code
+@table@code
 @item NAME
 The name to display in the header.
 @item FUN
@@ -119,6 +139,7 @@ The minimal (resp. maximal) width this column takes.
 Either :left, :right, or :center.  How the contents of the column are
 aligned.
 @item ELIDE
+@cindex eliding string
 If the content of an element takes more space than the MAX, whether to
 substitute the last few characters of that content by a fixed
 @emph{eliding string}.  If this ELIDE is not a string, then it means
@@ -129,24 +150,30 @@ not to elide, but to truncate the contents.
 @comment  node-name,  next,  previous,  up
 @section Groups
 
-The first subsection of this section describes the specifications of
-groups.  And the second describes a planned feature that is not yet
-implemented.
+@cindex filter groups
+
+There are two types of filter groups: the fixed and the automatic
+filter groups.
 
 @menu
 * Fixed groups::
-* Automatic groups (planned)::
+* Automatic groups::
+* Define automatic filter groups::
 @end menu
 
-@node Fixed groups, Automatic groups (planned), Groups, Groups
+@node Fixed groups, Automatic groups, Groups, Groups
 @comment  node-name,  next,  previous,  up
 @subsection Fixed groups
 
+@cindex fixed filter groups
+
 Like in Ibuffer, we can group elements together in the display.  One
 difference with Ibuffer is that elements that are not in any group are
 ignored.  If one wants a "default" group, specify that explicitly.  The
 specifications of @code{GROUPS} are as follows.
 
+@cindex fixed filter groups, specification
+
 @table @code
 @item NAME
 The name of the group.  This will be enclosed in square brackets and
@@ -156,44 +183,127 @@ A function with one argument.  If the function returns 
non-nil, then
 that element is considered to pertain to the group.
 @end table
 
+@cindex fixed filter groups, default group
+
 So a default group just uses a function that always returns @code{t},
 and is put at the end of the list @code{GROUPS}.
 
 Empty groups might or might not be displayed, depending on the value
 of @code{DISCARD-EMPTY-P}.
 
-@node Automatic groups (planned),  , Fixed groups, Groups
+@node Automatic groups, Define automatic filter groups, Fixed groups, Groups
+@comment  node-name,  next,  previous,  up
+@subsection Automatic groups
+
+@cindex automatic filter groups, mechanism
+
+An automatic filter group is a function that can give labels to
+elements in a list.  These labels will be used to group elements
+automatically: the elements with the same label will be grouped
+together, automagically.  Besides, an automatic filter group is also
+responsible for sorting group labels, and for giving a default label,
+if no labels are specified for some element.
+
+To be precise, an automatic filter group is a function with the
+signature: @code{(ELEMENT &optional TYPE)}.  The optional argument
+@code{TYPE} says what the caller wants from the function:
+
+@cindex automatic filter groups, types
+
+@table@code
+@item nil
+If it is omitted or nil, the function should just return the label for
+@code{ELEMENT}.
+@item default
+If it is the symbol @code{default}, the function should return a
+default label.
+@item sorter
+If it is the symbol @code{sorter}, the function should return a
+function with two arguments, @code{X} and @code{Y}.  This returned
+function should return a non-nil value if and only if group @code{X}
+should be placed earlier than group @code{Y}.
+@end table
+
+@cindex automatic filter groups, example call
+
+So, for example, the call @code{(FUN t 'default)} should produce the
+default label, @code{(FUN t 'sorter)} should return the function used
+to sort groups, and @code{(FUN ELEMENT)} should return the label for
+@code{ELEMENT}, where @code{FUN} is an automatic filter group.
+
+@node Define automatic filter groups,  , Automatic groups, Groups
 @comment  node-name,  next,  previous,  up
-@subsection Automatic groups (planned)
+@subsection Define automatic filter groups
 
-I plan to add support for automatic groups.  This means that, instead
-of providing a list of groups, one provides a function with one
-argument.  That argument will be fed the list of elements.  Then the
-function is supposed to return a list of the following form:
+@cindex custom automatic filter groups
+@cindex define automatic filter groups
+@findex ilist-define-automatic-group
+@findex ilist-dag
+
+If one wants to define ones own automatic filter group, then the macro
+@code{ilist-define-automatic-group}, or the shorter alias
+@code{ilist-dag}, might come in handy.
+
+In case you wonder, this @emph{dag} has nothing to do with an
+@emph{directed acyclic graph}; it is just an abbreviation to save some
+typing.  The coincidence of the names is a misfortune.
+
+@cindex signature of ilist-define-automatic-group
+
+This macro is called as follows.
 
 @lisp
-(list
- (NAME
-  (INDEX1 . ELEMENT1)
-  (INDEX2 . ELEMENT2)
-  ...)
- ...)
+(ilist-dag NAME DEFAULT SORTER &rest BODY)
 @end lisp
 
-That is, it should return cons cells of indices and elements, where
-the indices mean the indices of the corresponding element, in the
-original list.
+@table @code
+@item NAME
+This is a string.  The resulting function defined by this macro will
+be named as @code{ilist-automatic-group-NAME}.
+@item DEFAULT
+This is also a string.  It is used to label elements for which this
+automatic group returns nil as its label.
+
+@cindex reason for using default in automatic groups
+
+Why not just let the automatic group function give the default label
+instead of nil, then?  Well, people make mistakes all the time, at
+least I do.  So I think this mechanism can help people to remember
+give a default label for elements.
+@item SORTER
+This can be a symbol, or an s-expression.
+
+If it is a symbol, it will be used as the sorting function of the
+group labels.  Note that one does not have to quote this symbol,
+though you can still quote it.
 
-Then the user can provide functions to automatically group elements
-based on the criteria that fit the domain of application.
+@cindex ilist-dag sorter convention
+
+If it is an s-expression., it will be used to define a function
+@code{ilist-automatic-group-NAME-sorter}, which then becomes the
+sorting function.  The variables @code{X} and @code{Y} are bound to
+the labels to sort in this expression.  The sorter function should
+return a non-nil value if and only if the group labelled @code{X}
+should be displayed before the group labelled @code{Y}.
+@end table
 
 @node Mapping over lines, Moving, Entry point, Top
 @comment  node-name,  next,  previous,  up
 @chapter Mapping over lines
 
+@cindex mapping
+@cindex loop through display
+@findex ilist-map-lines
+
 For the convenience of package-users, this package also provides some
 auxiliary functions to operate on the displayed list.  One is
-@code{ilist-map-lines}.  It is called as follows.
+@code{ilist-map-lines}.  Its return value is the list of execution
+results on the lines over which the function is executed.  By default
+it skips invisible lines, but this behaviour can be alterred.
+
+It is called as follows.
+
+@cindex signature of ilist-map-lines
 
 @lisp
 (ilist-map-lines FUN &optional PREDICATE START END NO-SKIP-INVISIBLE)
@@ -217,11 +327,21 @@ If non-nil, then we don’t skip invisible lines.
 @comment  node-name,  next,  previous,  up
 @chapter Moving
 
+@cindex moving around
+@cindex navigations
+@cindex round buffer
+
 It might be desired to move between the displayed list items in a
 @emph{cyclic} manner, that is, assuming the top of the buffer is
 identified with the bottom of the buffer.  So the package provides
-four functions for moving.  If the argument @code{NO-SKIP-INVISIBLE}
-is non-nil, then we don’t skip invisible lines.
+four functions for moving.  These functions all have an argument
+@code{NO-SKIP-INVISIBLE}; if that argument is non-nil, then invisible
+lines won't skipped.
+
+@findex ilist-forward-line
+@findex ilist-backward-line
+@findex ilist-forward-group-header
+@findex ilist-backward-group-header
 
 @table @code
 @item ilist-backward-line
@@ -240,7 +360,7 @@ Move between group headers.
 @include fdl-1.3.texi
 
 @node Index,  , Copying This Manual, Top
-@unnumbered Index
+@appendix Index
 
 @printindex cp