Added config file support for "overrides" setting parameter.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@2639 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

4 files changed, 33 insertions, 7 deletions

diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 175a88a3f..4fb50061c 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -521,7 +521,8 @@ _`initial_header_level`
 .. _stylesheet [html4css1 writer]:
 
 stylesheet
-    CSS stylesheet URL, used verbatim.  Overrides stylesheet_path.
+    CSS stylesheet URL, used verbatim.  Overrides stylesheet_path
+    [#override]_.
 
     Default: "default.css".  Options: ``--stylesheet``.
 
@@ -533,8 +534,9 @@ stylesheet
 
 stylesheet_path
     Path to CSS stylesheet [#pwd]_.  Overrides "stylesheet" URL
-    setting (``--stylesheet``).  Path is adjusted relative to the
-    output HTML file.  Also defined for the `LaTeX Writer`__.
+    setting (``--stylesheet``) [#override]_.  Path is adjusted
+    relative to the output HTML file.  Also defined for the `LaTeX
+    Writer`__.
 
     Default: None.  Options: ``--stylesheet-path``.
 
@@ -629,8 +631,9 @@ _`documentoptions`
 .. _stylesheet [latex2e writer]:
 
 stylesheet
-    Specify a stylesheet file. The file will be ``\input`` by latex in
-    the document header.  Also defined for the `HTML Writer`__.
+    Specify a stylesheet file.  Overrides stylesheet_path
+    [#override]_.  The file will be ``\input`` by latex in the
+    document header.  Also defined for the `HTML Writer`__.
 
     Default: no stylesheet ("").  Option: ``--stylesheet``.
 
@@ -640,7 +643,7 @@ stylesheet
 
 stylesheet_path
     Path to stylesheet [#pwd]_.  Overrides "stylesheet" setting
-    (``--stylesheet``).
+    (``--stylesheet``) [#override]_.
 
     Please note that you will have to run ``latex`` from the directory
     containing the output file; otherwise the stylesheet reference
@@ -799,6 +802,12 @@ _`_source`
 .. [#pwd] Path relative to the working directory of the process at
    launch.
 
+.. [#override] The overridden setting will automatically be set to
+   ``None`` for command-line options and config file settings.  Client
+   programs which specify defaults that override other settings must
+   do the overriding explicitly, by assigning ``None`` to the other
+   settings.
+
 
 ------------------------------
 Old-Format Configuration Files
diff --git a/docutils/docutils/frontend.py b/docutils/docutils/frontend.py
index 78cd638cb..0b1af5da8 100644
--- a/docutils/docutils/frontend.py
+++ b/docutils/docutils/frontend.py
@@ -460,6 +460,11 @@ class OptionParser(optparse.OptionParser, docutils.SettingsSpec):
         keyword argument dictionary entries of components' ``settings_spec``
         attribute."""
 
+        self.overrides = {}
+        """{setting: overridden setting} mapping, used by `validate_options`.
+        The overridden setting is set to `None` when the key setting is
+        encountered."""
+
         self.lists = {}
         """Set of list-type settings."""
 
@@ -508,6 +513,8 @@ class OptionParser(optparse.OptionParser, docutils.SettingsSpec):
                         self.validators[option.dest] = kwargs['validator']
                     if kwargs.get('action') == 'append':
                         self.lists[option.dest] = 1
+                    if kwargs.get('overrides'):
+                        self.overrides[option.dest] = kwargs['overrides']
                 if component.settings_defaults:
                     self.defaults.update(component.settings_defaults)
         for component in components:
@@ -621,7 +628,10 @@ section "Old-Format Configuration Files".
         self.remove_section('options')
 
     def validate_settings(self, filename, option_parser):
-        """Call the validator function on all applicable settings."""
+        """
+        Call the validator function and implement overrides on all applicable
+        settings.
+        """
         for section in self.sections():
             for setting in self.options(section):
                 validator = option_parser.validators.get(setting)
@@ -638,6 +648,9 @@ section "Old-Format Configuration Files".
                             % (filename, section, error.__class__.__name__,
                                error, setting, value)), None, sys.exc_info()[2])
                     self.set(section, setting, new_value)
+                override = option_parser.overrides.get(setting)
+                if override:
+                    self.set(section, override, None)
 
     def optionxform(self, optionstr):
         """
diff --git a/docutils/test/functional/tests/standalone_rst_html4css1.py b/docutils/test/functional/tests/standalone_rst_html4css1.py
index 736905c9c..c7a2b7301 100644
--- a/docutils/test/functional/tests/standalone_rst_html4css1.py
+++ b/docutils/test/functional/tests/standalone_rst_html4css1.py
@@ -8,4 +8,5 @@ parser_name = "rst"
 writer_name = "html4css1"
 
 # Settings
+settings_overrides['stylesheet'] = None
 settings_overrides['stylesheet_path'] = "../tools/stylesheets/default.css"
diff --git a/docutils/test/test_settings.py b/docutils/test/test_settings.py
index 3dcbc92d8..1b2ed5d0c 100755
--- a/docutils/test/test_settings.py
+++ b/docutils/test/test_settings.py
@@ -45,6 +45,7 @@ class ConfigFileTests(unittest.TestCase):
                 'no_random': 1,
                 'python_home': 'http://www.python.org',
                 'source_link': 1,
+                'stylesheet': None,
                 'stylesheet_path': fixpath('data/stylesheets/pep.css'),
                 'template': fixpath('data/pep-html-template')},
         'one': {'datestamp': '%Y-%m-%d %H:%M UTC',
@@ -52,9 +53,11 @@ class ConfigFileTests(unittest.TestCase):
                 'no_random': 1,
                 'python_home': 'http://www.python.org',
                 'source_link': 1,
+                'stylesheet': None,
                 'stylesheet_path': fixpath('data/stylesheets/pep.css'),
                 'template': fixpath('data/pep-html-template')},
         'two': {'generator': 0,
+                'stylesheet': None,
                 'stylesheet_path': fixpath('data/test.css')},
         'list': {'expose_internals': ['a', 'b', 'c', 'd', 'e']},
         'list2': {'expose_internals': ['a', 'b', 'c', 'd', 'e', 'f']},