Added "cloak_email_addresses" setting & support; updated test & docs. Thanks to Barry Warsaw & Ned Batchelder for the idea and initial patch.

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

7 files changed, 79 insertions, 9 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 95af46972..7218ac5bc 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -135,6 +135,7 @@ Changes Since 0.3.7
     support.
   - Added support for table stub columns.
   - Added support for ``align`` attribute on ``figure`` elements.
+  - Added the ``cloak_email_addresses`` setting & support.
 
 * docutils/writers/latex2e.py:
 
diff --git a/docutils/THANKS.txt b/docutils/THANKS.txt
index 91b90f259..26b6e9114 100644
--- a/docutils/THANKS.txt
+++ b/docutils/THANKS.txt
@@ -17,6 +17,7 @@ donations, tasty treats, and related projects:
 * Aahz
 * David Abrahams
 * David Ascher
+* Ned Batchelder
 * Heiko Baumann
 * Eric Bellot
 * Ian Bicking
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 7e93626a1..ebff78289 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -527,6 +527,19 @@ attribution
 
     __ `attribution [latex2e writer]`_
 
+_`cloak_email_addresses`
+    Scramble email addresses to confuse harvesters.  In the visible
+    text of an email address, the "@" will be replaced by "at", and
+    all periods (".") will be replaced by "dot", with spaces added.
+    In the reference URI, the address will be replaced by %-escapes.
+    For example, "abc@example.org" will be output as::
+
+        <a class="reference"
+         href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
+        abc at example dot org</a>
+
+    Default: don't cloak (None).  Option: ``--cloak-email``.
+
 _`compact_lists`
     Remove extra vertical whitespace between items of bullet lists and
     enumerated lists, when list items are "simple" (i.e., all items
diff --git a/docutils/docutils/writers/html4css1.py b/docutils/docutils/writers/html4css1.py
index cdc8bf583..cdb3f7f88 100644
--- a/docutils/docutils/writers/html4css1.py
+++ b/docutils/docutils/writers/html4css1.py
@@ -101,7 +101,12 @@ class Writer(writers.Writer):
          ('Omit the XML declaration.  Use with caution.',
           ['--no-xml-declaration'],
           {'dest': 'xml_declaration', 'default': 1, 'action': 'store_false',
-           'validator': frontend.validate_boolean}),))
+           'validator': frontend.validate_boolean}),
+         ('Scramble email addresses to confuse harvesters.  '
+          'For example, "abc@example.org" will become '
+          '``<a href="mailto:%61%62%63%40...">abc at example dot org</a>``.',
+          ['--cloak-email-addresses'],
+          {'action': 'store_true', 'validator': frontend.validate_boolean}),))
 
     relative_path_settings = ('stylesheet_path',)
 
@@ -240,6 +245,7 @@ class HTMLTranslator(nodes.NodeVisitor):
         self.header = []
         self.footer = []
         self.in_document_title = 0
