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 Citations #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)¹:

• [](#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²).

Footnotes

1. Assuming these normally don't occur naturally in input files since they not produce anything very visible ^^ ↩

2. I am using SILE, not LaTeX, but at the core this boils down to the same kind of \label and \ref/\pageref logic. ↩

[AlbertLei]

Cross-references and auto-numbering are very important to my writing. Indeed, if djot supports these features natively, I would consider switching to djot instead of Pandoc Markdown, which I believe doesn’t support auto-numbering and cross-references natively at this time.

For syntax, I personally prefer those by pandoc-crossref and Quarto. They're very similar. Here are examples of numbering images and referencing them:

## pandoc-crossref syntax

![Caption](file.ext){#fig:label}

See @fig:label for an illustration.

## quarto syntax

![Caption](file.ext){#fig-label}

See @fig-label for an illustration.

Quarto also supports auto-numbering and cross-referencing for call-out and theorem environments, which could be useful.

• Quarto corssref docs and pandoc-crossref docs

I did not use it, but quarto also allows defining new types of cross references: docs

Other remarks on syntax

• Both pandoc-crossref and Quarto use # for auto-numbering and @ for cross-references. Since Pandoc already uses @ for citations, I think it’s good to use it for cross-references too, as they’re very similar in function.
• Both Quarto and pandoc-crossref will replace @fig:label with Figure $figNum, similar to LaTeX’s \Cref{}. If one just wants the number without the "Figure" prefix (like LaTeX’s \ref{}), one can use [-@fig:label].
• In implementation, both provide reasonable defaults for label-prefix (eg, fig:) and output prefix (eg, Figure). I think these are good decisions. As a user, my only complaint is that @eq:label outpus equation 1 instead of equation (1). The latter is more standard in academic writing.

Cross-references and hyperlinks

I think this issue is mainly about auto-numbering and referring to the correct number. In implementation, one may consider also supporting hyperlinks (at least for HTML and PDF outputs), without requiring extra syntax from users.

• Personally, I don’t use hyperlinks for academic writing. I just need counters and referring to counters, which I can handle by some pre-process scripts.

Other syntax options

MyST has the following syntax (docs)

$$
y = x^2
$$ (mymath)

The equation {eq}`mymath` is quadratic.

Asciidoctor supports counters (docs). But it seems not support cross-ref (i do not use asciidoc myself)

[jgm]

LaTeX allows quite a bit of flexibility in its counters. For example, you might want the figures to be numbered after the section or chapter, e.g. Figure 3.2. I think this kind of configurability would be necessary for a really workable solution.

[Omikhleia]

In implementation, both provide reasonable defaults for label-prefix (eg, fig:) and output prefix (eg, Figure). I think these are good decisions

That's a renderer styling issue no? (For different current document languages and usages, independent from the Djot syntax)

[AlbertLei]

That's a renderer styling issue no? (For different current document languages and usages, independent from the Djot syntax)

@Omikhleia I agree. In the previous post, I am (mostly) expressing my desire for this feature and thought-streaming. My main point is that "Cross-references and Numbering" may be solved by introducing some "counter attribute" and allow pandoc users "cite" (@) that attribute. Now I see that's not really about syntax.

[AlbertLei]

LaTeX allows quite a bit of flexibility in its counters. For example, you might want the figures to be numbered after the section or chapter, e.g. Figure 3.2.

@jgm I agree that flexibility is essential (particularly for pdf books). I think the djot/pandoc parser can accurately infer the header/section counters for figures?

I'm mostly a LaTeX user. I think a LaTeX-like \pageref{} command can be challenging for djot. For other edge cases, I'm open to manually specifying the "counter dependency." Eg, for "Figure 3.2", I could tell djot the section label for that figure.