mrg naming conventions (also removed names of glossary files)

Signed-off-by: Rieks <RieksJ@users.noreply.github.com>

docs/terminology-design/saf.yaml

@@ -10,8 +10,7 @@ scope:
   scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/terminology-design  # URL of the scope-directory
   curatedir: terms # directory where all curated files are located. Full URL is `scopedir`/`curatedir`
   glossarydir: glossaries # directory where all glossary files and GDFs are located. Full URL is `scopedir`/`glossarydir`
-  mrgfile: mrg.termdsn.yaml # file that contains the (default) machine readable glossary. Full URL is `scopedir`/`mrgfile`
-  hrgfile: glossary # file that contains the (default) human readable glossary. Full URL is `scopedir`/`hrgfile`
+  defaultvsn: latest # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.`scopetag`.`defaultvsn`.yaml
   license: LICENSE.md # file that contains the (default) licensing conditions. Full URL is `scopedir`/`license`
   statuses: [ proposed, approved, deprecated ] # list of status tags that are defined for terminological artifacts in this scope
   issues: https://github.com/tno-terminology-design/tev2-specifications/issues # URL where issues can be raised and handled

docs/tev2/saf.yaml

@@ -10,8 +10,7 @@ scope:
   scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/tev2  # URL of the scope-directory
   curatedir: terms # directory where all curated files are located. Full URL is `scopedir`/`curatedir`
   glossarydir: glossaries # directory where all glossary files and GDFs are located. Full URL is `scopedir`/`glossarydir`
-  mrgfile: mrg-tev2-test.yaml # file that contains the (default) machine readable glossary. Full URL is `scopedir`/`mrgfile`
-  hrgfile: glossary-tev2 # file that contains the (default) human readable glossary. Full URL is `scopedir`/`hrgfile`
+  defaultvsn: latest # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.tev2.latest.yaml
   license: LICENSE.md # file that contains the (default) licensing conditions. Full URL is `scopedir`/`license`
   statuses: [ proposed, approved, deprecated ] # list of status tags that are defined for terminological artifacts in this scope
   issues: https://github.com/tno-terminology-design/tev2-specifications/issues # URL where issues can be raised and handled
@@ -42,16 +41,13 @@ scopes:  #
 #
 versions:
 - vsntag: test # this version MUST only be used for testing the MRG generator
-  mrgfile: mrg-tev2-test.yaml # URL: <scopedir>/<glossarydir>/<mrgfile>
   termselcrit:
   - "*@tev2" # import all tev2 terms.
 - vsntag: v0.1
-  mrgfile: mrg-tev2.v0.1.yaml # URL: <scopedir>/<glossarydir>/<mrgfile>
   termselcrit:
   - "tags[identify,ppa]@essif-lab"
   - "*@tev2" # import all tev2 terms.
 - vsntag: v0.9.4 # a versiontag that identifies this version from all other versions in the SAF
-  mrgfile: mrg-tev2-v0.9.4.yaml # URL: <scopedir>/<glossarydir>/<mrgfile>
   altvsntags: # alternative verstiontags
     - latest
     - 0x921456
@@ -63,7 +59,6 @@ versions:
   from: 20220312
   to:
 - vsntag: v0.9.0 # a versiontag that identifies this version from all other versions in the SAF
-  mrgfile: mrg-tev2-v0.9.0.yaml # URL: <scopedir>/<glossarydir>/<mrgfile>
   altvsntags: # alternative verstiontags
     - 0x654129
   termselcrit:

docs/tev2/spec-files/11-saf.md

@@ -51,8 +51,7 @@ scope:
   scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/tev2  # URL of the scope-directory
   curatedir: terms # directory where all curated files are located. Full URL is `scopedir`/`curatedir`
   glossarydir: glossaries # directory where all glossary files and GDFs are located. Full URL is `scopedir`/`glossarydir`
-  mrgfile: mrg-tev2-test.yaml # file that contains the (default) machine readable glossary. Full URL is `scopedir`/`mrgfile`
-  hrgfile: glossary-tev2 # file that contains the (default) human readable glossary. Full URL is `scopedir`/`hrgfile`
+  defaultvsn: latest # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.`scopetag`.`defaultvsn`.yaml
   license: LICENSE.md # file that contains the (default) licensing conditions. Full URL is `scopedir`/`license`
   statuses: [ proposed, approved, deprecated ] # list of status tags that are defined for knowledge artifacts in this scope
   issues: https://github.com/tno-terminology-design/tev2-specifications/issues # URL where issues can be raised and handled
