ikiwiki/doc/bugs/footnotes-look-weird.mdwn

Multimarkdown footnotes are pretty useful. If they are enabled in a
wiki, they don't look so good with the default stylesheet, however, as
the references are in the same size and positioning as everything
else.

This particular wiki does not use multimarkdown, so there's no easy
way to demonstrate this here, you'll have to trust me on this. :)

The following stylesheet should be added to `style.css`:

    a.footnote { vertical-align: super; font-size: xx-small; }
    div.footnotes { font-size: small; }

This is a typical style that user-agents apply to the `<sup>` tag. For
example, chromium has this builtin style for `<sup>`:

    vertical-align: super;
    font-size: smaller;

Bootstrap uses this instead:

    sup {
        top: -.5em;
    }
    
    sub, sup {
        position: relative;
        font-size: 75%;
        line-height: 0;
        vertical-align: baseline;
    }

I settled on `xx-small` because it's the only size that doesn't affect
line-height here. However, Bootstrap's way may be better.

At any rate, the correct way to fix this is to *avoid* custom styling
and use the `<sup>` 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 `<a>` with a `class`, should be a `<sup>`).
> 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
>>> `<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]]