Improve the manual.

1 files changed, 148 insertions, 121 deletions

diff --git a/smenu.1 b/smenu.1
index b7eb80d..df951a7 100644
--- a/smenu.1
+++ b/smenu.1
@@ -43,8 +43,8 @@ Non-selectable words are skipped when moving the selection cursor and
 cannot be searched for.
 .P
 The \fB-W\fP option can be used to set the characters (or multibyte
-sequences) which will be used to delimit the input words. The default
-delimiters are: \fISPACE\fP, \fI\\t\fP and \fI\\n\fP.
+sequences) which will be used to delimit the input words.
+The default delimiters are: \fISPACE\fP, \fI\\t\fP and \fI\\n\fP.
 .P
 The \fB-L\fP has a similar meaning for lines.
 .P
@@ -57,8 +57,8 @@ word separators so that a group of words are taken as a single entity.
 .P
 Non printable characters in words that are not a delimiter are
 converted to their traditional form (\fI\\n\fP for end-of-line,
-\fI\\t\fP for tabulation...) by default. A single dot (\fI.\fP) is also
-used as a placeholder otherwise.
+\fI\\t\fP for tabulation...) by default.
+A single dot (\fI.\fP) is also used as a placeholder otherwise.
 .P
 \fBWarning\fP, \fBUTF-8\fP encoded codepoints are quietly converted
 into a dot (\fI.\fP) when the user locale is not \fBUTF-8\fP aware like
@@ -71,86 +71,92 @@ or the \fIvi\fP direction keys (\fBh\fP, \fBj\fP, \fBk\fP and \fBl\fP).
 \fBHOME\fP, \fBEND\fP, \fBPgDn\fP and \fBPgUp\fP can also be used if
 available and have their traditional meanings.
 .SS "Searching for a word"
-The \fB/\fP or \fB^F\fP (\fBCtrl-f\fP) can be used to initiate a
-search by prefix among the words after the cursor.
+The key \fB/\fP or the key combination \fB^F\fP (\fBCtrl-f\fP) can be
+used to initiate a search by prefix among the words after the cursor.
 .P
-After that the cursor attribute is modified and all the characters
-entered 7s after this change go in a search buffer with the cursor
-moving immediately to the next word matching this prefix. Any character
-entered within 5s after that completes that buffer and resets the 5s
-timer and possibly moves the cursor again.
+After that, the cursor attribute is modified and all characters
+entered 7s after this change go into a search buffer with the cursor
+moving immediately to the next word matching this prefix.
+.P
+Any character entered in the 5s after this action completes this buffer,
+resets the 5s timer and advances the cursor again if another word matches
+the new buffer.
 .P
 As soon as the timer ends, the search mode is ended and the cursor
 regains its initial appearance.
 .P
 The search buffer is persistent as long as the cursor is on a matching
 word when a new search is initialized.
-.br
-If the beginning of the word under the cursor does not match the
-previous search buffer, then the search buffer if erased.
 .P
-At any time in this mode you can move the cursor with the keys
-described above. \fBESC\fP ends this mode immediately.
+If the cursor is moved in this mode, the timer will expire immediately
+As if \fBENTER\fP or \fBESC\fP was pressed.
+.P
+Pressing \fBENTER\fP or \fBESC\fP immediately exits this mode.
 .P
-The \fBSPACE\fP or \fBn\fP key repeats the last search if the search
-buffer is not empty. As in search mode, nothing happens if there is no
-matching word after the cursor.
+Pressing \fBSPACE\fP or \fBn\fP repeats the last search if the search
+buffer is not empty.
+Nothing will happen if there is no matching word after the cursor.
 .P
 Note that the \fBSPACE\fP and \fBn\fP keys cannot be used when the search
 mode is active because they must be available if you want to search a
 word containing these characters.
 .SS "Selection and Exit"
-Hitting \fBq\fP exits without outputting anything, nothing is selected.
+Pressing \fBq\fP gives the possibility to exit without selecting anything.
 .P
