Overhauled manpage. It's in POD format now.

3 files changed, 802 insertions, 195 deletions

diff --git a/Makefile b/Makefile
index fd525721..1c0b5fda 100644
--- a/Makefile
+++ b/Makefile
@@ -63,6 +63,10 @@ doc: cleandoc
 		pydoc.writedocs("$(CWD)")'
 	find . -name \*.html -exec sed -i 's|'$(CWD)'|../..|g' -- {} \;
 
+man:
+	pod2man --stderr --center='ranger manual' --date='$(NAME)-$(VERSION)' \
+		--release=$(shell date +%x) doc/ranger.pod doc/ranger.1
+
 cleandoc:
 	test -d $(DOCDIR) && rm -f -- $(DOCDIR)/*.html || true
 
@@ -75,4 +79,4 @@ bm:
 snapshot:
 	git archive --prefix='$(NAME)-$(VERSION)/' --format=tar HEAD | gzip > $(SNAPSHOT_NAME)
 
-.PHONY: default options compile clean doc cleandoc test bm snapshot install
+.PHONY: default options compile clean doc cleandoc test bm snapshot install man
diff --git a/doc/ranger.1 b/doc/ranger.1
index 5b9d9df8..4d6dab24 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -1,226 +1,415 @@
-.TH RANGER 1 ranger-1.4.3
-.SH NAME
-ranger - visual file manager
-.\"-----------------------------------------
-.SH SYNOPSIS
-.B ranger
-.R [OPTIONS] [FILE]
-.\"-----------------------------------------
-.SH DESCRIPTION
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
+.\"
+.\" 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.4.3" "09/24/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 [\fIoptions\fR] [\fIpath/filename\fR]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
 Ranger is a file manager with an ncurses frontend written in Python.
-.P
+.PP
 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
+\&\fBvim\fR, \fBmutt\fR or \fBncmpcpp\fR so the usage will be intuitive and efficient.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-\-verison\fR" 14
+.IX Item "--verison"
+print the version and exit
+.IP "\fB\-h\fR, \fB\-\-help\fR" 14
+.IX Item "-h, --help"
+print a list of options and exit
+.IP "\fB\-d\fR, \fB\-\-debug\fR" 14
+.IX Item "-d, --debug"
+activate the debug mode: Whenever an erroroccurs, 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 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.
-.TP
---copy-config=\fIwhich\fR
+.IP "\fB\-\-choosefile\fR=\fItargetfile\fR" 14
+.IX Item "--choosefile=targetfile"
+Allows you to pick a file with ranger.  This changes the behaviour so that when you open a file, ranger will exit and write the name of that file into \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.
+.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
+\&\fIall\fR, \fIapps\fR, \fIcommands\fR, \fIkeys\fR, \fIoptions\fR, \fIscope\fR.
+.IP "\fB\-\-fail\-unless\-c\fRd" 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 filetype 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 behaviour.
+the execution of this filetype is explicitly handled in the configuration.
+.SH "KEY BINDINGS"
+.IX Header "KEY 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
+.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 \fBpo\fR.
-.TP
-m\fIX\fR
+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
+.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" 14
+.IX Item "V"
+Unmark all files
+.IP "^V\fIdirection\fR" 14
+.IX Item "^Vdirection"
+Mark all files in the given direction.  Works just like d\fIdirection\fR.
+.IP "g\fIN\fR" 14
+.IX Item "gN"
 Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet,
 it will be created.
-.TP
-gn, ^N
+.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
+.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.
+.IP "/" 14
+Search for files in the current directory.
+.IP ":" 14
+Open the console.
+.IP "?" 14
+Opens the help screen with more keybindings and documentation
+.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, "enter" it, like a directory, by clicking on the preview.
-.TP
-Right Mouse Button
-Enter a directory
-.TP
-Scroll Wheel
+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"
 Scroll
-.\"-----------------------------------------
-.SS Commands
-.TP
-:delete
+.SH "COMMANDS"
+.IX Header "COMMANDS"
+.IP ":delete" 4
+.IX Item ":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
+.IP ":rename \fInewname\fR" 4
+.IX Item ":rename newname"
 Rename the current file.  Also try the keybinding A for appending something
 to a file name.
-.TP
-:quit
+.IP ":quit" 4
+.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.
-.\"-----------------------------------------
-.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://savannah.nongnu.org/projects/ranger >
-.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 >
+.SH "FILES"
+.IX Header "FILES"
+ranger reads several configuration files which are located in
+\&\f(CW$HOME\fR/.config/ranger or \f(CW$XDG_CONFIG_HOME\fR/ranger if \f(CW$XDG_CONFIG_HOME\fR is defined.
+The configuration is done mostly in python.  (Note that python files get
+compiled and the compiled files are stored in your configuration directory too.
+Since python3 they are saved in the _\|_pycache_\|_ directory, earlier versions
+store them with the .pyc extension in the same directory.)  When removing a
+config file, remove the compiled file too.
+.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
+overlayed on top of the defaults (options.py, command.py, keys.py) or can be
+subclassed (apps.py, colorschemes).
+.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 "keys.py" 10
+.IX Item "keys.py"
+Defines keybindings.
+.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 "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.
+.IP "history" 10
+.IX Item "history"
+Contains a list of commands that have been previously typed in.
+.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 \*(L"$HOME/.config\*(R".
+.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 (to put in your ~/.bashrc) 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=/tmp/chosendir
+\&   /usr/bin/ranger \-\-choosedir=$tempfile "$@"
+\&   if [ \-f $tempfile \-a "$(cat $tempfile)" != "$(pwd | tr \-d "\en")" ]
+\&   then
+\&     cd "$(cat $tempfile)"
+\&     rm $tempfile
+\&   fi
+\& }
+.Ve
+.SH "LICSENSE"
+.IX Header "LICSENSE"
+\&\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>" 4
+.IX Item "Download: <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
+.SH "BUGS"
+.IX Header "BUGS"
+Please report them here and include as much relevant information as possible: 
+<http://savannah.nongnu.org/bugs/?group=ranger>
diff --git a/doc/ranger.pod b/doc/ranger.pod
new file mode 100644
index 00000000..db3210b2
--- /dev/null
+++ b/doc/ranger.pod
@@ -0,0 +1,414 @@
+=head1 NAME
+
+ranger - visual file manager
+
+
+
+
+=head1 SYNOPSIS
+
+B<ranger> [I<options>] [I<path/filename>]
+
+
+
+
+=head1 DESCRIPTION
+
+Ranger is a file manager with an ncurses frontend written in Python.
+
+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
+B<vim>, B<mutt> or B<ncmpcpp> so the usage will be intuitive and efficient.
+
+
+
+
+=head1 OPTIONS
+
+=over 14
+
+=item B<--verison>
+
+print the version and exit
+
+=item B<-h>, B<--help>
+
+print a list of options and exit
+
+=item B<-d>, B<--debug>
+
+activate the debug mode: Whenever an erroroccurs, 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 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 behaviour 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<apps>, I<commands>, I<keys>, I<options>, I<scope>.
+
+=item B<--fail-unless-c>d
+
+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 filetype 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 behaviour.
+the execution of this filetype is explicitly handled in the configuration.
+
+=back
+
+
+
+
+=head1 KEY 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 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
+
+Unmark all files
+
+=item ^VI<direction>
+
+Mark all files in the given direction.  Works just like dI<direction>.
+
+=item gI<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.
+
+=item /
+
+Search for files in the current directory.
+
+=item :
+
+Open the console.
+
+=item ?
+
+Opens the help screen with more keybindings and documentation
+
+=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
+
+Scroll
+
+=back
+
+
+
+
+=head1 COMMANDS
+
+=over
+
+=item :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.
+
+=item :rename I<newname>
+
+Rename the current file.  Also try the keybinding A for appending something
+to a file name.
+
+=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.
+
+=back
+
+
+
+
+=head1 FILES
+
+ranger reads several configuration files which are located in
+$HOME/.config/ranger or $XDG_CONFIG_HOME/ranger if $XDG_CONFIG_HOME is defined.
+The configuration is done mostly in python.  (Note that python files get
+compiled and the compiled files are stored in your configuration directory too.
+Since python3 they are saved in the __pycache__ directory, earlier versions
+store them with the .pyc extension in the same directory.)  When removing a
+config file, remove the compiled file too.
+
+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
+overlayed on top of the defaults (options.py, command.py, keys.py) or can be
+subclassed (apps.py, colorschemes).
+
+=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 keys.py
+
+Defines keybindings.
+
+=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 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.
+
+=item history
+
+Contains a list of commands that have been previously typed in.
+
+=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 "$HOME/.config".
+
+=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 (to put in your ~/.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 "$@"
+   if [ -f $tempfile -a "$(cat $tempfile)" != "$(pwd | tr -d "\n")" ]
+   then
+     cd "$(cat $tempfile)"
+     rm $tempfile
+   fi
+ }
+
+
+
+
+=head1 LICSENSE
+
+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
+
+
+
+
+=head1 BUGS
+
+Please report them here and include as much relevant information as possible: 
+L<http://savannah.nongnu.org/bugs/?group=ranger>