From bbcf0ddfc2a36ec4449a0b9a202ce788145f7fb3 Mon Sep 17 00:00:00 2001 From: Rieks Date: Thu, 25 Apr 2024 08:44:53 +0200 Subject: [PATCH] Use Spec-Up XRefs Signed-off-by: Rieks --- .github/workflows/deploy-docs.yml | 2 +- docs/how-to/use-spec-up-term-references.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 1101085..6438c63 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -57,8 +57,8 @@ jobs: mrg-import -c tev2-config.yaml mrgt -c tev2-config.yaml hrgt -f -c tev2-config.yaml - trrt -f -c tev2-config-specup.yaml trrt -f -c tev2-config.yaml + trrt -f -c tev2-config-specup.yaml # Commit generated MRGs to repo, so other projects can use (import) them - name: Commit MRGs to repository diff --git a/docs/how-to/use-spec-up-term-references.md b/docs/how-to/use-spec-up-term-references.md index 41559d8..0804100 100644 --- a/docs/how-to/use-spec-up-term-references.md +++ b/docs/how-to/use-spec-up-term-references.md @@ -4,7 +4,7 @@ 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. +[[xref: tev2, TEv2]] allows customization of the syntax that authors use for [[xref: tev2, TermRefs]]. 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 @@ -18,12 +18,12 @@ In this [MVE](@), we only support the Spec-Up syntax for [[ref: term references] - 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). +- [[ref: Spec-Up term references]] are resolved using the default [[xref: tev2, terminology]] of the [[xref: tev2, current scope]]. +- [[ref: Spec-Up XRefs]] are resolved in a similar fashion, using the `{title}` part as a [[xref: tev2, scopetag]]. ## 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: +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 [[xref: tev2, named capturing groups]] specified in the [interpreter profile of the TRRT](trrt#interpreter-profile@tev2), as follows: | Spec-Up syntax | TEv2 equivalent | Comments | | -------------- | --------------- | -------- | @@ -48,11 +48,11 @@ trrt: - "**/*.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)). +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 [[xref: tev2, TRRT]] must be called using another, appropriate [[xref: tev2, converter]] (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. +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 [[xref: tev2, curated texts]], and therefore they end up in the [TEv2 MRG](mrg@tev2) that is used to dereference them. -----