From b5d8d0644e46072294105a7dc18d2b1107f05ffb Mon Sep 17 00:00:00 2001 From: toonn Date: Sat, 18 May 2019 14:47:05 +0200 Subject: 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. --- doc/ranger.1 | 80 ++++++++++++++++++++++++++++++++++++------------- doc/ranger.pod | 95 ++++++++++++++++++++++++++++++---------------------------- 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 , 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 , 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 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 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 + placeholder. For example this macro can be used to echo the key that was +pressed after \*(L"c\*(R": +.PP +.Vb 1 +\& map c echo %any +.Ve +.PP +\&\f(CW%any\fR is used in the ranger configuration to create a keybinding for adding a +bookmark. c 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 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 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 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 "..." -\& "fileinfo": display each line as "..." -\& "mtime": display each line as "..." in ISO format -\& "humanreadablemtime": display each line as "..." in a human -\& readable format, more precise the more recent -\& "permissions": display each line as " " -\& "sizemtime": display each line as "... " in ISO format -\& "humanreadablesizemtime": display each line as "... " -\& 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 "..." +\& "fileinfo": +\& display each line as "..." +\& "mtime": +\& display each line as "..." in ISO format +\& "humanreadablemtime": +\& display each line as "..." in a human readable +\& format, more precise the more recent. +\& "sizemtime": +\& display each line as "... " in ISO format +\& "humanreadablesizemtime": +\& display each line as "... " in a human +\& readable format, more precise the more recent. +\& "permissions": +\& display each line as " " +\& "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 contains instructions on how to use and configure ranger. +This I contains instructions on how to use and configure ranger. -I, you can press I for a list of key bindings, commands or +Inside I, you can press I for a list of key bindings, commands or settings. The F 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 command. -Additionally, if you create a key binding that uses , 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 , the key entered in that +position can be used through the %any and %any_path macros. (When using +multiple 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 placeholder. The macro %any_path will be replaced with +the path of the bookmark mapped to the key pressed in the position of the + 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 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 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 set_bookmark %any -When mapping keys you can use the placeholder , the key entered -in that position can be used through the %any and %any_path macros. In -this context is used as a placeholder in the keybinding. The -macro %any will be replaced with the key pressed in the place of -. The macro %any_path will replaced with the path of the bookmark -which is mapped to the key in the place of . 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 echo %any + map c 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 set_bookmark %any + map p' 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 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' 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 "..." - "fileinfo": display each line as "..." - "mtime": display each line as "..." in ISO format - "humanreadablemtime": display each line as "..." in a human - readable format, more precise the more recent - "permissions": display each line as " " - "sizemtime": display each line as "... " in ISO format - "humanreadablesizemtime": display each line as "... " - 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 "..." + "fileinfo": + display each line as "..." + "mtime": + display each line as "..." in ISO format + "humanreadablemtime": + display each line as "..." in a human readable + format, more precise the more recent. + "sizemtime": + display each line as "... " in ISO format + "humanreadablesizemtime": + display each line as "... " in a human + readable format, more precise the more recent. + "permissions": + display each line as " " + "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 class. See the I module for some examples. -- cgit 1.4.1-2-gfad0