Merge new and old %any documentation

Some new docs were written up for the %any macro but they were in the
wrong place. There were also some whitespace issues that snuck into the
last commit that needed fixing up.

2 files changed, 110 insertions, 65 deletions

diff --git a/doc/ranger.1 b/doc/ranger.1
index 69109cf2..0a548dd4 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "RANGER 1"
-.TH RANGER 1 "ranger-1.9.2" "2019-05-17" "ranger manual"
+.TH RANGER 1 "ranger-1.9.2" "2019-05-18" "ranger manual"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -155,9 +155,9 @@ ranger \- visual file manager
 ranger is a console file manager with \s-1VI\s0 key bindings.
 .SH "RESOURCES"
 .IX Header "RESOURCES"
-\&\fIThis manual\fR contains instructions on how to use and configure ranger.
+This \fImanual\fR contains instructions on how to use and configure ranger.
 .PP
-\&\fIInside ranger\fR, you can press \fI?\fR for a list of key bindings, commands or
+Inside \fIranger\fR, you can press \fI?\fR for a list of key bindings, commands or
 settings.
 .PP
 The \fI\s-1README\s0\fR contains install instructions.
@@ -383,13 +383,45 @@ are in different directories:
 Macros for file paths are generally shell-escaped so they can be used in the
 \&\f(CW\*(C`shell\*(C'\fR command.
 .PP
-Additionally, if you create a key binding that uses <any>, a special statement
-which accepts any key, then the macro \f(CW%any\fR (or \f(CW%any0\fR, \f(CW%any1\fR, \f(CW%any2\fR, ...) can be
-used in the command to get the key that was pressed.
+When mapping keys you can use the placeholder <any>, the key entered in that
+position can be used through the \f(CW%any\fR and \f(CW%any_path\fR macros. (When using
+multiple <any> placeholders you can index the macros: \f(CW%any0\fR, \f(CW%any_path0\fR, \f(CW%any1\fR,
+\&\f(CW%any_path1\fR...) The macro \f(CW%any\fR will be replaced with the key pressed in the
+position of the <any> placeholder. The macro \f(CW%any_path\fR will be replaced with
+the path of the bookmark mapped to the key pressed in the position of the
+<any> placeholder. For example this macro can be used to echo the key that was
+pressed after \*(L"c\*(R":
+.PP
+.Vb 1
+\& map c<any> echo %any
+.Ve
+.PP
+\&\f(CW%any\fR is used in the ranger configuration to create a keybinding for adding a
+bookmark. c<set_bookmark> creates a bookmark for the current directory and the
+key for the bookmark is the first supplied argument. In this case the key
+pressed after \*(L"m\*(R":
+.PP
+.Vb 1
+\& map m<any> set_bookmark %any
+.Ve
+.PP
+The \f(CW%any_path\fR macro can be used to echo the path of the bookmark that is set to
+the key pressed after \*(L"c\*(R":
+.PP
+.Vb 1
+\& map c<any> echo %any_path
+.Ve
+.PP
+A practical example of the use of \f(CW%any_path\fR is the pasting of cut/copied files
+to a bookmarked directory:
+.PP
+.Vb 1
+\& map p\*(Aq<any> paste dest=%any_path
+.Ve
 .PP
 The macro \f(CW%rangerdir\fR expands to the directory of ranger's python library, you
 can use it for something like this command:
-  alias show_commands shell less \f(CW%rangerdir\fR/config/commands.py
+ alias show_commands shell less \f(CW%rangerdir\fR/config/commands.py
 .PP
 \&\f(CW%confdir\fR expands to the directory given by \fB\-\-confdir\fR.
 .PP
@@ -1301,19 +1333,27 @@ Flags:
 .IX Item "linemode linemodename"
 Sets the linemode of all files in the current directory.  The linemode may be:
 .Sp
-.Vb 12
-\& "filename": display each line as "<basename>...<size>"
-\& "fileinfo": display each line as "<basename>...<file(1) output>"
-\& "mtime": display each line as "<basename>...<mtime>" in ISO format
-\& "humanreadablemtime": display each line as "<basename>...<mtime>" in a human
-\&     readable format, more precise the more recent
-\& "permissions": display each line as "<permissions> <owner> <group> <basename>"
-\& "sizemtime": display each line as "<basename>...<size> <mtime>" in ISO format
-\& "humanreadablesizemtime": display each line as "<basename>...<size> <mtime>"
-\&     in a human readable format, more precise the more recent
-\& "metatitle": display metadata from .metadata.json files if
-\&     available, fall back to the "filename" linemode if no
-\&     metadata was found.  See :meta command.
+.Vb 10
+\& "filename":
+\&   display each line as "<basename>...<size>"
+\& "fileinfo":
+\&   display each line as "<basename>...<file(1) output>"
+\& "mtime":
+\&   display each line as "<basename>...<mtime>" in ISO format
+\& "humanreadablemtime":
+\&   display each line as "<basename>...<mtime>" in a human readable
+\&   format, more precise the more recent.
+\& "sizemtime":
+\&   display each line as "<basename>...<size> <mtime>" in ISO format
+\& "humanreadablesizemtime":
+\&   display each line as "<basename>...<size> <mtime>" in a human
+\&   readable format, more precise the more recent.
+\& "permissions":
+\&   display each line as "<permissions> <owner> <group> <basename>"
+\& "metatitle":
+\&   display metadata from .metadata.json files if available, fall back
+\&   to the "filename" linemode if no metadata was found.
+\&   See :meta command.
 .Ve
 .Sp
 The custom linemodes may be added by subclassing the \fILinemodeBase\fR class.
diff --git a/doc/ranger.pod b/doc/ranger.pod
index 7420f15d..d5de3851 100644
--- a/doc/ranger.pod
+++ b/doc/ranger.pod
@@ -28,9 +28,9 @@ ranger is a console file manager with VI key bindings.
 
 =head1 RESOURCES
 
-I<This manual> contains instructions on how to use and configure ranger.
+This I<manual> contains instructions on how to use and configure ranger.
 
-I<Inside ranger>, you can press I<?> for a list of key bindings, commands or
+Inside I<ranger>, you can press I<?> for a list of key bindings, commands or
 settings.
 
 The F<README> contains install instructions.
@@ -286,48 +286,45 @@ are in different directories:
 Macros for file paths are generally shell-escaped so they can be used in the
 C<shell> command.
 
-Additionally, if you create a key binding that uses <any>, a special statement
-which accepts any key, then the macro %any (or %any0, %any1, %any2, ...) can be
-used in the command to get the key that was pressed.
+When mapping keys you can use the placeholder <any>, the key entered in that
+position can be used through the %any and %any_path macros. (When using
+multiple <any> placeholders you can index the macros: %any0, %any_path0, %any1,
+%any_path1...) The macro %any will be replaced with the key pressed in the
+position of the <any> placeholder. The macro %any_path will be replaced with
+the path of the bookmark mapped to the key pressed in the position of the
+<any> placeholder. For example this macro can be used to echo the key that was
+pressed after "c":
 
-The macro %rangerdir expands to the directory of ranger's python library, you
-can use it for something like this command:
-  alias show_commands shell less %rangerdir/config/commands.py
-
-%confdir expands to the directory given by B<--confdir>.
+ map c<any> echo %any
 
-%datadir expands to the directory given by B<--datadir>.
-
-The macro %space expands to a space character. You can use it to add spaces to
-the end of a command when needed, while preventing editors to strip spaces off
-the end of the line automatically.
+%any is used in the ranger configuration to create a keybinding for adding a
+bookmark. c<set_bookmark> creates a bookmark for the current directory and the
+key for the bookmark is the first supplied argument. In this case the key
+pressed after "m":
 
+ map m<any> set_bookmark %any
 
-When mapping keys you can use the placeholder <any>, the key entered
-in that position can be used through the %any and %any_path macros. In
-this context <any> is used as a placeholder in the keybinding. The
-macro %any will be replaced with the key pressed in the place of
-<any>. The macro %any_path will replaced with the path of the bookmark
-which is mapped to the key in the place of <any>. For example:
+The %any_path macro can be used to echo the path of the bookmark that is set to
+the key pressed after "c":
 
-	map c<any> echo %any
+ map c<any> echo %any_path
 
-can be used to echo the key that was pressed after "c". %any is used in
-the ranger configuration to create a keybinding for adding a bookmark.
+A practical example of the use of %any_path is the pasting of cut/copied files
+to a bookmarked directory:
 
-	map m<any> set_bookmark %any
+ map p'<any> paste dest=%any_path
 
-set_bookmark creates a bookmark for the current directory and the
-key for the bookmark is the first supplied argument. In this case -
-the key pressed after "m".
+The macro %rangerdir expands to the directory of ranger's python library, you
+can use it for something like this command:
+ alias show_commands shell less %rangerdir/config/commands.py
 
-	map c<any> echo %any_path
+%confdir expands to the directory given by B<--confdir>.
 
-can be used to echo the path of the booksmark that is set to the key
-pressed after "c". A practical example of the use of %any_path is the
-pasting of the cut\copied files in a selected bookmark
+%datadir expands to the directory given by B<--datadir>.
 
-	map p'<any> paste dest=%any_path
+The macro %space expands to a space character. You can use it to add spaces to
+the end of a command when needed, while preventing editors to strip spaces off
+the end of the line automatically.
 
 To write a literal %, you need to escape it by writing %%.
 
@@ -1412,18 +1409,26 @@ Flags:
 
 Sets the linemode of all files in the current directory.  The linemode may be:
 
- "filename": display each line as "<basename>...<size>"
- "fileinfo": display each line as "<basename>...<file(1) output>"
- "mtime": display each line as "<basename>...<mtime>" in ISO format
- "humanreadablemtime": display each line as "<basename>...<mtime>" in a human
-     readable format, more precise the more recent
- "permissions": display each line as "<permissions> <owner> <group> <basename>"
- "sizemtime": display each line as "<basename>...<size> <mtime>" in ISO format
- "humanreadablesizemtime": display each line as "<basename>...<size> <mtime>"
-     in a human readable format, more precise the more recent
- "metatitle": display metadata from .metadata.json files if
-	 available, fall back to the "filename" linemode if no
-	 metadata was found.  See :meta command.
+ "filename":
+   display each line as "<basename>...<size>"
+ "fileinfo":
+   display each line as "<basename>...<file(1) output>"
+ "mtime":
+   display each line as "<basename>...<mtime>" in ISO format
+ "humanreadablemtime":
+   display each line as "<basename>...<mtime>" in a human readable
+   format, more precise the more recent.
+ "sizemtime":
+   display each line as "<basename>...<size> <mtime>" in ISO format
+ "humanreadablesizemtime":
+   display each line as "<basename>...<size> <mtime>" in a human
+   readable format, more precise the more recent.
+ "permissions":
+   display each line as "<permissions> <owner> <group> <basename>"
+ "metatitle":
+   display metadata from .metadata.json files if available, fall back
+   to the "filename" linemode if no metadata was found.
+   See :meta command.
 
 The custom linemodes may be added by subclassing the I<LinemodeBase> class.
 See the I<ranger.core.linemode> module for some examples.