footnotes might want to be a normal part of an AST

[matklad]

Today, footnotes are collected into the footnotes map on the root node. I am not entirely sure that's the best approach:

• footnotes are usually numbered and hence ordered. JSON however specifies that maps are unordered. If we keep them in the end of the doc, we probably want to use an array rather than a map.
• footnote placement in the original document might be relevant. For example, I might want to do a single footnote section per document, or a footnote section per chapter. In this sense, having footnotes appear in the AST where they are defined might be usful. The writer then has a choice between rendering the note at the definition place, or hoisting it to the end of the doc.

[matklad]

Curiously, link references are part of the AST. If anything, it should be thee opposite, because link refs are just data (urls) while footnotes are actual rendered content.

[jgm]

The ordering of the notes is generally determined by the ordering of their references. The references are in an ordered container (the document itself).

Pandoc puts the notes directly in the AST, but this has caused complaints throughout the years, by people who want to do things like have two references point to the same note, or have a reference to another note inside a note. Odd cases, but I'm not sure I really see the drawback of the current approach, given the above. Nothing about the present setup prevents you from having footnotes printed per-section, for example. You just collect the references in that section, look up the contents of the notes in the table, and render them there.

[matklad]

Yeah, that makes sense. Then wee probably should remove reference_definition from ast as well

for

[^note]: note
[link]: link

the ast looks oddly inconsistent:

doc
  reference_definition (2:1:15-nil)
    reference_key text="link"
    reference_value text="link"
references = {
  ["link"] = "link",
}
footnotes = {
  ["note"] =
    footnote (1:1:1-2:1:15)
      para (1:10:10-2:0:14)
        str (1:10:10-1:13:13) text="note"
}

[jgm]

The reason I kept reference_definition is to support rendering back to djot. You might want the reference definitions to appear in the same place, rather than being all at the end. Of course, the same applies to footnotes, so we should probably treat both cases the same, however we treat them.