README: numerous changes upon careful proof-reading.

1 files changed, 29 insertions, 23 deletions

diff --git a/README.md b/README.md
index 7e46e14..5382ddb 100644
--- a/README.md
+++ b/README.md
@@ -44,21 +44,25 @@ causes it to be removed in spite of this.
 log, or all nine if given the `-l` argument. The `cl` command is an alias for
 for `cdlog` with no arguments and `cll` for `cdlog -l`.
 
-* The `mcd` and `mcs` are menu-selection-based analogs of `cd` and `mcs`.
+* The `mcd` and `mcs` are menu-selection-based analogs of `cd` and `cs`.
 They print the contents of the history (first nine entries), and you can
 pick which directory to change to or swap with. The terminal cursor is then
 retraced back to the top of the menu, and the screen is erased from
 that point to the bottom.
 
-* The `cdr` command is used for recovering previous sessions.
-When `cdlog` started, it allocated a new session.
-The `cdr` recovery command presents you with a numbered list of previous
-sessions.  You can recover to one of the sessions, use a `c` prefix on the number to clone
-the session into the current session, or press Enter to do nothing. Deleting
-unwanted sessions is possible with a `d` prefix. The `n` choice will select
-again the new session that `cdlog` had allocated on startup, and that one
-won't appear in the list of recoverable sessions unless it has been already
-persisted by the execution of a directory-changing command.
+* The `cdr` command is used for switching to and managing previous sessions.
+Though the `r` stands for "recovery", it may actually be used at any time and
+may be usefully used multiple times.  When `cdlog` starts, it initially
+allocates a new session.  The `cdr` recovery command presents you with a
+numbered menu of previous sessions. Entering an empty input line exits the
+menu.  You can recover to one of the sessions by entering its number.  The menu
+accepts additional notations for useful actions.  Use a `c` prefix on the
+numeric selection to clone the session into the current session.  Deleting
+unwanted sessions is possible with a `d` prefix; the specified entry is deleted
+and you remain in the recovery menu.  There is an `n` command which will make
+current again that new new session that `cdlog` had allocated on startup. That
+new session does not appear in the numbered list of recoverable sessions unless
+it has been already persisted by the execution of a directory-changing command.
 
 * The `cdalias` command is used for defining "cd aliases"; see below.
 
@@ -66,15 +70,16 @@ persisted by the execution of a directory-changing command.
 
 * The `cdunalias` command removes a cd alias.
 
-* The `c` command takes one argument. If it successfully, resolves to a path,
+* The `c` command provides an API into `cdlog`'s name resolution.
+It takes one argument. If it successfully resolves the argument to a path,
 that path it is printed, and the termination status is successful. Otherwise
 nothing is printed and the termination status is failed. If the argument is a
 digit in the range 1 to 9, then it resolves to the specified element in the
 `cdlog` history, if it is nonblank.  If the argument begins with `@`, then it
-resolves as a search; see Searches below. Otherwise, it is resolved as a
+resolves as a search; see Searches below. Otherwise, it is tried as a
 `cdlog` alias; see Aliases below.
 
-In addition, the `cdlog.sh` script sets the bash `direxpand` option.
+In addition, the `cdlog.sh` script sets the Bash `direxpand` option.
 With the `direxpand` option, Tab completion on a directory coming
 from a variable name will expand that variable into the command line.
 
@@ -87,7 +92,7 @@ same directory you are already in. There is no effect on the history.
 `cd` contains no slashes, then it is used as a key to look up an
 alias, which replaces it. The replacement is not considered to
 be an alias even if it looks like one. Aliases are defined using
-the `cdalias` command which is an alias. It takes two arguments.
+the `cdalias` command. It takes two arguments.
 
 Implementation notes: aliases are stored in the `cdlog_alias`
 array.  The `cdlog.chdir` function recognizes an alias only if
@@ -104,9 +109,9 @@ value.
 
 ## Searches
 
-Search are arguments which begin with `@`. The rest
-of such an argument argument is interpreted as a pattern which is applied
-against the history to find the most recent path containing a match.
+A search is an arguments which begins with `@`. The rest
+of the argument is interpreted as a pattern which is applied
+against the history to find the most recent matching path.
 
 In commands which accept a numeric argument denoting a reference
 to the `cdlog` history by position, the `@` prefix may be omitted
@@ -115,11 +120,6 @@ swap the current directory with the most recent history entry
 whose path contains a match for `foo`, and `cs @foo` will do
 exactly the same thing.
 
-When a pattern can is used in situations in which a path
-or alias is expected, namely as an argument to `cd`, the `@`
-is not optional, because without it, the argument would be
-interpreted as a path or alias.
-
 To include a leading `@` as part of the search pattern, write `@@`:
 the first `@` is recognized as the prefix, and removed; the
 second `@` remains as part of the pattern.
@@ -129,6 +129,9 @@ second `@` remains as part of the pattern.
 Whenever the history changes, the current directory and the
 contents of the history are written to the file `~/.cslog.N.dirs`,
 one path per line, where `N` is an internal session number.
+(This location for the session file is only a default; see the
+section Alternative Session Directory below which describes the
+`cdlog_sess_dir` variable.)
 
 When `cdlog` initializes, it allocates a session by finding a free
 value `N` in the range 1 to 10. If it cannot find one due to the
@@ -201,7 +204,10 @@ tabs engage further completion.
 * Bash's `direxpand` option does not work for `~-n` notation. Completion
 works, but the notation remains unexpanded.
 
-* `cslog` has intuitive, simpler commands. The actions of pushing entries into
+* Bash's `~-n` notation does not expand inside double quotes, whereas
+variables do.
+
+* `cdlog` has intuitive, simpler commands. The actions of pushing entries into
 the log, and rotating among them aren't conflated into a single command.
 The rotating command `cs` is usefully different from `pushd [+/-]n`,
 taking only positive integer arguments with no sign, and rotating among