-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Attempt to integrate Spec-Up term references
Signed-off-by: Rieks <[email protected]>
- Loading branch information
Showing
11 changed files
with
474 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| title: Using Spec-Up Term References | ||
| --- | ||
|
|
||
| # Spec-Up Term References Integration | ||
|
|
||
| [TEv2](@tev2) allows customization of the syntax that authors use for [TermRefs](@tev2). In this page, we show what it takes to use the syntax as [defined by Spec-Up](https://identity.foundation/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](https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#term-references) consists of [[ref: Spec-Up definitions]] (located in a so-called [definition list](https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#definition-lists)), and [[ref: Spec-Up term references]], that can be used to refer to such definitions. | ||
|
|
||
| Recently, Spec-Up introduced a [syntax for external term references](https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#external-term-references), that uses new feature called [[ref: 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 [[ref: term references]] and [[ref: XRefs]]. This means that | ||
|
|
||
| - we do not use [[ref: Spec-Up definitions]] or [definition lists](https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#definition-lists)). | ||
| - we use [TEv2 machine readable glossaries](mrg@tev2) to find the definitions of terms that are being referred to. | ||
| - [[ref: Spec-Up term references]] are resolved using the default [terminology](@tev2) of the [current scope](@tev2). | ||
| - [[ref: Spec-Up XRefs]] are resolved in a similar fashion, using the `{title}` part as a [scopetag](@tev2). | ||
|
|
||
| ## The TRRT Interpreter for Spec-Up Term References | ||
|
|
||
| In order to use Spec-Up [[ref: term references]] and [[ref: XRefs]], we need to write a [TEv2 interpreter](interpreter@tev2) that recognizes them. This can be done by mapping the `{term}` and `{title}` fields of the Spec-Up references to the [named capturing groups](@tev2) specified in the [interpreter profile of the TRRT](trrt#interpreter-profile@tev2), 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](term-ref@tev2). | | ||
| | `[[xref: {title}, {term}]]` | `[{term}](@{title})` | A Spec-Up `{title}` maps onto the `scopetag` captruing group of a [TEv2 TermRef](term-ref@tev2). | | ||
|
|
||
| This leads to the [following regex](https://www.debuggex.com/r/I1gqkMGPKMs9dfeE): | ||
|
|
||
| ```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](config-file@tev2)), the escape character `\` must be escaped. So the `trrt` section would read as follows: | ||
|
|
||
| ```yaml | ||
| 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 [[ref: Spec-Up term reference]] or a [[ref: Spec-Up XRef]] are to be rendered in a different way, that means that the [TRRT](@tev2) must be called using another, appropriate [converter](@tev2) (either a [predefined one](trrt#predefined-converters@tev2), or a [customized one](trrt#converter-customization@tev2)). | ||
| The following text (below the horizontal line) is a literal quote from the Spec-Up single-file-test spec.md file, showing that [[ref: Spec Up definitions]] are untouched, whereas [[ref: Spec-Up term references]] are converted as we would expect them to. | ||
| Note that the [[ref: term references]] for `Term 1`, `Term 2` and `Term 3` will actually work. That is NOT because the [[ref: definitions]] are processed, but because they are defined as [curated texts](@tev2), and therefor they end up in the [TEv2 MRG](mrg@tev2) 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: | ||
|
|
||
| <pre> | ||
| [[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! | ||
| </pre> | ||
|
|
||
| [[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: [[ref: Term 1]], [[ref: Term Two]], [[ref: 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| --- | ||
| # Front matter for TEv2 Curated Texts | ||
| term: spec-up-definition | ||
| glossaryTerm: "Definition (Spec-Up style)" | ||
| glossaryText: "a construct of the form `[[def: {term}, {alias1}, {alias2}, ... ]] ~ {definition}`, which specifies the mapping between the term `{term}` and a description of the term's meaning (provided by `{definition}`." | ||
| glossaryNotes: | ||
| - "`{alias1}, {alias2}, ...` is optional syntax that specifies aliases (synomyms) for `{term}`." | ||
| - "In [TEv2](@tev2), `{term}` and its aliases would be specified as [form phrases](@tev2)." | ||
| - "A recent addition is the use of so-called [[ref: XRefs]], which allows definitions to be used across diffrent files and projects." | ||
| formPhrases: [ "definition{ss}", "spec-up definition{ss}" ] | ||
| --- | ||
|
|
||
| # Definition (Spec-Up style) | ||
|
|
||
| A [[ref: Spec-Up Definition]] is a construct of the form `[[def: {term}, {term alias}, ... ]] ~ {definition}`, where | ||
|
|
||
| - `{definition}` is a descrition of the meaning of term `{term}`, and | ||
| - `{term alias}, ...` is a (comma separated) list of words or phrases that are considered to have the same meaning as `{term}`. They are not necessarily synonyms, but are typically what [TEv2](@tev2) would call [form phrases](@tev2). | ||
|
|
||
| ## How Spec-Up uses Definitions and Term References | ||
|
|
||
| In [Spec-Up's](https://identity.foundation/spec-up/) way of thinking, a specification file contains: | ||
|
|
||
| 1. a [definition list](https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#definition-lists), which contains all [[ref: definitions]] used within the file. It typically sits somewhere at the beginning of the specification file. | ||
| 2. [[ref: term references]], whose `{term}` part is one of the `{term}`s (or aliases) in a [[ref: definition]]. | ||
|
|
||
| An example of this is given in the [single-file-test/spec.md file](https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md#definition-lists) in the [Spec-Up Github repo](https://github.com/decentralized-identity/spec-up/tree/master/). | ||
|
|
||
| ## TEv2 does NOT use Spec-Up Definitions | ||
|
|
||
| The reason for this is that such [[ref: definitions]] only provide the very minimal things that, in the [TEv2](@tev2) vision, people would want to do with them. | ||
|
|
||
| The most obvious features that TEv2 provides that are not facilitated by [[ref: Spec-Up definitions]] are: | ||
|
|
||
| - the generation of a wide variety of (human readable) glossaries from the [[ref: definitions]]; | ||
| - generating (persistent) links to the documentation pages of terms; | ||
| - extending terminology-features without changing the underlying (programming) code. | ||
|
|
||
| ## Notes | ||
|
|
||
| Terms can still be defined and curated in various ways, but that does require that the curated texts that define terms (regardless of they are [[ref: spec-up definitions]] or specified in another way, e.g., as Wiki pages), are somehow converted in either | ||
|
|
||
| - a [TEv2-style machine readable glossary](mrg@tev2), so that [[ref: term references]] can be resolved using the [TEv2 TRRT tool](trrt@tev2), regardless of they are [[ref: Spec-Up term references]] or [TEv2 TermRefs](term-ref@tev2), or | ||
| - a set of [TEv2-style curated texts](curated-text@tev2), which can be processed by the [TEv2 MRGT tool](mrgt@tev2) to create such a [TEv2-style machine readable glossary](mrg@tev2). | ||
|
|
||
|
|
Oops, something went wrong.