Skip to content

How To Use Spec-Up Term References

TEv2 allows customization of the syntax that authors use for TermRefs. In this page, we show what it takes to use the syntax as defined by Spec-Up, which is a tool that aims to facilitate the writing of technical specifications aimed at standards bodies or industry groups.

Background: Spec-Up Syntax for Term References

The Spec-Up syntax for (regular) term references consists of Spec-Up definitions (located in a so-called definition list), and Spec-Up term references, that can be used to refer to such definitions.

Recently, Spec-Up introduced a syntax for external term references, that uses new feature called XRefs. This feature allows authors to refer to terms that are defined in the text they are writing themselves, but in a text that is curated elsewhere.

Requirements for using Spec-Up syntax by TEv2 tools

In this MVE, we only support the Spec-Up syntax for term references and XRefs. This means that

The TRRT Interpreter for Spec-Up Term References

In order to use Spec-Up term references and XRefs, we need to write a TEv2 interpreter that recognizes them. This can be done by mapping the {term} and {title} fields of the Spec-Up references to the named capturing groups specified in the interpreter profile of the TRRT, as follows:

Spec-Up syntax TEv2 equivalent Comments
[[ref: {term}]] [{term}](@) A Spec-Up {term} maps onto the showtext capturing group of a TEv2 TermRef.
[[xref: {title}, {term}]] [{term}](@{title}) A Spec-Up {title} maps onto the scopetag captruing group of a TEv2 TermRef.

This leads to the following regex:

(?:(?<=[^`])|^)\[\[(?:xref:\s*(?<scopetag>[a-z0-9_-]+),|ref:)\s*(?<showtext>[^\n\],]+)\]\]

Notes:

When applying the regex in a YAML file (e.g. a TEv2 configuration file), the escape character \ must be escaped. So the trrt section would read as follows:

trrt:
  interpreter: "(?:(?<=[^`])|^)\\[\\[(?:xref:\\s*(?<scopetag>[a-z0-9_-]+),|ref:)\\s*(?<showtext>[^\n\\],]+)\\]\\]"
  converter: html-hovertext-link # style in which TermRefs are to be rendered - change as you like
  input:                         # glob pattern for files to be processed - adjust as necessary
    - "**/*.md"

If a Spec-Up term reference or a Spec-Up XRef are to be rendered in a different way, that means that the TRRT must be called using another, appropriate converter (either a predefined one, or a customized one).

The following text (below the horizontal line) is a literal quote from the Spec-Up single-file-test spec.md file, showing that Spec Up definitions are untouched, whereas Spec-Up term references are converted as we would expect them to.

Note that the term references for Term 1, Term 2 and Term 3 will actually work. That is NOT because the definitions are processed, but because they are defined as curated texts, and therefore they end up in the TEv2 MRG that is used to dereference them.

Definition Lists

Many specs may want to include a section for terminology references, and Definition Lists are a great way to do that. Here's how to leverage Spec-Up's automatic term reference features via Definition List markup:

[[def: Term 1, Term One]]:
~ This is the first term we will define.

[[def: Term 2, Term Two]]:
~ This is the second term, but not the last.

[[def: Term 3, Term Three]]:
~ This is the last term, because you know what they say: third term's the charm!

[[def: Term 1, Term One]]: ~ This is the first term we will define.

[[def: Term 2, Term Two]]: ~ This is the second term, but not the last.

[[def: Term 3, Term Three]]: ~ This is the last term, because you know what they say: third term's the charm!

Now let's refer to some of the terms defined above to show how the auto-linking of terms works: Term 1, Term Two, Term 3. Additionally, as long as you define your terms using Definition Lists (as seen in the markdown above), you will be able to hover any reference to a term to see a tooltip with its definition.