X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/81852a7db7a56e1f2d27afb3f17a09a847aa8b03..5b381e7fd157c0e381a87b386996485d6c7067c8:/doc/bugs/footnotes-look-weird.mdwn diff --git a/doc/bugs/footnotes-look-weird.mdwn b/doc/bugs/footnotes-look-weird.mdwn index a5af38e50..a821ab43c 100644 --- a/doc/bugs/footnotes-look-weird.mdwn +++ b/doc/bugs/footnotes-look-weird.mdwn @@ -37,8 +37,95 @@ At any rate, the correct way to fix this is to *avoid* custom styling and use the `` tag for the footnote reference, as it has *meaning* which is important to have proper semantic output (e.g. for screen readers), as detailed in [this Stack Overflow discussion][]. +--[[anarcat]] [this Stack Overflow discussion]: http://stackoverflow.com/questions/501671/superscript-in-css-only +> ikiwiki code does not interpret Markdown or translate it into HTML. +> If I'm interpreting what you say correctly, you seem to be implying +> that you think [[!cpan Text::MultiMarkdown]] is producing incorrect +> HTML for footnotes (is an `` with a `class`, should be a ``). +> 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 +> Text::MultiMarkdown Markdown implementation. Is that an accurate +> 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 +>>> `[1]` 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 `
` small as well so that it has less weight than the rest of the text. -- [[anarcat]]