making it ready for review

Signed-off-by: Rieks <[email protected]>

.github/workflows/deploy-docs.yml

@@ -82,11 +82,6 @@ jobs:
     - name: Build the MkDocs site
       run: mkdocs build  # Builds the static site from Markdown files
       working-directory: ${{github.workspace}}  # Ensures mkdocs builds from the root directory
-
-    - name: List generated site structure
-      run: |
-        echo "Listing the contents of the generated site directory:"
-        ls -R ./site
 
     # GitHub Pages setup
     - name: Setup Pages

docs/how-to/add-tev2-tools-to-actions-script.md

@@ -6,20 +6,18 @@ Title: Add TEv2 to GitHub Actions
 
 You only need to do this if you intend to use the tools in a GitHub workflow.
 
-All you need to do is add some texts to the workflow file 
+All you need to do is add some texts to the [workflow file](@) 
 that is used to generate the static website. This file is located
 in the `/.github/workflows` directory of your repo.
 
-In this MVE, we also have such a file. 
-It is called [`deploy-docs.yml`](https://github.com/tno-terminology-design/tev2-mve/blob/main/.github/workflows/deploy-docs.yml).
+In this [MVE](@), we also have such a file. It is called
+[`deploy-docs.yml`](https://github.com/tno-terminology-design/tev2-mve/blob/main/.github/workflows/deploy-docs.yml).
 You can use this as an example.
 
-You can also see there the particular parts that you must have in your workflow file
-
 This file is a standard/minimal workflow for creating a GitHub Pages website,
 where we have inserted the following action-steps:
 
-~~~
+~~~ yaml
     # Setting up Node, as this is needed to install the TEv2 tools
     - name: Setup Node.js
       uses: actions/setup-node@v3
@@ -33,7 +31,7 @@ and it is not necessary to duplicate that then.
 
 The TEv2-specific part that (always) needs to be added is as follows:
 
-~~~
+~~~ yaml
     # TEv2 Tool installation
     - name: Install terminology tools globally
       run: npm install -g @tno-terminology-design/trrt @tno-terminology-design/hrgt @tno-terminology-design/mrgt @tno-terminology-design/mrg-import
@@ -55,165 +53,6 @@ The TEv2-specific part that (always) needs to be added is as follows:
         file_pattern: 'docs/glossaries/mrg.mve*.yaml'
 ~~~
 
+That's all.
 
-
-
-
-
-
-The [TEv2 tools] you need are avaiable as NPM packages. We use the [MRG import](@tev2), [MRGT](@tev2), [HRGT](@tev2) and [TRRT](@tev2), which can be installed by executing:
-
-~~~
-npm install -g @tno-terminology-design/mrg-import
-npm install -g @tno-terminology-design/mrgt
-npm install -g @tno-terminology-design/hrgt
-npm install -g @tno-terminology-design/trrt
-~~~
-
-You can verify that they are installed correctly by 
-making the `docs` directory your current directory,
-and then run the following commands
-
-~~~
-mrg-import --version
-mrgt --version
-hrgt --version
-trrt --version
-~~~
-
-all of which should return a version number. 
-In case of trouble, you may consult
-
-- [npm Troubleshooting Guide](https://docs.npmjs.com/troubleshooting)
-  This is the official npm troubleshooting guide which covers common problems including installation issues on different operating systems.
-
-- [Stack Overflow](https://stackoverflow.com/questions/tagged/npm)
-  Stack Overflow has a vast number of questions and answers on npm issues across all platforms. Users can search for their specific issues or ask new questions.
-
-- [Issues on the Node.js GitHub repo](https://github.com/nodejs/node/issues)
-  The Node.js GitHub repository can be useful for browsing or reporting issues directly related to Node.js, which may indirectly solve npm issues.
-
-- [npm Community](https://npm.community/)
-  The npm Community forum is a place to discuss problems and share solutions with other npm users across different environments.
-
-## File/Directory Structure
-
-The `docs` directory is the root directory in which TEv2 works (the reason for
-this is that it contains the [Scope Administration File](saf@tev2) (`saf.yaml`)
-for the MVE scope). This directory is constructed as follows:
-
-~~~
-├── mrgs
-│   ├── mrg.mve.terms.yaml
-│   └── mrg.mve.yaml
-├── terms
-│   ├── term-1.md
-│   └── term-2.md
-├── outputs
-│   └── readme.md
-├── index.md
-├── mve-glossary.md
-├── saf.yaml
-└── tev2-configs.yaml
-~~~
-
-- `mrgs` (directory) contains [machine readable glossaries](@tev2). They are either
-imported (by the [mrg-import](@tev2) tool), or generated (by the [mrgt](@tev2) tool). 
-The [glossaries](@tev2) generated within this scope are `mrg.mve.terms.yaml` 
-(the [mrg](@tev2) of [terms](@tev2) that are defined within this scope) and
-`mrg.mve.yaml` (the [mrg](@tev2) that holds the default [terminology](@tev2) 
-of this [scope](@tev2)). Other [mrgs](@tev2) that might exist would be imported.
-
-- `terms` (directory) contains files with [curated texts](@tev2), i.e., 
-markdown texts that document the terminology defined within this [scope](@tev2). 
-
-- `index.md` file (this file).
-
-- `mve-glossary.md` is a markdown file that contains a [marker](mrg-ref@tev2)
-that the [hrgt tool](hrgt@tev2) converts into a [human readable glossary](@tev2)
-of the [terms](@tev2) that are defined in this [scope](@tev2).
-
-- `saf.yaml` is the [scope administration file](saf@tev2).
-
-- `tev2-configs.yaml` is a [TEv2 configuration file](@tev2) that holds 
-configurations for the [TEv2 tools](@tev2).
-
-## Working with TEv2 tools
-
-The purpose of this site is to provide you with an initial setup that enables you to run the tools by yourselves, so that you can see what they do.
-
-**We assume that all commands are run from the directory that contains the file `saf.yaml`**
-
-You can do this as follows:
-
-### Step 0: Make sure the tools become available
-
-You can do this by installing npm (the node packet manager) on your machine, and subsequently making all tools available, as follows:
-
-~~~ cmd
-npm install -g @tno-terminology-design/mrg-import
-npm install -g @tno-terminology-design/mrgt
-npm install -g @tno-terminology-design/hrgt
-npm install -g @tno-terminology-design/trrt
-~~~
-
-You can verify they are available by
-
-1. going to the directory that contains `saf.yaml`, and then
-2. executing the following command(s) from within that directory:
-
-~~~ cmd
-<toolname> --version
-~~~
-
-(where `<toolname>` is `mrg-import`, `mrgt`, `hrgt`, or `trrt`).
-
-### Step 1: importing MRGs
-
-The first step consists of ensuring that [terminologies](@tev2) that are
-defined elsewhere, and that you rely on to be available (e.g., as you refer
-to its [terms](@tev2)), are actually available.
-
-You can skip this step if there are no such [terminologies](@tev2).
-
-As this file makes extensive use of the [terms](@tev2) defined by TEv2,
-we need to import its (default) [MRG](@tev2). You can do that by executing
-the following command from within the directory that contains `saf.yaml`
-
-~~~ cmd
-mrg-import -c "tev2-configs.yaml"
-~~~
-
-This will add various files in the `mrgs` directory, called `mrg.tev2*.yaml`.
-You can discard all, except `mrg.tev2.yaml`, but you can also leave them
-where they are, as they are not in the way.
-
-### Step 2: generating Machine Readable Glossaries (MRGs)
-
-In the second step, we will generate [machine readable glossaries](@tev2)
-for the [terminologies](@tev2) that are defined in the [saf](@tev2).
-You can do that by executing the following command:
-
-~~~ cmd
-mrgt -c "tev2-configs.yaml"
-~~~
-
-This adds another two [MRGs](@tev2) to the `mrgs` directory:
-
-- `mrg.mve.terms.yaml` holds the [MRG](@tev2) that contains all [terms](@tev2)
-that are defined in our MVE-[scope](@tev2).
-- `mrg.mve.yaml` holds the [MRG](@tev2) that contains all [terms](@tev2)
-in the default [terminology](@tev2) of our MVE-[scope](@tev2).
-
-It so happens that these files have the same contents.
-
-### Step 3: generating Human Readable Glossaries (HRGs)
-
-Next, we can generate the [human readable glossaries](@tev2).
-
-You can do that by executing the following command:
-
-~~~ cmd
-hrgt -c "tev2-configs.yaml"
-~~~
-
+## Notes

docs/how-to/config-files.md

@@ -60,7 +60,7 @@ For example,
   as the value for its `converter` argument. And it will only process files that
   have the extension `.md` and that are located in the [scopedir](@tev2) itself.
 
-# Notes
+## Notes
 
 1. **Converters determine what the output of a tool looks like**.
    Each tool that uses [converters](@tev2) comes with a set of predefined ones.

docs/how-to/generate-mrgs.md

@@ -12,7 +12,7 @@ This results in the generated [MRGs](@tev2) to become available in the
 `mrgs`-directory (as specified by the [SAF](@tev2)).
 In our case, that would be 
 
-- `mrg.mve.terms.yaml`, which holds the [MRG](@tev2) that contains all [terms](@tev2)
+- `mrg.mve.mve-terms.yaml`, which holds the [MRG](@tev2) that contains all [terms](@tev2)
 that are defined in our [MVE](@), and
 - `mrg.mve.yaml`, which holds the [MRG](@tev2) that contains all [terms](@tev2)
 in the default [terminology](@tev2) of our MVE-[scope](@tev2).

docs/how-to/saf.md

@@ -16,44 +16,57 @@ is called the [scopedir](@tev2) (of that [scope](@tev2)).
 It is the root relative to which all TEv2-related paths are specified.
 
 Here is an example of the [SAF](@tev2) for this [MVE](@).
-For starters, you can simply copy this text, and adjust the contents of the various fields.
+For starters, you can simply copy this text, and adjust the contents of the various fields. When you do so, please be very accurate with the values that you provide. 
 
 ~~~ yaml
 scope:
-  # identifier that we use for this terminology
+  # Identifier that we use as a name for this scope
   scopetag: mve
-  # URL of the scope-directory (within the repo)
+  # URL of the scope-directory within the repo
   scopedir: https://github.com/tno-terminology-design/tev2-mve/tree/master/docs
-  # path to directory where curated files are located. Full URL is `scopedir`/`curatedir`
+  # path to directory where curated files are located. 
+  # Full URL is `scopedir`/`curatedir`
   curatedir: terms
-  # path to directory where all MRGs are located. Full URL is `scopedir`/`glossarydir`
+  # path to directory where all MRGs are located. 
+  # Full URL is `scopedir`/`glossarydir`
   glossarydir: mrgs
-  # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml
-  defaultvsn: terms
-  # base URL for creating links to rendered versions of Curated Texts. It should also serve as the home page of the terminology.
-  website: https://tno-terminology-design.github.io/tev2-mve/docs
-  # Path to the directory where Curated Texts are rendered. What `curatedir` is for Curated Texts is, `navpath` is for the rendered versions of Curated Texts.
+  # vsntag that identifies the default terminology. 
+  # Its MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml
+  defaultvsn: mve-terms
+  # Base URL for creating links to rendered versions of Curated Texts.
+  # It should also serve as the home page of the terminology.
+  website: https://tno-terminology-design.github.io/tev2-mve
+  # Path to the directory where Curated Texts are rendered. 
+  # What `curatedir` is for Curated Texts, `navpath` is for 
+  # the rendered versions of Curated Texts.
   navpath: /terms
-  # Name of the field in the front matter of a body file used by your static site generator in a URL, to uniquely identify that file (e.g., "id", "slug", "permalink"). If not specified, the filename of the body file will be used. | 
-  navid:
+  # Name of a field that can be found in the front matter of a 
+  # curated text file, that will be used to generate links that
+  # are routable by the static site generator that is being used.
+  # If not specified, the filename of the body file will be used.
+  navid: term
 #
-# The `scopes` section contains a mapping between scopetags that are used within the scope, 
-# and the associated scopedirs.
-# This enables tools to find the SAF of these scopes, and from there all other directories, files etc.
-# that live within them, e.g. to use/import their data.
+# The `scopes` section contains a mapping between scopetags 
+# that are used within the scope, and the associated scopedirs.
+# This enables tools to find the SAF of these scopes,
+# and from there all other directories, files etc. that live
+# within them, e.g. to use/import their data.
 #
-scopes:  #
-- scopetag: tev2
-  # URL of the scope-directory
+scopes:
+- scopetag: tev2 # name we use to identify the scope found at
+  # the URL of the scope-directory:
   scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs
 #
-# The `versions` section specifies the terminologies that are actively maintained by the curators.
-# For each (version of such a) terminology, instructions are given that say which terms are to be included.
-# One such section must have a `vsntag` that matches the value of `defaultvsn` in the `scope`-section
+# The `versions` section specifies the terminologies 
+# that are actively maintained by the curators of this scope.
+# For each (version of such a) terminology, termselection instructions
+# must be provided that specify which terms are to be included.
+# One of these section must have a `vsntag` that matches 
+# the value of `defaultvsn` in the `scope`-section.
 #
 versions:
   # this version contains all terms that are curated within this scope
-- vsntag: terms 
+- vsntag: mve-terms 
   termselection:
   # include all terms that are curated within the current scope
   - "*"

docs/saf.yaml

@@ -2,30 +2,56 @@
 # This is a Scope Administration File (SAF) that can be used in conjunction with Terminology Engine v2: https://tno-terminology-design.github.io/tev2-specifications/docs/category/introduction-overview.
 #
 scope:
-  scopetag: mve # identifier that curators have determined for this terminology
-  scopedir: https://github.com/tno-terminology-design/tev2-mve/tree/master/docs # URL of the scope-directory
-  curatedir: terms # directory where all curated files are located. Full URL is `scopedir`/`curatedir`
-  glossarydir: mrgs # directory where all MRGs are located. Full URL is `scopedir`/`glossarydir`
-  defaultvsn: terms # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml
-  website: https://tno-terminology-design.github.io/tev2-mve # base URL for creating links to rendered versions of Curated Texts. It should also serve as the home page of the terminology.
-  navpath: /terms # Path to the directory where Curated Texts are rendered. What `curatedir` is for Curated Texts is, `navpath` is for the rendered versions of Curated Texts.
-  navid: term # Name of the field in the front matter of a body file used by your static site generator in a URL, to uniquely identify that file (e.g., "id", "slug", "permalink"). If not specified, the filename of the body file will be used. | 
+  # Identifier that we use as a name for this scope
+  scopetag: mve
+  # URL of the scope-directory within the repo
+  scopedir: https://github.com/tno-terminology-design/tev2-mve/tree/master/docs
+  # path to directory where curated files are located. 
+  # Full URL is `scopedir`/`curatedir`
+  curatedir: terms
+  # path to directory where all MRGs are located. 
+  # Full URL is `scopedir`/`glossarydir`
+  glossarydir: mrgs
+  # vsntag that identifies the default terminology. 
+  # Its MRG is located at `scopedir`/`glossarydir`/mrg.mve.yaml
+  defaultvsn: mve-terms
+  # Base URL for creating links to rendered versions of Curated Texts.
+  # It should also serve as the home page of the terminology.
+  website: https://tno-terminology-design.github.io/tev2-mve
+  # Path to the directory where Curated Texts are rendered. 
+  # What `curatedir` is for Curated Texts, `navpath` is for 
+  # the rendered versions of Curated Texts.
+  navpath: /terms
+  # Name of a field that can be found in the front matter of a 
+  # curated text file, that will be used to generate links that
+  # are routable by the static site generator that is being used.
+  # If not specified, the filename of the body file will be used.
+  navid: term
 #
-# The `scopes` section contains a mapping between scopetags that are used within the scope, and the associated scopedirs.
-# This enables tools to find the SAF of these scopes, and from there all other directories, files etc.
-# that live within them, e.g. to use/import their data.
+# The `scopes` section contains a mapping between scopetags 
+# that are used within the scope, and the associated scopedirs.
+# This enables tools to find the SAF of these scopes,
+# and from there all other directories, files etc. that live
+# within them, e.g. to use/import their data.
 #
-scopes:  #
-- scopetag: tev2
-  scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs # URL of the scope-directory
+scopes:
+- scopetag: tev2 # name we use to identify the scope found at
+  # the URL of the scope-directory:
+  scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs
 #
-# The `versions` section specifies the terminologies that are actively maintained by the curators.
-# For each (version of such a) terminology, instructions are given that say which terms are to be included.
+# The `versions` section specifies the terminologies 
+# that are actively maintained by the curators of this scope.
+# For each (version of such a) terminology, termselection instructions
+# must be provided that specify which terms are to be included.
+# One of these section must have a `vsntag` that matches 
+# the value of `defaultvsn` in the `scope`-section.
 #
 versions:
-- vsntag: terms # this version contains all terms that are curated within this scope
+  # this version contains all terms that are curated within this scope
+- vsntag: mve-terms 
   termselection:
-  - "*" # include all terms that are curated within the current scope
+  # include all terms that are curated within the current scope
+  - "*"
 # - vsntag: documentation # this version contains all terms we use to refer to in this site
 #   termselection:
 #   - "*"@tev2" # include all terms of the default TEv2 terminology