X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/337736663b74ba0f15b688ed2af2e2f75bd22b14..30ac2faa9354760925dfe93f2680b4376e17ed37:/doc/bugs/footnotes-look-weird.mdwn

diff --git a/doc/bugs/footnotes-look-weird.mdwn b/doc/bugs/footnotes-look-weird.mdwn
index 3fb8f4bfd..a821ab43c 100644
--- a/doc/bugs/footnotes-look-weird.mdwn
+++ b/doc/bugs/footnotes-look-weird.mdwn
@@ -48,6 +48,13 @@ screen readers), as detailed in [this Stack Overflow discussion][].
 > If so, please report that as a MultiMarkdown bug, not an ikiwiki bug,
 > or alternatively don't use MultiMarkdown.
 >
+> The recommended backend for the [[plugins/mdwn]] plugin is
+> [[!cpan Text::Markdown::Discount]], which optionally implements
+> footnotes using the same syntax as MultiMarkdown (originating in
+> "PHP Markdown Extra"). However, ikiwiki doesn't currently enable
+> that particular feature. Maybe it should, at least via a site-wide
+> option.
+>
 > What remains after eliminating the MultiMarkdown bug seems to be:
 > ikiwiki's default stylesheet does not contain the necessary styling
 > to work around the non-semantic markup produced by the non-default
@@ -55,5 +62,70 @@ screen readers), as detailed in [this Stack Overflow discussion][].
 > summary?
 > --[[smcv]]
 
+>> That is an accurate summary.
+>>
+>> I didn't realize that Discount didn't actually support footnotes in
+>> Ikiwiki by default. I guess I enabled Multimarkdown exactly for that
+>> kind of stuff that was missing...  It seems to me it would be
+>> reasonable to enable footnotes in Ikiwiki. There's already a lot of
+>> stuff that Discount does that is way more exotic (e.g. tables) and
+>> non-standard (e.g. `abbr:`).
+>>
+>> Ideally, users would get to configure which
+>> [Discount flags](http://www.pell.portland.or.us/~orc/Code/markdown/#flags)
+>> are enabled in their configuration, but I understand that makes the
+>> configuration more complicated and error-prone.
+>>
+>>> Discount enables enough features by default that adding footnotes doesn't
+>>> seem bad to me. I'm also tempted by something like
+>>>
+>>> ```
+>>> mdwn_enable: [footnotes]
+>>> mdwn_disable: [alphalist, superscript]
+>>> ```
+>>>
+>>> where the default for anything that was neither specifically enabled
+>>> nor specifically disabled would be to enable everything that we don't
+>>> think is a poor fit for the processing model (pandoc-style document
+>>> headers) or likely to trigger by mistake (typographic quotes and
+>>> [[maybe alpha lists|forum/"S."_gets_replace_by_"a."_in_my_ikiwiki]]).
+>>> --[[smcv]]
+>>>
+>>>> Makes perfect sense to me. --[[anarcat]]
+>>>>
+>>>>> I have now enabled footnotes in Discount by default, with a new
+>>>>> `mdwn_footnotes` option that can switch them off if they become
+>>>>> problematic. --[[smcv]]
+>>>
+>> For example, to enable footnotes, one needs to call Discount like this:
+>> 
+>>       Text::Markdown::Discount::markdown($text, Text::Markdown::Discount::MKD_EXTRA_FOOTNOTE())
+>>
+>> That being said, Discount generates proper semantic markup when
+>> footnotes, so this bug doesn't apply to the default Discount mode,
+>> if we ignore the fact that it doesn't support footnotes at all.
+>> Should I open a todo about this and the above?
+>>
+>> Also, it seems this *is* a bug with multimarkdown - I have
+>> [reported the issue there](https://github.com/bobtfish/text-multimarkdown/issues/30).
+>>
+>> In the meantime, wouldn't it be better to have some styling here to
+>> workaround the problem in MMD?
+>>
+>>> Honestly, I'd rather have ikiwiki's level of support for the non-preferred
+>>> Markdown implementation be: if you are stuck on a platform with no C compiler
+>>> or Perl headers, you can use the pure-Perl Markdown flavours, and they
+>>> will sort of mostly work (but might not look great).
+>>>
+>>> I'm a little concerned that styling these rather generically-named classes
+>>> might interfere with the implementations of footnotes in other Markdown
+>>> implementations, or indeed non-Markdown - I wouldn't want to style
+>>> `a.footnote` if the HTML produced by some other htmlize hook was
+>>> `<sup><a class="footnote" ...>[1]</a></sup>` for instance.
+>>> But they're probably harmless.
+>>>
+>>>> Alright, your call. :) At least this bug will be available as a workaround
+>>>> for others that stumble upon the same problem! :) --[[anarcat]]
+
 Note that I also make the bottom `<div>` small as well so that it has
 less weight than the rest of the text. -- [[anarcat]]