@@ -83,8 +82,7 @@ The following fields are defined for the `scope` section of a [SAF](@):
 | `scopedir`    | Y | URL of the location of the [scopedir](@) associated with the [scopetags](@) listed in the `scopetags` field. |
 | `curatedir`   | Y | Path to the directory where all [curated files](@) are located. This directory may contain subdirectories to allow [curators](@) to organize the files in any way they see fit. Full URL is `<scopedir>`/`<curatedir>`.|
 | `glossarydir` | Y | Path to the directory where all [glossary](@)-related files are located. Full URL is `<scopedir>`/`<glossarydir>`. This directory SHOULD contain one [MRG](@) for every element in the version-section in the [SAF](@), and one or multiple [HRGs](@). It MAY contain other files, e.g. containing instructions, headers, footers or other things that are necessary for generating specific [glossaries](@). |
-| `mrgfile`     | Y | Name of the file that contains the default [MRG](@) for this [scope](@). Full URL is `<scopedir>`/`<glossarydir>`/`<mrgfile>`. The filename MUST appear in one of the elements of the `versions` section of the [SAF](@). |
-| `hrgfile`     | Y | Name of the file that contains the default [HRG](@) for this [scope](@). Full URL is `<scopedir>`/`<glossarydir>`/`<hrgfile>`. |
+| `defaultvsn`  | Y | [versiontag](@) that [identifies](@) the default [terminology](@) for this [scope](@). The associated [MRG](@) is located at `scopedir`/`glossarydir`/mrg.`scopetag`.`defaultvsn`.yaml |
 | `license`     | Y | File in the root of the [scopedir](@) that contains the (default) licensing data. |
 | `statuses`    | n | Ordered list of [tags](@) that are defined in this [scope](@) for specifying stages in the life-cycle of [knowledge artifacts](@). The first element in the list represents the first stage, and the last element the last stage in the life-cycle. |
 | `issues`      | n | URL where issues can be reported and handled.|
@@ -100,7 +98,7 @@ It might be more practical to move all of the stuff that is particular to this s
 
 ### SAF Scopes - Mapping Scopetags and Scopedirs {#scopes}
 
-The `scopetags` section is a list that specifies a mapping between [scopetags](@) as they are used in this [scope](@), the associated [scopedir]((@)) and if necessary, other paths and filenames for [knowledge artifacts](@) within the [scope](@). The latter is only required when specifying the [scope](@) for which the [SAF](@) is created/maintained, as for other [scopes](@), such other paths and filenames can readily be found by inspecting the [SAF](@) that is located in the root of the [scopedir](@) of such [scopes](@).
+The `scopetags` section is a list that specifies a mapping between [scopetags](@) as they are used in this [scope](@), and the associated [scopedir](@).
 
 <details>
   <summary>Example of a `scopes` section</summary>
@@ -131,6 +129,10 @@ The following fields are defined for the `scopes` section of a [SAF](@):
 
 </details>
 
+:::info Editor's note
+It may be simpler to change the `scopetags`-field, which is currently a list of scopetags, into a `scopetag`-field, which would specifiy a single scopetag. This would encourage curators to use no more than one scopetag for each scope they refer to, but if they really wanted to, they could make multiple entries with different scopetags that refer to the same scopedir.
+:::
+
 | Name        | Req'd | Description |
 | ----------- | :---: | ----------- |
 | `scopetags`   | Y | List of at least one [scopetag](@), that the [curator(s)](@) of this [scope](@) have determined for the [terminology](@) of a specific [scope](@). The associated [scopedir](@) is specified in the section `scopes`.|
