diff options
Diffstat (limited to 'doc/ranger.pod')
| -rw-r--r-- | doc/ranger.pod | 103 |
1 files changed, 69 insertions, 34 deletions
diff --git a/doc/ranger.pod b/doc/ranger.pod index 6903c030..219d2f0b 100644 --- a/doc/ranger.pod +++ b/doc/ranger.pod @@ -75,7 +75,7 @@ Open ranger with I<targetfile> selected. Create copies of the default configuration files in your local configuration directory. Existing ones will not be overwritten. Possible values: I<all>, -I<rc>, I<apps>, I<commands>, I<options>, I<scope>. +I<rc>, I<commands>, I<scope>. =item B<--list-unused-keys> @@ -124,6 +124,9 @@ Print a list of options and exit. =head1 CONCEPTS +This part explains how certain parts of ranger work and how they can be used +efficiently. + =head2 TAGS Tags are single characters which are displayed left of a filename. You can use @@ -175,7 +178,7 @@ are in different directories: @diff %c %f Macros for file paths are generally shell-escaped so they can be used in the -:shell command. +C<shell> command. =head2 BOOKMARKS @@ -190,39 +193,72 @@ Bookmarks are selectable when tabbing in the :cd command. Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. +=head2 RIFLE + +Rifle is the file opener of ranger. It can be used as a standalone program or +a python module. It is located at F<ranger/ext/rifle.py>. In contrast to +other, more simple file openers, rifle can automatically find installed +programs so it can be used effectively out of the box on a variety of systems. + +It's configured in F<rifle.conf> through a list of conditions and commands. +For each line the conditions are checked and if they are met, the respective +command is taken into consideration. By default, simply the first matching +rule is used. In ranger, you can list and choose rules by typing "r" or simply +by typing "<rulenumber><enter>". If you use rifle standalone, you can list all +rules with the "-l" option and pick a rule with "-p <number>". + +The rules, along with further documentation, are contained in +F<ranger/config/rifle.conf>. + =head2 FLAGS Flags give you a way to modify the behavior of the spawned process. They are -used in the commands :open_with (key "r") and :shell (key "!"). +used in the commands C<:open_with> (key "r") and C<: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 + f Fork the process. (Run in background) c Run the current file only, instead of the selection r Run application with root privilege (requires sudo) t Run application in a new terminal window -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". +There are some additional flags that can currently be used only in the C<shell> +command: (for example C<:shell -w df>) + + p Redirect output to the pager + s Silent mode. Output will be discarded. + w Wait for an Enter-press when the process is done + +By default, all the flags are off unless specified otherwise in the +F<rifle.conf> configuration file. You can specify as many flags as you want. +An uppercase flag negates the effect: "ffcccFsf" is equivalent to "cs". -The "t" flag looks for the environment variable TERMCMD, and uses it as the -terminal command, if it's not set it'll use xterm. +The terminal program name for the "t" flag is taken from the environment +variable $TERMCMD. If it doesn't exist, it tries to extract it from $TERM and +uses "xterm" as a fallback if that fails. -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. +Examples: C<:open_with c> will open the file that you currently point at, even +if you have selected other files. C<:shell -w df> will run "df" and wait for +you to press Enter before switching back to ranger. -=head2 MODES +=head2 PLUGINS -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. +ranger's plugin system consists of python files which are located in +F<~/.config/ranger/plugins/> and are imported in alphabetical order when +starting ranger. A plugin changes rangers behavior by overwriting or extending +a function that ranger uses. This allows you to change pretty much every part +of ranger, but there is no guarantee that things will continue to work in +future versions as the source code evolves. -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. +There are some hooks that are specifically made for the use in plugins. They +are functions that start with hook_ and can be found throughout the code. + + grep 'def hook_' -r /path/to/rangers/source + +Also try: + + pydoc ranger.api + +The F<examples> directory contains several sample plugins, including a well +documented hello-world plugin using hooks in a compatibility-friendly way. @@ -443,8 +479,8 @@ Enter a directory or run a file. =item Scroll Wheel -Scrolls up or down. You can point at the column of the parent directory to -switch directories. +Scrolls up or down. You can point at the column of the parent directory while +scrolling to switch directories. =back @@ -956,16 +992,16 @@ any of these files. =over 10 -=item commands.py - -A python module that defines commands which can be used in ranger's console by -typing ":". - =item rc.conf Contains a list of commands which are executed on startup. Mostly key bindings and settings are defined here. +=item commands.py + +A python module that defines commands which can be used in ranger's console by +typing ":" or in the rc.conf file. + =item rifle.conf This is the configuration file for the built-in file launcher called "rifle". @@ -973,10 +1009,9 @@ This is the configuration file for the built-in file launcher called "rifle". =item scope.sh This is a script that handles file previews. When the options -I<use_preview_script> and I<preview_files> or, respectively, -I<preview_directories> are set, the program specified in the option -I<preview_script> is run and its output and/or exit code determines rangers -reaction. +I<use_preview_script> and I<preview_files> are set, the program specified in +the option I<preview_script> is run and its output and/or exit code determines +rangers reaction. =item colorschemes/ @@ -1030,7 +1065,7 @@ These environment variables have an effect on ranger: =item RANGER_LEVEL -Ranger sets this environment variable to "1" or increments it if it already +ranger sets this environment variable to "1" or increments it if it already exists. External programs can determine whether they were spawned from ranger by checking for this variable. |