Fix for "Footnote titles not translatable #244" (#247)

* Fix metadata extra to consume only initial fenced block

As noted in Issue #234

  #234

the metadata extra uses regex that is too greedy and can eat more than
what is intended if links appear in the markdown. This small change
corrects this.

Resolves: #234

* Add David Lowry-Duda as a contributor

* Updated fix on metadata to work without fences

The previous commit towards resolving Issue #234 didn't incorporate
previous behavior that fences shouldn't be necessary. First introduced
in Pull Request #215, metadata should be accessible even without
including `---` fences around opening metadata.

This fix now preserves the ability to use either `---` fences (maybe
without a subsequent blank line) or no fences (but with a blank line).

Resolves: #234

* Add language support for footnotes

As noted in Issue #244, it is not currently possible to customize the
text used in footnotes. It is always "Jump back to footnote <number> in
the text." It may be desirable to provide a programmable way to supply
different text, such as in different languages.

This provides that support when used from within the interpreter. Usage
is

    markdowner = markdown2.Markdown(extras=["footnotes"])
    markdowner.footnote_title = "Retournez vers footnote %d. "
    markdowner.convert(text)

This also adds the ability to change the footnote link text, through

    markdowner.footnote_link_text = "<something>"

because they are very similar.

Resolves: #244

* Added footenoteBackLink class to footnotes

* Make user-provided backlinks for custom footnotes more natural

Users no longer need to include html closing tags in custom definitions
for footnote_title or footnote_link_text. And naked except Exception
statements have been replaced with the expected errors. These notes were
made by nicholasserra in Pull Request #247

* "title=" no longer required for custom footnote title

* Added ability to provide custom class variables to Markdown instance

It is now possible to provide class variables to the Markdown instance
in the testing library by creating a file.customargs file containing a
dictionary.

For example, one might have have a footnotes_customtitle test, which
could be tested by making the following file.

footnotes_customtitle.customargs
---
{"footnote_title" : "Return to %d above"}
---

When testing footnote_customtitle, the Markdown instance will be passed
the variable, essentially like

```
markdowner = markdown2.Markdown(*opts)
markdowner.footnote_title = "Return to %d above"
text = markdowner.convert(html)
```

This was done to allow tests for #247

* Added missing quotes to footnote_titles

* Added test for custom footnote_title to test suite

There is now a test for custom footnote_titles in the test suite.

Adds tests for: PR #247
Resolves: #244

* Change custom footnotes to function inline

The behavior of custom footnote text is now implemented in the following
way, as recommended in #247

```
markdown2.markdown(text, extras=["footnotes"],
                   footnote_title="Regresar a %d.")
```

This is in contrast to the previous implementation, which required an
intermediate step defining a class variable. As the interface changed,
it was necessary to rewrite the relevant test, which now defines the
customization in the footnotes_custom.opts file.

Author: davidlowryduda

lib/markdown2.py

@@ -162,22 +162,28 @@ class MarkdownError(Exception):
 def markdown_path(path, encoding="utf-8",
                   html4tags=False, tab_width=DEFAULT_TAB_WIDTH,
                   safe_mode=None, extras=None, link_patterns=None,
+                  footnote_title=None, footnote_return_symbol=None,
                   use_file_vars=False):
     fp = codecs.open(path, 'r', encoding)
     text = fp.read()
     fp.close()
     return Markdown(html4tags=html4tags, tab_width=tab_width,
                     safe_mode=safe_mode, extras=extras,
                     link_patterns=link_patterns,
+                    footnote_title=footnote_title,
+                    footnote_return_symbol=footnote_return_symbol,
                     use_file_vars=use_file_vars).convert(text)
 
 
 def markdown(text, html4tags=False, tab_width=DEFAULT_TAB_WIDTH,
              safe_mode=None, extras=None, link_patterns=None,
+             footnote_title=None, footnote_return_symbol=None,
              use_file_vars=False):
     return Markdown(html4tags=html4tags, tab_width=tab_width,
                     safe_mode=safe_mode, extras=extras,
                     link_patterns=link_patterns,
+                    footnote_title=footnote_title,
+                    footnote_return_symbol=footnote_return_symbol,
                     use_file_vars=use_file_vars).convert(text)
 
 
@@ -203,7 +209,9 @@ class Markdown(object):
     _ws_only_line_re = re.compile(r"^[ \t]+$", re.M)
 
     def __init__(self, html4tags=False, tab_width=4, safe_mode=None,
-                 extras=None, link_patterns=None, use_file_vars=False):
+                 extras=None, link_patterns=None,
+                 footnote_title=None, footnote_return_symbol=None,
+                 use_file_vars=False):
         if html4tags:
             self.empty_element_suffix = ">"
         else:
@@ -233,6 +241,8 @@ def __init__(self, html4tags=False, tab_width=4, safe_mode=None,
         self._instance_extras = self.extras.copy()
 
         self.link_patterns = link_patterns
+        self.footnote_title = footnote_title
+        self.footnote_return_symbol = footnote_return_symbol
         self.use_file_vars = use_file_vars
         self._outdent_re = re.compile(r'^(\t|[ ]{1,%d})' % tab_width, re.M)
 
@@ -2037,15 +2047,31 @@ def _add_footnotes(self, text):
                 '<hr' + self.empty_element_suffix,
                 '<ol>',
             ]
