general updates

9 files changed, 142 insertions, 69 deletions

diff --git a/README b/README
index 57fce508..3cf0bfde 100644
--- a/README
+++ b/README
@@ -1,12 +1,18 @@
 ranger v.1.5.0
 ==============
-ranger is a file manager with VI key bindings.  It provides a minimalistic yet
-nice curses interface with a view on the directory hierarchy.  The secondary
-task of ranger is to psychically guess which program you want to use for
-opening particular files.
+ranger is a console file manager with VI key bindings.  It provides a
+minimalistic yet nice curses interface with a view on the directory hierarchy.
+The secondary task of ranger is to psychically guess which program you want to
+use for opening particular files.
 
 This file describes ranger and how to get it to run.  For instructions on the
-usage, please read the man page.
+usage, please read the man page.  See doc/HACKING for development specific
+information.  For configuration, check the sample files that ranger creates
+in your ~/.config/ranger directory.
+
+A note to packagers:  Versions meant for packaging are listed in the changelog
+on the website and are taken from the stable branch.  The master branch is a
+"work in progress" branch.
 
 
 About
diff --git a/doc/HACKING b/doc/HACKING
index dd384758..f6d5d064 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -10,7 +10,7 @@ Coding Style
     http://www.python.org/dev/peps/pep-0008/
 * Although this guide suggests otherwise, tabs are used for indentation
     of code and docstrings.  In other documents (readme, etc), use spaces.
-* Test the code with unit tests where it makes sense
+* Test the code with "doctest" where it makes sense
 
 
 Patches
@@ -35,29 +35,25 @@ ranger/fsobject/fsobject.py
 About the UI:
 ranger/gui/widgets/browsercolumn.py
 ranger/gui/widgets/browserview.py
-ranger/gui/defaultui.py
+ranger/gui/ui.py
 
 
 Common Changes
 --------------
 
 * Change which files are previewed in the auto preview:
-In ranger/gui/widget/browsercolumn.py
+In ranger/fsobject/file.py
 the constant PREVIEW_BLACKLIST
 
 * Adding options:
 In ranger/defaults/options.py
 add the default value, like: my_option = True
-In ranger/shared/settings.py
+In ranger/container/settingobject.py
 add the name of your option to the constant ALLOWED_SETTINGS
 
 The setting is now accessible at self.settings.my_option,
 assuming <self> is a "SettingsAware" object.
 
-* Changing commands, adding aliases:
-ranger/defaults/commands.py
-or ~/.config/ranger/commands.py
-
 * Adding colorschemes:
 Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
 and modify it according to your needs.  Alternatively, mimic the jungle
@@ -66,15 +62,6 @@ In ranger/defaults/options.py (or ~/.config/ranger/options.py), change
     colorscheme = 'default'
 to: colorscheme = 'myscheme'
 
-* Change which files are considered to be "hidden":
-In ranger/defaults/options.py
-change the hidden_filter regular expression.
-
-* Change the key map:
-Modify ranger/defaults/keys.py.  This should be self-explanatory.
-Check out ranger/core/actions.py for the most common actions, of course
-you can also use your own functions.
-
 * Change the file type => application associations:
 In ranger/defaults/apps.py
 modify the method app_default.
@@ -88,8 +75,5 @@ Modify ranger/data/mime.types
 Version Numbering
 -----------------
 
-X.Y.Z, where:
-
-* X: Major version, milestone
-* Y: Minor version, even number => stable version
-* Z: Revision, may be omitted if zero
+Three numbers;  The first changes on a rewrite, the second changes when major
+configuration incompatibilities occur and the third changes with each release.
diff --git a/doc/ranger.1 b/doc/ranger.1
index de50f621..19a0bb42 100644
--- a/doc/ranger.1
+++ b/doc/ranger.1
@@ -124,7 +124,7 @@
 .\" ========================================================================
 .\"
 .IX Title "RANGER 1"
-.TH RANGER 1 "ranger-1.5.0" "10/05/2011" "ranger manual"
+.TH RANGER 1 "ranger-1.5.0" "10/07/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
@@ -139,10 +139,15 @@ ranger \- visual file manager
 [\fB\-\-flags\fR=\fIflags\fR] [\fIpath/filename\fR]
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
-ranger is a file manager with \s-1VI\s0 key bindings.  It provides a minimalistic yet
-nice curses interface with a view on the directory hierarchy.  The secondary
-task of ranger is to psychically guess which program you want to use for
-opening particular files.
+ranger is a console file manager with \s-1VI\s0 key bindings.  It provides a
+minimalistic yet nice curses interface with a view on the directory hierarchy.
+The secondary task of ranger is to psychically guess which program you want to
+use for opening particular files.
+.PP
+This manual mainly contains information on the usage of ranger.  Refer to the
+\&\fI\s-1README\s0\fR for install instructions and to \fIdoc/HACKING\fR for development
+specific information.  For configuration, check the sample files that ranger
+created in your \fI~/.config/ranger\fR directory.
 .SH "OPTIONS"
 .IX Header "OPTIONS"
 .IP "\fB\-d\fR, \fB\-\-debug\fR" 14