@@ -151,8 +153,6 @@ The third section in the [SAF](@) specifies the [terminology](@) of the [scope](
 #
 versions:
   - vsntag: v0.9.4 # a versiontag that identifies this version from all other versions in the SAF
-    mrgfile: mrg-tev2-v0.9.4.yaml # URL: <scopedir>/<glossarydir>/<mrgfile>
-    hrgfile: glossary-tev2-v0.9.4.html # URL: <scopedir>/<glossarydir>/<hrgfile>
     altvsntags: # alternative verstiontags
       - latest
       - 0x921456
@@ -164,8 +164,6 @@ versions:
     from: 20220312
     to:
   - vsntag: test # a versiontag that identifies this version from all other versions in the SAF
-    mrgfile: mrg-tev2-test.yaml # URL: <scopedir>/<glossarydir>/<mrgfile>
-    hrgfile: glossary-tev2-test.pdf # URL: <scopedir>/<glossarydir>/<hrgfile>
     altvsntags: # alternative verstiontags
       - 0x654129
     termselcrit:
@@ -190,8 +188,6 @@ The following fields are defined for the `versions` section of a [SAF](@):
 | Name        | Req'd | Description |
 | ----------- | :---: | ----------- |
 | `vsntag`      | Y | [Versiontag](@) that that is used to [identify](@) this version within the set of all other versions that are maintained within this [scope](@). in this [SAF](@). It MUST NOT be changed during the lifetime of this version.<br/>Must satisfy regex `[a-z0-9_-\.]+`. |
-| `mrgfile`     | Y | URL of the [MRG](@)-file that contains the [MRG-entries](@) of this version. Full URL is `<scopedir>`/`<glossarydir>`/`<mrgfile>`. |
-| `hrgfile`     | n | Name of the file that contains the [HRG](@) that renders all [MRG-entries](@) contained in the [MRG](@) as specified by the `mrgfile` field of this `versions` section. Full URL is `<scopedir>`/`<glossarydir>`/`<hrgfile>`. |
 | `altvsntags`  | n | List of alternative [versiontags](@) that may be used to refer to this version of the [scope's](@) [terminology](@). A typical use of this field would be to tag a version as the 'latest' version.<br/>Must satisfy regex `[a-z0-9_-\.]+`. |
 | `license`     | n | File that contains the (default) licensing conditions. Full URL is `scopedir`/`license`. If not specified, its value defaults to the value of the `license` field in the `scope` section (of this [SAF](@)). The purpose of this field is to allow different versions of the [scope's](@) [terminology](@) to have different licenses. |
 | `termselcrit` | Y | List of [term selection criteria](@) that are used to generate (this version of) the [scope's](@) [terminology](@). See [Terminology Construction](/docs/tev2/spec-tools/terminology-construction) for details. |

docs/tev2/spec-files/21-mrg.md

@@ -20,13 +20,17 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw',
 
 Every [scope](@) has (at least) one **Machine Readable Inventory**[^1] (that we call a **Machine Readable Glossary** or [MRG](@)), that renders the [terminology](@) of a specific [scope](@) into a specific, well-defined format that is described in this document. An [MRG](@) is meant to be used by the tools from the [toolbox](/docs/tev2/tev2-toolbox), e.g. for creating a [HRG](@), or to help resolve [term refs](@). A [scope](@) may have multiple [MRGs](@), each of which represents a specific version of its [terminology](@).
 
-[^1]: The [MRG](@) is an Inventory rather than a [glossary](@), because it contains _all_ [knowledge artifacts](@) that are [curated](@) within the [scope](@): apart from [terms](@), it also include e.g., [mental models](pattern@) and [use cases](@). We choose to maintain the [term](@) "Machine Readable Glossary" ([MRG](@)), because most of us would view it - initially, at least - as a list of [terms](@) and their [definitions](@).
+[^1]: The [MRG](@) is an inventory rather than a [glossary](@), because it contains _all_ [knowledge artifacts](@) that are [curated](@) within the [scope](@): apart from [terms](@), it also include e.g., [mental models](pattern@) and [use cases](@). We choose to maintain the [term](@) "Machine Readable Glossary" ([MRG](@)), because most of us would view it - initially, at least - as a list of [terms](@) and their [definitions](@).
 
-We use `mrg.<vsntag>.yaml` as the default name for [MRGs](@), where `<vsntag>` is the value of the `vsntag`-field in the `versions` section of the [SAF](@) that specifies the [MRG's](@) contents.
+## File naming conventions
 
-:::info Editor's note:
-We may need to revise the [MRG](@)-file naming conventions.
-:::
+Within (the [glossarydir](@) of) a particular [scopedir](@), we can generate (or import) and hence find all [MRG](@)-files that are needed within that [scope](@). We use the following file naming convention:
+
+**`mrg.<scopetag>.<vsntag>.yaml`** is the name of a file that contains an actual [MRG](@), or it is a file that links (references) such a file, where:
+  - **`<scopetag>`** is the [scopetag](@) that [identifies](@) the [scope](@) in which the [MRG](@) is curated, as specified in the [SAF](@) of the [scope](@). Its value must either be that of the `scopetag`-field in the [scope section](docs/tev2/spec-files/saf#terminology) of the [SAF](@), or it must be one of the values in the `scopetags`-field in the [scopes (plural) section](docs/tev2/spec-files/saf#scopes) of that [SAF](@).
+  - **`<vsntag>`** is the [versiontag](@) that [identifies](@) the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be either one of the `vsntag`-fields, or appear in one of the `alatvsntag`-fields in the [versions section](/docs/tev2/spec-files/saf#versions) of the [SAF](@).
+
+This naming convention enables tools (as well as [curators](@) and others) that operate within a particular [scope](@), to quickly find a particular [MRG](@) that is relevant for that [scope](@).
 
 ## MRG structure
 
@@ -125,7 +129,7 @@ The following table documents the fields that are used within the context of [TE
   <summary>Legend</summary>
 
 1. **`Name`** contains the field name;
-2. **`Req'd`** specifies whether (`Y`, or `Y*`) or not (`n`, or `F`) the field is required to be present as a header field. The `Y*` signifies that currently, the field is required, but that we envisage it to become optional when tooling becomes more mature, and will be able to automatically create the specified default value. The `F` means that we reserve this field for Future Use.
+2. **`Req'd`** specifies whether (`Y`) or not (`n`, or `F`) the field is required to be present as a header field. The `F` means that we reserve this field for Future Use.
 3. **`Description`** specifies the meaning of the field, and other things you may need to know, e.g. why it is needed, a required syntax, etc.
 
 </details>
@@ -136,7 +140,8 @@ The following table documents the fields that are used within the context of [TE
 | `term`            | Y | [Term](@) that is used to represent ([identify](@)) a [knowledge artifact](@) in this [scope](@).<br/>Must satisfy regex `[a-z0-9_-]+`. |
 | `termType`        | Y | [Text](term-type@) that [identifies](@) the kind of [knowledge artifact](@) that this [MRG entry](@) refers to. Typical values would be `concept`, `relation`, `pattern` (or `mental-model`), `term` (or `alias`), or `usecase`.<br/>Must satisfy regex `[a-z0-9_-]+`. |
 | `isa`             | n | [concept](@) of which this is a specialization. |
-| `glossaryText`    | Y | Text that is used as the (raw) contents for the entry of this [term](@) in a human readable [glossary](@). Note that this text SHOULD be allowed to contain [term refs](@). |
+| `glossaryTerm`    | n | Text that is used for the [term](@) in a human readable [glossary](@). For example, for a [term](@) called `member`, you may want to specify a glossaryTerm `member (of a [ommunity](@))`. |
+| `glossaryText`    | n | Text that is used as the (raw) contents for the entry of this [term](@) in a human readable [glossary](@). Such texts SHOULD be allowed to contain [term refs](@). |
 | `synonymOf`       | n | [term identifier](@) that [identifies](@) the [term](@) of which this is a [synonym](@). |
 | `grouptags`       | n | List of [grouptags](@), each of which signifies that the [(scoped) term](@) that this [curated text](@) documents, is part of the group of [terms](@) that it represents.<br/>Example: `[tev2, management]`.<br/>Must satisfy regex [`(?:\[\s*([a-z0-9_-]+)\s*(?:,\s*([a-z0-9_-]+))*\s*\])?`](https://www.debuggex.com/r/a51CXl1NzR3kwihT). |
 | `formPhrases`     | n | List of [texts](formphrase@) that are [used to convert](/docs/tev2/spec-tools/trrt#id) the `show text` parts of [term refs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). For details, see ['Syntax Specs - Form Phrases](/docs/tev2/spec-syntax/form-phrase-syntax). |
@@ -150,6 +155,4 @@ The following table documents the fields that are used within the context of [TE
 | `navurl`          | n | URL that locates a human readable, rendered version of the [curated text](@) of the [knowledge artifact](@) that this [MRG entry](@) describes. This URL is used to resolve [term refs](@) that refer to this [knowledge artifact](@). |
 | `headingIds`      | n | List of texts that can be used as a `trait` in a [term identifier](@), which typically are [markdown 'heading-ids'](https://www.markdownguide.org/extended-syntax/#linking-to-heading-ids). |
 
-
-
 # Footnotes