From 71ecd41e25f084dbf7995410cdb89432f6532c6a Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Sat, 4 Dec 2021 13:49:44 +0100
Subject: [PATCH] [FIX] Add links from derivatives section to entity list
 (#936)

* FIX: Add links from derivatives section to entity list

* fix brackets
---
 src/05-derivatives/01-introduction.md      |  5 +++--
 src/05-derivatives/02-common-data-types.md | 20 +++++++++++--------
 src/05-derivatives/03-imaging.md           | 23 +++++++++++++---------
 3 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index e37bb135cd..f215d9c59a 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -57,7 +57,8 @@ in [Derived dataset and pipeline description][derived-dataset-description].
     files.
 
 -   When necessary to distinguish two files that do not otherwise have a
-    distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
+    distinguishing entity, the [`_desc-<label>`](../99-appendices/09-entities.md#desc)
+    keyword-value SHOULD be used.
     This includes the cases of needing to distinguish both differing inputs and
     differing outputs (for example, `_desc-T1w` and `_desc-T2w` to distinguish
     brain mask files derived from T1w and T2w images;
@@ -67,7 +68,7 @@ in [Derived dataset and pipeline description][derived-dataset-description].
 -   When naming files that are not yet standardized, it is RECOMMENDED to use
     names consistent with BIDS conventions where those conventions apply.
     For example, if a summary statistic is derived from a given task, the file
-    name SHOULD contain `_task-<label>`.
+    name SHOULD contain [`_task-<label>`](../99-appendices/09-entities.md#task).
 
 <!-- Link Definitions -->
 
diff --git a/src/05-derivatives/02-common-data-types.md b/src/05-derivatives/02-common-data-types.md
index dfff52aa1b..e03d88ca14 100644
--- a/src/05-derivatives/02-common-data-types.md
+++ b/src/05-derivatives/02-common-data-types.md
@@ -24,8 +24,9 @@ share the following (non-required) ones:
 ### Examples
 
 Preprocessed `bold` NIfTI file in the original coordinate space of the original run.
-The location of the file in the original datasets is encoded in the `RawSources`
-metadata, and `desc-<label>` is used to prevent clashing with the original file name.
+The location of the file in the original datasets is encoded in the `RawSources` metadata,
+and [`_desc-<label>`](../99-appendices/09-entities.md#desc)
+is used to prevent clashing with the original file name.
 
 {{ MACROS___make_filetree_example(
    {
@@ -75,12 +76,13 @@ occurs in the derivatives, `Sources` and `RawSources` can both be specified.
 Derivatives are often aligned to a common spatial reference to allow for the
 comparison of acquired data across runs, sessions, subjects or datasets.
 A file may indicate the spatial reference to which it has been aligned using the
-`space` entity and/or the `SpatialReference` metadata.
+[`space` entity](../99-appendices/09-entities.md#space) and/or the `SpatialReference` metadata.
 
-The `space` entity may take any value in [Image-Based Coordinate Systems][coordsys].
+The [`space` entity](../99-appendices/09-entities.md#space) may take any value in
+[Image-Based Coordinate Systems][coordsys].
 
-If the `space` entity is omitted, or the space is not in the
-[Standard template identifiers][templates] table,
+If the [`space` entity](../99-appendices/09-entities.md#space) is omitted,
+or the space is not in the [Standard template identifiers][templates] table,
 then the `SpatialReference` metadata is REQUIRED.
 
 {{ MACROS___make_metadata_table(
@@ -174,10 +176,12 @@ Examples of preprocessing:
 -   Time-domain filtered EEG data
 -   MaxFilter (for example, SSS) cleaned MEG data
 
-The `space` keyword is recommended to distinguish files with different underlying
+The [`space` entity](../99-appendices/09-entities.md#space)
+is recommended to distinguish files with different underlying
 coordinate systems or registered to different reference maps.
 See [Spatial references](#spatial-references) for details.
-The `desc` (description) keyword is a general purpose field with freeform values,
+The [`desc` entity](../99-appendices/09-entities.md#desc) ("description")
+is a general purpose field with freeform values,
 which SHOULD be used to distinguish between multiple different versions of
 processing for the same input data.
 
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 4af6af617c..0cce5b1733 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -22,11 +22,13 @@ sufficiently similar in practice to treat them equivalently.
 
 When two or more instances of a given derivative are provided with resolution
 or surface sampling density being the only difference between them, then the
-`res` (for *resolution* of regularly sampled N-D data) and/or `den` (for
-*density* of non-parametric surfaces) SHOULD be used to avoid name conflicts.
+[`res`](../99-appendices/09-entities.md#res) (for *resolution* of regularly sampled N-D data) and/or
+[`den`](../99-appendices/09-entities.md#den) (for *density* of non-parametric surfaces)
+entities SHOULD be used to avoid name conflicts.
 Note that only files combining both regularly sampled (for example, gridded)
 and surface sampled data (and their downstream derivatives) are allowed
-to present both `res` and `den` entities simultaneously.
+to present both [`res`](../99-appendices/09-entities.md#res) and
+[`den`](../99-appendices/09-entities.md#den) entities simultaneously.
 
 Examples:
 
@@ -89,7 +91,8 @@ And one corresponding to `res-hi`
 ```
 
 Example of CIFTI-2 files (a format that combines regularly sampled data
-and non-parametric surfaces) having both `res` and `den` entities:
+and non-parametric surfaces) having both [`res`](../99-appendices/09-entities.md#res)
+and [`den`](../99-appendices/09-entities.md#den) entities:
 
 {{ MACROS___make_filetree_example(
    {
@@ -134,9 +137,9 @@ Template:
             <source_entities>[_space-<space>][_res-<label>][_den-<label>][_label-<label>][_desc-<label>]_mask.nii.gz
 ```
 
-A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
+A binary (1 - inside, 0 - outside) mask in the space defined by the [`space` entity](../99-appendices/09-entities.md#space).
 If no transformation has taken place, the value of `space` SHOULD be set to `orig`.
-If the mask is an ROI mask derived from an atlas, then the `label` entity SHOULD
+If the mask is an ROI mask derived from an atlas, then the [`label` entity](../99-appendices/09-entities.md#label)) SHOULD
 be used to specify the masked structure
 (see [Common image-derived labels](#common-image-derived-labels)),
 and the `Atlas` metadata SHOULD be defined.
@@ -247,7 +250,8 @@ Example:
 
 A segmentation can be used to generate a binary mask that functions as a
 discrete "label" for a single structure.
-In this case, the mask suffix MUST be used, the `label` entity SHOULD be used
+In this case, the mask suffix MUST be used,
+the [`label` entity](../99-appendices/09-entities.md#label)) SHOULD be used
 to specify the masked structure
 (see [Common image-derived labels](#common-image-derived-labels)),
 and the `Atlas` metadata SHOULD be defined.
@@ -270,7 +274,8 @@ For example:
 Probabilistic segmentations of brain tissue represent a single anatomical
 structure with values ranging from 0 to 1 in individual 3D volumes or across
 multiple frames.
-If a single structure is included, the `label` entity SHOULD be used to specify
+If a single structure is included,
+the [`label` entity](../99-appendices/09-entities.md#label) SHOULD be used to specify
 the structure.
 
 Template:
@@ -298,7 +303,7 @@ Example:
 ) }}
 
 See [Common image-derived labels](#common-image-derived-labels)
-for reserved key values for `label`.
+for reserved key values for [`label`](../99-appendices/09-entities.md#label).
 
 A 4D probabilistic segmentation, in which each frame corresponds to a different
 tissue class, must provide a label mapping in its JSON sidecar. For example: