diff options
| -rw-r--r-- | doc/ranger.1 | 125 | ||||
| -rw-r--r-- | doc/ranger.pod | 143 |
2 files changed, 256 insertions, 12 deletions
diff --git a/doc/ranger.1 b/doc/ranger.1 index 2192047c..56e12432 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -192,6 +192,108 @@ the execution of this file type is explicitly handled in the configuration. When a filename is supplied, run it with the given \fIflags\fR to modify behavior. The execution of this file type is explicitly handled in the configuration. +.SH "CONCEPTS" +.IX Header "CONCEPTS" +.SS "\s-1TAGS\s0" +.IX Subsection "TAGS" +Tags are single characters which are displayed left of a filename. You can use +tags however you want. Press \*(L"t\*(R" to toggle tags and \*(L"T\*(R" to remove any tags of +the selection. The default tag is an Asterisk (\*(L"*\*(R"), but you can use any tag by +typing \fI"<tagname>\fR. +.SS "\s-1SELECTION\s0" +.IX Subsection "SELECTION" +The \fIselection\fR is defined as \*(L"All marked files \s-1IF\s0 \s-1THERE\s0 \s-1ARE\s0 \s-1ANY\s0, otherwise +the current file.\*(R" Be aware of this when using the :delete command, which +deletes all files in the selection. +.PP +You can mark files by pressing <Space>, v, etc. A yellow \fBMrk\fR symbol at the +bottom right indicates that there are marked files in this directory. +.SS "\s-1MACROS\s0" +.IX Subsection "MACROS" +Macros can be used in commands to abbreviate things. +.PP +.Vb 5 +\& %f the highlighted file +\& %d the path of the current directory +\& %s the selected files in the current directory. +\& %t all tagged files in the current directory +\& %c the full paths of the currently copied/cut files +.Ve +.PP +The macros \f(CW%f\fR, \f(CW%d\fR and \f(CW%s\fR also have upper case variants, \f(CW%F\fR, \f(CW%D\fR and \f(CW%S\fR, +which refer to the next tab. To refer to specific tabs, add a number in +between. (%7s = selection of the seventh tab.) +.PP +\&\f(CW%c\fR is the only macro which ranges out of the current directory. So you may +\&\*(L"abuse\*(R" the copying function for other purposes, like diffing two files which +are in different directories: +.PP +.Vb 2 +\& Yank the file A (type yy), move to the file B, then type +\& @diff %c %f +.Ve +.PP +Macros for file paths are generally shell-escaped so they can be used in the +:shell command. +.SS "\s-1PREVIEWS\s0" +.IX Subsection "PREVIEWS" +By default, only text files are previewed, but you can enable external preview +scripts by creating \fI~/.config/ranger/scope.sh\fR (see preview_script option.) +This script will then be executed each time you attempt to preview a file. +.PP +Fetch the default scope.sh (from \fIranger/data/scope.sh\fR) by running +\&\f(CW\*(C`ranger \-\-copy\-config=scope\*(C'\fR +.PP +This default script contains more documentation and calls to the programs +\&\fIlynx\fR and \fIelinks\fR for html, \fIhighlight\fR for text/code, \fIimg2txt\fR for +images, \fIatool\fR for archives, \fIpdftotext\fR for PDFs and \fImediainfo\fR for video +and audio +files. +.PP +Install these programs (just the ones you need) and scope.sh will automatically +use them. Make sure to also have the options \*(L"use_preview_script\*(R" and +\&\*(L"preview_files\*(R" turned on. +.SS "\s-1BOOKMARKS\s0" +.IX Subsection "BOOKMARKS" +Type \fBm<key>\fR to bookmark the current directory. You can re-enter this +directory by typing \fB`<key>\fR. <key> can be any letter or digit. Unlike vim, +both lowercase and uppercase bookmarks are persistent. +.PP +Each time you jump to a bookmark, the special bookmark at key ` will be set +to the last directory. So typing \*(L"``\*(R" gets you back to where you were before. +.PP +Bookmarks are selectable when tabbing in the :cd command. +.PP +Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. +.SS "\s-1FLAGS\s0" +.IX Subsection "FLAGS" +Flags give you a way to modify the behaviour of the spawned process. They are +used in the commands :open_with (key \*(L"r\*(R") and :shell (key \*(L"!\*(R"). +.PP +.Vb 5 +\& s Silent mode. Output will be discarded. +\& d Detach the process. (Run in background) +\& p Redirect output to the pager +\& w Wait for an Enter\-press when the process is done +\& c Run the current file only, instead of the selection +.Ve +.PP +By default, all the flags are off unless specified otherwise in the \fIapps.py\fR +configuration file. You can specify as many flags as you want. An uppercase +flag negates the effect: \*(L"ddcccDs\*(R" is equivalent to \*(L"cs\*(R". +.PP +Examples: \f(CW\*(C`:open_with p\*(C'\fR will pipe the output of that process into +the pager. \f(CW\*(C`:shell \-w df\*(C'\fR will run \*(L"df\*(R" and wait for you to press Enter before +switching back to ranger. +.SS "\s-1MODES\s0" +.IX Subsection "MODES" +By specifying a mode (a positive integer), you can tell ranger what to do with +a file when running it. You can specify which mode to use by typing <mode>l or +<mode><Enter> or :open_with <mode>. The default mode is 0. +.PP +Examples: \f(CW\*(C`l\*(C'\fR (mode zero) to list the contents of an archive, \f(CW\*(C`1l\*(C'\fR (mode one) +to extract an archive. See the \fIapps.py\fR configuration file for all programs +and modes. .SH "KEY BINDINGS" .IX Header "KEY BINDINGS" Many key bindings take an additional numeric argument. Type \fI5j\fR to move @@ -201,6 +303,8 @@ or \fI3?\fR to read the third chapter of the documentation. Key bindings can be changed. Detailed instructions for this are in the key binding configuration file at \fIranger/defaults/keys.py\fR. You can copy it to your local configuration directory with the \-\-copy\-config option. +.SS "\s-1MAIN\s0 \s-1BINDINGS\s0" +.IX Subsection "MAIN BINDINGS" .IP "h, j, k, l" 14 .IX Item "h, j, k, l" Move left, down, up or right @@ -275,6 +379,12 @@ Mark all files in the given direction. Works just like d\fIdirection\fR. .IP "u^V\fIdirection\fR" 14 .IX Item "u^Vdirection" Unmark all files in the given direction. Works just like d\fIdirection\fR. +.IP "/" 14 +Search for files in the current directory. +.IP ":" 14 +Open the console. +.SS "\s-1ADDITIONAL\s0 \s-1KEYBINDINGS\s0" +.IX Subsection "ADDITIONAL KEYBINDINGS" .IP "g\fIN\fR" 14 .IX Item "gN" Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it @@ -288,10 +398,6 @@ Go to the next or previous tab. You can also use \s-1TAB\s0 and \s-1SHIFT+TAB\s0 .IP "gc, ^W" 14 .IX Item "gc, ^W" Close the current tab. The last tab cannot be closed this way. -.IP "/" 14 -Search for files in the current directory. -.IP ":" 14 -Open the console. .IP "?" 14 Opens the help screen with more key bindings and documentation .SS "\s-1MIDNIGHT\s0 COMMANDER-LIKE \s-1BINDINGS\s0" @@ -488,6 +594,8 @@ Enable this if key combinations with the Alt Key don't work for you. (Especially on xterm) .SH "COMMANDS" .IX Header "COMMANDS" +You can enter the commands in the console which is opened by pressing \*(L":\*(R". +Press <F1> to view help about the currently typed in command. .IP "bulkrename" 2 .IX Item "bulkrename" This command opens a list of selected files in an external editor. After you @@ -692,6 +800,15 @@ the \*(L"S\*(R" key. Defaults to \*(L"bash\*(R". .IP "\s-1XDG_CONFIG_HOME\s0" 8 .IX Item "XDG_CONFIG_HOME" Specifies the directory for configuration files. Defaults to \fI\f(CI$HOME\fI/.config\fR. +.IP "\s-1PYTHONOPTIMIZE\s0" 8 +.IX Item "PYTHONOPTIMIZE" +This variable determines the optimize level of python. +.Sp +Using PYTHONOPTIMIZE=1 (like python \-O) will make python discard assertion +statements. You will gain efficiency at the cost of losing some debug info. +.Sp +Using PYTHONOPTIMIZE=2 (like python \-OO) will additionally discard any +docstrings. Using this will disable the <F1> key on commands. .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "\s-1VIM:\s0 File Chooser" diff --git a/doc/ranger.pod b/doc/ranger.pod index be1d14fd..5945ad7c 100644 --- a/doc/ranger.pod +++ b/doc/ranger.pod @@ -92,6 +92,112 @@ configuration. +=head1 CONCEPTS + +=head2 TAGS + +Tags are single characters which are displayed left of a filename. You can use +tags however you want. Press "t" to toggle tags and "T" to remove any tags of +the selection. The default tag is an Asterisk ("*"), but you can use any tag by +typing I<"<tagnameE<gt>>. + +=head2 PREVIEWS + +By default, only text files are previewed, but you can enable external preview +scripts by creating F<~/.config/ranger/scope.sh> (see preview_script option.) +This script will then be executed each time you attempt to preview a file. + +Fetch the default scope.sh (from F<ranger/data/scope.sh>) by running +C<ranger --copy-config=scope> + +This default script contains more documentation and calls to the programs +I<lynx> and I<elinks> for html, I<highlight> for text/code, I<img2txt> for +images, I<atool> for archives, I<pdftotext> for PDFs and I<mediainfo> for video +and audio +files. + +Install these programs (just the ones you need) and scope.sh will automatically +use them. Make sure to also have the options "use_preview_script" and +"preview_files" turned on. + +=head2 SELECTION + +The I<selection> is defined as "All marked files IF THERE ARE ANY, otherwise +the current file." Be aware of this when using the :delete command, which +deletes all files in the selection. + +You can mark files by pressing <Space>, v, etc. A yellow B<Mrk> symbol at the +bottom right indicates that there are marked files in this directory. + +=head2 MACROS + +Macros can be used in commands to abbreviate things. + + %f the highlighted file + %d the path of the current directory + %s the selected files in the current directory. + %t all tagged files in the current directory + %c the full paths of the currently copied/cut files + +The macros %f, %d and %s also have upper case variants, %F, %D and %S, +which refer to the next tab. To refer to specific tabs, add a number in +between. (%7s = selection of the seventh tab.) + +%c is the only macro which ranges out of the current directory. So you may +"abuse" the copying function for other purposes, like diffing two files which +are in different directories: + + Yank the file A (type yy), move to the file B, then type + @diff %c %f + +Macros for file paths are generally shell-escaped so they can be used in the +:shell command. + +=head2 BOOKMARKS + +Type B<m<keyE<gt>> to bookmark the current directory. You can re-enter this +directory by typing B<`<keyE<gt>>. <key> can be any letter or digit. Unlike vim, +both lowercase and uppercase bookmarks are persistent. + +Each time you jump to a bookmark, the special bookmark at key ` will be set +to the last directory. So typing "``" gets you back to where you were before. + +Bookmarks are selectable when tabbing in the :cd command. + +Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. + +=head2 FLAGS + +Flags give you a way to modify the behaviour of the spawned process. They are +used in the commands :open_with (key "r") and :shell (key "!"). + + s Silent mode. Output will be discarded. + d Detach the process. (Run in background) + p Redirect output to the pager + w Wait for an Enter-press when the process is done + c Run the current file only, instead of the selection + +By default, all the flags are off unless specified otherwise in the F<apps.py> +configuration file. You can specify as many flags as you want. An uppercase +flag negates the effect: "ddcccDs" is equivalent to "cs". + +Examples: C<:open_with p> will pipe the output of that process into +the pager. C<:shell -w df> will run "df" and wait for you to press Enter before +switching back to ranger. + +=head2 MODES + +By specifying a mode (a positive integer), you can tell ranger what to do with +a file when running it. You can specify which mode to use by typing <mode>l or +<mode><Enter> or :open_with <mode>. The default mode is 0. + +Examples: C<l> (mode zero) to list the contents of an archive, C<1l> (mode one) +to extract an archive. See the F<apps.py> configuration file for all programs +and modes. + + + + =head1 KEY BINDINGS Many key bindings take an additional numeric argument. Type I<5j> to move @@ -102,6 +208,8 @@ Key bindings can be changed. Detailed instructions for this are in the key binding configuration file at F<ranger/defaults/keys.py>. You can copy it to your local configuration directory with the --copy-config option. +=head2 MAIN BINDINGS + =over 14 =item h, j, k, l @@ -201,6 +309,20 @@ Mark all files in the given direction. Works just like dI<direction>. Unmark all files in the given direction. Works just like dI<direction>. +=item / + +Search for files in the current directory. + +=item : + +Open the console. + +=back + +=head2 ADDITIONAL KEYBINDINGS + +=over 14 + =item gI<N> Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it @@ -218,14 +340,6 @@ Go to the next or previous tab. You can also use TAB and SHIFT+TAB instead. Close the current tab. The last tab cannot be closed this way. -=item / - -Search for files in the current directory. - -=item : - -Open the console. - =item ? Opens the help screen with more key bindings and documentation @@ -499,6 +613,9 @@ Enable this if key combinations with the Alt Key don't work for you. =head1 COMMANDS +You can enter the commands in the console which is opened by pressing ":". +Press <F1> to view help about the currently typed in command. + =over 2 =item bulkrename @@ -760,6 +877,16 @@ the "S" key. Defaults to "bash". Specifies the directory for configuration files. Defaults to F<$HOME/.config>. +=item PYTHONOPTIMIZE + +This variable determines the optimize level of python. + +Using PYTHONOPTIMIZE=1 (like python -O) will make python discard assertion +statements. You will gain efficiency at the cost of losing some debug info. + +Using PYTHONOPTIMIZE=2 (like python -OO) will additionally discard any +docstrings. Using this will disable the <F1> key on commands. + =back |