Added documentation (mainly ranger/help/console.py)

5 files changed, 256 insertions, 12 deletions

diff --git a/ranger/gui/widgets/console.py b/ranger/gui/widgets/console.py
index 2d542182..a496f6a9 100644
--- a/ranger/gui/widgets/console.py
+++ b/ranger/gui/widgets/console.py
@@ -362,7 +362,7 @@ class SearchConsole(Console):
 
 class OpenConsole(ConsoleWithTab):
 	"""
-	The OpenConsole allows you to execute shell commands:
+	The Open Console allows you to execute shell commands:
 	!vim *         will run vim and open all files in the directory.
 
 	%f will be replaced with the basename of the highlighted file
@@ -372,14 +372,14 @@ class OpenConsole(ConsoleWithTab):
 
 	!d! mplayer    will run mplayer with flags (d means detached)
 	!@ mplayer     will open the selected files with mplayer
-	               (equivalent to !mplayer %s)
+			   (equivalent to !mplayer %s)
 
-	those two can be combinated:
+	Those two can be combinated:
 
 	!d!@mplayer    will open the selection with a detached mplayer
+				   (again, this is equivalent to !d!mplayer %s)
 
-	For a list of other flags than "d", look at the documentation
-	of ranger.applications.
+	For a list of other flags than "d", check chapter 2.5 of the documentation
 	"""
 	prompt = '!'
 
@@ -444,10 +444,29 @@ class OpenConsole(ConsoleWithTab):
 
 class QuickOpenConsole(ConsoleWithTab):
 	"""
-	The QuickOpenConsole allows you to open files with
-	pre-defined programs and modes very quickly. By adding flags
-	to the command, you can specify precisely how the program is run,
-	ie. the d-flag will run it detached from the filemanager.
+	The Quick Open Console allows you to open files with predefined programs
+	and modes very quickly.  By adding flags to the command, you can specify
+	precisely how the program is run, e.g. the d-flag will run it detached
+	from the file manager.
+
+	For a list of other flags than "d", check chapter 2.5 of the documentation
+
+	The syntax is "open with: <application> <mode> <flags>".
+	The parsing of the arguments is very flexible.  You can leave out one or
+	more arguments (or even all of them) and it will fall back to default
+	values.  You can switch the order as well.
+	There is just one rule:
+
+	If you supply the <application>, it has to be the first argument.
+
+	Examples:
+
+	open with: mplayer D     open the selection in mplayer, but not detached
+	open with: 1             open it with the default handler in mode 1
+	open with: d             open it detached with the default handler
+	open with: p             open it as usual, but pipe the output to "less"
+	open with: totem 1 Ds    open in totem in mode 1, will not detach the
+							 process (flag D) but discard the output (flag s)
 	"""
 
 	prompt = 'open with: '
diff --git a/ranger/help/__init__.py b/ranger/help/__init__.py
index b02fbd7d..090c4b5e 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', 'starting')
+HELP_TOPICS = ('index', 'movement', 'starting', 'console', 'fileop')
 
 def get_docstring_of_module(path, module_name):
 	imported = __import__(path, fromlist=[module_name])
