branch: externals/blist
commit a41af4fc54fc7cae564591dc15d2396400ba9436
Author: JSDurand <mmem...@gmail.com>
Commit: JSDurand <mmem...@gmail.com>
Add documentation.
Now the documentation also records the option `blist-select-manner`
and its various options. It also contains a detailed description of
the tab naming process now.
---
README.org | 123 +++++++++++++++++++++++++++++++++++++++++-
blist.texinfo | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 290 insertions(+), 2 deletions(-)
diff --git a/README.org b/README.org
index 02f45f7f27..bad5822d15 100644
--- a/README.org
+++ b/README.org
@@ -327,7 +327,128 @@ group) at point.
- =o=: Open the bookmark in another window.
- =v=: Select the bookmarks (the MG0-convention). How multiple
bookmarks are opened is controlled by the variable
- =blist-select-manner=. See its documentation for details.
+ =blist-select-manner=. This will be detailed in the following
+ subsection.
+
+*** Opening multiple bookmarks
+
+The function =blist-select= can open multiple bookmarks at the same
+time. It opens the bookmarks selected according to the
+MG0-convention, as the above already said. Now we will see how these
+multiple bookmarks are opened.
+
+If the finction =blist-select= is invoked without prefix argument, the
+variable =blist-select-manner= will be used to determine the way
+multiple bookmarks are opened; otherwise, it will prompt the user and
+read a list of opening options.
+
+As a quick summary, if the list does not contain /left/, it means to
+use /right/; if no /up/, it means /down/; if no /vertical/, it means
+/horizontal/.
+
+There will be no errors if there are unrecognized symbols in the list:
+they are simply ignored.
+
+To be more precise, the variable =blist-select-manner= controls how
+the windows that hold the opened bookmarks will be placed, as follows:
+
+- /vertical/: The windows will be placed in a /vertical/ direction.
+ Its direction is upwards or downwards, according to further options
+ below.
+- /horizontal/: The windows will be placed in a /horizontal/
+ direction. Its direction is leftwards or rightwards, according to
+ further options below.
+
+ If both /vertical/ and /horizontal/ are present, /vertical/ take
+ precedence.
+- /spiral/: The windows are opened in a spiral manner: first a window
+ is opened below (or above) the reference window, then another window
+ is opened to the left (or right) of the first window, with size half
+ that of the first window. This process of vertical / horizontal
+ alteration continues afterwards.
+
+ The up / down / left / right direction is determined by the
+ options below.
+- /main-side/: The first window is opened as the main window, and the
+ other windows are put in side slides. If /vertical/ is present, the
+ side windows are either at the bottom or at the top; otherwise the
+ side windows are either at the left or at the right. This takes
+ precedence over /spiral/.
+- /left/, /right/, /up/, /down/: Determines the direction of opening
+ windows. The precedence relation is that /left/ takes precedence
+ over /right/ and /up/ over /down/.
+- /onetab/: All the windows and bookmarks are opened in a new tab.
+
+ If =blist-select= is invoked with a prefix argument, the function
+ will prompt the user for a name of the new tab. The user can leave
+ the name empty, and then the name of the new tab will be determined
+ automatically. The bookmark names of the selected items will be
+ available through the histories while entering the name of the new
+ tab.
+
+ Note that this requires the package =tab-bar=.
+- /one-per-tab/: A new tab will be created for each bookmark. If this
+ option is present, all other options will be ignored, as each
+ bookmark is opened as the only window in the dedicated tab, and
+ there is no need to bother with the window directions. The tab for
+ the first item will be selected after the execution of this
+ function.
+
+ The names of the new tabs will be determined in the following
+ manner:
+
+ After creating a tab and jumping to the corresponding bookmark in
+ that tab, the user will be prompted for how to name the tab. The
+ user has the following options.
+ + =y=: The user will be prompted for the name of the new tab. The
+ user can leave the name empty for automatic naming.
+
+ + =Y=: For each following item, it will be assumed that the user
+ will enter =y=.
+
+ + =n=: The tab name will not be modified.
+
+ The user can also enter some (possibly negative) number before
+ entering =n=, and that number of tabs will be skipped.
+
+ + =N=, =!=: For each following item, it will be assumed that the
+ user will enter =n=.
+
+ + =b=: The name of the new tab will be the name of the corresponding
+ bookmark.
+
+ + =B=, ===: For each following item, it will be assumed that the
+ user will enter =b=.
+
+ + =p=: The function will jump to the previous tab and run the same
+ procedure to allow the user to change the previous tab name.
+
+ The user can also enter some number before entering =p=, so that
+ this procedure simply rolls back that number of items.
+
+ If no more previous tabs exist, just ask the same question again.
+
+ + =C-g=: Quit the bookmark opening, tab-creating, tab-naming
+ procedure. Note that those already-opened tabs will not be
+ closed.
+
+ + *anything else*: A help screen will be displayed, a help message
+ will be shown, and the same question will be asked again. If the
+ user presses keys that are not listed above in a row, then the
+ help screen will be scrolled. The user can press =-= before
+ pressing such a key, and the help screen will be scrolled in the
+ other direction.
+
+ In addition, while the user is in the process of determing how to
+ name the tabs, if ther user presses =tab= or =C-i=, the prompt will
+ include additional information about how many items remain to be
+ determined, what tabs are already opened, and which tab we are in
+ right now.
+
+ After the execution of this function, the information about tabs
+ will also be shown in the echo area.
+
+ Note that this requires the package =tab-bar=.
** Annotations
diff --git a/blist.texinfo b/blist.texinfo
index 7a46ce6a4e..373a0d69dd 100644
--- a/blist.texinfo
+++ b/blist.texinfo
@@ -94,6 +94,10 @@ Two default automatic groups
* Default group::
* Type-only group::
+Jump to bookmarks
+
+* Opening multiple bookmarks::
+
@end detailmenu
@end menu
@@ -685,7 +689,170 @@ Open the bookmark in another window.
@vindex blist-select-manner
Select the bookmarks (the @strong{MG0-convention}). How multiple
bookmarks are opened is controlled by the variable
-@code{blist-select-manner}. See its documentation for details.
+@code{blist-select-manner}. This will be detailed in the following
+subsection.
+@end table
+
+@menu
+* Opening multiple bookmarks::
+@end menu
+
+@node Opening multiple bookmarks, , Jump to bookmarks, Jump to bookmarks
+@comment node-name, next, previous, up
+@subsection Opening multiple bookmarks
+
+@vindex blist-select-manner
+@cindex multiple bookmarks
+
+The function @code{blist-select} can open multiple bookmarks at the same
+time. It opens the bookmarks selected according to the
+@strong{MG0-convention}, as the above already said. Now we will see how
+these multiple bookmarks are opened.
+
+If the finction @code{blist-select} is invoked without prefix argument,
+the variable @code{blist-select-manner} will be used to determine the
+way multiple bookmarks are opened; otherwise, it will prompt the user
+and read a list of opening options.
+
+As a quick summary, if the list does not contain @emph{left}, it means
+to use @emph{right}; if no @emph{up}, it means @emph{down}; if no
+@emph{vertical}, it means @emph{horizontal}.
+
+There will be no errors if there are unrecognized symbols in the
+list: they are simply ignored.
+
+To be more precise, the variable @code{blist-select-manner} controls how
+the windows that hold the opened bookmarks will be placed, as follows:
+
+@table @emph
+@cindex vertical
+@item vertical
+The windows will be placed in a @emph{vertical} direction. Its
+direction is upwards or downwards, according to further options below.
+@cindex horizontal
+@item horizontal
+The windows will be placed in a @emph{horizontal} direction. Its
+direction is leftwards or rightwards, according to further options
+below.
+
+If both @emph{vertical} and @emph{horizontal} are present,
+@emph{vertical} take precedence.
+@cindex spiral
+@item spiral
+The windows are opened in a spiral manner: first a window is opened
+below (or above) the reference window, then another window is opened to
+the left (or right) of the first window, with size half that of the
+first window. This process of vertical / horizontal alteration
+continues afterwards.
+
+The up / down / left / right direction is determined by the options
+below.
+@cindex main-side
+@item main-side
+The first window is opened as the main window, and the other windows are
+put in side slides. If @emph{vertical} is present, the side windows are
+either at the bottom or at the top; otherwise the side windows are
+either at the left or at the right. This takes precedence over
+@emph{spiral}.
+@cindex left
+@cindex right
+@cindex up
+@cindex down
+@item left
+@itemx right
+@itemx up
+@itemx down
+Determines the direction of opening windows. The precedence relation is
+that @emph{left} takes precedence over @emph{right} and @emph{up} over
+@emph{down}.
+@cindex tab
+@cindex onetab
+@cindex one-tab
+@item onetab
+All the windows and bookmarks are opened in a new tab.
+
+If @code{blist-select} is invoked with a prefix argument, the function
+will prompt the user for a name of the new tab. The user can leave the
+name empty, and then the name of the new tab will be determined
+automatically. The bookmark names of the selected items will be
+available through the histories while entering the name of the new tab.
+
+Note that this requires the package @code{tab-bar}.
+@cindex one-per-tab
+@cindex one tab per bookmark
+@cindex one bookmark per tab
+@item one-per-tab
+A new tab will be created for each bookmark. If this option is present,
+all other options will be ignored, as each bookmark is opened as the
+only window in the dedicated tab, and there is no need to bother with
+the window directions. The tab for the first item will be selected
+after the execution of this function.
+
+The names of the new tabs will be determined in the following manner:
+
+After creating a tab and jumping to the corresponding bookmark in that
+tab, the user will be prompted for how to name the tab. The user has
+the following options.
+@cindex tab options
+@itemize
+@item @kbd{y}
+The user will be prompted for the name of the new tab. The user can
+leave the name empty for automatic naming.
+
+@item @kbd{Y}
+For each following item, it will be assumed that the user will enter
+@kbd{y}.
+
+@item @kbd{n}
+The tab name will not be modified.
+
+The user can also enter some (possibly negative) number before entering
+@kbd{n}, and that number of tabs will be skipped.
+
+@item @kbd{N}
+@item @kbd{!}
+For each following item, it will be assumed that the user will enter
+@kbd{n}.
+
+@item @kbd{b}
+The name of the new tab will be the name of the corresponding bookmark.
+
+@item @kbd{B}
+@item @kbd{=}
+For each following item, it will be assumed that the user will enter
+@kbd{b}.
+
+@item @kbd{p}
+The function will jump to the previous tab and run the same procedure to
+allow the user to change the previous tab name.
+
+The user can also enter some number before entering @kbd{p}, so that
+this procedure simply rolls back that number of items.
+
+If no more previous tabs exist, just ask the same question again.
+
+@item @kbd{C-g}
+Quit the bookmark opening, tab-creating, tab-naming procedure. Note
+that those already-opened tabs will not be closed.
+
+@item @strong{anything else}
+A help screen will be displayed, a help message will be shown, and the
+same question will be asked again. If the user presses keys that are
+not listed above in a row, then the help screen will be scrolled. The
+user can press @kbd{-} before pressing such a key, and the help screen
+will be scrolled in the other direction.
+@end itemize
+
+In addition, while the user is in the process of determing how to name
+the tabs, if ther user presses @kbd{tab} or @kbd{C-i}, the prompt will
+include additional information about how many items remain to be
+determined, what tabs are already opened, and which tab we are in right
+now.
+
+After the execution of this function, the information about tabs will
+also be shown in the echo area.
+
+Note that this requires the package @code{tab-bar}.
@end table
@node Annotations, Others, Jump to bookmarks, Usage