+        self.in_mailto = 0
 
     def astext(self):
         return ''.join(self.head_prefix + self.head
@@ -259,6 +265,20 @@ class HTMLTranslator(nodes.NodeVisitor):
         text = text.replace(u'\u00a0', "&nbsp;")
         return text
 
+    def cloak_mailto(self, uri):
+        """Try to hide a mailto: URL from harvesters."""
+        addr = uri.split(':', 1)[1]
+        if '?' in addr:
+            addr, query = addr.split('?', 1)
+            query = '?' + query
+        else:
+            query = ''
+        escaped = ['%%%02X' % ord(c) for c in addr]
+        return 'mailto:%s%s' % (''.join(escaped), query)
+
+    def cloak_email(self, addr):
+        return addr.replace('@', ' at ').replace('.', ' dot ')
+
     def attval(self, text,
                whitespace=re.compile('[\n\r\t\v\f]')):
         """Cleanse, HTML encode, and return attribute value text."""
@@ -315,7 +335,10 @@ class HTMLTranslator(nodes.NodeVisitor):
             node[-1]['classes'].append('last')
 
     def visit_Text(self, node):
-        self.body.append(self.encode(node.astext()))
+        text = node.astext()
+        if self.in_mailto and self.settings.cloak_email_addresses:
+            text = self.cloak_email(text)
+        self.body.append(self.encode(text))
 
     def depart_Text(self, node):
         pass
@@ -1086,6 +1109,10 @@ class HTMLTranslator(nodes.NodeVisitor):
             self.context.append('</div>\n')
         if node.has_key('refuri'):
             href = node['refuri']
+            if ( self.settings.cloak_email_addresses
+                 and href.startswith('mailto:')):
+                href = self.cloak_mailto(href)
+                self.in_mailto = 1
         else:
             assert node.has_key('refid'), \
                    'References must have "refuri" or "refid" attribute.'
@@ -1096,6 +1123,7 @@ class HTMLTranslator(nodes.NodeVisitor):
     def depart_reference(self, node):
         self.body.append('</a>')
         self.body.append(self.context.pop())
+        self.in_mailto = 0
 
     def visit_revision(self, node):
         self.visit_docinfo_item(node, 'revision', meta=None)
diff --git a/docutils/test/functional/expected/pep_html.html b/docutils/test/functional/expected/pep_html.html
index 6e990e61a..00d7d1d2b 100644
--- a/docutils/test/functional/expected/pep_html.html
+++ b/docutils/test/functional/expected/pep_html.html
@@ -38,7 +38,7 @@ to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
 </tr>
 <tr class="field"><th class="field-name">Author:</th><td class="field-body">John Doe &lt;john&#32;&#97;t&#32;example.org&gt;</td>
 </tr>
-<tr class="field"><th class="field-name">Discussions-To:</th><td class="field-body">&lt;<a class="reference" href="mailto:devnull&#64;example.org?subject=PEP%20100">devnull&#32;&#97;t&#32;example.org</a>&gt;</td>
+<tr class="field"><th class="field-name">Discussions-To:</th><td class="field-body">&lt;<a class="reference" href="mailto:%64%65%76%6E%75%6C%6C%40%65%78%61%6D%70%6C%65%2E%6F%72%67?subject=PEP%20100">devnull&#32;&#97;t&#32;example.org</a>&gt;</td>
 </tr>
 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
 </tr>
@@ -56,18 +56,35 @@ to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
 <div class="contents topic" id="contents">
 <p class="topic-title first"><a name="contents">Contents</a></p>
 <ul class="simple">
-<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
-<li><a class="reference" href="#copyright" id="id3" name="id3">Copyright</a></li>
+<li><a class="reference" href="#abstract" id="id5" name="id5">Abstract</a></li>
+<li><a class="reference" href="#copyright" id="id6" name="id6">Copyright</a></li>
+<li><a class="reference" href="#references-and-footnotes" id="id7" name="id7">References and Footnotes</a></li>
 </ul>
 </div>
 <div class="section" id="abstract">
-<h1><a class="toc-backref" href="#id2" name="abstract">Abstract</a></h1>
-<p>Just a test.</p>
+<h1><a class="toc-backref" href="#id5" name="abstract">Abstract</a></h1>
+<p>This is just a test <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>.  See the <a class="reference" href="http://www.python.org/peps/">PEP repository</a> <a class="footnote-reference" href="#id3" id="id4" name="id4">[2]</a> for the real
+thing.</p>
 </div>
 <div class="section" id="copyright">
-<h1><a class="toc-backref" href="#id3" name="copyright">Copyright</a></h1>
+<h1><a class="toc-backref" href="#id6" name="copyright">Copyright</a></h1>
 <p>This document has been placed in the public domain.</p>
 </div>
+<div class="section" id="references-and-footnotes">
+<h1><a class="toc-backref" href="#id7" name="references-and-footnotes">References and Footnotes</a></h1>
+<table class="docutils footnote" frame="void" id="id2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>PEP editors: <a class="reference" href="mailto:%70%65%70%73%40%70%79%74%68%6F%6E%2E%6F%72%67">peps at python dot org</a></td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id4" name="id3">[2]</a></td><td><a class="reference" href="http://www.python.org/peps/">http://www.python.org/peps/</a></td></tr>
+</tbody>
+</table>
+</div>
 
 </div>
 </body>
diff --git a/docutils/test/functional/input/pep_html.txt b/docutils/test/functional/input/pep_html.txt
index 5cca3726e..483077131 100644
--- a/docutils/test/functional/input/pep_html.txt
+++ b/docutils/test/functional/input/pep_html.txt
@@ -14,10 +14,19 @@ Post-History: 13-Jun-2001
 Abstract
 ========
 
-Just a test.
+This is just a test [#]_.  See the `PEP repository`_ for the real
+thing.
+
+.. _PEP repository: http://www.python.org/peps/
 
 
 Copyright
 =========
 
 This document has been placed in the public domain.
+
+
+References and Footnotes
+========================
+
+.. [#] PEP editors: peps@python.org
diff --git a/docutils/test/functional/tests/pep_html.py b/docutils/test/functional/tests/pep_html.py
index 47e8b52d3..efb067ac4 100644
--- a/docutils/test/functional/tests/pep_html.py
+++ b/docutils/test/functional/tests/pep_html.py
@@ -14,3 +14,4 @@ settings_overrides['template'] = "../tools/pep-html-template"
 settings_overrides['python_home'] = "http://www.python.org"
 settings_overrides['pep_home'] = "http://www.python.org/peps"
 settings_overrides['no_random'] = 1
+settings_overrides['cloak_email_addresses'] = 1