update documentation for options, plugins and examples

3 files changed, 127 insertions, 172 deletions

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 <brokets>, 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] <zc>" 4
 .IX Item "collapse_preview [bool] <zc>"
 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] <zi>" 4
 .IX Item "flushinput [bool] <zi>"
 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] <zm>" 4
 .IX Item "mouse_enabled [bool] <zm>"
@@ -553,8 +577,8 @@ Preview directories in the preview column?
 .IP "preview_files [bool] <zp>" 4
 .IX Item "preview_files [bool] <zp>"
 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] <or>" 4
 .IX Item "sort_reverse [bool] <or>"
-Sort reversed?
+Reverse the order of files?
 .IP "sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>" 4
 .IX Item "sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>"
 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 <F1> 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()<CR>
-.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.
diff --git a/doc/ranger.pod b/doc/ranger.pod
index 2a3a345b..bb0abc9c 100644
--- a/doc/ranger.pod
+++ b/doc/ranger.pod
@@ -457,10 +457,21 @@ 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 <brokets>, if
 a hotkey exists.
 
-Settings can be changed in the file F<~/.config/ranger/options.py> or on the
+Settings can be changed in the file F<~/.config/ranger/rc.conf> or on the
 fly with the command B<:set option value>.  Examples:
- :set column_ratios (1,2,3)
- :set show_hidden=True
+
+ set column_ratios 1,2,3
+ set show_hidden true
+
+The different types of settings and an example for each type:
+
+ setting type   | example values
+ ---------------+----------------------------
+ bool           | true, false
+ integer        | 1, 23, 1337
+ string         | foo, hello world
+ list           | 1,2,3,4
+ none           | none
 
 =over
 
@@ -470,26 +481,28 @@ 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.
 
+=item autoupdate_cumulative_size [bool]
+
+You can display the "real" cumulative size of directories by using the command
+:get_cumulative_size or typing "dc".  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.
+
 =item collapse_preview [bool] <zc>
 
 When no preview is visible, should the last column be squeezed to make use of
 the whitespace?
 
-=item colorscheme_overlay [function, None]
-
-An overlay function for colorschemes.  See the default options.py for an
-explanation and an example.
-
 =item colorscheme [string]
 
 Which colorscheme to use?  These colorschemes are available by default:
-B<default>, B<default88>, B<texas>, B<jungle>, B<snow>. Snow is monochrome,
-texas and default88 use 88 colors.
+B<default>, B<jungle>, B<snow>.  Snow is a monochrome scheme, jungle replaces
+blue directories with green ones for better visibility on certain terminals.
 
-=item column_ratios [tuple, list]
+=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.
 
 =item dirname_in_tabs [bool]
@@ -508,29 +521,34 @@ Display the file size in the status bar?
 
 Display tags in all columns?
 
-=item draw_bookmark_borders [bool]
-
-Draw borders around the bookmark window?
-
 =item draw_borders [bool]
 
 Draw borders around columns?
 
+=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?
+
 =item flushinput [bool] <zi>
 
 Flush the input after each key hit?  One advantage is that when scrolling down
 with "j", ranger stops scrolling instantly when you release the key.  One
 disadvantage is that when you type commands blindly, some keys might get lost.
 
-=item hidden_filter [regexp]
+=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.
 
-A regular expression pattern for files which should be hidden.
+ set hidden_filter ^\.|~$
 
-=item max_console_history_size [integer, None]
+=item max_console_history_size [integer, none]
 
-How many console commands should be kept in history?
+How many console commands should be kept in history?  "none" will disable the
+limit.
 
-=item max_history_size [integer, None]
+=item max_history_size [integer, none]
 
 How many directory changes should be kept in history?
 
@@ -552,7 +570,7 @@ Preview directories in the preview column?
 
 Preview files in the preview column?
 
-=item preview_script [string, None]
+=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
@@ -595,7 +613,7 @@ Sort directories first?
 
 =item sort_reverse [bool] <or>
 
-Sort reversed?
+Reverse the order of files?
 
 =item sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>
 
@@ -870,17 +888,12 @@ Unmark all files matching a regular expression pattern.
 
 ranger reads several configuration files which are located in
 F<$HOME/.config/ranger> or F<$XDG_CONFIG_HOME/ranger> if $XDG_CONFIG_HOME 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.)
