New setting `stylesheet_dirs`.

Comma-separated list of directories where stylesheets are found. Used by
`stylesheet_path` when expanding relative path arguments.

Now, it is easy to add a custom stylesheet to Docutils default
stylesheet with, e.g., --stylesheet_path="html4css1.css, mystyle.css"
    
Changed behaviour of the default settings: 
if there is a file "html4css1.css" in the working directory of the
process at launch, it is used instead of the one provided by Docutils
in the writer source directory.


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

8 files changed, 255 insertions, 123 deletions

diff --git a/HISTORY.txt b/HISTORY.txt
index fffdae50a..544a23268 100644
--- a/HISTORY.txt
+++ b/HISTORY.txt
@@ -36,6 +36,9 @@ Changes Since 0.10
 * docutils/writers/html4css1/__init__.py
 
   - Fix [ 3600051 ] for tables in a list, table cells are not compacted.
+  - New setting `stylesheet_dirs`: Comma-separated list of directories
+    where stylesheets are found. Used by `stylesheet_path` when expanding
+    relative path arguments.
 
 * docutils/writers/latex2e/__init__.py
 
@@ -44,6 +47,7 @@ Changes Since 0.10
     Activate the SmartQuotes_ transform if you want this feature.
   - Fix literal use of babel shorthands (straight quote, tilde, ...).
   - Fix [ 3603246 ] Bug in option "--graphicx-option=auto".
+  - New setting `stylesheet_dirs`.
 
 .. _SmartQuotes: docs/user/config.html#smart-quotes
 
diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt
index 9566642cb..0f49f7b99 100644
--- a/RELEASE-NOTES.txt
+++ b/RELEASE-NOTES.txt
@@ -37,6 +37,20 @@ Changes Since 0.10
   - Drop the simple algorithm replacing straight double quotes with
     English typographic ones. Use the SmartQuotes transform
     (``--smart-quotes=True``) instead.
+  - New setting `stylesheet_dirs`: Comma-separated list of directories
+    where stylesheets are found. Used by `stylesheet_path` when expanding
+    relative path arguments.
+
+* docutils/writers/html4css1/__init__.py
+  - New setting `stylesheet_dirs` (see above).
+  
+    Now, it is easy to add a custom stylesheet to Docutils' default
+    stylesheet with, e.g., ``--stylesheet_path='html4css1.css, mystyle.css'``
+    
+    Changed behaviour of the default settings: 
+      if there is a file ``html4css1.css`` in the working directory of the
+      process at launch, it is used instead of the one provided by Docutils
+      in the writer source directory.
 
 
 Release 0.10 (2012-12-16)
diff --git a/docs/user/config.txt b/docs/user/config.txt
index a08942a60..2a06bc843 100644
--- a/docs/user/config.txt
+++ b/docs/user/config.txt
@@ -383,8 +383,8 @@ exists). The language identifier can have an optional subtag,
 typically for variations based on country (from `ISO 3166`_
 2-letter country codes).  Avoid subtags except where they add
 useful distinguishing information. Examples of language tags
-include "fr", "en-GB", "pt_br" (the same as "pt-BR"), and
-"de-1901" (German with pre-1998 spelling).
+include "fr", "en-GB", "pt-br" (the same as "pt-BR"), and
+"de-1901" (German with pre-1996 spelling).
 
 The language of document parts can be specified with a
 "language-<language tag>" `class attribute`_, e.g.
@@ -823,12 +823,10 @@ attribution
 
 Format for block quote attributions: one of "dash" (em-dash
 prefix), "parentheses"/"parens", or "none".  Also defined for the
-`LaTeX Writer`__.
+`LaTeX Writer <attribution [latex2e writer]_>`__.
 
 Default: "dash".  Options: ``--attribution``.
 
-__ `attribution [latex2e writer]`_
-
 cloak_email_addresses
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -881,13 +879,12 @@ embed_stylesheet
 Embed the stylesheet in the output HTML file.  The stylesheet file
 must specified by the stylesheet_path__ setting and must be
 accessible during processing.
