Skip to main content

TermRefs - Syntax

As an author or curator, you want to be able to mark words or phrases and have them refer to (the documentation of) a particular concept or other semantic unit. Such marked-up words or phrases are called TermRefs.

TermRefs can be converted (by the TRRT) into so-called renderable refs, which are texts that are being rendered in a way that helps readers better understand the words/phrases that you marked up. For example, when the document you authored is used in a website, the TermRef could be rendered en an emphasized way, and have a popup balloon that has its definition when a reader hovers its mouse over it.

The TRRT specifications specify

  • how TermRefs are converted;
  • how you can customize the TermRef syntax to your needs;
  • how you can customize the renderable refs to look like what you want.

The following tabs-table tells you which syntaxes are predefined:

Default TermRef Syntax​

By default a TermRef can be thought of as a special kind of Markdown link. It link-part does not contain a URL or fragment, but contains text that refers to (a specific trait of) a specific concept or other semantic unit, as defined in a particular terminology.

The most general form of the default syntax is:

[ show text ]( termType:term#trait@terminology-identifier )

where:

  • show text (required) is the text that will be highlighted/emphasized to indicate it is linked. It must not contain the characters @ or ] (this is needed to distinguish TermRefs from regular markdown links).
  • termType (optional) is a term type. When not specified, it is given the default type for semantic units in the current scope, which usually would be concept.
  • term (optional) is a term. If not specified, its value is constructed based on the value of showtext, as specified in the TRRT.
  • trait (optional) refers to a particular characteristic of the semantic unit. If specified, it must be the heading id of the section in the body of a curated text that describes the characteristic. If not specified it refers to the whole of (the documentation of) the semantic unit.
  • terminology-identifier is a terminology identifier. If not specified, its value is taken to be the default terminology of the current scope.

Examples​

Editor's note

vanaf hier tekst reviseren. Merk op dat de conversie spullen naar de TRRT specs moeten verhuizen!

  • [TermRef Examples](term-ref#example)

This TermRef refers to the semantic unit that is identified by the term identifier <termType>:<term>@<terminology-identifier>. When all optional fields are specified, this

The par

that identifies the terminology in which termid identifies a semantic unit.

Here is an example of a TermRef: [definitions](definition@). When this text is rendered into a human readable form, it will show the text definitions (plural) enhanced, and it will link to the text that describes (or defines) the term definition (singular). If you would want to use this term as it is defined in the scope called essif-lab, you could do that by writing [definitions](definition@essif-lab) (provided that essif-lab is a defined scopetag within the scope that you operate in).

Motivation for the chosen syntax​

We want to enable authors to use TermRefs pervasively, which means it must be easy to use, and mistakes should be (relatively) hard to make, yet easy to detect, identify, and correct. Markdown links are of the form [show text](ref-text), where show text is the text that is rendered and emphasized so that a reader knows it can be clicked, and ref-text is a (relative or absolute) URL, or a heading ID, that identifies the resource (e.g. web page, or place therein) that is being referenced. So, we need a syntax for TermRefs that is
- sufficiently similar to a Markdown link,
- 'humanly interpretable' when it isn't processed by the TRRT,
- easy to use for authors, and
- sufficiently distinct from a Markdown link so that the TRRT will not process Markdown links yet will process the TermRefs.

Customizing TermRef Syntax (#customize)​

Editor's note

this section needs to be written.