Merge branch 'master' into stable

Conflicts:
	ranger/defaults/options.py

5 files changed, 1959 insertions, 362 deletions

diff --git a/doc/HACKING b/doc/HACKING
index dd384758..f6d5d064 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -10,7 +10,7 @@ Coding Style
     http://www.python.org/dev/peps/pep-0008/
 * Although this guide suggests otherwise, tabs are used for indentation
     of code and docstrings.  In other documents (readme, etc), use spaces.
-* Test the code with unit tests where it makes sense
+* Test the code with "doctest" where it makes sense
 
 
 Patches
@@ -35,29 +35,25 @@ ranger/fsobject/fsobject.py
 About the UI:
 ranger/gui/widgets/browsercolumn.py
 ranger/gui/widgets/browserview.py
-ranger/gui/defaultui.py
+ranger/gui/ui.py
 
 
 Common Changes
 --------------
 
 * Change which files are previewed in the auto preview:
-In ranger/gui/widget/browsercolumn.py
+In ranger/fsobject/file.py
 the constant PREVIEW_BLACKLIST
 
 * Adding options:
 In ranger/defaults/options.py
 add the default value, like: my_option = True
-In ranger/shared/settings.py
+In ranger/container/settingobject.py
 add the name of your option to the constant ALLOWED_SETTINGS
 
 The setting is now accessible at self.settings.my_option,
 assuming <self> is a "SettingsAware" object.
 
-* Changing commands, adding aliases:
-ranger/defaults/commands.py
-or ~/.config/ranger/commands.py
-
 * Adding colorschemes:
 Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
 and modify it according to your needs.  Alternatively, mimic the jungle
@@ -66,15 +62,6 @@ In ranger/defaults/options.py (or ~/.config/ranger/options.py), change
     colorscheme = 'default'
 to: colorscheme = 'myscheme'
 
-* Change which files are considered to be "hidden":
-In ranger/defaults/options.py
-change the hidden_filter regular expression.
-
-* Change the key map:
-Modify ranger/defaults/keys.py.  This should be self-explanatory.
-Check out ranger/core/actions.py for the most common actions, of course
-you can also use your own functions.
-
 * Change the file type => application associations:
 In ranger/defaults/apps.py
 modify the method app_default.
@@ -88,8 +75,5 @@ Modify ranger/data/mime.types
 Version Numbering
 -----------------
 
-X.Y.Z, where:
-
-* X: Major version, milestone
-* Y: Minor version, even number => stable version
-* Z: Revision, may be omitted if zero
+Three numbers;  The first changes on a rewrite, the second changes when major
+configuration incompatibilities occur and the third changes with each release.
diff --git a/doc/TODO b/doc/TODO
deleted file mode 100644
index 1577f97a..00000000
--- a/doc/TODO
+++ /dev/null
@@ -1,119 +0,0 @@
-Console
-
-   (X) #0   09/12/06  console commands
-   (X) #1   09/12/06  quick find
-   (X) #2   09/12/06  open with
-   (X) #4   09/12/06  history for console
-   (X) #13  09/12/27  display docstring of a command
-
-
-General
-
-   (X) #5   09/12/06  move code from fm into objects
-   (X) #6   09/12/06  move main to __init__
-   (X) #7   09/12/06  cooler titlebar
-   (X) #8   09/12/17  Add operations to modify files/directories
-   (X) #9   09/12/24  add a widget for managing running operations
-   (X) #10  09/12/24  sorting
-   (X) #11  09/12/27  filter
-   (X) #12  09/12/27  jump through the list in a specific order
-   (X) #14  09/12/29  make filelists inherit from pagers
-   (X) #15  09/12/29  better way of running processes!!~
-   (X) #16  10/01/01  list of bookmarks
-   (X) #21  10/01/01  write help!
-   (X) #22  10/01/03  add getopt options to change flags/mode
-   (X) #29  10/01/06  add chmod command
-   (X) #30  10/01/06  add a way to create symlinks
-   (X) #32  10/01/08  place the (hidden) cursor to a meaningful position
-   (X) #34  10/01/09  display free disk space
-   (X) #35  10/01/09  display disk usage of files in current directory
-   ( ) #36  10/01/11  help coloring is terribly inefficient
-   (X) #37  10/01/13  better tab completion for OpenConsole
-   ( ) #38  10/01/16  searching in pager
-   (X) #39  10/01/17  flushinput not always good
-   (X) #42  10/01/17  memorize directory for `` when using :cd
-   (X) #43  10/01/18  internally treat the bookmarks ` and ' the same
-   ( ) #44  10/01/18  more error messages :P
-   (X) #47  10/01/19  less restricive auto preview
-   (X) #48  10/01/19  abbreviate commands with first unambiguous substring
-   ( ) #50  10/01/19  add more unit tests
-   ( ) #51  10/01/21  remove directory.marked_items ?
-   (X) #55  10/01/24  allow change of filename when pasting
-          you're given the choice between overwriting or appending a "_"
-   ( ) #56  10/01/30  warn before deleting mount points
-   ( ) #57  10/01/30  warn before deleting unseen marked files
-   (X) #58  10/02/04  change the title of the terminal
-   (X) #61  10/02/09  show sum of size of marked files
-   (X) #63  10/02/15  limit filesize in previews
-   ( ) #64  10/02/25  scroll in previews
-   (X) #66  10/02/28  explain how colorschemes work
-   (X) #70  10/03/14  mouse handler for titlebar
-   (X) #71  10/03/21  previews: black/whitelist + read file
-   (X) #79  10/04/08  tab number zero
-   ( ) #80  10/04/08  when closing tabs, avoid gaps?
-   (X) #81  10/04/15  system crash when previewing /proc/kcore with root permissions
-   (X) #83  10/04/19  better ways to mark files. eg by regexp, filetype,..
-   ( ) #86  10/04/21  narg for move_parent
-   ( ) #60  10/02/05  utf support improvable
-   ( ) #91  10/05/12  in keys.py, fm.move(right=N) should run with mode=N
-   ( ) #92  10/05/14  allow to enter the realpath of a directory
-   ( ) #93  10/05/15  pause after running program
-
-
-Bugs
-
-   (X) #17  10/01/01  why do bookmarks disappear sometimes?
-   (X) #18  10/01/01  fix notify widget (by adding a LogView?)
-   (X) #19  10/01/01  resizing after pressing g
-   (X) #23  10/01/04  stop dir loading with ^C -> wont load anymore
-   (X) #25  10/01/06  directories sometimes dont reload correctly
-   (X) #26  10/01/06  :delete on symlinks of directories fails
-   (X) #31  10/01/06  ^C breaks cd-after-exit by stopping sourced shell script
-   (X) #40  10/01/17  freeze with unavailable sshfs
-          Not rangers fault (?)
-   (X) #41  10/01/17  capital file extensions are not recognized
-   (X) #46  10/01/19  old username displayed after using su
-   (X) #49  10/01/19  fix unit tests :'(
-   (X) #52  10/01/23  special characters in tab completion
-   (X) #54  10/01/23  max_dirsize_for_autopreview not working
-   (X) #62  10/02/15  curs_set can raise an exception
-   (X) #65  10/02/16  "source ranger ranger some/file.txt" shouldn't cd after exit
-   (X) #67  10/03/08  terminal title in tty
-   (X) #69  10/03/11  tab-completion breaks with Apps subclass
-   (X) #73  10/03/21  when clicking on the first column, it goes 1x down
-   (X) #74  10/03/21  console doesn't scroll
-   (X) #78  10/03/31  broken preview when deleting all files in a directory
-   (X) #85  10/04/26  no automatic reload of directory after using :filter
-   (X) #87  10/05/10  files are not properly closed after previewing
-   ( ) #88  10/05/10  race conditions for data loading from FS
-   (X) #90  10/05/11  no link target for broken links
-   ( ) #94  10/05/26  "pressed keys" text cut off when chaining ctrl-XYZ keys
-
-
-Ideas
-
-   ( ) #20  10/01/01  use inotify to monitor filesystem changes
-   ( ) #24  10/01/06  progress bar
-   (X) #27  10/01/06  hide bookmarks in list which contain hidden dir
-   (X) #28  10/01/06  use regexp instead of string for searching
-   (X) #33  10/01/08  accelerate mousewheel speed
-          won't do this
-   (X) #45  10/01/18  hooks for events like setting changes
-   (X) #53  10/01/23  merge fm and environment
-          won't do this
-   (X) #68  10/03/10  threads, to seperate ui and loading
-          won't do this
-   ( ) #72  10/03/21  ranger daemon which does the slow io tasks
-   ( ) #75  10/03/28  navigate in history
-   (X) #76  10/03/28  save history between sessions
-   (X) #77  10/03/28  colorscheme overlay in options.py
-   ( ) #82  10/04/19  :s command for batch renaming
-   ( ) #84  10/04/25  use pygments for syntax highlighting
-   ( ) #89  10/05/10  branch view
-
-
-Blocking
-
-   ( ) #60  10/02/05  utf support improvable
-   (X) #81  10/04/15  system crash when previewing /proc/kcore with root permissions
-
diff --git a/doc/help b/doc/help
deleted file mode 120000
index 09ad0c73..00000000
--- a/doc/help
+++ /dev/null
@@ -1 +0,0 @@
-../ranger/help
\ No newline at end of file
diff --git a/doc/ranger.1 b/doc/ranger.1
index 08776fc7..da98f718 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -1,235 +1,934 @@
-.TH RANGER 1 ranger-1.4.4
-.SH NAME
-ranger - visual file manager
-.\"-----------------------------------------
-.SH SYNOPSIS
-.B ranger
-.R [OPTIONS] [FILE]
-.\"-----------------------------------------
-.SH DESCRIPTION
-Ranger is a file manager with an ncurses frontend written in Python.
-.P
-It is designed to give you a broader overview of the file system by displaying
-previews and backviews, dividing the screen into several columns.
-The keybindings are similar to those of other console programs like
-.BR vim ", " mutt " or " ncmpcpp
-so the usage will be intuitive and efficient.
-.\"-----------------------------------------
-.SH OPTIONS
-.TP
---version
-Print the version and exit.
-.TP
--h, --help
-Print a list of options and exit.
-.TP
--d, --debug
-Activate the debug mode:  Whenever an error occurs, ranger will exit and
-print a full backtrace.  The default behaviour is to merely print the
-name of the exception in the statusbar/log and to try to keep running.
-.TP
--c, --clean
-Activate the clean mode:  Ranger will not access or create any configuration
-files nor will it leave any traces on your system.  This is useful when
-your configuration is broken, when you want to avoid clutter, etc.
-.TP
---choosefile=\fItargetfile\fR
+.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "RANGER 1"
+.TH RANGER 1 "ranger-1.5.0" "10/11/2011" "ranger manual"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+ranger \- visual file manager
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBranger\fR [\fB\-\-help\fR] [\fB\-\-version\fR] [\fB\-\-debug\fR] [\fB\-\-clean\fR]
+[\fB\-\-list\-unused\-keys\fR] [\fB\-\-fail\-unless\-cd\fR] [\fB\-\-choosedir\fR=\fItargetfile\fR]
+[\fB\-\-choosefile\fR=\fItargetfile\fR] [\fB\-\-copy\-config\fR=\fIfile\fR] [\fB\-\-mode\fR=\fImode\fR]
+[\fB\-\-flags\fR=\fIflags\fR] [\fIpath/filename\fR]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+ranger is a console file manager with \s-1VI\s0 key bindings.  It provides a
+minimalistic and nice curses interface with a view on the directory hierarchy.
+The secondary task of ranger is to figure out which program you want to use to
+open your files with.
+.PP
+This manual mainly contains information on the usage of ranger.  Refer to the
+\&\fI\s-1README\s0\fR for install instructions and to \fIdoc/HACKING\fR for development
+specific information.  For configuration, see the files in \fIranger/defaults\fR.
+They are usually installed to \fI/usr/lib/python*/site\-packages/ranger/defaults\fR
+and can be obtained with ranger's \-\-copy\-config option.
+.PP
+Inside ranger, you can press \fI1?\fR for a list of key bindings, \fI2?\fR for a list
+of commands and \fI3?\fR for a list of settings.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-d\fR, \fB\-\-debug\fR" 14
+.IX Item "-d, --debug"
+Activate the debug mode: Whenever an error occurs, ranger will exit and print a
+full traceback.  The default behavior is to merely print the name of the
+exception in the statusbar/log and try to keep running.
+.IP "\fB\-c\fR, \fB\-\-clean\fR" 14
+.IX Item "-c, --clean"
+Activate the clean mode:  ranger will not access or create any configuration
+files nor will it leave any traces on your system.  This is useful when your
+configuration is broken, when you want to avoid clutter, etc.
+.IP "\fB\-\-choosefile\fR=\fItargetfile\fR" 14
+.IX Item "--choosefile=targetfile"
 Allows you to pick a file with ranger.  This changes the behavior so that when
 you open a file, ranger will exit and write the name of that file into