-By default, hitting \fBENTER\fP writes the selected word to stdout when
-not in search mode. In search mode \fBENTER\fP ends this mode and does
-nothing more. If you want to be able to select a word \fIeven\fP in
-search mode, use the \fB-r\fP option to change this behavior.
+By default, \fBENTER\fP writes the selected word to stdout when not in
+search mode otherwise it exits from this mode and does nothing more.
+If you want to be able to select a word \fIeven\fP when in search mode,
+use the \fB-r\fP option to change this behavior.
 .SS Help
-A small help message can be displayed when hitting \fB?\fP. This display
-will last for 10s or until a valid key or \fBESC\fP is pressed.
+A small help message can be displayed when hitting \fB?\fP.
+This display will last for 10s or until a valid key or \fBESC\fP is
+pressed.
 .SS Scroll bar
-A scroll bar is displayed at the right of the scrolling window. Its
-appearance is meant to be classical but it has some particularities:
+A scroll bar is displayed at the right of the scrolling window.
+Its appearance is meant to be classical but it has some particularities:
 .IP * 2
 The scroll bar is not displayed if all the input words fit on only one
 line.
 .IP * 2
 Otherwise, the scroll bar is always displayed except when the \fB-q\fP
-option is set. This option completely disables the scroll bar display.
+option is set.
+This option completely disables the scroll bar display.
 .IP * 2
 When the scrolling window has only one line, the scroll bar has only 3
 states:
 .RS 2
 .IP - 2
-"\fBv\fP" when on all but the last line, indicating that you can go down
+\fBv\fP when on all but the last line, indicating that you can go down
 to see more.
 .IP - 2
-"\fB^\fP" when on the last line.
+\fB^\fP when on the last line.
 .IP - 2
-"\fB|\fP" otherwise.
+\fB|\fP otherwise.
 .RE
 .IP * 2
-When there is more than one line to display, "\fB/\fP" means that the window
-displays the first line, "\fB\\\fP" the last line. "\fB|\fP" is used to fill
-the gap, see below the different possible configurations.
+When there is more than one line to display, \fB/\fP means that the window
+displays the first line, \fB\\\fP the last line.
+\fB|\fP is used to fill the gap, see below the different possible
+configurations.
 .TS
+tab(@);
 l l l l l
 l l l l l
-l l l l.
-\\	\\	^	^	\\ 
-|	|	|	|	/
-/	v	/	v
+l l l l .
+\\@\\@^@^@\\ @Do not remove this trailing space!
+|@|@|@|@/
+/@v@/@v
 .TE
 .P
-A "\fB+\fP" can also appear in the scroll bar in lieu of a "\fB|\fP",
+A \fB+\fP can also appear in the scroll bar in lieu of a \fB|\fP,
 giving the relative position of the cursor line in the bunch of input
 words.
 .SS "Terminal resizing"
-The windows is redrawn if the terminal is resized. The redrawing is
-actually done only 1s after the end of the resizing to avoid artefacts
-on screen. The cursor will remain on the current selected word but may
-be displayed on another place in the window.
+The windows is redrawn if the terminal is resized.
+The redrawing is actually done only 1s after the end of the resizing to
+avoid artefacts on screen.
+The cursor will remain on the current selected word but may be displayed
+on another place in the window.
 .SS Unicode support
 This utility is Unicode aware and should be able to display correctly
 any Unicode character (even double-width ones) as long as the current
@@ -210,7 +216,9 @@ allowed:
 The \fBmethod\fP keyword can take the two possible values displayed
 above and determines if you want to use the native method (limited to 8
 colors) of the \fBansi\fP method (ISO 8613-6) if your terminal supports
-more than 8 colors. The default value corresponds to \fBansi\fP.
+more than 8 colors.
+
+The default value corresponds to \fBansi\fP.
 
 The attributes syntax is [fg][/bg][,toggles] where \fBfg\fP and
 \fBbg\fP are numbers representing the foreground and background