diff --git a/doc/ranger.pod b/doc/ranger.pod
index eaadcf5b..ab876d7f 100644
--- a/doc/ranger.pod
+++ b/doc/ranger.pod
@@ -17,10 +17,15 @@ B<ranger> [B<--help>] [B<--version>] [B<--debug>] [B<--clean>]
 
 =head1 DESCRIPTION
 
-ranger is a file manager with VI key bindings.  It provides a minimalistic yet
-nice curses interface with a view on the directory hierarchy.  The secondary
-task of ranger is to psychically guess which program you want to use for
-opening particular files.
+ranger is a console file manager with VI key bindings.  It provides a
+minimalistic yet nice curses interface with a view on the directory hierarchy.
+The secondary task of ranger is to psychically guess which program you want to
+use for opening particular files.
+
+This manual mainly contains information on the usage of ranger.  Refer to the
+F<README> for install instructions and to F<doc/HACKING> for development
+specific information.  For configuration, check the sample files that ranger
+created in your F<~/.config/ranger> directory.
 
 
 
diff --git a/ranger/__init__.py b/ranger/__init__.py
index 32a31eae..f6d6529b 100644
--- a/ranger/__init__.py
+++ b/ranger/__init__.py
@@ -14,18 +14,14 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """
-Console-based visual file manager.
+A console file manager with VI key bindings.
 
-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 columns.
-
-The keybindings are similar to those of other console programs like
-vim, mutt or ncmpcpp so the usage will be intuitive and efficient.
+It provides a minimalistic yet nice curses interface with a view on the
+directory hierarchy.  The secondary task of ranger is to psychically guess
+which program you want to use for opening particular files.
 """
 
 import os
-from ranger.core.main import main
 
 # Information
 __license__ = 'GPL3'
@@ -35,3 +31,14 @@ __email__ = 'romanz@lavabit.com'
 
 # Constants
 RANGERDIR = os.path.dirname(__file__)
+TICKS_BEFORE_COLLECTING_GARBAGE = 100
+TIME_BEFORE_FILE_BECOMES_GARBAGE = 1200
+MACRO_DELIMITER = '%'
+LOGFILE = '/tmp/errorlog'
+USAGE = '%prog [options] [path/filename]'
+
+# If the environment variable XDG_CONFIG_HOME is non-empty, CONFDIR is ignored
+# and the configuration directory will be $XDG_CONFIG_HOME/ranger instead.
+CONFDIR = '~/.config/ranger'
+
+from ranger.core.main import main
diff --git a/ranger/core/actions.py b/ranger/core/actions.py
index 58edc56a..9f7321be 100644
--- a/ranger/core/actions.py
+++ b/ranger/core/actions.py
@@ -38,7 +38,7 @@ MACRO_FAIL = "<\x01\x01MACRO_HAS_NO_VALUE\x01\01>"
 
 class _MacroTemplate(string.Template):
 	"""A template for substituting macros in commands"""
-	delimiter = '%'
+	delimiter = ranger.MACRO_DELIMITER
 
 class Actions(FileManagerAware, EnvironmentAware, SettingsAware):
 	search_method = 'ctime'
diff --git a/ranger/core/fm.py b/ranger/core/fm.py
index 9192f15c..6d772054 100644
--- a/ranger/core/fm.py
+++ b/ranger/core/fm.py
@@ -25,6 +25,7 @@ import stat
 import sys
 
 import ranger
+from ranger import *
 from ranger.core.actions import Actions
 from ranger.container.tags import Tags
 from ranger.gui.ui import UI
@@ -36,9 +37,6 @@ from ranger.ext.signals import SignalDispatcher
 from ranger import __version__
 from ranger.core.loader import Loader
 
-TICKS_BEFORE_COLLECTING_GARBAGE = 100
-TIME_BEFORE_FILE_BECOMES_GARBAGE = 1200
-
 class FM(Actions, SignalDispatcher):
 	input_blocked = False
 	input_blocked_until = 0
diff --git a/ranger/core/helper.py b/ranger/core/helper.py
index 9a403a15..f4035ef8 100644
--- a/ranger/core/helper.py
+++ b/ranger/core/helper.py
@@ -20,8 +20,6 @@ import os.path
 import sys
 from ranger import *
 
-LOGFILE = '/tmp/errorlog'
-
 def parse_arguments():
 	"""Parse the program arguments"""
 	from optparse import OptionParser, SUPPRESS_HELP
@@ -32,10 +30,9 @@ def parse_arguments():
 	if 'XDG_CONFIG_HOME' in os.environ and os.environ['XDG_CONFIG_HOME']:
 		default_confdir = os.environ['XDG_CONFIG_HOME'] + '/ranger'
 	else:
-		default_confdir = '~/.config/ranger'
-	usage = '%prog [options] [path/filename]'
+		default_confdir = CONFDIR
 