+
+            if not self.footnote_title:
+                self.footnote_title = "Jump back to footnote %d in the text."
+            if not self.footnote_return_symbol:
+                self.footnote_return_symbol = "&#8617;"
+
             for i, id in enumerate(self.footnote_ids):
                 if i != 0:
                     footer.append('')
                 footer.append('<li id="fn-%s">' % id)
                 footer.append(self._run_block_gamut(self.footnotes[id]))
-                backlink = ('<a href="#fnref-%s" '
-                    'class="footnoteBackLink" '
-                    'title="Jump back to footnote %d in the text.">'
-                    '&#8617;</a>' % (id, i+1))
+                try:
+                    backlink = ('<a href="#fnref-%s" ' +
+                            'class="footnoteBackLink" ' +
+                            'title="' + self.footnote_title + '">' +
+                            self.footnote_return_symbol +
+                            '</a>') % (id, i+1)
+                except TypeError:
+                    log.debug("Footnote error. `footnote_title` "
+                              "must include parameter. Using defaults.")
+                    backlink = ('<a href="#fnref-%s" '
+                        'class="footnoteBackLink" '
+                        'title="Jump back to footnote %d in the text.">'
+                        '&#8617;</a>' % (id, i+1))
+
                 if footer[-1].endswith("</p>"):
                     footer[-1] = footer[-1][:-len("</p>")] \
                         + '&#160;' + backlink + "</p>"

test/test_markdown2.py

@@ -90,8 +90,7 @@ def _assertMarkdownPath(self, text_path, encoding="utf-8", opts=None,
             extra["metadata"] = json_loads(
                 codecs.open(metadata_path, 'r', encoding=encoding).read())
             extra["metadata_path"] = metadata_path
-        self._assertMarkdown(text, html, text_path, html_path, opts=opts,
-            **extra)
+        self._assertMarkdown(text, html, text_path, html_path, opts=opts, **extra)
 
     def _assertMarkdown(self, text, html, text_path=None, html_path=None,
             opts=None, toc_html=None, toc_html_path=None, metadata=None,
@@ -197,9 +196,10 @@ def generate_tests(cls):
             if not exists(metadata_path):
                 metadata_path = None
 
-            test_func = lambda self, t=text_path, o=opts, c=toc_html_path, m=metadata_path: \
-                self._assertMarkdownPath(t, opts=o, toc_html_path=c,
-                                         metadata_path=m)
+            test_func = lambda self, t=text_path, o=opts, c=toc_html_path, \
+                    m=metadata_path: \
+                    self._assertMarkdownPath(t, opts=o, toc_html_path=c,
+                          metadata_path=m)
 
             tags_path = splitext(text_path)[0] + ".tags"
             if exists(tags_path):

test/tm-cases/footnotes_custom.html

@@ -0,0 +1,27 @@
+<p>This is a para with a footnote.<sup class="footnote-ref" id="fnref-1"><a href="#fn-1">1</a></sup></p>
+
+<p>This is another para with a footnote<sup class="footnote-ref" id="fnref-2"><a href="#fn-2">2</a></sup> in it. Actually it has two<sup class="footnote-ref" id="fnref-3"><a href="#fn-3">3</a></sup> of
+them. No, three<sup class="footnote-ref" id="fnref-4"><a href="#fn-4">4</a></sup>.</p>
+
+<div class="footnotes">
+<hr />
+<ol>
+<li id="fn-1">
+<p>Here is the body of the first footnote.&#160;<a href="#fnref-1" class="footnoteBackLink" title="Yo Dawg, I heard you came from 1.">&#8617;</a></p>
+</li>
+
+<li id="fn-2">
+<p>And of the second footnote.</p>
+
+<p>This one has multiple paragraphs.&#160;<a href="#fnref-2" class="footnoteBackLink" title="Yo Dawg, I heard you came from 2.">&#8617;</a></p>
+</li>
+
+<li id="fn-3">
+<p>Here is a footnote body that starts on next line.&#160;<a href="#fnref-3" class="footnoteBackLink" title="Yo Dawg, I heard you came from 3.">&#8617;</a></p>
+</li>
+
+<li id="fn-4">
+<p>quickie "that looks like a link ref if not careful"&#160;<a href="#fnref-4" class="footnoteBackLink" title="Yo Dawg, I heard you came from 4.">&#8617;</a></p>
+</li>
+</ol>
+</div>

test/tm-cases/footnotes_custom.opts

@@ -0,0 +1,3 @@
+{"extras": ["footnotes"],
+ "footnote_title" : "Yo Dawg, I heard you came from %d."
+}

test/tm-cases/footnotes_custom.text

@@ -0,0 +1,18 @@
+This is a para with a footnote.[^1]
+
+This is another para with a footnote[^2] in it. Actually it has two[^3] of
+them. No, three[^4].
+
+
+[^1]: Here is the body of the first footnote.
+
+[^2]: And of the second footnote.
+
+    This one has multiple paragraphs.
+
+[^3]: 
+    Here is a footnote body that starts on next line.
+
+[^4]: quickie "that looks like a link ref if not careful"
+
+