-\fItargetfile\fR
-.TP
---choosedir=\fItargetfile\fR
+\&\fItargetfile\fR.
+.IP "\fB\-\-choosedir\fR=\fItargetfile\fR" 14
+.IX Item "--choosedir=targetfile"
 Allows you to pick a directory with ranger.  When you exit ranger, it will
-write the last visited directory into \fItargetfile\fR
-.TP
---copy-config=\fIwhich\fR
+write the last visited directory into \fItargetfile\fR.
+.IP "\fB\-\-copy\-config\fR=\fIfile\fR" 14
+.IX Item "--copy-config=file"
 Create copies of the default configuration files in your local configuration
-directory.  Existing ones will not be overwritten.  Possible values:
-all, apps, commands, keys, options, scope.
-.TP
---fail-unless-cd
-Return the exit code 1 if ranger is used to run a file, for example with
-`ranger --fail-unless-cd filename`.  This can be useful for scripts.
-.TP
--r \fIdir\fR, --confdir=\fIdir\fR
-Define a different configuration directory.  The default is
-$XDG_CONFIG_HOME/ranger (which defaults to ~/.config/ranger)
-.TP
--m \fIn\fR, --mode=\fIn\fR
-When a filename is supplied, make it run in mode \fIn\fR. Check the
-documentation for more information on modes.
-.TP
--f \fIflags\fR, --flags=\fIflags\fR
-When a filename is supplied, make it run with the flags \fIflags\fR. Check the
-documentation for more information on flags.
-.\"-----------------------------------------
-.SH USAGE
-.\"-----------------------------------------
-.SS General Keybindings
-Many keybindings take an additional numeric argument.  Type \fI5j\fR to move
-down 5 lines, \fI10<Space>\fR to mark 10 files or \fI3?\fR to read the
-third chapter of the documentation.
-.TP
-h, j, k, l
-Move left, down, up, right
-.TP
-^D or J, ^U or K
+directory.  Existing ones will not be overwritten.  Possible values: \fIall\fR,
+\&\fIrc\fR, \fIapps\fR, \fIcommands\fR, \fIoptions\fR, \fIscope\fR.
+.IP "\fB\-\-list\-unused\-keys\fR" 14
+.IX Item "--list-unused-keys"
+List common keys which are not bound to any action in the \*(L"browser\*(R" context.
+This list is not complete, you can bind any key that is supported by curses:
+use the key code returned by \f(CW\*(C`getch()\*(C'\fR.
+.IP "\fB\-\-fail\-unless\-cd\fR" 14
+.IX Item "--fail-unless-cd"
+Return the exit code 1 if ranger is used to run a file instead of used for file
+browsing. (For example, \*(L"ranger \-\-fail\-unless\-cd test.txt\*(R" returns 1.)
+.IP "\fB\-m\fR \fIn\fR, \fB\-\-mode\fR=\fIn\fR" 14
+.IX Item "-m n, --mode=n"
+When a filename is supplied, run it in mode \fIn\fR.  This has no effect unless
+the execution of this file type is explicitly handled in the configuration.
+.IP "\fB\-f\fR \fIflags\fR, \fB\-\-flags\fR=\fIflags\fR" 14
+.IX Item "-f flags, --flags=flags"
+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.
+.IP "\fB\-\-version\fR" 14
+.IX Item "--version"
+Print the version and exit.
+.IP "\fB\-h\fR, \fB\-\-help\fR" 14
+.IX Item "-h, --help"
+Print a list of options and exit.
+.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-1PREVIEWS\s0"
+.IX Subsection "PREVIEWS"
+By default, only text files are previewed, but you can enable external preview
+scripts by setting the option \f(CW\*(C`use_preview_script\*(C'\fR and \f(CW\*(C`preview_files\*(C'\fR to True.
+.PP
+This default script is \fI~/.config/ranger/scope.sh\fR. It 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.
+.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-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 behavior 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"
+Key bindings are defined in the file \fIranger/defaults/rc.conf\fR.  Check this
+file for a list of all key bindings.  You can copy it to your local
+configuration directory with the \-\-copy\-config=rc option.
+.PP
+Many key bindings take an additional numeric argument.  Type \fI5j\fR to move
+down 5 lines, \fI2l\fR to open a file in mode 2, \fI10<Space>\fR to mark 10 files.
+.PP
+This list contains the most useful bindings:
+.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
+.IP "^D or J, ^U or K" 14
+.IX Item "^D or J, ^U or K"
 Move a half page down, up
-.TP
-H, L
+.IP "H, L" 14
+.IX Item "H, L"
 Move back and forward in the history
-.TP
-gg
+.IP "gg" 14
+.IX Item "gg"
 Move to the top
-.TP
-G
+.IP "G" 14
+.IX Item "G"
 Move to the bottom
-.TP
-^R
+.IP "^R" 14
+.IX Item "^R"
 Reload everything
-.TP
-^L
+.IP "^L" 14
+.IX Item "^L"
 Redraw the screen
-.TP
-S
+.IP "S" 14
+.IX Item "S"
 Open a shell in the current directory
-.TP
-yy
-Yank the selection to the "copy" buffer and mark them as to be copied
-.TP
-dd
-Cut the selection to the "copy" buffer and mark them as to be moved
-.TP
-pp
-Paste the files from the "copy" buffer here (by moving or copying, depending
-on how they are marked.) By default, this will not overwrite existing files.
-To overwrite them, use \fBpo\fR.
-.TP
-m\fIX\fR
+.IP "?" 14
+Opens this man page
+.IP "yy" 14
+.IX Item "yy"
+Yank the selection to the \*(L"copy\*(R" buffer and mark them as to be copied
+.IP "dd" 14
+.IX Item "dd"
+Cut the selection to the \*(L"copy\*(R" buffer and mark them as to be moved
+.IP "pp" 14
+.IX Item "pp"
+Paste the files from the \*(L"copy\*(R" buffer here (by moving or copying, depending on
+how they are marked.) By default, this will not overwrite existing files.  To
+overwrite them, use \fIpo\fR.
+.IP "m\fIX\fR" 14
+.IX Item "mX"
 Create a bookmark with the name \fIX\fR
-.TP
-`\fIX\fR
+.IP "`\fIX\fR" 14
+.IX Item "`X"
 Move to the bookmark with the name \fIX\fR
-.TP
-n, N
-Find the next file, the previous file.  You can define what to look for
-by typing c\fIX\fR.  If nothing is specified, pressing n will get you to
-the newest file in the directory.
-.TP
-o\fIX\fR
+.IP "n, N" 14
+.IX Item "n, N"
+Find the next file.  By default, this gets you to the newest file in the
+directory, but if you search something using the keys /, cm, ct, ..., it will
+get you to the next found entry.
+.IP "N" 14
+.IX Item "N"
+Find the previous file.
+.IP "o\fIX\fR" 14
+.IX Item "oX"
 Change the sort method (like in mutt)
-.TP
-z\fIX\fR
-Change settings
-.TP
-f
-Quickly navigate by entering a part of the filename
-.TP
-Space
-Mark a file
-.TP
-v, V
-Toggle the mark-status of all files, unmark all files
-.TP
-/
-Open the search console
-.TP
-:
-Open the command console
-.TP
-?
-Opens the help screen with more keybindings and documentation
-.\"-----------------------------------------
-.SS Keybindings for using Tabs
-Tabs are used to work in different directories in the same Ranger instance.
-.TP
-g\fIN\fR
-Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet,
-it will be created.
-.TP
-gn, ^N
+.IP "z\fIX\fR" 14
+.IX Item "zX"
+Change settings.  See the settings section for a list of settings and their
+hotkey.
+.IP "f" 14
+.IX Item "f"
+Quickly navigate by entering a part of the filename.
+.IP "Space" 14
+.IX Item "Space"
+Mark a file.
+.IP "v" 14
+.IX Item "v"
+Toggle the mark-status of all files, unmark all files.
+.IP "V, uv" 14
+.IX Item "V, uv"
+Unmark all files
+.IP "/" 14
+Search for files in the current directory.
+.IP ":" 14
+Open the console.
+.IP "Alt\-\fIN\fR" 14
+.IX Item "Alt-N"
+Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it
+will be created.
+.IP "gn, ^N" 14
+.IX Item "gn, ^N"
 Create a new tab.
-.TP
-gt, gT
-Go to the next or previous tab.  You can also use TAB and SHIFT+TAB.
-.TP
-gc, ^W
-Close the current tab.  The last tab cannot be closed.
-.P
-.\"-----------------------------------------
-.SS Mouse Usage
-.TP
-Left Mouse Button
-Click on something and you'll move there.
-To run a file, "enter" it, like a directory, by clicking on the preview.
-.TP
-Right Mouse Button
-Enter a directory
-.TP
-Scroll Wheel
-Scroll
-.\"-----------------------------------------
-.SS Commands
-.TP
-:delete
-Destroy all files in the selection with a roundhouse kick.  Ranger will
-ask for a confirmation if you attempt to delete multiple (marked) files or
-non-empty directories.
-.TP
-:rename \fInewname\fR
-Rename the current file.  Also try the keybinding A for appending something
-to a file name.
-.TP
-:quit
-Quit ranger.  The current directory will be bookmarked as ' so you can
-re-enter it by typing `` or '' the next time you start ranger.
-.\"-----------------------------------------
-.SH TIPS
-.SS
-Change the directory after exit
-A script like this in your bashrc would make you change the directory
-of your parent shell after exiting ranger:
-.nf
-
-ranger() {
-    command ranger --fail-unless-cd $@ &&
-    cd "$(grep \\^\\' ~/.config/ranger/bookmarks | cut -b3-)"
-}
-.\"-----------------------------------------
-.SH CONFIGURATION
-The files in
-.B ranger/defaults/
-can be copied into your configuration directory (by default, this is
-~/.config/ranger) and customized according to your wishes.
-Most files don't have to be copied completely though: Just define those
-settings you want to add or change and they will override the defauls.
-Colorschemes can be placed in ~/.config/ranger/colorschemes.
-.P
-All configuration is done in Python.
-Each configuration file should contain sufficient documentation.
-.\"-----------------------------------------
-.SH COPYRIGHT
-Copyright \(co
-2009, 2010
-Roman Zimbelmann
-.P
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-There is NO warranty;
-not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-.\"-----------------------------------------
-.SH SEE ALSO
-The project page:
-.RB < http://ranger.nongnu.org/ >
-.P
-The mailing list:
-.RB < http://savannah.nongnu.org/mail/?group=ranger >
-.\"-----------------------------------------
-.SH BUGS
-Please report them here and include as much relevant information
-as possible:
-.P
-.RB < http://savannah.nongnu.org/bugs/?group=ranger >
+.IP "gt, gT" 14
+.IX Item "gt, gT"
+Go to the next or previous tab. You can also use \s-1TAB\s0 and \s-1SHIFT+TAB\s0 instead.
+.IP "gc, ^W" 14
+.IX Item "gc, ^W"
+Close the current tab.  The last tab cannot be closed this way.
+.SS "\s-1MIDNIGHT\s0 COMMANDER-LIKE \s-1BINDINGS\s0"
+.IX Subsection "MIDNIGHT COMMANDER-LIKE BINDINGS"
+.IP "<F1>" 14
+.IX Item "<F1>"
+Display Help.
+.IP "<F3>" 14
+.IX Item "<F3>"
+Display the file.
+.IP "<F4>" 14
+.IX Item "<F4>"
+Edit the file.
+.IP "<F5>" 14
+.IX Item "<F5>"
+Copy the file.
+.IP "<F6>" 14
+.IX Item "<F6>"
+Cut the file.
+.IP "<F7>" 14
+.IX Item "<F7>"
+Open the console with \*(L":mkdir \*(R".
+.IP "<F8>" 14
+.IX Item "<F8>"
+Prompt for deletion of the selected files.
+.IP "<F10>" 14
+.IX Item "<F10>"
+Exit ranger.
+.SS "READLINE-LIKE \s-1BINDINGS\s0 \s-1IN\s0 \s-1THE\s0 \s-1CONSOLE\s0"
+.IX Subsection "READLINE-LIKE BINDINGS IN THE CONSOLE"
+.IP "^B, ^F" 14
+.IX Item "^B, ^F"
+Move left and right (B for back, F for forward)
+.IP "^P, ^N" 14
+.IX Item "^P, ^N"
+Move up and down (P for previous, N for Next)
+.IP "^A, ^E" 14
+.IX Item "^A, ^E"
+Move to the start or to the end
+.IP "^D" 14
+.IX Item "^D"
+Delete the current character.
+.IP "^H" 14
+.IX Item "^H"
+Backspace.
+.SH "MOUSE BUTTONS"
+.IX Header "MOUSE BUTTONS"
+.IP "Left Mouse Button" 4
+.IX Item "Left Mouse Button"
+Click on something and you'll move there.  To run a file, \*(L"enter\*(R" it, like a
+directory, by clicking on the preview.
+.IP "Right Mouse Button" 4
+.IX Item "Right Mouse Button"
+Enter a directory or run a file.
+.IP "Scroll Wheel" 4
+.IX Item "Scroll Wheel"
+Scrolls up or down.  You can point at the column of the parent directory to
+switch directories.
+.SH "SETTINGS"
+.IX Header "SETTINGS"
+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
+fly with the command \fB:set option value\fR.  Examples:
+ :set column_ratios (1,2,3)
+ :set show_hidden=True
+.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 "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]"
+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
+with the preview column being as large as the other columns combined.
+.IP "dirname_in_tabs [bool]" 4
+.IX Item "dirname_in_tabs [bool]"
+Display the directory name in tabs?
+.IP "display_size_in_main_column [bool]" 4
+.IX Item "display_size_in_main_column [bool]"
+Display the file size in the main column?
+.IP "display_size_in_status_bar [bool]" 4
+.IX Item "display_size_in_status_bar [bool]"
+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 "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]"
+How many directory changes should be kept in history?
+.IP "mouse_enabled [bool] <zm>" 4
+.IX Item "mouse_enabled [bool] <zm>"
+Enable mouse input?
+.IP "padding_right [bool]" 4
+.IX Item "padding_right [bool]"
+When collapse_preview is on and there is no preview, should there remain a
+little padding on the right?  This allows you to click into that space to run
+the file.
+.IP "preview_directories [bool] <zP>" 4
+.IX Item "preview_directories [bool] <zP>"
+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]"
+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.
+.IP "save_console_history [bool]" 4
+.IX Item "save_console_history [bool]"
+Should the console history be saved on exit?  If disabled, the console history
+is reset when you restart ranger.
+.IP "scroll_offset [integer]" 4
+.IX Item "scroll_offset [integer]"
+Try to keep this much space between the top/bottom border when scrolling.
+.IP "shorten_title [integer, bool]" 4
+.IX Item "shorten_title [integer, bool]"
+Trim the title of the window if it gets long?  The number defines how many
+directories are displayed at once, False turns off this feature.
+.IP "show_cursor [bool]" 4
+.IX Item "show_cursor [bool]"
+Always show the terminal cursor?
+.IP "show_hidden_bookmarks [bool]" 4
+.IX Item "show_hidden_bookmarks [bool]"
+Show dotfiles in the bookmark preview window? (Type ')
+.IP "show_hidden [bool] <zh>, <^H>" 4
+.IX Item "show_hidden [bool] <zh>, <^H>"
+Show hidden files?
+.IP "sort_case_insensitive [bool] <zc>" 4
+.IX Item "sort_case_insensitive [bool] <zc>"
+Sort case-insensitively?  If true, \*(L"a\*(R" will be listed before \*(L"B\*(R" even though
+its \s-1ASCII\s0 value is higher.
+.IP "sort_directories_first [bool] <zd>" 4
+.IX Item "sort_directories_first [bool] <zd>"
+Sort directories first?
+.IP "sort_reverse [bool] <or>" 4
+.IX Item "sort_reverse [bool] <or>"
+Sort reversed?
+.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,
+\&\fBctime\fR, \fBmtime\fR, \fBnatural\fR, \fBtype\fR, \fBsize\fR
+.Sp
+Note: You can reverse the order by using an uppercase O in the key combination.
+.IP "tilde_in_titlebar [bool]" 4
+.IX Item "tilde_in_titlebar [bool]"
+Abbreviate \f(CW$HOME\fR with ~ in the title bar (first line) of ranger?
+.IP "unicode_ellipsis [bool]" 4
+.IX Item "unicode_ellipsis [bool]"
+Use a unicode \*(L"...\*(R" character instead of \*(L"~\*(R" to mark cut-off filenames?
+.IP "update_title [bool]" 4
+.IX Item "update_title [bool]"
+Set a window title?
+.IP "use_preview_script [bool] <zv>" 4
+.IX Item "use_preview_script [bool] <zv>"
+Use the preview script defined in the setting \fIpreview_script\fR?
+.IP "xterm_alt_key [bool]" 4
+.IX Item "xterm_alt_key [bool]"
+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".
+.PP
+There are additional commands which are directly translated to python
+functions, one for every method in the ranger.core.actions.Actions class.
+They are not documented here, since they are mostly for key bindings, not to be
+typed in by a user.  Read the source if you are interested in them.
+.IP "bulkrename" 2
+.IX Item "bulkrename"
+This command opens a list of selected files in an external editor.  After you
+edit and save the file, it will generate a shell script which does bulk
+renaming according to the changes you did in the file.
+.Sp
+This shell script is opened in an editor for you to review.  After you close
+it, it will be executed.
+.IP "cd [\fIdirectory\fR]" 2
+.IX Item "cd [directory]"
+The cd command changes the directory.  The command \f(CW\*(C`:cd \-\*(C'\fR is equivalent to
+typing ``.
+.IP "chain \fIcommand1\fR[; \fIcommand2\fR[; \fIcommand3\fR...]]" 2
+.IX Item "chain command1[; command2[; command3...]]"
+Combines multiple commands into one, separated by columns.
+.IP "chmod \fIoctal_number\fR" 2
+.IX Item "chmod octal_number"
+Sets the permissions of the selection to the octal number.
+.Sp
+The octal number is between 000 and 777. The digits specify the permissions for
+the user, the group and others.  A 1 permits execution, a 2 permits writing, a
+4 permits reading.  Add those numbers to combine them. So a 7 permits
+everything.
+.Sp
+Key bindings in the form of [\-+]<who><what> and =<octal> also exist.  For
+example, \fB+ar\fR allows reading for everyone, \-ow forbids others to write and
+=777 allows everything.
+.Sp
+See also: man 1 chmod
+.IP "cmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "cmap key command"
+Binds keys for the console. Works like the \f(CW\*(C`map\*(C'\fR command.
+.IP "console [\-p\fIN\fR] \fIcommand\fR" 2
+.IX Item "console [-pN] command"
+Opens the console with the command already typed in.  The cursor is placed at
+\&\fIN\fR.
+.IP "copycmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
+.IX Item "copycmap key newkey [newkey2 ...]"
+See \f(CW\*(C`copymap\*(C'\fR
+.IP "copymap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
+.IX Item "copymap key newkey [newkey2 ...]"
+Copies the keybinding \fIkey\fR to \fInewkey\fR in the \*(L"browser\*(R" context.  This is a
+deep copy, so if you change the new binding (or parts of it) later, the old one
+is not modified.
+.Sp
+To copy key bindings of the console, taskview, or pager use \*(L"copycmap\*(R",
+\&\*(L"copytmap\*(R" or \*(L"copypmap\*(R".
+.IP "copypmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
+.IX Item "copypmap key newkey [newkey2 ...]"
+See \f(CW\*(C`copymap\*(C'\fR
+.IP "copytmap \fIkey\fR \fInewkey\fR [\fInewkey2\fR ...]" 2
+.IX Item "copytmap key newkey [newkey2 ...]"
+See \f(CW\*(C`copymap\*(C'\fR
+.IP "cunmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "cunmap key command"
+Removes key mappings of the console. Works like the \f(CW\*(C`unmap\*(C'\fR command.
+.IP "delete [\fIconfirmation\fR]" 2
+.IX Item "delete [confirmation]"
+Destroy all files in the selection with a roundhouse kick.  ranger will ask for
+a confirmation if you attempt to delete multiple (marked) files or non-empty
+directories.
+.Sp
+When asking for confirmation, this command will only proceed if the last given
+word starts with a `y'.
+.IP "edit [\fIfilename\fR]" 2
+.IX Item "edit [filename]"
+Edit the current file or the file in the argument.
+.IP "eval [\fI\-q\fR] \fIpython_code\fR" 2
+.IX Item "eval [-q] python_code"
+Evaluates the python code.  `fm' is a reference to the \s-1FM\s0 instance.  To display
+text, use the function `p'.  The result is displayed on the screen unless you
+use the \*(L"\-q\*(R" option.
+.Sp
+Examples:
+ :eval fm
+ :eval len(fm.env.directories)
+ :eval p(\*(L"Hello World!\*(R")
+.IP "filter [\fIstring\fR]" 2
+.IX Item "filter [string]"
+Displays only the files which contain the \fIstring\fR in their basename.
+.IP "find \fIpattern\fR" 2
+.IX Item "find pattern"
+Search files in the current directory that match the given (case-insensitive)
+regular expression pattern as you type.  Once there is an unambiguous result,
+it will be run immediately. (Or entered, if it's a directory.)
+.IP "grep \fIpattern\fR" 2
+.IX Item "grep pattern"
+Looks for a string in all marked files or directories.
+.IP "load_copy_buffer" 2
+.IX Item "load_copy_buffer"
+Load the copy buffer from \fI~/.config/ranger/copy_buffer\fR.  This can be used to
+pass the list of copied files to another ranger instance.
+.IP "map \fIkey\fR \fIcommand\fR" 2
+.IX Item "map key command"
+Assign the key combination to the given command.  Whenever you type the
+key/keys, the command will be executed.  Additionally, if you use a quantifier
+when typing the key, like 5j, it will be passed to the command as the attribute
+\&\*(L"self.quantifier\*(R".
+.Sp
+The keys you bind with this command are accessible in the file browser only,
+not in the console, task view or pager.  To bind keys there, use the commands
+\&\*(L"cmap\*(R", \*(L"tmap\*(R" or \*(L"pmap\*(R".
+.IP "mark \fIpattern\fR" 2
+.IX Item "mark pattern"
+Mark all files matching the regular expression pattern.
+.IP "mkdir \fIdirname\fR" 2
+.IX Item "mkdir dirname"
+Creates a directory with the name \fIdirname\fR.
+.IP "open_with [\fIapplication\fR] [\fIflags\fR] [\fImode\fR]" 2
+.IX Item "open_with [application] [flags] [mode]"
+Open the selected files with the given application, unless it is omitted, in
+which case the default application is used.  \fIflags\fR are characters out of
+\&\*(L"sdpcwSDPCW\*(R" and \fImode\fR is any positive integer. Their meanings are discussed
+in their own sections.
+.IP "pmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "pmap key command"
+Binds keys for the pager. Works like the \f(CW\*(C`map\*(C'\fR command.
+.IP "punmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "punmap key command"
+Removes key mappings of the pager. Works like the \f(CW\*(C`unmap\*(C'\fR command.
+.IP "quit" 2
+.IX Item "quit"
+Like quit!, but closes only this tab if multiple tabs are open.
+.IP "quit!" 2
+.IX Item "quit!"
+Quit ranger.  The current directory will be bookmarked as ' so you can re-enter
+it by typing `` or '' the next time you start ranger.
+.IP "rename \fInewname\fR" 2
+.IX Item "rename newname"
+Rename the current file.  If a file with that name already exists, the renaming
+will fail.  Also try the key binding A for appending something to a file name.
+.IP "save_copy_buffer" 2
+.IX Item "save_copy_buffer"
+Save the copy buffer from \fI~/.config/ranger/copy_buffer\fR.  This can be used to
+pass the list of copied files to another ranger instance.
+.IP "search \fIpattern\fR" 2
+.IX Item "search pattern"
+Search files in the current directory that match the given (case insensitive)
+regular expression pattern.
+.IP "search_inc \fIpattern\fR" 2
+.IX Item "search_inc pattern"
+Search files in the current directory that match the given (case insensitive)
+regular expression pattern.  This command gets you to matching files as you
+type.
+.IP "set \fIoption\fR=\fIvalue\fR" 2
+.IX Item "set option=value"
+Assigns a new value to an option.  Valid options are listed in the settings
+section.  Use tab completion to get the current value of an option, though this
+doesn't work for functions and regular expressions. Valid values are:
+.Sp
+.Vb 8
+\& None           None
+\& bool           True or False
+\& integer        0 or 1 or \-1 or 2 etc.
+\& list           [1, 2, 3]
+\& tuple          1, 2, 3 or (1, 2, 3)
+\& function       lambda <arguments>: <expression>
+\& regexp         regexp(\*(Aq<pattern>\*(Aq)
+\& string         Anything
+.Ve
+.IP "shell [\-\fIflags\fR] \fIcommand\fR" 2
+.IX Item "shell [-flags] command"
+Run a shell command.  \fIflags\fR are discussed in their own section.
+.IP "terminal" 2
+.IX Item "terminal"
+Spawns the \fIx\-terminal-emulator\fR starting in the current directory.
+.IP "touch \fIfilename\fR" 2
+.IX Item "touch filename"
+Creates an empty file with the name \fIfilename\fR, unless it already exists.
+.IP "tmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "tmap key command"
+Binds keys for the taskview. Works like the \f(CW\*(C`map\*(C'\fR command.
+.IP "tunmap \fIkey\fR \fIcommand\fR" 2
+.IX Item "tunmap key command"
+Removes key mappings of the taskview. Works like the \f(CW\*(C`unmap\*(C'\fR command.
+.IP "unmap [\fIkeys\fR ...]" 2
+.IX Item "unmap [keys ...]"
+Removes the given key mappings in the \*(L"browser\*(R" context.  To unmap key bindings
+in the console, taskview, or pager use \*(L"cunmap\*(R", \*(L"tunmap\*(R" or \*(L"punmap\*(R".
+.IP "unmark \fIpattern\fR" 2
+.IX Item "unmark pattern"
+Unmark all files matching a regular expression pattern.
+.SH "FILES"
+.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.
+.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).
+.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".
+.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.
+.IP "scope.sh" 10
+.IX Item "scope.sh"
+This is a script that handles file previews.  When the options
+\&\fIuse_preview_script\fR and \fIpreview_files\fR or, respectively,
+\&\fIpreview_directories\fR are set, the program specified in the option
+\&\fIpreview_script\fR is run and its output and/or exit code determines rangers
+reaction.
+.IP "colorschemes/" 10
+.IX Item "colorschemes/"
+Colorschemes can be placed here.
+.SS "\s-1STORAGE\s0"
+.IX Subsection "STORAGE"
+.IP "bookmarks" 10
+.IX Item "bookmarks"
+This file contains a list of bookmarks.  The syntax is /^(.):(.*)$/. The first
+character is the bookmark key and the rest after the colon is the path to the
+file.  In ranger, bookmarks can be set by typing m<key>, accessed by typing
+\&'<key> and deleted by typing um<key>.
+.IP "copy_buffer" 10
+.IX Item "copy_buffer"
+When running the command :save_copy_buffer, the paths of all currently copied
+files are saved in this file.  You can later run :load_copy_buffer to copy the
+same files again, pass them to another ranger instance or process them in a
+script.
+.IP "history" 10
+.IX Item "history"
+Contains a list of commands that have been previously typed in.
+.IP "tagged" 10
+.IX Item "tagged"
+Contains a list of tagged files. The syntax is /^(.:)?(.*)$/ where the first
+letter is the optional name of the tag and the rest after the optional colon is
+the path to the file.  In ranger, tags can be set by pressing t and removed
+with T.  To assign a named tag, type "<tagname>.
+.SH "ENVIRONMENT"
+.IX Header "ENVIRONMENT"
+These environment variables have an effect on ranger:
+.IP "\s-1EDITOR\s0" 8
+.IX Item "EDITOR"
+Defines the editor to be used for the \*(L"E\*(R" key.  Defaults to the first installed
+program out of \*(L"vim\*(R", \*(L"emacs\*(R" and \*(L"nano\*(R".
+.IP "\s-1SHELL\s0" 8
+.IX Item "SHELL"
+Defines the shell that ranger is going to use with the :shell command and
+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"
+.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()
+\&   silent !ranger \-\-choosefile=/tmp/chosenfile \`[ \-z \*(Aq%\*(Aq ] && echo \-n . || dirname %\`
+\&   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
+.SH "LICENSE"
+.IX Header "LICENSE"
+\&\s-1GNU\s0 General Public License 3 or (at your option) any later version.
+.SH "LINKS"
+.IX Header "LINKS"
+.IP "Download: http://ranger.nongnu.org/ranger\-stable.tar.gz <http://ranger.nongnu.org/ranger-stable.tar.gz>" 4
+.IX Item "Download: http://ranger.nongnu.org/ranger-stable.tar.gz <http://ranger.nongnu.org/ranger-stable.tar.gz>"
+.PD 0
+.IP "The project page: <http://ranger.nongnu.org/>" 4
+.IX Item "The project page: <http://ranger.nongnu.org/>"
+.IP "The mailing list: <http://savannah.nongnu.org/mail/?group=ranger>" 4
+.IX Item "The mailing list: <http://savannah.nongnu.org/mail/?group=ranger>"
+.PD
+.PP
+ranger is maintained with the git version control system.  To fetch a fresh
+copy, run:
+.PP
+.Vb 1
+\& git clone git://git.savannah.nongnu.org/ranger.git
+.Ve
+.SH "BUGS"
+.IX Header "BUGS"
+Report bugs here: <http://savannah.nongnu.org/bugs/?group=ranger>
+.PP
+Please include as much relevant information as possible.  For the most
+diagnostic output, run ranger like this: \f(CW\*(C`PYTHONOPTIMIZE= ranger \-\-debug\*(C'\fR
diff --git a/doc/ranger.pod b/doc/ranger.pod
new file mode 100644
index 00000000..ec272de1
--- /dev/null
+++ b/doc/ranger.pod
@@ -0,0 +1,1034 @@
+=head1 NAME
+
+ranger - visual file manager
+
+
+
+
+=head1 SYNOPSIS
+
+B<ranger> [B<--help>] [B<--version>] [B<--debug>] [B<--clean>]
+[B<--list-unused-keys>] [B<--fail-unless-cd>] [B<--choosedir>=I<targetfile>]
+[B<--choosefile>=I<targetfile>] [B<--copy-config>=I<file>] [B<--mode>=I<mode>]
+[B<--flags>=I<flags>] [I<path/filename>]
+
+
+
+
+=head1 DESCRIPTION
+
+ranger is a console file manager with VI key bindings.  It provides a
+minimalistic and nice curses interface with a view on the directory hierarchy.
+The secondary task of ranger is to figure out which program you want to use to
+open your files with.
+
+This manual mainly contains information on the usage of ranger.  Refer to the
+F<README> for install instructions and to F<doc/HACKING> for development
+specific information.  For configuration, see the files in F<ranger/defaults>.
+They are usually installed to F</usr/lib/python*/site-packages/ranger/defaults>
+and can be obtained with ranger's --copy-config option.
+
+Inside ranger, you can press I<1?> for a list of key bindings, I<2?> for a list
+of commands and I<3?> for a list of settings.
+
+
+
+
+=head1 OPTIONS
+
+=over 14
+
+=item B<-d>, B<--debug>
+
+Activate the debug mode: Whenever an error occurs, ranger will exit and print a
+full traceback.  The default behavior is to merely print the name of the
+exception in the statusbar/log and try to keep running.
+
+=item B<-c>, B<--clean>
+
+Activate the clean mode:  ranger will not access or create any configuration
+files nor will it leave any traces on your system.  This is useful when your
+configuration is broken, when you want to avoid clutter, etc.
+
+=item B<--choosefile>=I<targetfile>
+
+Allows you to pick a file with ranger.  This changes the behavior so that when
+you open a file, ranger will exit and write the name of that file into
+I<targetfile>.
+
+=item B<--choosedir>=I<targetfile>
+
+Allows you to pick a directory with ranger.  When you exit ranger, it will
+write the last visited directory into I<targetfile>.
+
+=item B<--copy-config>=I<file>
+
+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>.
+
+=item B<--list-unused-keys>
+
+List common keys which are not bound to any action in the "browser" context.
+This list is not complete, you can bind any key that is supported by curses:
+use the key code returned by C<getch()>.
+
+=item B<--fail-unless-cd>
+
+Return the exit code 1 if ranger is used to run a file instead of used for file
+browsing. (For example, "ranger --fail-unless-cd test.txt" returns 1.)
+
+=item B<-m> I<n>, B<--mode>=I<n>
+
+When a filename is supplied, run it in mode I<n>.  This has no effect unless
+the execution of this file type is explicitly handled in the configuration.
+
+=item B<-f> I<flags>, B<--flags>=I<flags>
+
+When a filename is supplied, run it with the given I<flags> to modify
+behavior.  The execution of this file type is explicitly handled in the
+configuration.
+
+=item B<--version>
+
+Print the version and exit.
+
+=item B<-h>, B<--help>
+
+Print a list of options and exit.
+
+=back
+
+
+
+
+=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 setting the option C<use_preview_script> and C<preview_files> to True.
+
+This default script is F<~/.config/ranger/scope.sh>. It 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.
+
+=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 behavior 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
+
+Key bindings are defined in the file F<ranger/defaults/rc.conf>.  Check this
+file for a list of all key bindings.  You can copy it to your local
+configuration directory with the --copy-config=rc option.
+
+Many key bindings take an additional numeric argument.  Type I<5j> to move
+down 5 lines, I<2l> to open a file in mode 2, I<10<SpaceE<gt>> to mark 10 files.
+
+This list contains the most useful bindings:
+
+=head2 MAIN BINDINGS
+
+=over 14
+
+=item h, j, k, l
+
+Move left, down, up or right
+
+=item ^D or J, ^U or K
+
+Move a half page down, up
+
+=item H, L
+
+Move back and forward in the history
+
+=item gg
+
+Move to the top
+
+=item G
+
+Move to the bottom
+
+=item ^R
+
+Reload everything
+
+=item ^L
+
+Redraw the screen
+
+=item S
+
+Open a shell in the current directory
+
+=item ?
+
+Opens this man page
+
+=item yy
+
+Yank the selection to the "copy" buffer and mark them as to be copied
+
+=item dd
+
+Cut the selection to the "copy" buffer and mark them as to be moved
+
+=item pp
+
+Paste the files from the "copy" buffer here (by moving or copying, depending on
+how they are marked.) By default, this will not overwrite existing files.  To
+overwrite them, use I<po>.
+
+=item mI<X>
+
+Create a bookmark with the name I<X>
+
+=item `I<X>
+
+Move to the bookmark with the name I<X>
+
+=item n, N
+
+Find the next file.  By default, this gets you to the newest file in the
+directory, but if you search something using the keys /, cm, ct, ..., it will
+get you to the next found entry.
+
+=item N
+
+Find the previous file.
+
+=item oI<X>
+
+Change the sort method (like in mutt)
+
+=item zI<X>
+
+Change settings.  See the settings section for a list of settings and their
+hotkey.
+
+=item f
+
+Quickly navigate by entering a part of the filename.
+
+=item Space
+
+Mark a file.
+
+=item v
+
+Toggle the mark-status of all files, unmark all files.
+
+=item V, uv
+
+Unmark all files
+
+=item /
+
+Search for files in the current directory.
+
+=item :
+
+Open the console.
+
+
+=item Alt-I<N>
+
+Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet, it
+will be created.
+
+=item gn, ^N
+
+Create a new tab.
+
+=item gt, gT
+
+Go to the next or previous tab. You can also use TAB and SHIFT+TAB instead.
+
+=item gc, ^W
+
+Close the current tab.  The last tab cannot be closed this way.
+
+=back
+
+=head2 MIDNIGHT COMMANDER-LIKE BINDINGS
+
+=over 14
+
+=item <F1>
+
+Display Help.
+
+=item <F3>
+
+Display the file.
+
+=item <F4>
+
+Edit the file.
+
+=item <F5>
+
+Copy the file.
+
+=item <F6>
+
+Cut the file.
+
+=item <F7>
+
+Open the console with ":mkdir ".
+
+=item <F8>
+
+Prompt for deletion of the selected files.
+
+=item <F10>
+
+Exit ranger.
+
+=back
+
+=head2 READLINE-LIKE BINDINGS IN THE CONSOLE
+
+=over 14
+
+=item ^B, ^F
+
+Move left and right (B for back, F for forward)
+
+=item ^P, ^N
+
+Move up and down (P for previous, N for Next)
+
+=item ^A, ^E
+
+Move to the start or to the end
+
+=item ^D
+
+Delete the current character.
+
+=item ^H
+
+Backspace.
+
+=back
+
+
+=head1 MOUSE BUTTONS
+
+=over
+
+=item Left Mouse Button
+
+Click on something and you'll move there.  To run a file, "enter" it, like a
+directory, by clicking on the preview.
+
+=item Right Mouse Button
+
+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.
+
+=back
+
+
+
+
+=head1 SETTINGS
+
+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
+fly with the command B<:set option value>.  Examples:
+ :set column_ratios (1,2,3)
+ :set show_hidden=True
+
+=over
+
+=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.
+
+=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.
+
+=item column_ratios [tuple, 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
+with the preview column being as large as the other columns combined.
+
+=item dirname_in_tabs [bool]
+
+Display the directory name in tabs?
+
+=item display_size_in_main_column [bool]
+
+Display the file size in the main column?
+
+=item display_size_in_status_bar [bool]
+
+Display the file size in the status bar?
+
+=item display_tags_in_all_columns [bool]
+
+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 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]
+
+A regular expression pattern for files which should be hidden.
+
+=item max_console_history_size [integer, None]
+
+How many console commands should be kept in history?
+
+=item max_history_size [integer, None]
+
+How many directory changes should be kept in history?
+
+=item mouse_enabled [bool] <zm>
+
+Enable mouse input?
+
+=item padding_right [bool]
+
+When collapse_preview is on and there is no preview, should there remain a
+little padding on the right?  This allows you to click into that space to run
+the file.
+
+=item preview_directories [bool] <zP>
+
+Preview directories in the preview column?
+
+=item preview_files [bool] <zp>
+
+Preview files in the preview column?
+
+=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.
+
+=item save_console_history [bool]
+
+Should the console history be saved on exit?  If disabled, the console history
+is reset when you restart ranger.
+
+=item scroll_offset [integer]
+
+Try to keep this much space between the top/bottom border when scrolling.
+
+=item shorten_title [integer, bool]
+
+Trim the title of the window if it gets long?  The number defines how many
+directories are displayed at once, False turns off this feature.
+
+=item show_cursor [bool]
+
+Always show the terminal cursor?
+
+=item show_hidden_bookmarks [bool]
+
+Show dotfiles in the bookmark preview window? (Type ')
+
+=item show_hidden [bool] <zh>, <^H>
+
+Show hidden files?
+
+=item sort_case_insensitive [bool] <zc>
+
+Sort case-insensitively?  If true, "a" will be listed before "B" even though
+its ASCII value is higher.
+
+=item sort_directories_first [bool] <zd>
+
+Sort directories first?
+
+=item sort_reverse [bool] <or>
+
+Sort reversed?
+
+=item sort [string] <oa>, <ob>, <oc>, <om>, <on>, <ot>, <os>
+
+Which sorting mechanism should be used?  Choose one of B<atime>, B<basename>,
+B<ctime>, B<mtime>, B<natural>, B<type>, B<size>
+
+Note: You can reverse the order by using an uppercase O in the key combination.
+
+=item tilde_in_titlebar [bool]
+
+Abbreviate $HOME with ~ in the title bar (first line) of ranger?
+
+=item unicode_ellipsis [bool]
+
+Use a unicode "..." character instead of "~" to mark cut-off filenames?
+
+=item update_title [bool]
+
+Set a window title?
+
+=item use_preview_script [bool] <zv>
+
+Use the preview script defined in the setting I<preview_script>?
+
+=item xterm_alt_key [bool]
+
+Enable this if key combinations with the Alt Key don't work for you.
+(Especially on xterm)
+
+=back
+
+
+=head1 COMMANDS
+
+You can enter the commands in the console which is opened by pressing ":".
+
+There are additional commands which are directly translated to python
+functions, one for every method in the ranger.core.actions.Actions class.
+They are not documented here, since they are mostly for key bindings, not to be
+typed in by a user.  Read the source if you are interested in them.
+
+=over 2
+
+=item bulkrename
+
+This command opens a list of selected files in an external editor.  After you
+edit and save the file, it will generate a shell script which does bulk
+renaming according to the changes you did in the file.
+
+This shell script is opened in an editor for you to review.  After you close
+it, it will be executed.
+
+=item cd [I<directory>]
+
+The cd command changes the directory.  The command C<:cd -> is equivalent to
+typing ``.
+
+=item chain I<command1>[; I<command2>[; I<command3>...]]
+
+Combines multiple commands into one, separated by columns.
+
+=item chmod I<octal_number>
+
+Sets the permissions of the selection to the octal number.
+
+The octal number is between 000 and 777. The digits specify the permissions for
+the user, the group and others.  A 1 permits execution, a 2 permits writing, a
+4 permits reading.  Add those numbers to combine them. So a 7 permits
+everything.
+
+Key bindings in the form of [-+]<who><what> and =<octal> also exist.  For
+example, B<+ar> allows reading for everyone, -ow forbids others to write and
+=777 allows everything.
+
+See also: man 1 chmod
+
+=item cmap I<key> I<command>
+
+Binds keys for the console. Works like the C<map> command.
+
+=item console [-pI<N>] I<command>
+
+Opens the console with the command already typed in.  The cursor is placed at
+I<N>.
+
+=item copycmap I<key> I<newkey> [I<newkey2> ...]
+
+See C<copymap>
+
+=item copymap I<key> I<newkey> [I<newkey2> ...]
+
+Copies the keybinding I<key> to I<newkey> in the "browser" context.  This is a
+deep copy, so if you change the new binding (or parts of it) later, the old one
+is not modified.
+
+To copy key bindings of the console, taskview, or pager use "copycmap",
+"copytmap" or "copypmap".
+
+=item copypmap I<key> I<newkey> [I<newkey2> ...]
+
+See C<copymap>
+
+=item copytmap I<key> I<newkey> [I<newkey2> ...]
+
+See C<copymap>
+
+=item cunmap I<key> I<command>
+
+Removes key mappings of the console. Works like the C<unmap> command.
+
+=item delete [I<confirmation>]
+
+Destroy all files in the selection with a roundhouse kick.  ranger will ask for
+a confirmation if you attempt to delete multiple (marked) files or non-empty
+directories.
+
+When asking for confirmation, this command will only proceed if the last given
+word starts with a `y'.
+
+=item edit [I<filename>]
+
+Edit the current file or the file in the argument.
+
+=item eval [I<-q>] I<python_code>
+
+Evaluates the python code.  `fm' is a reference to the FM instance.  To display
+text, use the function `p'.  The result is displayed on the screen unless you
+use the "-q" option.
+
+Examples:
+ :eval fm
+ :eval len(fm.env.directories)
+ :eval p("Hello World!")
+
+=item filter [I<string>]
+
+Displays only the files which contain the I<string> in their basename.
+
+=item find I<pattern>
+
+Search files in the current directory that match the given (case-insensitive)
+regular expression pattern as you type.  Once there is an unambiguous result,
+it will be run immediately. (Or entered, if it's a directory.)
+
+=item grep I<pattern>
+
+Looks for a string in all marked files or directories.
+
+=item load_copy_buffer
+
+Load the copy buffer from F<~/.config/ranger/copy_buffer>.  This can be used to
+pass the list of copied files to another ranger instance.
+
+=item map I<key> I<command>
+
+Assign the key combination to the given command.  Whenever you type the
+key/keys, the command will be executed.  Additionally, if you use a quantifier
+when typing the key, like 5j, it will be passed to the command as the attribute
+"self.quantifier".
+
+The keys you bind with this command are accessible in the file browser only,
+not in the console, task view or pager.  To bind keys there, use the commands
+"cmap", "tmap" or "pmap".
+
+=item mark I<pattern>
+
+Mark all files matching the regular expression pattern.
+
+=item mkdir I<dirname>
+
+Creates a directory with the name I<dirname>.
+
+=item open_with [I<application>] [I<flags>] [I<mode>]
+
+Open the selected files with the given application, unless it is omitted, in
+which case the default application is used.  I<flags> are characters out of
+"sdpcwSDPCW" and I<mode> is any positive integer. Their meanings are discussed
+in their own sections.
+
+=item pmap I<key> I<command>
+
+Binds keys for the pager. Works like the C<map> command.
+
+=item punmap I<key> I<command>
+
+Removes key mappings of the pager. Works like the C<unmap> command.
+
+=item quit
+
+Like quit!, but closes only this tab if multiple tabs are open.
+
+=item quit!
+
+Quit ranger.  The current directory will be bookmarked as ' so you can re-enter
+it by typing `` or '' the next time you start ranger.
+
+=item rename I<newname>
+
+Rename the current file.  If a file with that name already exists, the renaming
+will fail.  Also try the key binding A for appending something to a file name.
+
+=item save_copy_buffer
+
+Save the copy buffer from I<~/.config/ranger/copy_buffer>.  This can be used to
+pass the list of copied files to another ranger instance.
+
+=item search I<pattern>
+
+Search files in the current directory that match the given (case insensitive)
+regular expression pattern.
+
+=item search_inc I<pattern>
+
+Search files in the current directory that match the given (case insensitive)
+regular expression pattern.  This command gets you to matching files as you
+type.
+
+=item set I<option>=I<value>
+
+Assigns a new value to an option.  Valid options are listed in the settings
+section.  Use tab completion to get the current value of an option, though this
+doesn't work for functions and regular expressions. Valid values are:
+
+ None           None
+ bool           True or False
+ integer        0 or 1 or -1 or 2 etc.
+ list           [1, 2, 3]
+ tuple          1, 2, 3 or (1, 2, 3)
+ function       lambda <arguments>: <expression>
+ regexp         regexp('<pattern>')
+ string         Anything
+
+=item shell [-I<flags>] I<command>
+
+Run a shell command.  I<flags> are discussed in their own section.
+
+=item terminal
+
+Spawns the I<x-terminal-emulator> starting in the current directory.
+
+=item touch I<filename>
+
+Creates an empty file with the name I<filename>, unless it already exists.
+
+=item tmap I<key> I<command>
+
+Binds keys for the taskview. Works like the C<map> command.
+
+=item tunmap I<key> I<command>
+
+Removes key mappings of the taskview. Works like the C<unmap> command.
+
+=item unmap [I<keys> ...]
+
+Removes the given key mappings in the "browser" context.  To unmap key bindings
+in the console, taskview, or pager use "cunmap", "tunmap" or "punmap".
+
+=item unmark I<pattern>
+
+Unmark all files matching a regular expression pattern.
+
+=back
+
+
+
+
+=head1 FILES
+
+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.
+
+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>).
+
+When starting ranger with the B<--clean> option, it will not access or create
+any of these files.
+
+=head2 CONFIGURATION
+
+=over 10
+
+=item apps.py
+
+Controls which applications are used to open files.
+
+=item commands.py
+
+Defines commands which can be used by typing ":".
+
+=item rc.conf
+
+Contains a list of commands which are executed on startup.  Mostly key bindings
+are defined here.
+
+=item options.py
+
+Sets a handful of basic options.
+
+=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.
+
+=item colorschemes/
+
+Colorschemes can be placed here.
+
+=back
+
+=head2 STORAGE
+
+=over 10
+
+=item bookmarks
+
+This file contains a list of bookmarks.  The syntax is /^(.):(.*)$/. The first
+character is the bookmark key and the rest after the colon is the path to the
+file.  In ranger, bookmarks can be set by typing m<key>, accessed by typing
+'<key> and deleted by typing um<key>.
+
+=item copy_buffer
+
+When running the command :save_copy_buffer, the paths of all currently copied
+files are saved in this file.  You can later run :load_copy_buffer to copy the
+same files again, pass them to another ranger instance or process them in a
+script.
+
+=item history
+
+Contains a list of commands that have been previously typed in.
+
+=item tagged
+
+Contains a list of tagged files. The syntax is /^(.:)?(.*)$/ where the first
+letter is the optional name of the tag and the rest after the optional colon is
+the path to the file.  In ranger, tags can be set by pressing t and removed
+with T.  To assign a named tag, type "<tagname>.
+
+=back
+
+
+
+
+=head1 ENVIRONMENT
+
+These environment variables have an effect on ranger:
+
+=over 8
+
+=item EDITOR
+
+Defines the editor to be used for the "E" key.  Defaults to the first installed
+program out of "vim", "emacs" and "nano".
+
+=item SHELL
+
+Defines the shell that ranger is going to use with the :shell command and
+the "S" key.  Defaults to "bash".
+
+=item XDG_CONFIG_HOME
+
+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
+
+
+
+
+=head1 EXAMPLES
+
+=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()
+   silent !ranger --choosefile=/tmp/chosenfile `[ -z '%' ] && echo -n . || dirname %`
+   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"'
+
+
+
+
+=head1 LICENSE
+
+GNU General Public License 3 or (at your option) any later version.
+
+
+
+
+=head1 LINKS
+
+=over
+
+=item Download: L<http://ranger.nongnu.org/ranger-stable.tar.gz>
+
+=item The project page: L<http://ranger.nongnu.org/>
+
+=item The mailing list: L<http://savannah.nongnu.org/mail/?group=ranger>
+
+=back
+
+ranger is maintained with the git version control system.  To fetch a fresh
+copy, run:
+
+ git clone git://git.savannah.nongnu.org/ranger.git
+
+
+
+
+=head1 BUGS
+
+Report bugs here: L<http://savannah.nongnu.org/bugs/?group=ranger>
+
+Please include as much relevant information as possible.  For the most
+diagnostic output, run ranger like this: C<PYTHONOPTIMIZE= ranger --debug>