Remove html_permalink_text again and give meaning to html_add_permalinks.

CHANGES

@@ -25,7 +25,8 @@ Release 1.1 (in development)
 
 * #526: Added Iranian translation.
 
-* #559: Added :confval:`html_permalink_text`.
+* #559: :confval:`html_add_permalinks` is now a string giving the
+  text to display in permalinks.
 
 
 Release 1.0.6 (in development)

doc/config.rst

@@ -499,20 +499,18 @@ that use Sphinx' HTMLWriter class.
 
 .. confval:: html_add_permalinks
 
-   If true, Sphinx will add "permalinks" for each heading and description
-   environment as paragraph signs that become visible when the mouse hovers over
-   them.  Default: ``True``.
+   Sphinx will add "permalinks" for each heading and description environment as
+   paragraph signs that become visible when the mouse hovers over them.
+
+   This value determines the text for the permalink; it defaults to ``"¶"``.
+   Set it to ``None`` or the empty string to disable permalinks.
 
    .. versionadded:: 0.6
       Previously, this was always activated.
 
-.. confval:: html_permalink_text
-
-   A string specifying the text which should be used for "permalinks".
-   Default: ``u'\u00B6'``.
-
-   .. versionadded:: 1.1
-      Previously, this was always the current default value.
+   .. versionchanged:: 1.1
+      This can now be a string to select the actual text of the link.
+      Previously, only boolean values were accepted.
 
 .. confval:: html_sidebars
 

sphinx/config.py

@@ -92,8 +92,7 @@ class Config(object):
         html_additional_pages = ({}, 'html'),
         html_use_modindex = (True, 'html'),  # deprecated
         html_domain_indices = (True, 'html'),
-        html_add_permalinks = (True, 'html'),
-        html_permalink_text = (u'\u00B6', 'html'),
+        html_add_permalinks = (u'\u00B6', 'html'),
         html_use_index = (True, 'html'),
         html_split_index = (False, 'html'),
         html_copy_source = (True, 'html'),

sphinx/writers/html.py

@@ -59,8 +59,11 @@ class HTMLTranslator(BaseTranslator):
         self.highlightlang = builder.config.highlight_language
         self.highlightlinenothreshold = sys.maxint
         self.protect_literal_text = 0
-        self.add_permalinks = builder.config.html_add_permalinks
-        self.permalink_text = builder.config.html_permalink_text
+        self.permalink_text = builder.config.html_add_permalinks
+        # support backwards-compatible setting to a bool
+        if not isinstance(self.permalink_text, basestring):
+            self.permalink_text = self.permalink_text and u'\u00B6' or ''
+        self.permalink_text = self.encode(self.permalink_text)
         self.secnumber_suffix = builder.config.html_secnumber_suffix
 
     def visit_start_of_file(self, node):
@@ -82,13 +85,12 @@ class HTMLTranslator(BaseTranslator):
                and node['ids'] and node['first']:
             self.body.append('<!--[%s]-->' % node['ids'][0])
     def depart_desc_signature(self, node):
-        if node['ids'] and self.add_permalinks and self.builder.add_permalinks:
+        if node['ids'] and self.permalink_text and self.builder.add_permalinks:
             self.body.append(u'<a class="headerlink" href="#%s" '
                              % node['ids'][0] +
                              u'title="%s">%s</a>' % (
                              _('Permalink to this definition'),
-                             self.permalink_text)
-                             )
+                             self.permalink_text))
         self.body.append('</dt>\n')
 
     def visit_desc_addname(self, node):
@@ -483,7 +485,7 @@ class HTMLTranslator(BaseTranslator):
 
     def depart_title(self, node):
         close_tag = self.context[-1]
-        if (self.add_permalinks and self.builder.add_permalinks and
+        if (self.permalink_text and self.builder.add_permalinks and
             node.parent.hasattr('ids') and node.parent['ids']):
             aname = node.parent['ids'][0]
             # add permalink anchor