@@ -220,46 +228,54 @@ color and \fBtoggles\fP is a strings which can contain the characters
 and \fIi\fPtalic.
 .IP * 2
 Spaces are allowed anywhere in the lines and between them, even around
-the "\fB=\fP".
+the \fB=\fP.
 .IP * 2
 Everything following a \fB;\fP is ignored.
+.IP * 2
+When undefined, the default limits are:
+.TS
+tab(@);
+l l .
+words@32767
+word_length@256
+columns@256
+.TE
 .SH OPTIONS
 .IP "\fB-h\fP or \fB-?\fP"
 Displays a log (\fB-h\fP) or short (\fB-?\fP) help message and exits.
 .IP "\fB-n\fP \fIlines\fB"
-Gives the maximum number of lines in the scrolling selection window. By
-default five lines at most are displayed and the other ones, if
+Gives the maximum number of lines in the scrolling selection window.
+By default five lines at most are displayed and the other ones, if
 any, need you to scroll the window.
 .IP "\fB-t\fP [\fIcolumns\fP]"
 This option sets the tabulation mode and, if a number is specified,
 limits the number of displayed columns to that number.
-
-In this mode, embedded line separators are ignored. The options \fB-A\fP
-and \fB-Z\fP can nevertheless be used to force words to appear in the first
-(respectively last) position of the displayed line.
+In this mode, embedded line separators are ignored.
+The options \fB-A\fP and \fB-Z\fP can nevertheless be used to force words
+to appear in the first (respectively last) position of the displayed line.
 .P
 .RS
 Note that in this mode each column has the same width.
 .RE
 .IP \fB-k\fP
 By default, the spaces surrounding the output string will be deleted.
-This option forces them to be retained. Note that these spaces must have
-been protected to be selected.
+This option forces them to be retained.
+Note that these spaces must have been protected to be selected.
 .IP "\fB-s\fP \fIpattern\fP"
 Pre-Position the cursor to the first word matching the specified pattern.
 
 \fIpattern\fP can be:
 .RS
 .IP * 2
-A "\fB#\fP" immediately followed by a \fBnumber\fP giving the initial
-position of the cursor (counting from 0). If this number if greater than
-the number of words, the cursor will be set on the latest selectable
-position.
+A \fB#\fP immediately followed by a \fBnumber\fP giving the initial
+position of the cursor (counting from 0).
+If this number if greater than the number of words, the cursor will be
+set on the latest selectable position.
 .IP * 2
-A single "\fB#\fP" or the string \fB#last\fP to set the initial
+A single \fB#\fP or the string \fB#last\fP to set the initial
 cursor position to the latest selectable word position.
 .IP * 2
-A string starting with a "\fB/\fP" indicating that we want the cursor
+A string starting with a \fB/\fP indicating that we want the cursor
 to be set to the first word matching the given regular expression.
 .IP * 2
 A \fBprefix\fP string indicating that we want the cursor to be set on the
