X-Git-Url: https://www.fleuret.org/cgi-bin/gitweb/gitweb.cgi?a=blobdiff_plain;f=selector.1;h=7e0835db2bedd6bea6df61346fb111bf0258f3bf;hb=b15b3147e8a6deffa2f742b3b5d6c7ee5fb09671;hp=cc9209ac09205698c0dfe41abc237fb815baa5cb;hpb=31a7b19d2aad15f9804b2377a16d518f54038675;p=selector.git

diff --git a/selector.1 b/selector.1
index cc9209a..7e0835d 100644
--- a/selector.1
+++ b/selector.1
@@ -1,42 +1,114 @@
-.TH "SELECTORcg" "1"
+.TH "SELECTOR" "1"
 .SH "NAME"
-selector - A simple shell command for dynamic pattern selection
+selector - A simple command line utility for dynamic pattern selection
 .SH "SYNOPSIS"
 .PP
-\fBselector\fP [\fBoptions\fP] -f <filename>
+\fBselector\fP [\fBoptions\fP] [<filename1> [<filename2> ...]]
 .SH "DESCRIPTION"
 .PP
-\fBselector\fP is a simple shell command which provides a dynamic
-string selection. A you type a list of substring separated by ';', the
-display is updated to show only the lines containing all the said
-substrings.
+\fBselector\fP is a command line utility for dynamic string
+selection. As you type a list of strings separated by ";" or a regexp,
+the display is updated in real time to show only the lines containing
+all the said strings, or matching the regexp.
 
-The main usage of selector is as a super shell-history. With the
-correct option, it will inject the selected line into the virtual tty
-input buffer, hence allowing the user to edit the line and execute it
-as a standard command.
+The main usage of selector is as an efficient search in the shell
+command history. With the correct option, it will inject the selected
+line into the virtual tty input buffer, hence allowing the user to
+edit the line and execute it as a standard command.
+
+Selector is also a good tool to test regexps.
+
+.SH "KEYS"
+.PP
+
+Keys corresponding to ASCII codes between " " and "~" add a character
+to the pattern string. The Backspace key, "^H" and "^?" delete the
+character immediately on the left of the cursor, while the Delete key
+and "^D" delete the character at cursor location.
+
+The Up and Down cursor keys move the selected line accordingly, and
+PageUp and PageDown move by ten lines. The Home and End key move to
+the top and the bottom of the list respectively. The return key
+selects the current line and exits.
+
+The shortcuts "^A", "^E", "^U", and "^K" do somehow what they do in
+readline, and you can exit selector without doing anything by either
+interrupting the command with "^C" or by typing "^G".
+
+The "^R" key switches between the standard multi-substring mode and
+the regexp mode, and "^I" between the case-sensitive and
+case-insensitive modes.
 
 .SH "OPTIONS"
 .IP "\fB-h\fP" 10
 display help and exits
+.IP "\fB-m\fP" 10
+force the monochrome mode
+.IP "\fB-i\fP" 10
+inverse the order of the lines
+.IP "\fB-b\fP" 10
+remove the numeric prefix from bash history
+.IP "\fB-z\fP" 10
+remove the time prefix from zsh history
+.IP "\fB-d\fP" 10
+remove duplicated lines
+.IP "\fB-e\fP" 10
+start with the regexp mode activated
+.IP "\fB-a\fP" 10
+make the matching case sensitive
+.IP "\fB-q\fP" 10
+make a flash instead of a beep when there is an edition error
+.IP "\fB--\fP" 10
+state that all following arguments are filenames
+.IP "\fB-t <title>\fP" 10
+add a title in the modeline
+.IP "\fB-c <fg modeline> <bg modeline> <fg highlight> <bg highlight>\fP" 10
+select the modeline and highlight color numbers
 .IP "\fB-v\fP" 10
 inject the selected line into the tty input buffer
-.IP "\fB-t <color theme number>\fP" 10
-select a color them
 .IP "\fB-o <output filename>\fP" 10
 write the selected line into the specified file
 .IP "\fB-s <pattern separator>\fP" 10
 specify the symbol to separate the substrings in the search pattern
 .IP "\fB-l <max number of lines>\fP" 10
-specify the maximum number of lines to consider
+specify the maximum number of lines to take into account
 .IP "\fB-f <input filename>\fP" 10
-specify the file to search into
+specify a file to search into (option kept for compatibility reasons)
 
 .SH "EXAMPLES"
 
-To use selector to search into your shell history:
+To use selector to search into your bash history, you can use
+
+.B selector -d -i -b -v <(history)
+
+.SH "INTERACTION WITH READLINE"
+
+For better efficiency, you can associate selector to a single key in
+in the console through the use of the readline configuration file
+~/.inputrc.
+
+To do so, you have first to pick a key and know the character sequence
+associated to it. You can figure that out by typing at the console
+prompt Ctrl-q followed by the key you want to use. For instance, if
+you want to use Alt-r, you may get "^[r". Then, you have to add in
+~/.inputrc the following line:
+
+"^[r": "^A^K selector -d -i -b -v <(history)^M"
+
+Note that you have to put the actual control characters in the
+configuration file, not a "^" followed by a character. To do so with
+Emacs for instance, you have to use the Ctrl-q key followed by another
+key: Ctrl-q Ctrl-a inserts "^A", Ctrl-q Ctrl-[ inserts "^[", etc.
+
+These control characters have the following roles: "^A" puts the
+cursor to the mostleft location, "^K" erases the current content of
+the readline buffer, and "^M" simulates the enter key.
+
+.SH "BUGS"
 
-selector -f ${HISTFILE} -v
+There are modeline display problems if the pattern is too long. If a
+line contains control characters, the returned line has been converted
+to printable characters.
 
 .SH "AUTHOR"
 .PP