Add support for cross-references

[jkitchin]

It occurred to me we can leverage the org-cite syntax for cross-references, e.g. [cite/ref:@Label] would be a cross-reference to "label" defined in a CUSTOM_ID on a heading, a NAME or in raw latex like \label{label}.

You could use substyles for equations, pageref, etc. e.g. [cite/ref/eq:@Label] for an equation.

You could also use a prefix to indicate a figure, table, equation, e.g. [cite/ref/eq:Equation @Label]

This adds a bit of complexity to the processors, and probably won't be fully supported by all of them. For LaTeX though, it would make for a total replacement of org-ref.

[jkitchin]

Here is an example of what this looks like:

[jkitchin]

I am putting this issue here to think about whether this is a good idea. On the plus side, it eliminates the need for org-ref cross-ref links.

On the minus side, it uses the org-cite syntax in a way that wasn't intended (although it is perfectly compatible with the idea). It adds complexity in following, inserting, activation and export because you have to check what kind of citation/reference it is based on the style, and then do the right thing. It is not clear what other backends would do for these styles.

It is implemented in a stand-alone way, so it is not necessary to use it if you don't want to.

[bdarcus]

@tecosaur raised a question about cross-ref support related to org-cite a few weeks ago, just before it was merged.

Wouldn't it be better, rather than hack citations for something for which they weren't designed, we figure out a general solution for cross-references?

Or at least to raise this on the org list for discussion?

My naive question, for example: what if we simply allow typed internal links?

[bdarcus]

Also, beyond the general question, what are other processors supposed to do with such "citations"?

[jkitchin]

@tecosaur raised a question about cross-ref support related to org-cite a few weeks ago, just before it was merged.

Wouldn't it be better, rather than hack citations for something for which they weren't designed, we figure out a general solution for cross-references?

This is a pretty general solution.

Or at least to raise this on the org list for discussion?

My naive question, for example: what if we simply allow typed internal links?

I am not sure what you mean by typed internal links; if you mean something like eqref:label, that is what org-ref already does. If you mean something like [ref/type: prefix @Label] that would be a whole new syntax and element to work out, although I guess it would be similar to the cite code.

The existing syntax for other elements isn't sufficiently flexible for what crossrefs needs though (except for the cite syntax, and regular links). I want to avoid regular links because they will conflict with the ones in org-ref already.

Also, beyond the general question, what are other processors supposed to do with such "citations"?

The same thing as for other citations, convert them to an appropriate representation. For latex export it is trivial, you just convert them to things like \ref{label}. For other backends, it could mean replacing them with numbers, or other labels, maybe making them into some kind of link (e.g. for html) to an anchor. Some of this kind of stuff is already done for citations in oc-basic.el, e.g. to get numbers for them, etc.

They are "citations" in the sense that you are referring to a source in the text in a place that is away from the source. It is just that the targets are in the document, and not in the bibliography. In the end, they are just links that point to other places.

[bdarcus]

I am not sure what you mean by typed internal links; if you mean something like eqref:label, that is what org-ref already does ...

This is basically what I mean.

The existing syntax for other elements isn't sufficiently flexible for what crossrefs needs though (except for the cite syntax, and regular links).

It would help to make these requirements explicit.

Per my response on the list, I'm not currently seeing why the existing internal linking isn't sufficient.

Also, beyond the general question, what are other processors supposed to do with such "citations"?

The same thing as for other citations, convert them to an appropriate representation.... For other backends, it could mean replacing them with numbers, or other labels, maybe making them into some kind of link (e.g. for html) to an anchor.

I don't think that's a reasonable expectation at all.

A library like citeproc-el, on which oc-csl depends, just does citations and bibliographies, as it should.

They are "citations" in the sense that you are referring to a source in the text in a place that is away from the source. It is just that the targets are in the document, and not in the bibliography. In the end, they are just links that point to other places.

Citations are references to external sources; not to content internal to the document.

That's not a trivial distinction, and why pretty much all software I have found that handles both treats them differently, with different UIs, etc.

[denismaier]

Just a quick comment: Pandoc currently also lacks an official syntax for cross-references. Instead you can abuse citations for cross-references and let a filter (pandoc-crossref) find and resolve the cross-references. Citeproc will then only see and process the still unresolved references.

[jkitchin]

I sort of prefer thinking of it as leveraging the syntax! Although I am aware many might already think I abused the link syntax heavily in org-ref.