-Also defined for the `LaTeX Writer`__.
+Also defined for the `LaTeX Writer <embed_stylesheet [latex2e writer]_>`__.
 
 Default: enabled.  Options: ``--embed-stylesheet,
 --link-stylesheet``.
 
 __ `stylesheet_path [html4css1 writer]`_
-__ `embed_stylesheet [latex2e writer]`_
 
 field_name_limit
 ~~~~~~~~~~~~~~~~
@@ -903,16 +900,14 @@ Default: 14 (i.e. 14 characters).  Option: ``--field-name-limit``.
 footnote_references
 ~~~~~~~~~~~~~~~~~~~
 
-Format for footnote references, one of "superscript" or
-"brackets".  Also defined for the `LaTeX Writer`__.
+Format for footnote references, one of "superscript" or "brackets".
+Also defined for the `LaTeX Writer <footnote_references [latex2e writer]_>`__.
 
 Overrides [#override]_ trim_footnote_reference_space_, if
 applicable. [#footnote_space]_
 
 Default: "brackets".  Option: ``--footnote-references``.
 
-__ `footnote_references [latex2e writer]`_
-
 initial_header_level
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -958,10 +953,8 @@ the output document. Supported values are (case insensitive):
 :HTML:
   Format math in standard HTML enhanced by CSS rules
 
-  Requires the ``math.css`` stylesheet (stored in the same
-  installation-dependent directory as the `default stylesheet`__).
-
-  .. __: `stylesheet_path [html4css1 writer]`_
+  Requires the ``math.css`` stylesheet (in the system
+  `stylesheet directory <stylesheet_dirs [html4css1 writer]_>`_
 
 :MathML:
   Embed math content as presentational MathML_.
@@ -1010,21 +1003,41 @@ stylesheet
 ~~~~~~~~~~
 
 A comma-separated list of CSS stylesheet URLs, used verbatim.
-Also defined for the `LaTeX Writer`__.
+Also defined for the `LaTeX Writer <stylesheet [latex2e writer]_>`__.
 
 Overrides also stylesheet-path__. [#override]_
 
 Default: None.  Options: ``--stylesheet``.
 
-__ `stylesheet [latex2e writer]`_
 __ `stylesheet_path [html4css1 writer]`_
 
+.. _stylesheet_dirs [html4css1 writer]:
+
+stylesheet_dirs
+~~~~~~~~~~~~~~~
+
+A comma-separated list of directories where stylesheets can be found.
+Used by the stylesheet_path__ setting when expanding relative path arguments.
+
+Note: This setting defines a "search path" (similar to the PATH variable for
+executables). However, the term "path" is already used in the
+stylesheet_path__ setting with the meaning of a file location.
+
+__
+__ `stylesheet_path [html4css1 writer]`_
+
+Default: the working directory of the process at launch and the directory
+with default stylesheet files (writer and installation specific).
+Use the ``--help`` option to get the exact value.
+Option: ``--stylesheet-directories``.
+
 .. _stylesheet_path [html4css1 writer]:
 
 stylesheet_path
 ~~~~~~~~~~~~~~~
 
-A comma-separated list of paths [#pwd]_ to CSS stylesheets.
+A comma-separated list of paths to CSS stylesheets. Relative paths are
+expanded if a matching file is found in the stylesheet_dirs__.
 If embed_stylesheet__ is False, paths are rewritten relative to the
 output HTML file. Also defined for the `LaTeX Writer`__.
 
@@ -1032,26 +1045,26 @@ Also overrides "stylesheet". [#override]_
 Pass an empty string (to either "stylesheet" or "stylesheet_path") to
 deactivate stylesheet inclusion.
 
-Default: "html4css1.css" in the docutils/writers/html4css1/
-directory (installed automatically; for the exact machine-specific
-path, use the ``--help`` option).  Options: ``--stylesheet-path``.
+Default: "html4css1.css".
+Options: ``--stylesheet-path``.
 
 __ `embed_stylesheet [html4css1 writer]`_
 __ `stylesheet_path [latex2e writer]`_
+__ `stylesheet_dirs [html4css1 writer]`_
 
 .. _table_style [html4css1 writer]:
 
 table_style
 ~~~~~~~~~~~
 
-Added to standard table classes to allow styling with CSS.
+Class value(s) added to tables to allow styling with CSS.
 The default sylesheet defines:
 
 borderless
-  no borders around the table.
+  No borders around the table.
 
-.. TODO: booktabs
-           a line above and below the table and one after the head.
+booktabs
+  Lines above and below the table and a thin line after the head.
 
 Default: "".  Option: ``--table-style``.
 
@@ -1087,7 +1100,7 @@ __ `xml_declaration [docutils_xml writer]`_
 
 
 [pep_html writer]
------------------
+~~~~~~~~~~~~~~~~~
 
 The PEP/HTML Writer derives from the standard HTML Writer, and shares
 all settings defined in the `[html4css1 writer]`_ section.  The
@@ -1097,38 +1110,37 @@ before the "[pep_html writer]" section.
 The PEP/HTML Writer's default for the following settings differ from
 those of the standard HTML Writer:
 
-* ``stylesheet_path``: The default is
-  ``docutils/writers/pep_html/pep.css`` in the installation directory.
-  For the exact machine-specific path, use the ``--help`` option.
+`stylesheet_path <stylesheet_path [html4css1 writer]_>`_:
+  Default: "pep.css"
 
-* ``template``: The default is
-  ``docutils/writers/pep_html/template.txt`` in the installation
+`template <template [html4css1 writer]_>`_:
+  Default: ``docutils/writers/pep_html/template.txt`` in the installation
   directory.  For the exact machine-specific path, use the ``--help``
   option.
 
 no_random
-~~~~~~~~~
+"""""""""
 Do not use a random banner image.  Mainly used to get predictable
 results when testing.
 
 Default: random enabled (None).  Options: ``--no-random`` (hidden).
 
 pep_home
-~~~~~~~~
+""""""""
 
 Home URL prefix for PEPs.
 
 Default: current directory (".").  Options: ``--pep-home``.
 
 python_home
-~~~~~~~~~~~
+"""""""""""
 Python's home URL.
 
 Default: parent directory ("..").  Options: ``--python-home``.
 
 
 [s5_html writer]
-----------------
+~~~~~~~~~~~~~~~~
 
 The S5/HTML Writer derives from the standard HTML Writer, and shares
 all settings defined in the `[html4css1 writer]`_ section.  The
@@ -1138,16 +1150,17 @@ before the "[s5_html writer]" section.
 The S5/HTML Writer's default for the following settings differ
 from those of the standard HTML Writer:
 
-* ``compact_lists``: The default here is to disable compact lists.
+compact_lists_:
+    Default: disable compact lists.
 
-* ``template``: The default is
-  ``docutils/writers/s5_html/template.txt`` in the installation
+template_:
+  Default: ``docutils/writers/s5_html/template.txt`` in the installation
   directory.  For the exact machine-specific path, use the ``--help``
   option.
 
 
 hidden_controls
-~~~~~~~~~~~~~~~
+"""""""""""""""
 
 Auto-hide the presentation controls in slideshow mode, or or keep
 them visible at all times.
@@ -1156,7 +1169,7 @@ Default: auto-hide (1).  Options: ``--hidden-controls``,
 ``--visible-controls``.
 
 current_slide
-~~~~~~~~~~~~~
+"""""""""""""
 
 Enable or disable the current slide indicator ("1/15").
 
@@ -1164,7 +1177,7 @@ Default: disabled (None).  Options: ``--current-slide``,
 ``--no-current-slide``.
 
 overwrite_theme_files
-~~~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""""
 
 Allow or prevent the overwriting of existing theme files in the
 ``ui/<theme>`` directory.  This has no effect if "theme_url_" is
@@ -1174,7 +1187,7 @@ Default: keep existing theme files (None).  Options:
 ``--keep-theme-files``, ``--overwrite-theme-files``.
 
 theme
-~~~~~
+"""""
 
 Name of an installed S5 theme, to be copied into a ``ui/<theme>``
 subdirectory, beside the destination file (output HTML).  Note
@@ -1185,7 +1198,7 @@ Also overrides the "theme_url_" setting. [#override]_
 Default: "default".  Option: ``--theme``.
 
 theme_url
-~~~~~~~~~
+"""""""""
 The URL of an S5 theme directory.  The destination file (output
 HTML) will link to this theme; nothing will be copied.  Also overrides
 the "theme_" setting. [#override]_
@@ -1193,7 +1206,7 @@ the "theme_" setting. [#override]_
 Default: None.  Option: ``--theme-url``.
 
 view_mode
-~~~~~~~~~
+"""""""""
 
 The initial view mode, either "slideshow" or "outline".
 
@@ -1348,24 +1361,48 @@ __ `stylesheet [html4css1 writer]`_
    http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
 
 
+.. _stylesheet_dirs [latex2e writer]:
+
+stylesheet_dirs
+~~~~~~~~~~~~~~~
+
+A comma-separated list of directories where stylesheets can be found.
+Used by the stylesheet_path__ setting.
+
+Note: This setting defines a "search path" (similar to the PATH variable for
+executables). However, the term "path" is already used in the
+stylesheet_path__ setting with the meaning of a file location.
+
+__
+__ `stylesheet_path [latex2e writer]`_
+
+Default: the working directory of the process at launch and the directory
+with default stylesheet files (writer and installation specific).
+Use the ``--help`` option to get the exact value.
+Option: ``--stylesheet-directories``.
+
 .. _stylesheet_path [latex2e writer]:
 
 stylesheet_path
 ~~~~~~~~~~~~~~~
 
-Similar to stylesheet__, however paths [#pwd]_ are rewritten relative to
-the output file (if there is a common part in the given path and the
-output file path). Also defined for the `HTML Writer`__.
+A comma-separated list of style files. Relative paths are expanded if a
+matching file is found in the stylesheet_dirs__.
+If embed_stylesheet__ is False, paths are rewritten relative to the
+output file path. Run ``latex`` from the directory containing
+the output file. 
+
+The stylesheet__  option is preferred for files in the `TeX input path`_.
 
-Run ``latex`` from the directory containing the output file. Fails for
-files in the TEXINPUTS path; use stylesheet__ in this case.
+Also defined for the
+`HTML Writer <stylesheet_path [html4css1 writer]_>`__.
 
 Also overrides stylesheet__. [#override]_
 
 Default: no stylesheet ("").  Option: ``--stylesheet-path``.
 
-__ `stylesheet [latex2e writer]`_
-__ `stylesheet_path [html4css1 writer]`_
+__ `stylesheet_dirs [latex2e writer]`_
+__ `embed_stylesheet [latex2e writer]`_
 __
 __ `stylesheet [latex2e writer]`_
 
@@ -1421,12 +1458,7 @@ __ `footnote_references [html4css1 writer]`_
 attribution
 ~~~~~~~~~~~
 
-Format for block quote attributions, the same as for the `HTML writer`__:
-one of "dash" (em-dash prefix), "parentheses"/"parens" or "none".
-
-Default: "dash".  Option: ``--attribution``.
-
-__ `attribution [html4css1 writer]`_
+See `attribution [html4css1 writer]`_.
 
 compound_enumerators
 ~~~~~~~~~~~~~~~~~~~~
@@ -1446,7 +1478,7 @@ Default: "" (quoting of whitespace and special chars).
 Option: ``--literal-block-env``.
 
 .. [#] A literal-block element, when processed by a Docutils writer might
-   have it's origin in literal block following "::" or a 
+   have it's origin in literal block following "::" or a
    ``.. parsed-literal::`` directive.
 
    A LaTeX verbatim environment is only usable if there is no other
@@ -1461,7 +1493,7 @@ compound enumerators.  This has no effect unless
 `compound_enumerators`_ are enabled.
 
 Default: disabled (None).
-Options: ``--section-prefix-for-enumerators``, 
+Options: ``--section-prefix-for-enumerators``,
 ``--no-section-prefix-for-enumerators``.
 
 section_enumerator_separator
@@ -1498,7 +1530,7 @@ borderless
 Default: "standard".  Option: ``--table-style``.
 
 [xetex writer]
---------------
+~~~~~~~~~~~~~~
 
 The xetex writer derives from the latex2e writer, and shares
 all settings defined in the `[latex2e writer]`_ section.  The
@@ -1507,42 +1539,25 @@ before the "[xetex writer]" section.
 
 The following settings differ from those of the latex2e writer:
 
-font_encoding
+font_encoding_
     Disabled  (XeTeX uses Unicode-encoded fonts).
 
-.. _latex_preamble [xetex writer]:
+latex_preamble_
+    Default: Font setup for `Linux Libertine`_,::
 
-latex_preamble
-~~~~~~~~~~~~~~
-
-LaTeX code that will be inserted in the document preamble.
-
-Default:
-  Font setup for `Linux Libertine`_,::
-
-    % Linux Libertine (free, wide coverage, not only for Linux)
-    \setmainfont{Linux Libertine O}
-    \setsansfont{Linux Biolinum O}
-    \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
+      % Linux Libertine (free, wide coverage, not only for Linux)
+      \setmainfont{Linux Libertine O}
+      \setsansfont{Linux Biolinum O}
+      \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
 
   The optional argument ``HyphenChar=None`` to the monospace font
   prevents word hyphenation in literal text.
 
-
-Option: ``--latex-preamble``.
+template__
+    Default: "xelatex.tex"
 
 .. _Linux Libertine: http://www.linuxlibertine.org/
-
-.. _template [xetex writer]:
-
-template
-~~~~~~~~
-
-Path to template file.
-
-Default: "xelatex.tex" in the ``docutils/writers/latex2e/``
-directory (installed automatically; for the exact machine-specific
-path, use the ``--help`` option).  Options: ``--template``.
+__ `template [latex2e writer]`_
 
 
 [odf_odt writer]
@@ -1553,7 +1568,7 @@ The following command line options are specific to ``odtwriter``:
 stylesheet
 ~~~~~~~~~~
 
-Specify a stylesheet URL, used verbatim.  
+Specify a stylesheet URL, used verbatim.
 
 Default: writers/odf_odt/styles.odt in the installation directory.
 
diff --git a/docutils/utils/__init__.py b/docutils/utils/__init__.py
index 5a96da2a7..3c979117f 100644
--- a/docutils/utils/__init__.py
+++ b/docutils/utils/__init__.py
@@ -513,8 +513,28 @@ def get_stylesheet_list(settings):
     stylesheets = settings.stylesheet_path or settings.stylesheet or []
     # programmatically set default can be string or unicode:
     if not isinstance(stylesheets, list):
-        stylesheets = [cls.strip() for cls in stylesheets.split(',')]
-    return stylesheets
+        stylesheets = [path.strip() for path in stylesheets.split(',')]
+    # expand relative paths if found in stylesheet-dirs:
+    return [find_file_in_dirs(path, settings.stylesheet_dirs)
+            for path in stylesheets]
+
+def find_file_in_dirs(path, dirs):
+    """
+    Search for `path` in the list of directories `dirs`.
+
+    Return the first expansion that matches an existing file.
+    """
+    if os.path.isabs(path):
+        return path
+    for d in dirs:
+        if d == '.':
+            f = path
+        else:
+            d = os.path.expanduser(d)
+            f = os.path.join(d, path)
+        if os.path.exists(f):
+            return f
+    return path
 
 def get_trim_footnote_ref_space(settings):
     """
diff --git a/docutils/writers/html4css1/__init__.py b/docutils/writers/html4css1/__init__.py
index cef8828cd..3dd2d1108 100644
--- a/docutils/writers/html4css1/__init__.py
+++ b/docutils/writers/html4css1/__init__.py
@@ -34,9 +34,8 @@ import docutils
 from docutils import frontend, nodes, utils, writers, languages, io
 from docutils.utils.error_reporting import SafeString
 from docutils.transforms import writer_aux
-from docutils.utils.math import unichar2tex, pick_math_environment
+from docutils.utils.math import unichar2tex, pick_math_environment, math2html
 from docutils.utils.math.latex2mathml import parse_latex_math
-from docutils.utils.math.math2html import math2html
 
 class Writer(writers.Writer):
 
@@ -44,10 +43,8 @@ class Writer(writers.Writer):
     """Formats this writer supports."""
 
     default_stylesheet = 'html4css1.css'
-
-    default_stylesheet_path = utils.relative_path(
-        os.path.join(os.getcwd(), 'dummy'),
-        os.path.join(os.path.dirname(__file__), default_stylesheet))
+    default_stylesheet_dirs = ['.', utils.relative_path(
+        os.path.join(os.getcwd(), 'dummy'), os.path.dirname(__file__))]
 
     default_template = 'template.txt'
 
@@ -62,19 +59,20 @@ class Writer(writers.Writer):
           % default_template_path,
           ['--template'],
           {'default': default_template_path, 'metavar': '<file>'}),
-        ('Specify comma separated list of stylesheet URLs. '
+         ('Comma separated list of stylesheet URLs. '
           'Overrides previous --stylesheet and --stylesheet-path settings.',
           ['--stylesheet'],
-          {'metavar': '<URL>', 'overrides': 'stylesheet_path',
+          {'metavar': '<URL[,URL,...]>', 'overrides': 'stylesheet_path',
            'validator': frontend.validate_comma_separated_list}),
-         ('Specify comma separated list of stylesheet paths. '
-          'With --link-stylesheet, '
+         ('Comma separated list of stylesheet paths. '
+          'Relative paths are expanded if a matching file is found in '
+          'the --stylesheet-dirs. With --link-stylesheet, '
           'the path is rewritten relative to the output HTML file. '
-          'Default: "%s"' % default_stylesheet_path,
+          'Default: "%s"' % default_stylesheet,
           ['--stylesheet-path'],
-          {'metavar': '<file>', 'overrides': 'stylesheet',
+          {'metavar': '<file[,file,...]>', 'overrides': 'stylesheet',
            'validator': frontend.validate_comma_separated_list,
-           'default': [default_stylesheet_path]}),
+           'default': [default_stylesheet]}),
          ('Embed the stylesheet(s) in the output HTML file.  The stylesheet '
           'files must be accessible during processing. This is the default.',
           ['--embed-stylesheet'],
@@ -84,6 +82,13 @@ class Writer(writers.Writer):
           'Default: embed stylesheets.',
           ['--link-stylesheet'],
           {'dest': 'embed_stylesheet', 'action': 'store_false'}),
+         ('Comma-separated list of directories where stylesheets are found. '
+          'Used by --stylesheet-path when expanding relative path arguments. '
+          'Default: "%s"' % default_stylesheet_dirs,
+          ['--stylesheet-dirs'],
+          {'metavar': '<dir[,dir,...]>',
+           'validator': frontend.validate_comma_separated_list,
+           'default': default_stylesheet_dirs}),
          ('Specify the initial header level.  Default is 1 for "<h1>".  '
           'Does not affect document title & subtitle (see --no-doc-title).',
           ['--initial-header-level'],
@@ -1207,7 +1212,9 @@ class HTMLTranslator(nodes.NodeVisitor):
                 self.mathjax_url = self.math_output_options[0]
             self.math_header = self.mathjax_script % self.mathjax_url
         elif self.math_output == 'html':
-            math_code = math2html(math_code)
+            # TODO: fix display mode in matrices and fractions
+            # math2html.DocumentParameters.displaymode = (math_env != '')
+            math_code = math2html.math2html(math_code)
         elif self.math_output == 'mathml':
             self.doctype = self.doctype_mathml
             self.content_type = self.content_type_mathml
diff --git a/docutils/writers/latex2e/__init__.py b/docutils/writers/latex2e/__init__.py
index b45c579c3..3d1676f65 100644
--- a/docutils/writers/latex2e/__init__.py
+++ b/docutils/writers/latex2e/__init__.py
@@ -87,13 +87,15 @@ class Writer(writers.Writer):
          '".sty" or omitted and with \\input else. '
           ' Overrides previous --stylesheet and --stylesheet-path settings.',
           ['--stylesheet'],
-          {'default': '', 'metavar': '<file>',
+          {'default': '', 'metavar': '<file[,file,...]>',
            'overrides': 'stylesheet_path',
            'validator': frontend.validate_comma_separated_list}),
-         ('Like --stylesheet, but the path is rewritten '
-          'relative to the output file. ',
+         ('Comma separated list of LaTeX packages/stylesheets. '
+          'Relative paths are expanded if a matching file is found in '
+          'the --stylesheet-dirs. With --link-stylesheet, '
+          'the path is rewritten relative to the output *.tex file. ',
           ['--stylesheet-path'],
-          {'metavar': '<file>', 'overrides': 'stylesheet',
+          {'metavar': '<file[,file,...]>', 'overrides': 'stylesheet',
            'validator': frontend.validate_comma_separated_list}),
          ('Link to the stylesheet(s) in the output file. (default)',
           ['--link-stylesheet'],
@@ -103,6 +105,13 @@ class Writer(writers.Writer):
           ['--embed-stylesheet'],
           {'default': 0, 'action': 'store_true',
            'validator': frontend.validate_boolean}),
+         ('Comma-separated list of directories where stylesheets are found. '
+          'Used by --stylesheet-path when expanding relative path arguments. '
+          'Default: "."',
+          ['--stylesheet-dirs'],
+          {'metavar': '<dir[,dir,...]>',
+           'validator': frontend.validate_comma_separated_list,
+           'default': ['.']}),
          ('Customization by LaTeX code in the preamble. '
           'Default: select PDF standard fonts (Times, Helvetica, Courier).',
           ['--latex-preamble'],
diff --git a/test/test_utils.py b/test/test_utils.py
index dec123ee4..fd8d0d273 100755
--- a/test/test_utils.py
+++ b/test/test_utils.py
@@ -287,6 +287,19 @@ class HelperFunctionsTests(unittest.TestCase):
         target = os.path.join(u'eggs', u'fileB')
         self.assertEqual(utils.relative_path(None, target), u'eggs/fileB')
 
+    def test_find_file_in_dirs(self):
+        # Search for file `path` in the sequence of directories `dirs`.
+        # Return the first expansion that matches an existing file.
+        dirs = ('nonex', '.', '..')
+        self.assertEqual(utils.find_file_in_dirs('HISTORY.txt', dirs),
+                         '../HISTORY.txt')
+        # Return `path` if the file exists in the cwd or if there is no match
+        self.assertEqual(utils.find_file_in_dirs('alltests.py', dirs),
+                         'alltests.py')
+        self.assertEqual(utils.find_file_in_dirs('gibts/nicht.txt', dirs),
+                         'gibts/nicht.txt')
+
+
 
 if __name__ == '__main__':
     unittest.main()
diff --git a/test/test_writers/test_html4css1_misc.py b/test/test_writers/test_html4css1_misc.py
index b0f32a351..b011a1566 100755
--- a/test/test_writers/test_html4css1_misc.py
+++ b/test/test_writers/test_html4css1_misc.py
@@ -30,12 +30,62 @@ class EncodingTestCase(DocutilsTestSupport.StandardTestCase):
         # xmlcharrefreplace handler is used.
         self.assertIn(b('EUR = &#8364;'), result)
 
+class SettingsTestCase(DocutilsTestSupport.StandardTestCase):
+    data = 'test'
+
+    def test_default_stylesheet(self):
+        # default style sheet, embedded
+        mysettings = {'_disable_config': True,}
+        styles = core.publish_parts(self.data, writer_name='html4css1',
+                                  settings_overrides=mysettings)['stylesheet']
+        self.assertIn('Default cascading style sheet '
+                      'for the HTML output of Docutils.', styles)
+
+    def test_default_stylesheet_linked(self):
+        # default style sheet, linked
+        mysettings = {'_disable_config': True,
+                      'embed_stylesheet': False}
+        styles = core.publish_parts(self.data, writer_name='html4css1',
+                                  settings_overrides=mysettings)['stylesheet']
+        self.assertIn('docutils/writers/html4css1/html4css1.css', styles)
+
+    def test_math_stylesheet_linked(self):
+        # default + math style sheet, linked
+        mysettings = {'_disable_config': True,
+                      'embed_stylesheet': False,
+                      'stylesheet_path': 'html4css1.css, math.css'}
+        styles = core.publish_parts(self.data, writer_name='html4css1',
+                                  settings_overrides=mysettings)['stylesheet']
+        self.assertIn('docutils/writers/html4css1/html4css1.css', styles)
+        self.assertIn('docutils/writers/html4css1/math.css', styles)
+
+    def test_custom_stylesheet_linked(self):
+        # default + custom style sheet, linked
+        mysettings = {'_disable_config': True,
+                      'embed_stylesheet': False,
+                      'stylesheet_path': 'html4css1.css, '
+                                         'data/ham.css'}
+        styles = core.publish_parts(self.data, writer_name='html4css1',
+                                  settings_overrides=mysettings)['stylesheet']
+        self.assertIn('docutils/writers/html4css1/html4css1.css', styles)
+        self.assertIn('href="data/ham.css"', styles)
+
+    def test_custom_stylesheet_dir(self):
+        mysettings = {'_disable_config': True,
+                      'embed_stylesheet': False,
+                      'stylesheet_dirs': ('../docutils/writers/html4css1/',
+                                          'data'),
+                      'stylesheet_path': 'html4css1.css, ham.css'}
+        styles = core.publish_parts(self.data, writer_name='html4css1',
+                                  settings_overrides=mysettings)['stylesheet']
+        self.assertIn('docutils/writers/html4css1/html4css1.css', styles)
+        self.assertIn('href="data/ham.css"', styles)
+
 class MathTestCase(DocutilsTestSupport.StandardTestCase):
-    
+
     """Attention: This class tests the current implementation of maths support
     which is open to change in future Docutils releases. """
 
-    settings_overrides={'_disable_config': True,}
     mathjax_script = '<script type="text/javascript" src="%s">'
     default_mathjax_url = ('http://cdn.mathjax.org/mathjax/latest/MathJax.js'
                            '?config=TeX-AMS-MML_HTMLorMML')
@@ -45,40 +95,40 @@ class MathTestCase(DocutilsTestSupport.StandardTestCase):
 
     def test_math_output_default(self):
         # Currently MathJax with default URL. Likely to change to HTML!
-        mysettings = self.settings_overrides
+        mysettings = {'_disable_config': True,}
         head = core.publish_parts(self.data, writer_name='html4css1',
                                   settings_overrides=mysettings)['head']
         self.assertIn(self.mathjax_script % self.default_mathjax_url, head)
-        
+
     def test_math_output_mathjax(self):
         # Explicitly specifying math_output=MathJax, case insensitively
         # use default MathJax URL
-        mysettings = self.settings_overrides.copy()
-        mysettings.update({'math_output': 'MathJax'})
+        mysettings = {'_disable_config': True,
+                      'math_output': 'MathJax'}
         head = core.publish_parts(self.data, writer_name='html4css1',
             settings_overrides=mysettings)['head']
         self.assertIn(self.mathjax_script % self.default_mathjax_url, head)
 
     def test_math_output_mathjax_custom(self):
         # Customizing MathJax URL
-        mysettings = self.settings_overrides.copy()
-        mysettings.update({'math_output': 
-                           'mathjax %s' % self.custom_mathjax_url})
+        mysettings = {'_disable_config': True,
+                      'math_output':
+                      'mathjax %s' % self.custom_mathjax_url}
         head = core.publish_parts(self.data, writer_name='html4css1',
             settings_overrides=mysettings)['head']
         self.assertIn(self.mathjax_script % self.custom_mathjax_url, head)
-        
+
     def test_math_output_html(self):
         # There should be no MathJax script when math_output is not MathJax
-        mysettings = self.settings_overrides.copy()
-        mysettings.update({'math_output': 'HTML'})
+        mysettings = {'_disable_config': True,
+                      'math_output': 'HTML'}
         head = core.publish_parts(self.data, writer_name='html4css1',
             settings_overrides=mysettings)['head']
         self.assertNotIn('MathJax.js', head)
-        
+
     def test_math_output_mathjax_no_math(self):
-        mysettings = self.settings_overrides.copy()
-        mysettings.update({'math_output': 'MathJax'})
+        mysettings = {'_disable_config': True,
+                      'math_output': 'MathJax'}
         # There should be no math script when text does not contain math
         head = core.publish_parts('No math.', writer_name='html4css1')['head']
         self.assertNotIn('MathJax', head)