-	parser = OptionParser(usage=usage, version='ranger '+__version__)
+	parser = OptionParser(usage=USAGE, version='ranger '+__version__)
 
 	parser.add_option('-d', '--debug', action='store_true',
 			help="activate debug mode")
diff --git a/ranger/data/config_examples/options.py b/ranger/data/config_examples/options.py
index e37605ce..7006ebd5 100644
--- a/ranger/data/config_examples/options.py
+++ b/ranger/data/config_examples/options.py
@@ -1,32 +1,103 @@
 # ===================================================================
-# This is the main configuration file of ranger.  It consists of python code,
-# but fear not, you don't need any python knowledge for this.
+# This is the main configuration file of ranger.  It consists of python
+# code, but fear not, you don't need any python knowledge for changing
+# the settings.
 #
 # Lines beginning with # are comments.  To enable a line, remove the #.
 #
-# Technical information:  This file is imported as a python module.  Every
-# top-level variable with the name of a ranger setting will be used to change
-# the value of that setting.  You can use "del <variable-name>" to avoid that.
+# Here are the most important settings.  Refer to the man page for
+# a list and descriptions of all settings.
 # ===================================================================
 
-# This line imports some basic variables to get some basic variables
+# This line imports some basic variables
 from ranger.api.options import *
 
-# T
-#column_ratios = (1, 1, 4, 3)
+# Ranger can use a customizable external script for previews.  The included
+# default script prints previews of archives, html/pdf documents and even
+# images.  This is, however, disabled by default for performance reasons.  Turn
+# it on by uncommenting this line:
+#use_preview_script = True
 
-# A function that adds an additional macro:
+# This changes the location of the preview script
+#preview_script = "~/.config/ranger/scope.sh"
+
+# Use a simple character-wise sort algorithm instead of the default natural
+# sorting.  This is faster, although the difference is hardly noticeable.
+#sort = "basename"
+
+# Use a unicode "..." symbol when filenames are truncated.  This is disabled
+# by default since some systems don't support unicode+curses well.
+#unicode_ellipsis = True
+
+# Uncomment these lines to disable previews by default?
+#preview_files = False
+#preview_directories = False
+
+# xterm handles the ALT key differently.  If you use xterm, uncomment this line
+#xterm_alt_key = True
+
+# Change what files ranger should hide with this setting.  Its value is a
+# "regular expression".  If you don't know about them, there are lots of good
+# tutorials on the web!  Below is the default value.
+#hidden_filter = regexp(r"^\.|\.(?:pyc|pyo|bak|swp)$|^lost\+found$|^__cache__$")
+
+
+# ===================================================================
+# Beware: from here on, you are on your own.  This part requires python
+# knowledge.
+#
+# Since python is a dynamic language, it gives you the power to replace any
+# part of ranger without touching the code.  This is commonly referred to as
+# Monkey Patching and can be helpful if you, for some reason, don't want to
+# modify rangers code directly.  Just remember: the more you mess around, the
+# more likely it is to break when you switch to another version.  Here are some
+# practical examples of monkey patching.
 #
+# Technical information:  This file is imported as a python module.  If a
+# variable has the name of a setting, ranger will attempt to use it to change
+# that setting.  You can write "del <variable-name>" to avoid that.
+# ===================================================================
+# Add a new sorting algorithm: Random sort.
+# Enable this with :set sort=random
+
+#from ranger.fsobject.directory import Directory
+#from random import random
+#Directory.sort_dict['random'] = lambda path: random()
+
+# ===================================================================
+# A function that changes which files are displayed.  This is more powerful
+# than the hidden_filter setting since this function has more information.
+
+## Save the original filter function
+#import ranger.fsobject.directory
+#old_accept_file = ranger.fsobject.directory.accept_file
+
+## Define a new one
+#def accept_file_MOD(fname, mypath, hidden_filter, name_filter):
+#	if mypath == '/' and fname in ('boot', 'sbin', 'proc', 'sys'):
+#		return False
+#	else:
+#		return old_accept_file(fname, mypath, hidden_filter, name_filter)
+
+## Overwrite the old function
+#import ranger.fsobject.directory
+#ranger.fsobject.directory.accept_file = accept_file_MOD
+
+# ===================================================================
+# A function that adds an additional macro.  Test this with :shell -p echo %date
+
 ## Save the original macro function
-#import ranger.actions
-#old_get_macros = ranger.actions.Actions.get_macros
+#import ranger.core.actions
+#old_get_macros = ranger.core.actions.Actions._get_macros
 #
 ## Define a new macro function
 #import time
-#def add_my_macro(self):
-#  macros = old_get_macros(self)
-#  macros['date'] = time.strftime('%m/%d/%Y')
-#  return macros
+#def get_macros_MOD(self):
+#	macros = old_get_macros(self)
+#	macros['date'] = time.strftime('%m/%d/%Y')
+#	return macros
 #
 ## Overwrite the old one
-#ranger.actions.Actions.get_macros = add_my_macro
+#ranger.core.actions.Actions._get_macros = get_macros_MOD
+
+# ===================================================================