data/config_examples: added documentation

2 files changed, 82 insertions, 7 deletions

diff --git a/ranger/data/config_examples/apps.py b/ranger/data/config_examples/apps.py
index c9221dbf..36415e77 100644
--- a/ranger/data/config_examples/apps.py
+++ b/ranger/data/config_examples/apps.py
@@ -2,18 +2,66 @@
 # This is the configuration file for filetype detection and application
 # handling.  It's all in python; lines beginning with # are comments.
 #
-# Here, the class "CustomApplications" is defined as a subclass of the default
-# application handler class.  It is located at ranger/defaults/apps.py and
-# contains a whole lot of definitions.  You can just copy & paste them here.
+# Scroll down for a few examples.
+# ===================================================================
+# This system is based on things called MODES and FLAGS.  You can read
+# in the man page about them.  To remind you, here's a list of all flags.
+# An uppercase flag inverts previous flags of the same name.
+#     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
+#
+# To implement modes in this file, you can do something like:
+#     if context.mode == 1:
+#         <run in one way>
+#     elif context.mode == 2:
+#         <run in another way>
+#
+# To implement flags in this file, you could do this:
+#     context.flags += "d"
+# Another example:
+#     context.flags += "Dw"
+# ===================================================================
+# The methods are called with a "context" object which provides some
+# attributes that transfer information.  Relevant attributes are:
+#
+# mode -- a number, mainly used in determining the action in app_xyz()
+# flags -- a string with flags which change the way programs are run
+# files -- a list containing files, mainly used in app_xyz
+# filepaths -- a list of the paths of each file
+# file -- an arbitrary file from that list (or None)
+# fm -- the filemanager instance
+# popen_kws -- keyword arguments which are directly passed to Popen
+# ===================================================================
+# The return value of the functions should be either:
+# 1. A reference to another app, like:
+#     return self.app_editor(context)
+#
+# 2. A call to the "either" method, which uses the first program that
+# is installed on your system.  If none are installed, None is returned.
+#     return self.either(context, "libreoffice", "soffice", "ooffice")
+#
+# 3. A tuple of arguments that should be run.
+#     return "mplayer", "-fs", context.file.path
+# Since the tuple is flattened later, you can even put lists of files here:
+#     return "mplayer", "-fs", "-shuf", context.filepaths
+# This can, and will often be abbreviated with:
+#     return "mplayer", "-fs", "-shuf", context
 # ===================================================================
 
 # Import the basics
 from ranger.defaults.apps import CustomApplications as DefaultApps
 from ranger.api.apps import *
 
-# By default, we do nothing.
+#
+# Here, the class "CustomApplications" is defined as a subclass of the default
+# application handler class.  It is located at ranger/defaults/apps.py and
+# contains a whole lot of definitions.  The reason why we don't put them here
+# is that when you update, this file doesn't change.
 class CustomApplications(DefaultApps):
-	pass
+	pass  # By default, we do nothing.
 
 #	def app_kaffeine(self, context):
 #		return 'kaffeine', context
@@ -21,6 +69,8 @@ class CustomApplications(DefaultApps):
 #	def app_feh_fullscreen_by_default(self, context):
 #		return 'feh', '-F', context
 #
+#	# app_default is the function that is always called to determine which
+#	# application to run, unless you specify one manually with :open_with
 #	def app_default(self, context):
 #		f = context.file #shortcut
 #		if f.video or f.audio:
@@ -30,3 +80,21 @@ class CustomApplications(DefaultApps):
 #			return self.app_feh_fullscreen_by_default(context)
 #
 #		return DefaultApps.app_default(self, context)
+#
+#	# You could write this to use an entirely different program to open files:
+#	def app_default(self, context):
+#		return "mimeopen", context
+
+
+## Often a programs invocation is trivial.  For example:
+##    vim test.py readme.txt [...]
+## This could be implemented like:
+##    @depends_on("vim")
+##    def app_vim(self, context):
+##        return "vim", context
+## Instead of creating such a generic function for each program, just add
+## its name here and it will be automatically done for you.
+#CustomApplications.generic('zsnes', 'javac')
+
+## By setting flags='d', this programs will not block ranger's terminal:
+#CustomApplications.generic('gimp', 'evince', 'flags='d')
diff --git a/ranger/data/config_examples/rc.conf b/ranger/data/config_examples/rc.conf
index 3d16c964..87ede612 100644
--- a/ranger/data/config_examples/rc.conf
+++ b/ranger/data/config_examples/rc.conf
@@ -8,10 +8,17 @@
 # Each line is a command that will be run before the user interface
 # is initialized.  As a result, you can not use commands which rely on
 # the UI such as "delete" or "mark".  Lines starting with # are comments.
-# Refer to the man page or press 2? in ranger for a list of commands.
+#
+# Note: Press 1? in ranger for a list of key bindings and 2? for a list
+# of commands.
 # ===================================================================
+# The "map" command maps a key sequence to a command. "map gt cd /tmp"
+# maps the keys "gt" to the command "cd /tmp".  "copymap" copies a key
+# binding to another key sequence and "unmap" deletes the given key binding.
+#
+# Here are some examples:
 
-# common directories (this overrides some default keybindings)
+# go to common directories (this overrides some default keybindings)
 #map gt cd /tmp
 #map gc cd ~/.config
 #map gp cd /usr/portage