@@ -274,21 +290,23 @@ on \fBa\fP but \f(CBsmenu -I/c/x/v -s/c <<< "a b c d"\fP will find it and
 put the cursor on the \fBx\fP substituting the \fBc\fP on screen only
 .RE
 .IP "\fB-m\fP \fImessage\fP"
-Displays a message above the window. Beware, it will truncated if it
-does not fit on a terminal line.
+Displays a message above the window.
+Beware, it will truncated if it does not fit on a terminal line.
 .IP "\fB-w\fP"
 When \fB-t\fP is followed by a number of columns, the default is to
 compact the columns so that they use the less terminal width as
-possible. This option enlarges the columns in order to use the whole
-terminal width.
+possible.
+This option enlarges the columns in order to use the whole terminal width.
 
 When in column mode, \fB-w\fP can be used to force all the columns to
-have the same size (the largest one). See option \fB-c\fP below.
+have the same size (the largest one).
+See option \fB-c\fP below.
 .P
 .RS
 Note that the column's size is only calculated once when the words are
-displayed for the first time. A terminal resize will not update this
-value.  This choice enables a faster display.
+displayed for the first time.
+A terminal resize will not update this value.
+This choice enables a faster display.
 .RE
 .P
 .IP \fB-d\fP
@@ -297,10 +315,10 @@ the selection window after use as if it was never displayed.
 .IP \fB-M\fP
 Centers the display if possible.
 .IP \fB-c\fP
-Sets the column mode. In this mode the lines of words do not wrap when
-the right border of the terminal is reached but only when a special
-character is read. Some words will not be displayed without an
-horizontal scrolling.
+Sets the column mode.
+In this mode the lines of words do not wrap when the right border of
+the terminal is reached but only when a special character is read.
+Some words will not be displayed without an horizontal scrolling.
 
 If such a scrolling is needed, some indications may appear on the left
 and right edge of the window to help the user to reach the unseen words.
@@ -308,15 +326,15 @@ and right edge of the window to help the user to reach the unseen words.
 In this mode, the width of each column is minimal to keep the maximum
 information visible on the terminal.
 .IP \fB-l\fP
-Sets the line mode. This mode is the same as column mode but without
-any column alignment.
+Sets the line mode.
+This mode is the same as column mode but without any column alignment.
 .IP \fB-r\fP
 Enables \fBENTER\fP to validate the selection even in search mode.
 .IP \fB-b\fP
 Replace all non-printable characters by a blank.
 .IP "\fB-i\fP \fIregex\fP"
-Sets the \fBi\fPnclude filter to match the selectable words. All the
-other words will become non-selectable (excluded)
+Sets the \fBi\fPnclude filter to match the selectable words.
+All the other words will become non-selectable (excluded)
 .IP "\fB-e\fP \fIregex\fP"
 Sets the \fBe\fPxclude filter to match the non-selectable words.
 
@@ -326,9 +344,9 @@ The \fIregex\fP selections above are done before the possible word
 alterations realized with \fB-I\fP or \fB-E\fP (see below).
 .IP "\fB-C\fP [a|A|s|S|r|R|d|D][col1[-col2]],[col1[-col2]]..."
 In column mode, restricts the previous selections or de-selections to
-some columns. If no selection is given via \fB-i\fP and \fB-e\fP this
-option gives the possibility to select entire columns by giving their
-numbers (1 based).
+some columns.
+If no selection is given via \fB-i\fP and \fB-e\fP this option gives the
+possibility to select entire columns by giving their numbers (1 based).
 
 \fBa\fP/\fBA\fP, \fBs\fP/\fBS\fP or nothing select the specified ranges
 of columns. \fBr\fP/\fBR\fP or \fBd\fP/\fBD\fP select all but the
@@ -338,8 +356,8 @@ The words in the selected columns will be considered as included and the
 others excluded.
 
 Example of columns selection: \fI-a2,3,5-7\fP forces the cursor to only
-navigate in columns \fB2\fP,\fB3\fP,\fB5\fP,\fB6\fP and \fB7\fP. If
-\fBd\fP was used in place of \fBa\fP, all the columns would have been
+navigate in columns \fB2\fP,\fB3\fP,\fB5\fP,\fB6\fP and \fB7\fP.
+If \fBd\fP was used in place of \fBa\fP, all the columns would have been
 selected \fBexcept\fP the columns \fB2\fP,\fB3\fP,\fB5\fP,\fB6\fP and
 \fB7\fP.
 
@@ -353,12 +371,12 @@ One difference though: this is the line mode which is forced by this
 option NOT the column mode.
 .IP "\fB-S\fP /\fIregex\fP/replacement string/[g][v][s]"
 Post-processes the words by applying a regular expression based
-substitution. The argument must be formatted as in the \fBsed\fP
-editor.
+substitution.
+The argument must be formatted as in the \fBsed\fP editor.
 
-This option can be used more than once. Each substitution will be
-applied in sequence on each word. This sequence can be stopped if a
-\fBstop\fP flag is encountered.
+This option can be used more than once.
+Each substitution will be applied in sequence on each word.
+This sequence can be stopped if a \fBstop\fP flag is encountered.
 
 .RS
 \fBflags:\fP
@@ -367,8 +385,8 @@ The optional trailing \fBg\fP (for \fIg\fPlobal) means that all matched
 occurrences shall be replaced and not only the first one.
 .IP * 2
 The optional trailing \fBv\fP (for \fIv\fPisual) means that the altered
-words will only be used for display and search. The modifications will
-\fInot\fP be reflected in the returned word.
+words will only be used for display and search.
+The modifications will \fInot\fP be reflected in the returned word.
 .IP * 2
 The optional trailing \fBs\fP (for \fIs\fPtop) means that no more
 substitution will be allowed on this word even if another \fB-S\fP is
@@ -384,8 +402,8 @@ B\fP is
 selected meanwhile
 \f(CBR=$(echo a b c | smenu -S /b/B/\fBv\fP)\fR
 will display the same as above but \f(CBR\fP will contain the original
-word \fIb\fP if \fIB\fP is selected. In both cases, only the word
-\fIB\fP will be searchable and not \fIb\fP.
+word \fIb\fP if \fIB\fP is selected.
+In both cases, only the word \fIB\fP will be searchable and not \fIb\fP.
 .RE
 Notice that a substitution resulting in an empty string is equivalent
 to removing the word.
@@ -402,29 +420,31 @@ substituted by any other character except \fISPACE\fP, \fI\\t\fP,
 \fI\\f\fP, \fI\\n\fP, \fI\\r\fP and \fI\\v\fP.
 .P
 In the four previous options, \fIregex\fP is a \fBPOSIX\fP
-\fBE\fPxtended \fBR\fPegular \fBE\fPxpression. For details, please refer
-to the \fBregex\fP manual page.
+\fBE\fPxtended \fBR\fPegular \fBE\fPxpression.
+For details, please refer to the \fBregex\fP manual page.
 .IP "\fB-A\fP \fIregex\fP"
 In column mode, forces all words matching the given regular expression
-to be the first one in the displayed line. If you want to only rely on
-this method to build the lines, just specify an empty
-\fBregex\fP to set the end-of-line separator with \fI-L ''\fP)
+to be the first one in the displayed line.
+If you want to only rely on this method to build the lines, just specify
+an empty \fBregex\fP to set the end-of-line separator with \fI-L ''\fP)
 .IP "\fB-Z\fP \fIregex\fP"
 Similar to \fB-A\fP but forces the word to be the latest of its line.
 The same trick with \fB-L\fP can also be used.
-.IP "\fB-1\fP ... \fB-5\fP \fIregex\fP [\fIATTR\fP]
+.IP "\fB-1\fP ... \fB-5\fP \fIregex\fP [\fIATTR\fP]"
 Allows to give up to 5 classes of words specified by regular expressions a
-special display color. They are called \fBspecial levels\fP. Only
-selectable words will be considered.
+special display color.
+They are called \fBspecial levels\fP.
+Only selectable words will be considered.
 
 By default, the 5 special levels have their foreground color set to
-red, green, brown/yellow, purple and cyan. All these colors also can be
-set or modified permanently in the configuration files. See the example
-file above for an example.
+red, green, brown/yellow, purple and cyan.
+All these colors also can be set or modified permanently in the
+configuration files.
+See the example file above for an example.
 
 The optional second argument (\fIATTR\fP) can be used to override the
-default or configured attributes of each class. Its syntax is the same
-as the one used in the configuration file:
+default or configured attributes of each class.
+Its syntax is the same as the one used in the configuration file:
 .nf
 [\fIfg\fP][/\fIbg\fP][,{\fIb\fP|\fId\fP|\fIr\fP|\fIs\fP|\fIu\fP|\fIi\fP}] \
 | [{\fIb\fP|\fId\fP|\fIr\fP|\fIs\fP|\fIu\fP|\fIi\fP}]
@@ -439,17 +459,20 @@ Examples of possible attributes are:
 .fi
 .IP \fB-g\fP
 Replaces the blank after each words in column or tabular mode by a
-vertical bar "\fB|\fP". Some users may find the output more readable
+vertical bar \fB|\fP. Some users may find the output more readable
 with it.
 .IP \fB-q\fP
-Prevents the scroll bar display. Useful when all the input words can be
-displayed without the need of scrolling. By default the scroll bar is
-always displayed when there is more than one line. An absence of cursor
-in it gives a visual indication that all the input words are there.
+Prevents the scroll bar display.
+Useful when all the input words can be
+displayed without the need of scrolling.
+By default the scroll bar is always displayed when there is more than
+one line.
+An absence of cursor in it gives a visual indication that all the input
+words are there.
 .IP "\fB-W\fP \fIbytes\fP"
 This option can be used to specify the characters (or multibyte
-sequences) which will be used to delimit the input words. The default
-delimiters are: \fISPACE\fP, \fI\\t\fP and \fI\\n\fP.
+sequences) which will be used to delimit the input words.
+The default delimiters are: \fISPACE\fP, \fI\\t\fP and \fI\\n\fP.
 .IP "\fB-L\fP \fIbytes\fP"
 This option can be used to specify the characters (or multibyte
 sequences) which will be used to delimit the lines in the input stream.
