Omikhleia/markdown.sile

Support cross-references (debatable)

Omikhleia opened this issue · 1 comments

Omikhleia commented

"See chapter N, section N.M on page P"

We could use our "labelrefs.sile" package for such things, that would be handy for books/articles needing usual cross-reference links.

However Pandoc never seems to have reached a consensus on how this should be declared in (extended-)Markdown. We could come up with our own syntax extension, but that wouldn't be portable. To be investigated.

Omikhleia commented

Digging a bit on the topic, there's no consensus:

  • The pandoc-crossref filter uses specific forms of the citations (e.g. @fig:figure0). The idea makes sense, but their naming scheme is weird IMHO, too specific and doesn't seem to account for references by page numbering, only by numbered item...
  • Bookdown (with R-Markdown) specifies its own syntax extension. Looks interesting, but weird too.
  • Of course, some LaTeX-enabled Markdown modules do suggest (as with Pandoc's raw_tex extension) to directly use the LaTeX \label and \ref commands... I don't consider it's a good solution (very low-level and tied to the actual syntax of these commands in LaTeX - despite the naming resemblance, they do not exactly match what we have in labelrefs for SILE, etc.)
  • Some discussions on Pandoc (mailing-list or issues, I should have noted the link) mentioned using empty links. It's kind of a hack with bad semantics, indeed.

Anyway, we are not going to wait forever for a standard consensus on something so useful in print. I do reasonably like the "empty links" hack, as these wouldn't usually output anything, but have then near to no interest (if some sort of fake comments in Markdown were expected this way, this does sound plain wrong anyway!). Moreover, with link_attributes, we can pass information regarding how to render them.

E.g. the following makes pretty good sense, for automated cross-references

The section "[](#target){ .title }", that is [](#target){ .section },
is on page [](#target){ .page }.

This would be enough for a start - So re-assigning to milestone 1.1 and moving forward.