Incorrect Footnote Order

CxRes commented 5 years ago

Subject of the issue

I get an incorrect footnote order when I mix inline and regular footnotes.

Your environment

Windows 10 x64
"rehype-stringify": "^5.0.0", "remark-parse": "^6.0.3", "remark-rehype": "^4.0.0", "unified": "^7.1.0", "unified-stream": "^1.0.4"
Node 8.15.1

Steps to reproduce

The code (essentially lifted from the guide):

const options = {
  footnotes: true,
  gfm: true
};

const processor = unified()
  .use(parse, options)
  .use(remark2rehype)
  .use(html)

fs.readFile('sample.md', 'utf8', function(err, data) {
  processor.process(data)
    .then(function(out) {
      fs.writeFile('sample.html', out, 'utf8', function(err){
        if (err) throw err;
        return;
      })
    })
    .catch(function(err) {
      console.log(err);
    });
});

and input file sample.md:

Some text[^foo bar]

More text[^x]

[^x]: baz cuux

Actual behaviour

sample.html

<p>Some text<sup id="fnref-1"><a href="#fn-1" class="footnote-ref">1</a></sup></p>
<p>More text<sup id="fnref-x"><a href="#fn-x" class="footnote-ref">x</a></sup></p>
<div class="footnotes">
<hr>
<ol>
<li id="fn-x">baz cuux<a href="#fnref-x" class="footnote-backref">↩</a></li>
<li id="fn-1">foo bar<a href="#fnref-1" class="footnote-backref">↩</a></li>
</ol>
</div>

Expected behaviour

<p>Some text<sup id="fnref-1"><a href="#fn-1" class="footnote-ref">1</a></sup></p>
<p>More text<sup id="fnref-x"><a href="#fn-x" class="footnote-ref">x</a></sup></p>
<div class="footnotes">
<hr>
<ol>
<li id="fn-1">foo bar<a href="#fnref-1" class="footnote-backref">↩</a></li>
<li id="fn-x">baz cuux<a href="#fnref-x" class="footnote-backref">↩</a></li>
</ol>
</div>

ChristianMurphy commented 5 years ago

Remark is parsing the references as expected. https://astexplorer.net/#/gist/471584ba12aa4e52757dcbb9e11bd275/59c1f5114ec43c6c688990d5fd3bba1a38392153

Transferring this to remark-rehype, which handles more around the output to HTML.

wooorm commented 5 years ago

@CxRes Thanks for the detailed information! You’re saying this behaviour is incorrect, could you expand on why it’s incorrect? Why is your expected behaviour more correct?

CxRes commented 5 years ago

One would expect footnotes to listed at the bottom in the same order as their labels appear in the file. Since <a href="#fn-1"> appears before <>a href="#fn-x" in the document, the ordered list of footnotes must respect that order, meaning <li id="fn-1"> must precede <li id="fn-x">.

wooorm commented 5 years ago

That makes sense! Especially with inline footnotes.

Footnote definitions can be ordered manually in a document, so there may or may not be a reason why people are expecting this definition-order over usage-order, which is currently happening. Inline footnotes are different though, and they are currently usage-ordered and added after the definition-ordered definitions, which is not ideal.

One more question: What do you think should happen if a footnote is referenced multiple times? Should we order on first-used, or order on last-used?

CxRes commented 5 years ago

IMHO, that depends! One way to look at it is that only one of those references owns the footnote and the remainder are cross-refs. Owner then determines the placement.

Here comes my rant :). I actually do not like the idea of footnotes (which really become endnotes) here as they are really meant for paper and not computer screens. Partial solutions around this today are to use pop-ups or Tufte style sidenotes. In this vein, I also do not like the idea of arbitrary ordering either; what could be the author intention in wanting to place notes in different order when the user is required to scroll to the bottom of the page to access them. All that is likely to do is confuse the reader about the origin of the note esp if the document is long.

Alternatively one can place footnotes at the place where they appear in markdown in some kind of container. But here again we are restricting ourselves presuming that the screen obeys the linearity of paper (which for the most part it does not).

Now, if you are interested in the real rant, which every good software developer should ;) , I would direct you to the work of the great (and greatly irritable) Ted Nelson.

wooorm commented 5 years ago

I actually do not like the idea of footnotes (which really become endnotes) here as they are really meant for paper and not computer screens.

In this case, if footnotes are used in markdown and then transformed to HTML, you are right. You can use footnotes in markdown to do other things than transform to HTML though. So it is possible to “print” them on pages.

Alternatively one can place footnotes at the place where they appear in markdown in some kind of container.

This should be possible by overwriting the default behaviour.

I would direct you to the work [...] Ted Nelson.

Which work specifically?

CxRes commented 5 years ago

So it is possible to “print” them on pages.

Sure but even here markdown brings with it ambiguity and confusion. Again where should the (not inline) footnote be placed? In the same place as it appears in markdown? Nearest bottom of that page? What if the reference to the footnote fell in the previous page? How to deal with multiple references? etc.

Which work specifically?

The classic to start off with is Computer Lib/Dream Machines. Perhaps you can find it in a public library in NL. People in the developing world are not so lucky. There are some terrible scanned copies online. A small (but probably most relevant) excerpt of the book is freely available here.

His most recent article on the issue afaik is Toward a Deep Electronic Literature: The Generalization of Documents and Media.

You can read more on his older website or the xanadu website. The latest version of his site is a bit sparse, with mostly youtube explanation videos. Do watch the very moving Doug Engelbart eulogy though. I also managed to scrape of his last book The Future of Information from the internet archive.

wooorm commented 5 years ago

Sure but even here markdown brings with it ambiguity and confusion. [...]

All these questions are valid. And you can do all these things with markdown! Two notes that you may find interesting:

Markdown is not for HTML. Maybe it used to be. But if you drop that line of thinking, Markdown can do anything. You can make books, render man pages, etc... Even HTML does not dictate how things are presented. It defines semantics. And that’s what Markdown does as well!
I don’t think Markdown is ambiguous / confusing if it doesn’t dictate how things display. Similar to other tools that don’t dictate how they are used. It’s a hammer. You can use it for a bunch of things. It doesn’t dictate how it’s used. That doesn’t make a hammer confusing.

The classic to [...]

Thank you!

remarkjs / remark-rehype