Cross Reference Improvements

[rowanc1]

Context and Issue:

• Internal Cross Reference Simplifications using Markdown Links #9

Draft MEP:

• https://hackmd.io/us8ZmFHrTjaHBGkkdoz0CQ

From team meetings:

• EBP Team Meeting - October 2022 executablebooks/meta#831
• EBP Team Meeting - December executablebooks/meta#884

[mmcky]

Thanks @rowanc1 @chrisjsewell and @fwkoch for your work on this. I will take a much closer look soon as it is getting late here but one thought I have is:

- `` {ref}`my-id` `` becomes `[](#my-id)`
- `` {eq}`my-equation` `` becomes `[](#my-equation)`

I had always though the context provided by eq was important for sphinx translators when moving through the ast and coming across visit_math_reference for example. Given the right hand side is the same syntax, how will the parser encode the math_references?

Update: Maybe the answer lies in executablebooks/MyST-Parser#613 which I will need to take a closer look at too.

[rowanc1]

Thanks for the first review and thoughts @mmcky.

The AST should absolutely keep the kind, the current AST that we are using in mystjs looks something link this:

The proposed syntax does not know this kind upfront, however. This is the same way it doesn't know about enumeration or the title of the target. This is actually the same as how latex works as well, for example, with a single \ref. The spec needs a bit of tidying up (currently here, with the current warning), which we could plan out more as well in the MEP (I ran out of steam last night!). I think we should take inspiration from the JATS schema for various reference kinds (here, click on "OPTIONAL, and see suggested usage for the list).

I think the sacrifice that we are making here is that a "unknown reference" warning can not know what kind it is before it is resolved. So error messages loose some specificity, that is, "cannot resolve reference with {id} on {line}" vs. "cannot resolve reference of kind {eq} with {id} on {line}". There shouldn't be anything lost in the reference does resolve, however, which IMO is a decent trade-off for more familiarity to markdown users (but certainly in the realm of opinion!).

For sphinx magic, I am not entirely sure how @chrisjsewell has designed it. I believe he is visiting more of the domains explicitly in the search for the reference, but he can comment more on the details!