From 36fa003d834d7f5ef5ff456c2264476296958fc7 Mon Sep 17 00:00:00 2001 From: hut Date: Sun, 2 Dec 2012 02:43:21 +0100 Subject: update documentation for options, plugins and examples --- doc/ranger.1 | 155 ++++++++++++++++++++++++++--------------------------------- 1 file changed, 67 insertions(+), 88 deletions(-) (limited to 'doc/ranger.1') diff --git a/doc/ranger.1 b/doc/ranger.1 index cfdbd455..dc18cc4c 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -124,7 +124,7 @@ .\" ======================================================================== .\" .IX Title "RANGER 1" -.TH RANGER 1 "ranger-1.5.5" "08/10/2012" "ranger manual" +.TH RANGER 1 "ranger-1.5.5" "12/02/2012" "ranger manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -480,32 +480,49 @@ This section lists all built-in settings of ranger. The valid types for the value are in [brackets]. The hotkey to toggle the setting is in , if a hotkey exists. .PP -Settings can be changed in the file \fI~/.config/ranger/options.py\fR or on the +Settings can be changed in the file \fI~/.config/ranger/rc.conf\fR or on the fly with the command \fB:set option value\fR. Examples: - :set column_ratios (1,2,3) - :set show_hidden=True +.PP +.Vb 2 +\& set column_ratios 1,2,3 +\& set show_hidden true +.Ve +.PP +The different types of settings and an example for each type: +.PP +.Vb 7 +\& setting type | example values +\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& bool | true, false +\& integer | 1, 23, 1337 +\& string | foo, hello world +\& list | 1,2,3,4 +\& none | none +.Ve .IP "autosave_bookmarks [bool]" 4 .IX Item "autosave_bookmarks [bool]" Save bookmarks (used with mX and `X) instantly? This helps to synchronize bookmarks between multiple ranger instances but leads to *slight* performance loss. When false, bookmarks are saved when ranger is exited. +.IP "autoupdate_cumulative_size [bool]" 4 +.IX Item "autoupdate_cumulative_size [bool]" +You can display the \*(L"real\*(R" cumulative size of directories by using the command +:get_cumulative_size or typing \*(L"dc\*(R". The size is expensive to calculate and +will not be updated automatically. You can choose to update it automatically +though by turning on this option. .IP "collapse_preview [bool] " 4 .IX Item "collapse_preview [bool] " When no preview is visible, should the last column be squeezed to make use of the whitespace? -.IP "colorscheme_overlay [function, None]" 4 -.IX Item "colorscheme_overlay [function, None]" -An overlay function for colorschemes. See the default options.py for an -explanation and an example. .IP "colorscheme [string]" 4 .IX Item "colorscheme [string]" Which colorscheme to use? These colorschemes are available by default: -\&\fBdefault\fR, \fBdefault88\fR, \fBtexas\fR, \fBjungle\fR, \fBsnow\fR. Snow is monochrome, -texas and default88 use 88 colors. -.IP "column_ratios [tuple, list]" 4 -.IX Item "column_ratios [tuple, list]" +\&\fBdefault\fR, \fBjungle\fR, \fBsnow\fR. Snow is a monochrome scheme, jungle replaces +blue directories with green ones for better visibility on certain terminals. +.IP "column_ratios [list]" 4 +.IX Item "column_ratios [list]" How many columns are there, and what are their relative widths? For example, a -value of (1, 1, 1) would mean 3 even sized columns. (1, 1, 1, 1, 4) means 5 columns +value of 1,1,1 would mean 3 evenly sized columns. 1,1,1,1,4 means 5 columns with the preview column being as large as the other columns combined. .IP "dirname_in_tabs [bool]" 4 .IX Item "dirname_in_tabs [bool]" @@ -519,25 +536,32 @@ Display the file size in the status bar? .IP "display_tags_in_all_columns [bool]" 4 .IX Item "display_tags_in_all_columns [bool]" Display tags in all columns? -.IP "draw_bookmark_borders [bool]" 4 -.IX Item "draw_bookmark_borders [bool]" -Draw borders around the bookmark window? .IP "draw_borders [bool]" 4 .IX Item "draw_borders [bool]" Draw borders around columns? +.IP "draw_progress_bar_in_statusbar [bool]" 4 +.IX Item "draw_progress_bar_in_statusbar [bool]" +Draw a progress bar in the status bar which displays the average state of all +currently running tasks which support progress bars? .IP "flushinput [bool] " 4 .IX Item "flushinput [bool] " Flush the input after each key hit? One advantage is that when scrolling down with \*(L"j\*(R", ranger stops scrolling instantly when you release the key. One disadvantage is that when you type commands blindly, some keys might get lost. -.IP "hidden_filter [regexp]" 4 -.IX Item "hidden_filter [regexp]" -A regular expression pattern for files which should be hidden. -.IP "max_console_history_size [integer, None]" 4 -.IX Item "max_console_history_size [integer, None]" -How many console commands should be kept in history? -.IP "max_history_size [integer, None]" 4 -.IX Item "max_history_size [integer, None]" +.IP "hidden_filter [string]" 4 +.IX Item "hidden_filter [string]" +A regular expression pattern for files which should be hidden. For example, +this pattern will hide all files that start with a dot or end with a tilde. +.Sp +.Vb 1 +\& set hidden_filter ^\e.|~$ +.Ve +.IP "max_console_history_size [integer, none]" 4 +.IX Item "max_console_history_size [integer, none]" +How many console commands should be kept in history? \*(L"none\*(R" will disable the +limit. +.IP "max_history_size [integer, none]" 4 +.IX Item "max_history_size [integer, none]" How many directory changes should be kept in history? .IP "mouse_enabled [bool] " 4 .IX Item "mouse_enabled [bool] " @@ -553,8 +577,8 @@ Preview directories in the preview column? .IP "preview_files [bool] " 4 .IX Item "preview_files [bool] " Preview files in the preview column? -.IP "preview_script [string, None]" 4 -.IX Item "preview_script [string, None]" +.IP "preview_script [string, none]" 4 +.IX Item "preview_script [string, none]" Which script should handle generating previews? If the file doesn't exist, or use_preview_script is off, ranger will handle previews itself by just printing the content. @@ -587,7 +611,7 @@ its \s-1ASCII\s0 value is higher. Sort directories first? .IP "sort_reverse [bool] " 4 .IX Item "sort_reverse [bool] " -Sort reversed? +Reverse the order of files? .IP "sort [string] , , , , , , " 4 .IX Item "sort [string] , , , , , , " Which sorting mechanism should be used? Choose one of \fBatime\fR, \fBbasename\fR, @@ -807,35 +831,28 @@ Unmark all files matching a regular expression pattern. .IX Header "FILES" ranger reads several configuration files which are located in \&\fI\f(CI$HOME\fI/.config/ranger\fR or \fI\f(CI$XDG_CONFIG_HOME\fI/ranger\fR if \f(CW$XDG_CONFIG_HOME\fR is -defined. The configuration is done mostly in python. When removing a -configuration file, remove its compiled version too. (Python automatically -compiles modules. Since python3 they are saved in the _\|_pycache_\|_ directory, -earlier versions store them with the .pyc extension in the same directory.) -.PP -Use the \-\-copy\-config option to obtain the default configuration files. They -include further documentation and it's too much to put here. +defined. You can use the \-\-copy\-config option to obtain the default +configuration files. Each of the files contains further documentation. .PP You don't need to copy the whole file though, most configuration files are -overlaid on top of the defaults (\fIoptions.py\fR, \fIcommand.py\fR, \fIrc.conf\fR) or -can be sub-classed (\fIapps.py\fR, \fIcolorschemes\fR). +overlaid on top of the defaults (\fIcommands.py\fR, \fIrc.conf\fR) or can be +sub-classed (\fIcolorschemes\fR). .PP When starting ranger with the \fB\-\-clean\fR option, it will not access or create any of these files. .SS "\s-1CONFIGURATION\s0" .IX Subsection "CONFIGURATION" -.IP "apps.py" 10 -.IX Item "apps.py" -Controls which applications are used to open files. .IP "commands.py" 10 .IX Item "commands.py" -Defines commands which can be used by typing \*(L":\*(R". +A python module that defines commands which can be used in ranger's console by +typing \*(L":\*(R". .IP "rc.conf" 10 .IX Item "rc.conf" Contains a list of commands which are executed on startup. Mostly key bindings -are defined here. -.IP "options.py" 10 -.IX Item "options.py" -Sets a handful of basic options. +and settings are defined here. +.IP "rifle.conf" 10 +.IX Item "rifle.conf" +This is the configuration file for the built-in file launcher called \*(L"rifle\*(R". .IP "scope.sh" 10 .IX Item "scope.sh" This is a script that handles file previews. When the options @@ -846,6 +863,9 @@ reaction. .IP "colorschemes/" 10 .IX Item "colorschemes/" Colorschemes can be placed here. +.IP "plugins/" 10 +.IX Item "plugins/" +Plugins can be placed here. .SS "\s-1STORAGE\s0" .IX Subsection "STORAGE" .IP "bookmarks" 10 @@ -904,50 +924,9 @@ Using PYTHONOPTIMIZE=2 (like python \-OO) will additionally discard any docstrings. Using this will disable the key on commands. .SH "EXAMPLES" .IX Header "EXAMPLES" -.SS "\s-1BASH:\s0 Display that the shell spawned from ranger:" -.IX Subsection "BASH: Display that the shell spawned from ranger:" -By putting this in ~/.bashrc, \*(L"(in ranger) \*(R" will be displayed next to your -prompt to notify you that the shell spawned from ranger. -.PP -.Vb 1 -\& [ \-n "$RANGER_LEVEL" ] && PS1="$PS1"\*(Aq(in ranger) \*(Aq -.Ve -.SS "\s-1VIM:\s0 File Chooser" -.IX Subsection "VIM: File Chooser" -This is a vim function which allows you to use ranger to select a file for -opening in your current vim session. -.PP -.Vb 9 -\& fun! RangerChooser() -\& exec "silent !ranger \-\-choosefile=/tmp/chosenfile " . expand("%:p:h") -\& if filereadable(\*(Aq/tmp/chosenfile\*(Aq) -\& exec \*(Aqedit \*(Aq . system(\*(Aqcat /tmp/chosenfile\*(Aq) -\& call system(\*(Aqrm /tmp/chosenfile\*(Aq) -\& endif -\& redraw! -\& endfun -\& map ,r :call RangerChooser() -.Ve -.SS "Bash: cd to last path after exit" -.IX Subsection "Bash: cd to last path after exit" -This is a bash function (for \fI~/.bashrc\fR) to change the directory to the last -visited one after ranger quits. You can always type \f(CW\*(C`cd \-\*(C'\fR to go back to the -original one. -.PP -.Vb 9 -\& function ranger\-cd { -\& tempfile=\*(Aq/tmp/chosendir\*(Aq -\& /usr/bin/ranger \-\-choosedir="$tempfile" "${@:\-$(pwd)}" -\& test \-f "$tempfile" && -\& if [ "$(cat \-\- "$tempfile")" != "$(echo \-n \`pwd\`)" ]; then -\& cd \-\- "$(cat "$tempfile")" -\& fi -\& rm \-f \-\- "$tempfile" -\& } -\& -\& # This binds Ctrl\-O to ranger\-cd: -\& bind \*(Aq"\eC\-o":"ranger\-cd\eC\-m"\*(Aq -.Ve +There are various examples on how to extend ranger with plugins or combine +ranger with other programs. These can be found in the \*(L"examples\*(R" directory +that is provided along with the source code. .SH "LICENSE" .IX Header "LICENSE" \&\s-1GNU\s0 General Public License 3 or (at your option) any later version. -- cgit 1.4.1-2-gfad0