Make system messages stand out in HTML output.

TODO

@@ -1,6 +1,7 @@
 Global TODO
 ===========
 
+- "often used" combo box in sidebar
 - discuss and debug comments system
 - navigation links at the bottom too
 - write new Makefile, handle automatic version info and checkout
@@ -11,4 +12,3 @@ Global TODO
 - look at the old tools/ scripts, what functionality should be rewritten
 - add search via Xapian?
 - optionally have a contents tree view in the sidebar (AJAX based)?
-

converter/newfiles/doc_markup.rst

@@ -362,11 +362,17 @@ in a different style:
 
 .. describe:: envvar
 
-   An environment variable. Index entries are generated.
+   An environment variable.  Index entries are generated.
 
 .. describe:: file
 
-   The name of a file or directory.
+   The name of a file or directory.  Within the contents, you can use curly
+   braces to indicate a "variable" part, for example::
+
+      ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
+
+   In the built documentation, the ``x`` will be displayed differently to
+   indicate that it is to be replaced by the Python minor version.
 
 .. describe:: guilabel
 

sphinx/roles.py

@@ -21,9 +21,6 @@ ws_re = re.compile(r'\s+')
 generic_docroles = {
     'command' : nodes.strong,
     'dfn' : nodes.emphasis,
-    'file' : nodes.emphasis,
-    'filenq' : nodes.emphasis,
-    'filevar' : nodes.emphasis,
     'guilabel' : nodes.strong,
     'kbd' : nodes.literal,
     'keyword' : nodes.literal,
@@ -114,7 +111,25 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
 
 
 def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
-    return [nodes.emphasis(rawtext, text.replace('-->', u'\N{TRIANGULAR BULLET}'))], []
+    return [nodes.emphasis(
+        rawtext, utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], []
+
+
+_filevar_re = re.compile('{([^}]+)}')
+
+def file_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+    text = utils.unescape(text)
+    retnodes = []
+    pos = 0
+    for m in _filevar_re.finditer(text):
+        if m.start() > pos:
+            txt = text[pos:m.start()]
+            retnodes.append(nodes.literal(txt, txt))
+        retnodes.append(nodes.emphasis('', '', nodes.literal(m.group(1), m.group(1))))
+        pos = m.end()
+    if pos < len(text):
+        retnodes.append(nodes.literal(text[pos:], text[pos:]))
+    return retnodes, []
 
 
 specific_docroles = {
@@ -137,6 +152,7 @@ specific_docroles = {
     'token' : xfileref_role,
 
     'menuselection' : menusel_role,
+    'file' : file_role,
 }
 
 for rolename, func in specific_docroles.iteritems():

sphinx/style/default.css

@@ -744,6 +744,12 @@ form.comment textarea {
     margin-bottom: 10px;
 }
 
+.system-message {
+    background-color: #fda;
+    padding: 5px;
+    border: 3px solid red;
+}
+
 /* :::: PRINT :::: */
 @media print {
     div.documentwrapper {