Cross-references and numbering

[jgm]

LaTeX has a flexible system for creating numbering counters, labels, and cross-references. This can be used with headings, tables, figures, equations, even list items. This is a must for serious academic writing, but it's not easy to see how to create a system that is sufficiently flexible but still natural for plain text writing and easy to use.

[jgm]

Pandoc's example lists offer some of the functionality of these, but only some. It would be better to have a more general solution, rather than implementing example lists here.

[uvtc]

Can you please give an example of what you mean by this? I'm familiar with putting an #that-id in a doc, and then linking to it from elsewhere with a link pointing to #that-id...

Also, where does "numbering" factor in here?

[jgm]

In LaTeX you can have

\section{My section heading}\label{mysec}

and then at some other point in the document,

See Section \ref{mysec}.

The section will be automatically numbered and the reference will resolve automatically. You can do the same kind of thing for other automatically numbered things, like equations, figures, and tables.

[jgm]

pandoc-crossref provides these capabilities as an add-on to pandoc.

[uvtc]

Thanks, John. I found the link to pandoc-crossref.

Although I don't understand your "mysec" example (since you're explicitly naming the reference "mysec" and there doesn't appear to be any numbering or auto-numbering involved), I can see how, if you have a bunch of display-math examples, they would/should be auto-numbered... though I'm not sure how I'd know what number they would be (or what their #id's would be to link to them).

[stagnation]

Nice, I use this all the time in my own notes (mostly in rst but not sphinx nor pandoc) and would often like to write documents with links to sections in the same document, and sometimes with references to sections in other documents. There one would need some kind of name spaces I think, sphinx "extends" rst to add that, but with a global namespace, so documents add anchor labels with unique names for sections that are linked to.

[gfarrell]

I just stumbled across djot as I've been implementing my own sortof-markdownish-thing for writing essays to publish online, for which I've been trying to implement three things missing in markdown which I miss from LaTeX:

• footnotes (I see djot has these already)
• citations (there's some discussion in #32, but I don't think this was ever implemented?)
• references with automated numbering (for figures, tables, sections, etc.)

So, since this issue is about references, @jgm are you intending to work this into djot or is there more discussion to be had?

I came up with the same syntax as you for footnotes ^[...] (but with some differences which are off-topic here), for citations I like the ideas in #32, but I treated citations as an extension of the concept of a reference, for which I used @{type:label} syntax.

Reference anchors, in my design, were part of the blocks, so:

\`\`\`{label}haskell
-- some code, and this attempt at escaping the
-- code fence is a great example of a problem in
-- markdown
\`\`\`

![a nice sunset][sunset-img]{sunset}

And I limited the types of reference to sections, citations, figures, tables, and (code-)listings, which I know is restrictive but it prevented me from having to use a convention that I used in my LaTeX docs of \ref{fig:cool-graph} and \ref{table:amazing-results} which was easy to get wrong.

Anyway, the above is just stuff I tried but I'd be interested in trying to get citations and references into djot (and djoths) because I think I'd rather use your implementation for my website than have to solve all the problems you've already solved building my own markup language. Is there something I can do?

[jgm]

At this point we're still at the design phase, figuring out what syntax for citations and references should be. Implementing the decisions will be relatively straightforward.

[Omikhleia]

FWIW, regarding cross-references, in my workflows with either Markdown or Djot inputs, I went for "filtering" empty links (i.e. without link text)[^2]:

• [](#xxx) refers to whatever identifier xxx points at, by "closest" numbering -- so that could be a figure, table, section or any other numbering scheme there is at that point (equation number, verse number in poetry, current footnote no in a footnote etc.)
• (Despite using English keywords not being perfect...) I use (pseudo-)classes when I want :
  • The page reference [](#xxx){.page}
  • The upper section title []{#xxx){.title}
  • Or the upper sectioning number [](#xxx){.section} (in the broad sense, i.e. the closest section, chapter, etc. in which the item appears)

The syntax is not that friendly, but has the advantage of remaining somehow readable (and avoiding low-level syntax extensions, being entirely done via a filter and/or by the renderer itself, which is responsible anyway for tracking the underlying counters[^1]).

[^2]: Assuming these normally don't occur naturally in input files since they not produce anything very visible ^^

[^1]: I am using SILE, not LaTeX, but at the core this boils down to the same kind of \label and \ref/\pageref logic.