doc: New -s flag for console

Document the new console flag. `-s` allows specifying a sentinel string.
This sentinel is removed from the body of the command and the cursor is
set to its position when opening the console.

Sentinel replacement happens after macro expansion and there's no
characters which cannot occur in a path. It is therefore impossible to
use a sentinel which is 100% "macro safe."

Example, running `console -s <cursor> shell <cursor> %s` will open the
console with the contents `:shell | %s`, where `|` symbolizes the
cursor.

2 files changed, 14 insertions, 10 deletions

diff --git a/doc/ranger.1 b/doc/ranger.1
index f675da91..e1c025ed 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "RANGER 1"
-.TH RANGER 1 "ranger-1.9.3" "2020-11-18" "ranger manual"
+.TH RANGER 1 "ranger-1.9.3" "2021-01-22" "ranger manual"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -1247,7 +1247,7 @@ ranger.  For your convenience, this is a list of the \*(L"public\*(R" commands i
 \& chain command1[; command2[; command3...]]
 \& chmod octal_number
 \& cmap key command
-\& console [\-pSTARTPOSITION] command
+\& console [\-pSTARTPOSITION | \-s SENTINEL] command
 \& copycmap key newkey [newkey2...]
 \& copymap key newkey [newkey2...]
 \& copypmap key newkey [newkey2...]
@@ -1341,10 +1341,12 @@ example, \fB+ar\fR allows reading for everyone, \-ow forbids others to write and
 777= allows everything.
 .Sp
 See also: man 1 chmod
-.IP "console [\-p\fIN\fR] \fIcommand\fR" 2
-.IX Item "console [-pN] command"
-Opens the console with the command already typed in.  The cursor is placed at
-\&\fIN\fR.
+.IP "console [\-p\fIN\fR | \-s \fIsentinel\fR] \fIcommand\fR" 2
+.IX Item "console [-pN | -s sentinel] command"
+Opens the console with the command already typed in. The cursor is placed at
+\&\fIN\fR or at the first occurrence of \fIsentinel\fR. Note that sentinel strings can
+potentially occur inside macro expansions. If you cannot provide a sentinel,
+which is guaranteed to be unique, you should use \f(CW\*(C`\-p\*(C'\fR.
 .IP "copymap  \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
 .IX Item "copymap key newkey [newkey2 ...]"
 .PD 0
diff --git a/doc/ranger.pod b/doc/ranger.pod
index bbdfd24e..4cd5335a 100644
--- a/doc/ranger.pod
+++ b/doc/ranger.pod
@@ -1347,7 +1347,7 @@ ranger.  For your convenience, this is a list of the "public" commands including
  chain command1[; command2[; command3...]]
  chmod octal_number
  cmap key command
- console [-pSTARTPOSITION] command
+ console [-pSTARTPOSITION | -s SENTINEL] command
  copycmap key newkey [newkey2...]
  copymap key newkey [newkey2...]
  copypmap key newkey [newkey2...]
@@ -1448,10 +1448,12 @@ example, B<+ar> allows reading for everyone, -ow forbids others to write and
 
 See also: man 1 chmod
 
-=item console [-pI<N>] I<command>
+=item console [-pI<N> | -s I<sentinel>] I<command>
 
-Opens the console with the command already typed in.  The cursor is placed at
-I<N>.
+Opens the console with the command already typed in. The cursor is placed at
+I<N> or at the first occurrence of I<sentinel>. Note that sentinel strings can
+potentially occur inside macro expansions. If you cannot provide a sentinel
+which is guaranteed to be unique, you should use C<-p>.
 
 =item copymap  I<key> I<newkey> [I<newkey2> ...]