help: added documentation for running files

3 files changed, 110 insertions, 2 deletions

diff --git a/ranger/help/__init__.py b/ranger/help/__init__.py
index 6c594111..b02fbd7d 100644
--- a/ranger/help/__init__.py
+++ b/ranger/help/__init__.py
@@ -23,7 +23,7 @@ NO_HELP = """No help was found.
 Possibly the program was invoked with "python -OO" which
 discards all documentation."""
 
-HELP_TOPICS = ('index', 'movement')
+HELP_TOPICS = ('index', 'movement', 'starting')
 
 def get_docstring_of_module(path, module_name):
 	imported = __import__(path, fromlist=[module_name])
diff --git a/ranger/help/index.py b/ranger/help/index.py
index 003c4621..7dc82e7d 100644
--- a/ranger/help/index.py
+++ b/ranger/help/index.py
@@ -22,7 +22,7 @@
 
 	|0?|	This index
 	|1?|	Basic movement and browsing
-		Running Files
+	|2?|	Running Files
 		The console
 		File operations
 
diff --git a/ranger/help/starting.py b/ranger/help/starting.py
new file mode 100644
index 00000000..f4d5cb93
--- /dev/null
+++ b/ranger/help/starting.py
@@ -0,0 +1,108 @@
+# Copyright (c) 2009, 2010 hut <hut@lavabit.com>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+"""
+2. Running Files
+
+2.1. How to run files
+2.2. The "open with" prompt
+2.2. Programs
+2.4. Modes
+2.5. Flags
+
+
+==============================================================================
+2.1. How to run files
+
+While highlighting a file, press the "l" key to fire up the automatic
+filetype detection mechanism and attempt to start the file.
+
+	l	run the selection
+	<Enter>	run the selection with "mode 1" (see 2.2.)
+	r	open the "open with" prompt
+
+Note: The selection means, if there are marked files in this directory,
+use them.  Otherwise use the file under the cursor.
+
+
+==============================================================================
+2.2. open with:
+
+If the automatic filetype detection fails or starts the file in a wrong
+way, you can press "r" to manually tell ranger how to run it.
+
+Syntax: open with: <program> <flags> <mode>
+
+Examples:
+Open this file with vim:
+	open with: vim
+Run this file like with "./file":
+	open with: self
+Open this file with mplayer with the "detached" flag:
+	open with: mplayer d
+
+The parameters <program>, <flags> and <mode> are explained in the
+following paragraphs
+
+Note: The "open with" console is named QuickOpenConsole in the source code.
+
+
+==============================================================================
+2.3. Programs
+
+Programs have to be defined in ranger/defaults/apps.py.  Each function
+in the class CustomApplications which starts with "app_" can be used
+as a program in the "open with" prompt.
+
+You're encouraged to add your own program definitions to the list.  Refer to
+documentation in ranger/applications.py for more information on this subject.
+
+
+==============================================================================
+2.4. Modes
+
+Sometimes there are multiple variants to open a file.  For example, ranger
+gives you 2 ways of opening a video (by default):
+
+	0	fullscreen
+	1	windowed
+
+By specifying a mode, you can select one of those.  The "l" key will
+start a file in mode 0, <Enter> or ^J will start it in mode 1.
+You can specify a mode in the "open with" console by simply adding
+the number.  Eg: "open with: mplayer 1" or "open with: 1"
+
+For a list of all programs and modes, see ranger/defaults/apps.py
+
+
+==============================================================================
+2.5. Flags
+
+Flags give you a way to modify the behaviour of the spawned process.
+
+	s	Silent mode.  Output will be discarded.
+	d	Detach the process.
+	p	Redirect output to the pager
+
+For example, "open with: p" will pipe the output of that process into
+the pager.
+
+Note: Some combinations don't make sense, eg: "vim d" would open the file in
+vim and detach it.  Since vim is a console application, you loose grip
+of that process when you detach it.  It's up to you to do such sanity checks.
+
+
+==============================================================================
+"""
+# vim:tw=78:sw=4:sts=8:ts=8:ft=help