defaults/options: more documentation

1 files changed, 88 insertions, 44 deletions

diff --git a/ranger/defaults/options.py b/ranger/defaults/options.py
index 1328f2c5..3b44d4f6 100644
--- a/ranger/defaults/options.py
+++ b/ranger/defaults/options.py
@@ -1,35 +1,18 @@
+# -*- coding: utf-8 -*-
 # Copyright (C) 2009, 2010, 2011  Roman Zimbelmann <romanz@lavabit.com>
+# This configuration file is licensed under the same terms as ranger.
+# ===================================================================
+# 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.
 #
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# Lines beginning with # are comments.  To enable a line, remove the #.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-"""
-This is the default configuration file of ranger.
-
-There are two ways of customizing ranger.  The first and recommended
-method is creating a file at ~/.config/ranger/options.py and adding
-those lines you want to change.  It might look like this:
-
-from ranger.api.options import *
-preview_files = False  # I hate previews!
-max_history_size = 2000  # I can afford it.
-
-The other way is directly editing this file.  This will make upgrades
-of ranger more complicated though.
-
-Whatever you do, make sure the import-line stays intact and the type
-of the values stay the same.
-"""
+# You can customize ranger in the file ~/.config/ranger/options.py.
+# It has the same syntax as this file.  In fact, you can just copy this
+# file there with `ranger --copy-config=options' and make your modifications.
+# But make sure you update your configs when you update ranger.
+# ===================================================================
 
 from ranger.api.options import *
 
@@ -134,22 +117,83 @@ sort_directories_first = True
 # (Especially on xterm)
 xterm_alt_key = False
 
+# The color scheme overlay.  Explained below.
+colorscheme_overlay = None
 
-# Apply an overlay function to the colorscheme.  It will be called with
-# 4 arguments: the context and the 3 values (fg, bg, attr) returned by
-# the original use() function of your colorscheme.  The return value
-# must be a 3-tuple of (fg, bg, attr).
-# Note: Here, the colors/attributes aren't directly imported into
-# the namespace but have to be accessed with color.xyz.
-def colorscheme_overlay(context, fg, bg, attr):
-	if context.directory and attr & color.bold and \
-			not any((context.marked, context.selected)):
-		attr ^= color.bold  # I don't like bold directories!
+## Apply an overlay function to the colorscheme.  It will be called with
+## 4 arguments: the context and the 3 values (fg, bg, attr) returned by
+## the original use() function of your colorscheme.  The return value
+## must be a 3-tuple of (fg, bg, attr).
+## Note: Here, the colors/attributes aren't directly imported into
+## the namespace but have to be accessed with color.xyz.
+
+#from ranger.gui import color
+#def colorscheme_overlay(context, fg, bg, attr):
+#	if context.directory and attr & color.bold and \
+#			not any((context.marked, context.selected)):
+#		attr ^= color.bold  # I don't like bold directories!
+#
+#	if context.main_column and context.selected:
+#		fg, bg = color.red, color.default  # To highlight the main column!
+#
+#	return fg, bg, attr
 
-	if context.main_column and context.selected:
-		fg, bg = color.red, color.default  # To highlight the main column!
 
-	return fg, bg, attr
+# ===================================================================
+# 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 hidden_filter and 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
 
-# The above function was just an example, let's set it back to None
-colorscheme_overlay = None
+# ===================================================================
+# A function that adds an additional macro.  Test this with :shell -p echo %date
+
+## Save the original macro function
+#import ranger.core.actions
+#old_get_macros = ranger.core.actions.Actions._get_macros
+#
+## Define a new macro function
+#import time
+#def get_macros_MOD(self):
+#	macros = old_get_macros(self)
+#	macros['date'] = time.strftime('%m/%d/%Y')
+#	return macros
+#
+## Overwrite the old one
+#ranger.core.actions.Actions._get_macros = get_macros_MOD