Syntax and semantics for creating and referring to terms.

In this issue, we write the specifications of the syntax for (a) defining and (b) referring to terms. This top message contains such specifications, and will be edited/updated as needed and agreed. Subsequent messages document the discussions.

This issue is the first (draft) specifications. We expect the specifications to be enhanced, for which a new issue will then be created.

Referencing a concept

It should be easy for authors to refer to a defined concept, i.e. a concept for which a concept-file exists. An author can do this using the following the syntax %%<Term>|<ConceptReference>%%, where

• <Term> is an arbitrary string (that matches the (PCRE) regex ([\w-]+|"((?!").)+")), and
• <ConceptReference> is the file-id (without extension) of the file that specifies the concept (matching the (PCRE) regex [a-z-]+. <ConceptReference> is a valid reference to a concept-file when a file docs/terms/<ConceptReference>.mdx exists that is derived from the concept-template file.

The (proposed) semantics is as follows:

• when rendered in a web-page, <Term> is formatted in a (yet to be determined) specific style that sets it apart from is surrounding texts. For now, we make the text emphasized. This is done regardless of whether or not <ConceptReference> is a valid reference to a concept-file.
• if and only if <ConceptReference> is a valid reference to a concept-file, then:
  • hovering over the shown text shows a popuptext that is taken from the concept-file. For now, the popuptext is equal to the popuptext attribute in the Docusaurus header of the concept-file.
  • clicking on the shown text navigates the browser to the page that renders the concept-file, allowing the user to learn more about that concept.

Defining a concept

Concepts must be defined according to the requirements that can be found in the concept-template.

Continuous integration

Whenever a commit is done to the master (and/or developement?) branch, the pages should be regenerated to reflect any changes that may have been made in the terminology files. Also, a glossary of all terms shall be (re)generated that contains the updates.