-
-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.
 
 You don't need to copy the whole file though, most configuration files are
-overlaid on top of the defaults (F<options.py>, F<command.py>, F<rc.conf>) or
-can be sub-classed (F<apps.py>, F<colorschemes>).
+overlaid on top of the defaults (F<commands.py>, F<rc.conf>) or can be
+sub-classed (F<colorschemes>).
 
 When starting ranger with the B<--clean> option, it will not access or create
 any of these files.
@@ -889,22 +902,19 @@ any of these files.
 
 =over 10
 
-=item apps.py
-
-Controls which applications are used to open files.
-
 =item commands.py
 
-Defines commands which can be used by typing ":".
+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
-are defined here.
+and settings are defined here.
 
-=item options.py
+=item rifle.conf
 
-Sets a handful of basic options.
+This is the configuration file for the built-in file launcher called "rifle".
 
 =item scope.sh
 
@@ -918,6 +928,10 @@ reaction.
 
 Colorschemes can be placed here.
 
+=item plugins/
+
+Plugins can be placed here.
+
 =back
 
 =head2 STORAGE
@@ -1004,46 +1018,9 @@ docstrings.  Using this will disable the <F1> key on commands.
 
 =head1 EXAMPLES
 
-=head2 BASH: Display that the shell spawned from ranger:
-
-By putting this in ~/.bashrc, "(in ranger) " will be displayed next to your
-prompt to notify you that the shell spawned from ranger.
-
- [ -n "$RANGER_LEVEL" ] && PS1="$PS1"'(in ranger) '
-
-=head2 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.
-
- fun! RangerChooser()
-   exec "silent !ranger --choosefile=/tmp/chosenfile " . expand("%:p:h")
-   if filereadable('/tmp/chosenfile')
-     exec 'edit ' . system('cat /tmp/chosenfile')
-     call system('rm /tmp/chosenfile')
-   endif
-   redraw!
- endfun
- map ,r :call RangerChooser()<CR>
-
-=head2 Bash: cd to last path after exit
-
-This is a bash function (for F<~/.bashrc>) to change the directory to the last
-visited one after ranger quits.  You can always type C<cd -> to go back to the
-original one.
-
- function ranger-cd {
-   tempfile='/tmp/chosendir'
-   /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 '"\C-o":"ranger-cd\C-m"'
+There are various examples on how to extend ranger with plugins or combine
+ranger with other programs.  These can be found in the "examples" directory
+that is provided along with the source code.
 
 
 
diff --git a/ranger/container/settingobject.py b/ranger/container/settingobject.py
index ed9ab1ea..3562f444 100644
--- a/ranger/container/settingobject.py
+++ b/ranger/container/settingobject.py
@@ -16,18 +16,17 @@ ALLOWED_SETTINGS = {
 	'display_size_in_main_column': bool,
 	'display_size_in_status_bar': bool,
 	'display_tags_in_all_columns': bool,
-	'draw_bookmark_borders': bool,
 	'draw_borders': bool,
 	'draw_progress_bar_in_status_bar': bool,
 	'flushinput': bool,
-	'hidden_filter': (str, type(re.compile(""))), #XXX
+	'hidden_filter': (str, type(re.compile(""))), #COMPAT change to str-only
 	'max_console_history_size': (int, type(None)),
 	'max_history_size': (int, type(None)),
 	'mouse_enabled': bool,
+	'padding_right': bool,
 	'preview_directories': bool,
 	'preview_files': bool,
 	'preview_script': (str, type(None)),
-	'padding_right': bool,
 	'save_console_history': bool,
 	'scroll_offset': int,
 	'shorten_title': int,  # XXX Note: False is an instance of int
@@ -39,9 +38,9 @@ ALLOWED_SETTINGS = {
 	'sort_reverse': bool,
 	'sort': str,
 	'tilde_in_titlebar': bool,
+	'unicode_ellipsis': bool,
 	'update_title': bool,
 	'use_preview_script': bool,
-	'unicode_ellipsis': bool,
 	'xterm_alt_key': bool,
 }