diff --git a/ranger/help/console.py b/ranger/help/console.py
new file mode 100644
index 00000000..1ea06f90
--- /dev/null
+++ b/ranger/help/console.py
@@ -0,0 +1,201 @@
+# 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.
+"""
+3. Basic movement and browsing
+
+3.1. Overview of all the Console Modes
+3.2. List of Commands
+3.3. The (Quick) Command Console
+3.4. The Open Console
+
+
+==============================================================================
+3.1. Overview of all the Console Modes:
+
+There are, as of now, five different types of consoles:
+
+3.1.1. The Command Console, opened by pressing ":"
+      Usable for entering commands like you know it from vim.
+      Use the tab key to cycle through all available commands
+      and press F1 to view the docstring of the current command.
+
+3.1.2. The Quick Command Console, opened with ">"
+      Works just like 3.1.1, but it saves you pressing <RETURN> by checking
+      whether the current input can be executed in a meaningful way
+      and doing so automatically.  (works with commands like cd, find.)
+
+3.1.3. The Search Console, opened with "/"
+      Very much like the console you get in vim after pressing "/".
+      The current directory will be searched for files whose names
+      match the given regular expression.
+
+3.1.4. The Open Console, activated with "!"
+      Similar to ":!..." in vim.  The given command will be executed,
+      "%s" will be replaced with all the files in the selection,
+      "%f" is replaced with only the current highlighted file.
+      There are further options to tweak how the command is executed.
+
+3.1.5. The Quick Open Console, opened by pressing "r"
+      Rather than having to enter the full command, this console gives
+      you a higher level interface to running files.
+      You can define the application, the mode and the flags separated
+      with spaces.
+
+
+==============================================================================
+3.2. List of Commands
+
+This is a list of the few commands which are implemented by default.
+All commands except for ":delete" can be abbreviated to the shortest
+unambiguous name, e.g. ":chmod" can be written as ":ch" but not as ":c" since
+it conflicts with ":cd".
+
+
+:cd <dirname>
+      Changes the directory to <dirname> *
+
+:chmod <octal_number>
+      Sets the permissions of the selection to the octal number.
+
+:delete
+      Deletes the current selection.
+      "Selection" is defined as all the "marked files" (by default, you
+      can mark files with space or v).  If there are no marked files,
+      use the "current file" (where the cursor is)
+
+:edit <filename>
+      Opens the specified file in the text editor.
+
+:filter <string>
+      Displays only files which contain <string> in their basename.
+
+:find <string>
+      Look for a partial, case insensitive match in the filenames
+      of the current directory and execute it if there is only
+      one match. *
+
+:grep <string>
+      Looks for a string in all marked files or directory.
+      (equivalent to "!grep [some options] -e <string> -r %s | less")
+
+:mkdir <dirname>
+      Creates a directory with the name <dirname>
+
+:quit
+      Exits ranger
+
+:rename <newname>
+      Changes the name of the currently highlighted file to <newname>
+
+:touch <filename>
+      Creates a file with the name <filename>
+
+* implements handler for the Quick Command Console.
+
+
+==============================================================================
+3.3. The (Quick) Command Console
+
+Open these consoles by pressing ":" or ">"
+
+The Command Console and the "Quick" Command Console are mostly identical
+since they share the commands.  As explained in 3.1.2, the point in using
+the Quick Command Console is that the command is executed without the
+need to press <RETURN> as soon as ranger thinks you want it executed.
+
+Take the "find" command, for example.  It will attempt to find a file
+or directory which matches the given input, and if there is one unambiguous
+match, that file will be executed or that directory will be entered.
+If you use the "find" command in the quick console, as soon as there is
+one unambiguous match, <RETURN> will be pressed for you, giving you a
+very fast way to browse your files.
+
+
+All commands are defined in ranger/commands.py.  You can refer to this
+file for a list of commands.  Implementing new commands should be intuitive:
+Create a new class, a subclass of Command, and define the execute method
+is usually enough.  For parsing command input, the command parser in
+ranger/ext/command_parser.py is used.  The tab method should return None,
+a string or an iterable sequence containing the strings which should be
+cycled through by pressing tab.
+
+Only those commands which implement the quick_open method will be specially
+treated by the Quick Command Console.  For the rest, both consoles are equal.
+quick_open is called after each key press and if it returns True, the
+command will be executed immediately.
+
+
+Pressing F1 inside the console displays the docstring of the current command
+in the pager if docstrings are available (i.e.  unless python is run with
+the flag "-OO" which removes all docstrings.)
+
+
+==============================================================================
+3.4. The Open Console
+
+Open this console by pressing "!"
+
+The Open Console allows you to execute shell commands:
+!vim *         will run vim and open all files in the directory.
+
+%f will be replaced with the basename of the highlighted file
+%s will be selected with all files in the selection
+
+There is a special syntax for more control:
+
+!d! mplayer    will run mplayer with flags (d means detached)
+!@ mplayer     will open the selected files with mplayer
+	       (equivalent to !mplayer %s)
+
+Those two can be combinated:
+
+!d!@mplayer    will open the selection with a detached mplayer
+               (again, this is equivalent to !d!mplayer %s)
+
+For a list of other flags than "d", check chapter 2.5 of the documentation
+
+
+==============================================================================
+3.5. The Quick Open Console
+
+Open this console by pressing "r"
+
+The Quick Open Console allows you to open files with predefined programs
+and modes very quickly.  By adding flags to the command, you can specify
+precisely how the program is run, e.g. the d-flag will run it detached
+from the file manager.
+
+For a list of other flags than "d", check chapter 2.5 of the documentation
+
+The syntax is "open with: <application> <mode> <flags>".
+The parsing of the arguments is very flexible.  You can leave out one or
+more arguments (or even all of them) and it will fall back to default
+values.  You can switch the order as well.
+There is just one rule:
+
+If you supply the <application>, it has to be the first argument.
+
+Examples:
+
+open with: mplayer D     open the selection in mplayer, but not detached
+open with: 1             open it with the default handler in mode 1
+open with: d             open it detached with the default handler
+open with: p             open it as usual, but pipe the output to "less"
+open with: totem 1 Ds    open in totem in mode 1, will not detach the
+                         process (flag D) but discard the output (flag s)
+
+
+==============================================================================
+"""
+# vim:tw=78:sw=8:sts=8:ts=8:ft=help
diff --git a/ranger/help/fileop.py b/ranger/help/fileop.py
new file mode 100644
index 00000000..e47f7d2f
--- /dev/null
+++ b/ranger/help/fileop.py
@@ -0,0 +1,24 @@
+# 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.
+
+"""
+4. File Operations
+
+4.1. Xyz
+
+
+==============================================================================
+4.1. Xyz:
+"""
+# vim:tw=78:sw=4:sts=8:ts=8:ft=help
diff --git a/ranger/help/index.py b/ranger/help/index.py
index 57da5ff5..95fa9d16 100644
--- a/ranger/help/index.py
+++ b/ranger/help/index.py
@@ -23,8 +23,8 @@
 	|0?|	This index
 	|1?|	Basic movement and browsing
 	|2?|	Running Files
-		The console
-		File operations
+	|3?|	The console
+	|4?|	File operations
 
 
 ==============================================================================