updated man page, improved hooks

6 files changed, 183 insertions, 87 deletions

diff --git a/doc/ranger.1 b/doc/ranger.1
index 0e56551d..1bbcd349 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -124,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "RANGER 1"
-.TH RANGER 1 "ranger-1.5.5" "12/02/2012" "ranger manual"
+.TH RANGER 1 "ranger-1.5.5" "12/03/2012" "ranger manual"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -185,7 +185,7 @@ Open ranger with \fItargetfile\fR selected.
 .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: \fIall\fR,
-\&\fIrc\fR, \fIapps\fR, \fIcommands\fR, \fIoptions\fR, \fIscope\fR.
+\&\fIrc\fR, \fIcommands\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.
@@ -220,6 +220,8 @@ Print the version and exit.
 Print a list of options and exit.
 .SH "CONCEPTS"
 .IX Header "CONCEPTS"
+This part explains how certain parts of ranger work and how they can be used
+efficiently.
 .SS "\s-1TAGS\s0"
 .IX Subsection "TAGS"
 Tags are single characters which are displayed left of a filename.  You can use
@@ -272,7 +274,7 @@ are in different directories:
 .Ve
 .PP
 Macros for file paths are generally shell-escaped so they can be used in the
-:shell command.
+\&\f(CW\*(C`shell\*(C'\fR command.
 .SS "\s-1BOOKMARKS\s0"
 .IX Subsection "BOOKMARKS"
 Type \fBm<key>\fR to bookmark the current directory. You can re-enter this
@@ -285,40 +287,78 @@ to the last directory. So typing \*(L"``\*(R" gets you back to where you were be
 Bookmarks are selectable when tabbing in the :cd command.
 .PP
 Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same.
+.SS "\s-1RIFLE\s0"
+.IX Subsection "RIFLE"
+Rifle is the file opener of ranger.  It can be used as a standalone program or
+a python module.  It is located at \fIranger/ext/rifle.py\fR.  In contrast to
+other, more simple file openers, rifle can automatically find installed
+programs so it can be used effectively out of the box on a variety of systems.
+.PP
+It's configured in \fIrifle.conf\fR through a list of conditions and commands.
+For each line the conditions are checked and if they are met, the respective
+command is taken into consideration.  By default, simply the first matching
+rule is used.  In ranger, you can list and choose rules by typing \*(L"r\*(R" or simply
+by typing \*(L"<rulenumber><enter>\*(R".  If you use rifle standalone, you can list all
+rules with the \*(L"\-l\*(R" option and pick a rule with \*(L"\-p <number>\*(R".
+.PP
+The rules, along with further documentation, are contained in
+\&\fIranger/config/rifle.conf\fR.
 .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").
+used in the commands \f(CW\*(C`:open_with\*(C'\fR (key \*(L"r\*(R") and \f(CW\*(C`:shell\*(C'\fR (key \*(L"!\*(R").
 .PP
-.Vb 7
-\& 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
+.Vb 4
+\& f   Fork the process.  (Run in background)
 \& c   Run the current file only, instead of the selection
 \& r   Run application with root privilege (requires sudo)
 \& t   Run application in a new terminal window
 .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
-The \*(L"t\*(R" flag looks for the environment variable \s-1TERMCMD\s0, and uses it as the
-terminal command, if it's not set it'll use xterm.
-.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.
+There are some additional flags that can currently be used only in the \f(CW\*(C`shell\*(C'\fR
+command: (for example \f(CW\*(C`:shell \-w df\*(C'\fR)
+.PP
+.Vb 3
+\& p   Redirect output to the pager
+\& s   Silent mode.  Output will be discarded.
+\& w   Wait for an Enter\-press when the process is done
+.Ve
+.PP
+By default, all the flags are off unless specified otherwise in the
+\&\fIrifle.conf\fR configuration file.  You can specify as many flags as you want.
+An uppercase flag negates the effect: \*(L"ffcccFsf\*(R" is equivalent to \*(L"cs\*(R".
+.PP
+The terminal program name for the \*(L"t\*(R" flag is taken from the environment
+variable \f(CW$TERMCMD\fR.  If it doesn't exist, it tries to extract it from \f(CW$TERM\fR and
+uses \*(L"xterm\*(R" as a fallback if that fails.
+.PP
+Examples: \f(CW\*(C`:open_with c\*(C'\fR will open the file that you currently point at, even
+if you have selected other files.  \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-1PLUGINS\s0"
+.IX Subsection "PLUGINS"
+ranger's plugin system consists of python files which are located in
+\&\fI~/.config/ranger/plugins/\fR and are imported in alphabetical order when
+starting ranger.  A plugin changes rangers behavior by overwriting or extending
+a function that ranger uses.  This allows you to change pretty much every part
+of ranger, but there is no guarantee that things will continue to work in
+future versions as the source code evolves.
+.PP
+There are some hooks that are specifically made for the use in plugins.  They
+are functions that start with hook_ and can be found throughout the code.
+.PP
+.Vb 1
+\& grep \*(Aqdef hook_\*(Aq \-r /path/to/rangers/source
+.Ve
+.PP
+Also try:
+.PP
+.Vb 1
+\& pydoc ranger.api
+.Ve
+.PP
+The \fIexamples\fR directory contains several sample plugins, including a well
+documented hello-world plugin using hooks in a compatibility-friendly way.
 .SH "KEY BINDINGS"
 .IX Header "KEY BINDINGS"
 Key bindings are defined in the file \fIranger/config/rc.conf\fR.  Check this
@@ -472,8 +512,8 @@ directory, by clicking on the preview.
 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.
+Scrolls up or down.  You can point at the column of the parent directory while
+scrolling to switch directories.
 .SH "SETTINGS"
 .IX Header "SETTINGS"
 This section lists all built-in settings of ranger.  The valid types for the
@@ -897,24 +937,23 @@ When starting ranger with the \fB\-\-clean\fR option, it will not access or crea
 any of these files.
 .SS "\s-1CONFIGURATION\s0"
 .IX Subsection "CONFIGURATION"
-.IP "commands.py" 10
-.IX Item "commands.py"
-A python module that defines commands which can be used in ranger's console by
-typing \*(L":\*(R".
 .IP "rc.conf" 10
 .IX Item "rc.conf"
 Contains a list of commands which are executed on startup.  Mostly key bindings
 and settings are defined here.
+.IP "commands.py" 10
+.IX Item "commands.py"
+A python module that defines commands which can be used in ranger's console by
+typing \*(L":\*(R" or in the rc.conf file.
 .IP "rifle.conf" 10
 .IX Item "rifle.conf"
 This is the configuration file for the built-in file launcher called \*(L"rifle\*(R".
 .IP "scope.sh" 10
 .IX Item "scope.sh"
 This is a script that handles file previews.  When the options
-\&\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.
+\&\fIuse_preview_script\fR and \fIpreview_files\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.
@@ -949,7 +988,7 @@ with T.  To assign a named tag, type "<tagname>.
 These environment variables have an effect on ranger:
 .IP "\s-1RANGER_LEVEL\s0" 8
 .IX Item "RANGER_LEVEL"
-Ranger sets this environment variable to \*(L"1\*(R" or increments it if it already
+ranger sets this environment variable to \*(L"1\*(R" or increments it if it already
 exists.  External programs can determine whether they were spawned from ranger
 by checking for this variable.
 .IP "\s-1EDITOR\s0" 8
diff --git a/doc/ranger.pod b/doc/ranger.pod
index 6903c030..219d2f0b 100644
--- a/doc/ranger.pod
+++ b/doc/ranger.pod
@@ -75,7 +75,7 @@ Open ranger with I<targetfile> selected.
 
 Create copies of the default configuration files in your local configuration
 directory.  Existing ones will not be overwritten.  Possible values: I<all>,
-I<rc>, I<apps>, I<commands>, I<options>, I<scope>.
+I<rc>, I<commands>, I<scope>.
 
 =item B<--list-unused-keys>
 
@@ -124,6 +124,9 @@ Print a list of options and exit.
 
 =head1 CONCEPTS
 
+This part explains how certain parts of ranger work and how they can be used
+efficiently.
+
 =head2 TAGS
 
 Tags are single characters which are displayed left of a filename.  You can use
@@ -175,7 +178,7 @@ are in different directories:
  @diff %c %f
 
 Macros for file paths are generally shell-escaped so they can be used in the
-:shell command.
+C<shell> command.
 
 =head2 BOOKMARKS
 
@@ -190,39 +193,72 @@ Bookmarks are selectable when tabbing in the :cd command.
 
 Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same.
 
+=head2 RIFLE
+
+Rifle is the file opener of ranger.  It can be used as a standalone program or
+a python module.  It is located at F<ranger/ext/rifle.py>.  In contrast to
+other, more simple file openers, rifle can automatically find installed
+programs so it can be used effectively out of the box on a variety of systems.
+
+It's configured in F<rifle.conf> through a list of conditions and commands.
+For each line the conditions are checked and if they are met, the respective
+command is taken into consideration.  By default, simply the first matching
+rule is used.  In ranger, you can list and choose rules by typing "r" or simply
+by typing "<rulenumber><enter>".  If you use rifle standalone, you can list all
+rules with the "-l" option and pick a rule with "-p <number>".
+
+The rules, along with further documentation, are contained in
+F<ranger/config/rifle.conf>.
+
 =head2 FLAGS
 
 Flags give you a way to modify the behavior of the spawned process.  They are
-used in the commands :open_with (key "r") and :shell (key "!").
+used in the commands C<:open_with> (key "r") and C<:shell> (key "!").
 
- s   Silent mode.  Output will be discarded.
- d   Detach the process.  (Run in background)
- p   Redirect output to the pager
- w   Wait for an Enter-press when the process is done
+ f   Fork the process.  (Run in background)
  c   Run the current file only, instead of the selection
  r   Run application with root privilege (requires sudo)
  t   Run application in a new terminal window
 
-By default, all the flags are off unless specified otherwise in the F<apps.py>
-configuration file.  You can specify as many flags as you want.  An uppercase
-flag negates the effect: "ddcccDs" is equivalent to "cs".
+There are some additional flags that can currently be used only in the C<shell>
+command: (for example C<:shell -w df>)
+
+ p   Redirect output to the pager
+ s   Silent mode.  Output will be discarded.
+ w   Wait for an Enter-press when the process is done
+
+By default, all the flags are off unless specified otherwise in the
+F<rifle.conf> configuration file.  You can specify as many flags as you want.
+An uppercase flag negates the effect: "ffcccFsf" is equivalent to "cs".
 
-The "t" flag looks for the environment variable TERMCMD, and uses it as the
-terminal command, if it's not set it'll use xterm.
+The terminal program name for the "t" flag is taken from the environment
+variable $TERMCMD.  If it doesn't exist, it tries to extract it from $TERM and
+uses "xterm" as a fallback if that fails.
 
-Examples: C<:open_with p> will pipe the output of that process into
-the pager.  C<:shell -w df> will run "df" and wait for you to press Enter before
-switching back to ranger.
+Examples: C<:open_with c> will open the file that you currently point at, even
+if you have selected other files.  C<:shell -w df> will run "df" and wait for
+you to press Enter before switching back to ranger.
 
-=head2 MODES
+=head2 PLUGINS
 
-By specifying a mode (a positive integer), you can tell ranger what to do with
-a file when running it. You can specify which mode to use by typing <mode>l or
-<mode><Enter> or :open_with <mode>.  The default mode is 0.
+ranger's plugin system consists of python files which are located in
+F<~/.config/ranger/plugins/> and are imported in alphabetical order when
+starting ranger.  A plugin changes rangers behavior by overwriting or extending
+a function that ranger uses.  This allows you to change pretty much every part
+of ranger, but there is no guarantee that things will continue to work in
+future versions as the source code evolves.
 
-Examples: C<l> (mode zero) to list the contents of an archive, C<1l> (mode one)
-to extract an archive.  See the F<apps.py> configuration file for all programs
-and modes.
+There are some hooks that are specifically made for the use in plugins.  They
+are functions that start with hook_ and can be found throughout the code.
+
+ grep 'def hook_' -r /path/to/rangers/source
+
+Also try:
+
+ pydoc ranger.api
+
+The F<examples> directory contains several sample plugins, including a well
+documented hello-world plugin using hooks in a compatibility-friendly way.
 
 
 
@@ -443,8 +479,8 @@ Enter a directory or run a file.
 
 =item Scroll Wheel
 
-Scrolls up or down.  You can point at the column of the parent directory to
-switch directories.
+Scrolls up or down.  You can point at the column of the parent directory while
+scrolling to switch directories.
 
 =back
 
@@ -956,16 +992,16 @@ any of these files.
 
 =over 10
 
-=item commands.py
-
-A python module that defines commands which can be used in ranger's console by
-typing ":".
-
 =item rc.conf
 
 Contains a list of commands which are executed on startup.  Mostly key bindings
 and settings are defined here.
 
+=item commands.py
+
+A python module that defines commands which can be used in ranger's console by
+typing ":" or in the rc.conf file.
+
 =item rifle.conf
 
 This is the configuration file for the built-in file launcher called "rifle".
@@ -973,10 +1009,9 @@ This is the configuration file for the built-in file launcher called "rifle".
 =item scope.sh
 
 This is a script that handles file previews.  When the options
-I<use_preview_script> and I<preview_files> or, respectively,
-I<preview_directories> are set, the program specified in the option
-I<preview_script> is run and its output and/or exit code determines rangers
-reaction.
+I<use_preview_script> and I<preview_files> are set, the program specified in
+the option I<preview_script> is run and its output and/or exit code determines
+rangers reaction.
 
 =item colorschemes/
 
@@ -1030,7 +1065,7 @@ These environment variables have an effect on ranger:
 
 =item RANGER_LEVEL
 
-Ranger sets this environment variable to "1" or increments it if it already
+ranger sets this environment variable to "1" or increments it if it already
 exists.  External programs can determine whether they were spawned from ranger
 by checking for this variable.
 
diff --git a/examples/plugin_chmod_keybindings.py b/examples/plugin_chmod_keybindings.py
index c04cc492..62ca6c58 100644
--- a/examples/plugin_chmod_keybindings.py
+++ b/examples/plugin_chmod_keybindings.py
@@ -2,11 +2,11 @@
 # It could replace the ten lines in the rc.conf that create the key bindings
 # for the "chmod" command.
 
-import ranger.core.fm
-old_init_hook = ranger.core.fm.init_hook
+import ranger.api
+old_hook_init = ranger.api.hook_init
 
-def init_hook(fm):
-	old_init_hook(fm)
+def hook_init(fm):
+	old_hook_init(fm)
 
 	# Generate key bindings for the chmod command
 	command = "map {0}{1}{2} shell -d chmod {1}{0}{2} %s"
@@ -15,4 +15,4 @@ def init_hook(fm):
 			fm.execute_console(command.format('-', mode, perm))
 			fm.execute_console(command.format('+', mode, perm))
 
-ranger.core.fm.init_hook = init_hook
+ranger.api.hook_init = hook_init
diff --git a/ranger/api/__init__.py b/ranger/api/__init__.py
index cc64a7c0..1121197a 100644
--- a/ranger/api/__init__.py
+++ b/ranger/api/__init__.py
@@ -1,4 +1,28 @@
 """
-Files in this module contain helper functions used in
-configuration files.
+Files in this module contain helper functions used in configuration files.
 """
+
+# Hooks for use in plugins:
+
+def hook_init(fm):
+	"""
+	Parameters:
+	  fm = the file manager instance
+	Return Value:
+	  ignored
+
+	This hook is executed after fm is initialized but before fm.ui is
+	initialized.  You can safely print to stdout and have access to fm to add
+	keybindings and such.
+	"""
+
+def hook_ready(fm):
+	"""
+	Parameters:
+	  fm = the file manager instance
+	Return Value:
+	  ignored
+
+	This hook is executed after the user interface is initialized.  You should
+	NOT print anything to stdout anymore from here on.  Use fm.notify instead.
+	"""
diff --git a/ranger/core/fm.py b/ranger/core/fm.py
index b32e5730..3c100532 100644
--- a/ranger/core/fm.py
+++ b/ranger/core/fm.py
@@ -14,7 +14,7 @@ import socket
 import stat
 import sys
 
-import ranger
+import ranger.api
 from ranger.core.actions import Actions
 from ranger.core.tab import Tab
 from ranger.container.tags import Tags
@@ -28,9 +28,6 @@ from ranger.ext.signals import SignalDispatcher
 from ranger import __version__
 from ranger.core.loader import Loader
 
-def init_hook():
-	pass
-
 class FM(Actions, SignalDispatcher):
 	input_blocked = False
 	input_blocked_until = 0
@@ -126,8 +123,6 @@ class FM(Actions, SignalDispatcher):
 			self.notify(text, bad=True)
 		self.run = Runner(ui=self.ui, logfunc=mylogfunc, fm=self)
 
-		init_hook()
-
 	def destroy(self):
 		debug = ranger.arg.debug
 		if self.ui:
@@ -250,6 +245,8 @@ class FM(Actions, SignalDispatcher):
 		has_throbber = hasattr(ui, 'throbber')
 		zombies = self.run.zombies
 
+		ranger.api.hook_ready(self)
+
 		try:
 			while True:
 				loader.work()
diff --git a/ranger/core/main.py b/ranger/core/main.py
index df2a922e..dd07bff8 100644
--- a/ranger/core/main.py
+++ b/ranger/core/main.py
@@ -13,7 +13,7 @@ load_default_config = True
 def main():
 	"""initialize objects and run the filemanager"""
 	import locale
-	import ranger
+	import ranger.api
 	from ranger.core.shared import FileManagerAware, SettingsAware
 	from ranger.core.fm import FM
 
@@ -115,6 +115,7 @@ def main():
 
 		# Run the file manager
 		fm.initialize()
+		ranger.api.hook_init(fm)
 		fm.ui.initialize()
 
 		if arg.cmd: