about summary refs log tree commit diff stats
diff options
context:
space:
mode:
authortoonn <toonn@toonn.io>2021-01-22 20:22:43 +0100
committertoonn <toonn@toonn.io>2021-01-22 20:22:43 +0100
commit785102b5b0da2828ade2e7752d151144ab7524f5 (patch)
treed1a6ecdac2e7713f633db706e90655bb19b6cc23
parent8339dd9b344d0ba39028746403a67fb0202a9672 (diff)
downloadranger-785102b5b0da2828ade2e7752d151144ab7524f5.tar.gz
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.
-rw-r--r--doc/ranger.114
-rw-r--r--doc/ranger.pod10
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> ...]