@@ -462,23 +485,26 @@ The characters (or multibyte sequences) passed to \fB-L\fP are
 automatically added to the list of word delimiters as if \fB-W\fP was
 also used.
 .IP "\fB-T\fP [\fIseparator\fP]"
-Enables the multi-selections or tagged mode. In this mode, each
-selectable word can be selected without ending the program. The last
-selection is then done as usual by hitting the \fBENTER\fP key which
-also ends the program.
+Enables the multi-selections or tagged mode.
+In this mode, each selectable word can be selected without ending
+the program.
+The last selection is then done as usual by hitting the \fBENTER\fP key
+which also ends the program.
 
 All the tagged words (and the world under the cursor) are then sent
 to stdout separated by the optional argument given to the \fB-T\fP
-option. Note than this \fIseparator\fP can have more than one character
-and can even contain control character as in \f(CB$'\\n'\fP.
+option.
+Note than this \fIseparator\fP can have more than one character and can
+even contain control character as in \f(CB$'\\n'\fP.
 
 A space is used as the default separator if none is given.
 .IP \fB-V\fP
 Displays the current version and quits.
 .SH NOTES
 If tabulators (\fI\\t\fP) are embedded in the input, there is no way
-to replace them with the original number of spaces. In this case use
-an other filter (like \fIexpand\fR) to pre-process the data.
+to replace them with the original number of spaces.
+In this case use an other filter (like \fIexpand\fR) to pre-process
+the data.
 .SH EXAMPLES
 .SS 1
 Simple Yes/No/Cancel request with "No" as default choice:
@@ -509,7 +535,8 @@ Get a 3 columns report about VM statistics for the current process in
 .fi
 .SS 3
 Create a one column selection window containing the list of the first
-20 LVM physical volumes. At the end, the selection window will be erased.
+20 LVM physical volumes.
+At the end, the selection window will be erased.
 This example is written in \fBksh\fP).
 .P
 .nf
@@ -574,7 +601,7 @@ The selected number or string will be available in \f(CBR\fP
 
 Try to understand it as an exercise.
 .SH BUGS
-None that I am aware of. If you found one, please tell me.
-.SH AUTHOR
+None that I am aware of.
+If you found one, please tell me.
+.SH AUTHORS
 \(co 2015 Pierre Gentile (p.gen.progs@gmail.com)
-.SH SEE ALSO