]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/bugs/footnotes-look-weird.mdwn
(no commit message)
[git.ikiwiki.info.git] / doc / bugs / footnotes-look-weird.mdwn
index 4747353960d47b3d7659a9ca988a2fd93acdbbda..a821ab43c14d9a132dc8458a304d8d333bba3762 100644 (file)
@@ -3,10 +3,13 @@ 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.
 
 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; }
 The following stylesheet should be added to `style.css`:
 
     a.footnote { vertical-align: super; font-size: xx-small; }
-    div.footnote { font-size: smaller; }
+    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>`:
 
 This is a typical style that user-agents apply to the `<sup>` tag. For
 example, chromium has this builtin style for `<sup>`:
@@ -34,8 +37,95 @@ 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][].
 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
 
 
 [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]]
 Note that I also make the bottom `<div>` small as well so that it has
 less weight than the rest of the text. -- [[anarcat]]