Add new <xref:xxxx> syntax for Specref auto adding to bibliography

[thadguidry]

It would be useful to just mention a specification shortname and then MyST would automatically enable hover, as well as add to the bibliography, if configured to do so. addXrefToBib: true

Example syntax:

<xref:RFC8259>
[](xref:RFC8259)
[[RFC8259]]

See example of how ReSpec handles this: https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide#references

[rowanc1]

Thanks @thadguidry. We are also having some conversations around the cross-project links here. Do you know if respec is intended to be adopted wider than the w3c documentation? We are looking at ways to expose cross-references between myst projects, and this might be an option?

[thadguidry]

ReSpec

ReSpec (Specification Documentation platform) can be used for documenting any web standards, spec or technical documents actually. :-) but not the best candidate for your blog I'd say :-) And indeed it's more wider now than just W3C docs, witness:

ReSpec is a JS library that makes it easier to write technical specifications, or documents that tend to be technical in nature in general. It was originally designed for the purpose of writing W3C specifications, but has since grown to be able to support other outputs as well.

Its big plus is in fact its shorthands guide shows how similar it is to Bikeshed so it makes it easier to share. Defining concepts, even scoped concepts and variables are really what comes into play with documenting and referencing easily throughout a document. Much more powerful than links, and why folks use ReSpec for those features when having to document APIs, Standards, Request/Responses, Properties, etc. and reference them back and forth.

Bibliographical references have been moved out of ReSpec. You want to use specref.org.

SpecRef

SpecRef (the specification reference database & software) is used by ReSpec, Bikeshed, and others and can be used by any Publisher, Publishing Platform, or Community. Which is here where I am thinking of this discussion and having MyST absorbing some xref syntax, whatever form it might be in MyST that makes it similar enough and simple. <xref:RFC8529> seems simple enough, but [[RFC8529]] would be ideal and less tag-like? and closer to ReSpec and other platforms way of referencing standards and concepts (aka ReSpec's shorthands) which is typically using various bracket wrapping forms as seen in that shorthands guide. There's even some borrowed history there in general syntax of string interpolation via placeholders, JS's string interpolation, Ruby's placeholder substitution and Groovy's GString's and any of the evolved Web programming languages over the years.

Basically SpecRef is a database or tooling (your pick) that provides metadata about a Concept or Standard Reference.

[[RFC8529]] behind the scenes is really this:

{
    "href": "https://www.rfc-editor.org/rfc/rfc8529",
    "title": "YANG Data Model for Network Instances",
    "authors": [
        "L. Berger",
        "C. Hopps",
        "A. Lindem",
        "D. Bogdanovic",
        "X. Liu"
    ],
    "status": "Proposed Standard",
    "publisher": "IETF",
    "id": "rfc8529",
    "date": "March 2019"
}

Cross-references across projects/standards

Regarding exposing cross-references (or concepts/standards/etc.) between projects is definitely how the shorthands in ReSpec slowly added up (placeholders essentially as mentioned). Case in point, like the Plural Forms [=fruits=] can link to the singular concept of fruit, even across specs/projects!

Regarding brackets (delimited identifers) versus only prefix tokens like @ only for referencing

It was found to be very useful to use delimiter forms (starting/ending tokens like brackets, braces, html tags) instead of only a prefix token like @.
This allows referencing multi-worded concepts, like referencing [=default toJSON steps=] as shown https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide#referencing-terms-from-other-specifications

[choldgraf]

I'll just throw in a quick note that the [[ ]] link syntax is also very similar to how Obsidian handles internal references and links, and at least anecdotally I've seen a lot of people in the technical community really embrace that platform for writing. This also seems to be heavily inspired by how wikis handle their links.