[MISC] fix links, make json object links consistent, fix pandoc rendering

src/02-common-principles.md

@@ -99,8 +99,8 @@ A file name consists of a chain of *entities*, or key-value pairs, a *suffix* an
 Two prominent examples of entities are `subject` and `session`.
 
 For a data file that was collected in a given `session` from a given
-`subject`, the file name MUST begin with the string `sub-<label>_ses-<label>`. 
-If the `session` level is omitted in the folder structure, the file name MUST begin 
+`subject`, the file name MUST begin with the string `sub-<label>_ses-<label>`.
+If the `session` level is omitted in the folder structure, the file name MUST begin
 with the string `sub-<label>`, without `ses-<label>`.
 
 Note that `sub-<label>` corresponds to the `subject` entity because it has
@@ -134,8 +134,11 @@ See [Storage of derived datasets](#storage-of-derived-datasets) for more on
 organizing derivatives.
 
 Similar rules apply to source data, which is defined as data before
-harmonization, reconstruction, and/or file format conversion (for example, E-Prime event logs or
-DICOM files). This specification currently does not go into details of
+harmonization, reconstruction, and/or file format conversion (for example, E-Prime event logs or DICOM files).
+Storing actual source files with the data is preferred over links to
+external source repositories to maximize long term preservation,
+which would suffer if an external repository would not be available anymore.
+This specification currently does not go into the details of
 recommending a particular naming scheme for including different types of
 source data (raw event logs, parameter files, etc. before conversion to BIDS).
 However, in the case that these data are to be included:
@@ -412,7 +415,7 @@ onset duration  response_time correct stop_trial  go_trial
 ```
 
 Tabular files MAY be optionally accompanied by a simple data dictionary
-in the form of a [JSON object](https://www.w3schools.com/js/js_json_objects.asp)
+in the form of a JSON [object](https://www.json.org/json-en.html)
 within a JSON file.
 The JSON files containing the data dictionaries MUST have the same name as
 their corresponding tabular files but with `.json` extensions.
@@ -646,9 +649,7 @@ Validation and parsing tools MAY treat the presence of non-standard files and
 directories as an error, so consult the details of these tools for mechanisms
 to suppress warnings or provide interpretations of your file names.
 
-[]: <> (################)
-[]: <> (Link definitions)
-[]: <> (################)
+<!-- Link Definitions -->
 
 [dataset-description]: 03-modality-agnostic-files.md#dataset-description
 [derived-dataset-description]: 03-modality-agnostic-files.md#derived-dataset-and-pipeline-description

src/03-modality-agnostic-files.md

@@ -69,10 +69,10 @@ In addition to the keys for raw BIDS datasets,
 derived BIDS datasets include the following REQUIRED and RECOMMENDED
 `dataset_description.json` keys:
 
-| **Key name**   | **Description**                                                                                                                                                                    |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GeneratedBy    | REQUIRED. List of [objects][object] with at least one element.                                                                                                                     |
-| SourceDatasets | RECOMMENDED. A list of [objects][object] specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
+| **Key name**   | **Description**                                                                                                                                                              |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GeneratedBy    | REQUIRED. List of [objects][] with at least one element.                                                                                                                     |
+| SourceDatasets | RECOMMENDED. A list of [objects][] specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
 
 Each object in the `GeneratedBy` list includes the following REQUIRED, RECOMMENDED
 and OPTIONAL keys:
@@ -83,7 +83,7 @@ and OPTIONAL keys:
 | Version      | RECOMMENDED. Version of the pipeline.                                                                                                                                                                        |
 | Description  | OPTIONAL. Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if `Name` is `"Manual"`.                                                                                 |
 | CodeURL      | OPTIONAL. URL where the code used to generate the derivatives may be found.                                                                                                                                  |
-| Container    | OPTIONAL. [Object][object] specifying the location and relevant attributes of software container image used to produce the derivative. Valid fields in this object include `Type`, `Tag` and `URI`.          |
+| Container    | OPTIONAL. [Object][] specifying the location and relevant attributes of software container image used to produce the derivative. Valid fields in this object include `Type`, `Tag` and `URI`.                |
 
 Example:
 
@@ -344,7 +344,7 @@ For anonymization purposes all dates within one subject should be shifted by a
 randomly chosen (but consistent across all runs etc.) number of days.
 This way relative timing would be preserved, but chances of identifying a
 person based on the date and time of their scan would be decreased.
-Dates that are shifted for anonymization purposes should be set to a year 1925
+Dates that are shifted for anonymization purposes SHOULD be set to the year 1925
 or earlier to clearly distinguish them from unmodified data.
 Shifting dates is RECOMMENDED, but not required.
 
@@ -368,12 +368,16 @@ func/sub-control01_task-motor_bold.nii.gz	1877-06-15T13:55:33
 
 Template: `code/*`
 
-Source code of scripts that were used to prepare the dataset (for example if it
-was anonymized or defaced) MAY be stored here.<sup>1</sup> Extra care should be
-taken to avoid including original IDs or any identifiable information with the
-source code. There are no limitations or recommendations on the language and/or
+Source code of scripts that were used to prepare the dataset MAY be stored here.
+Examples include anonymization or decacing of the data, or
+the converstion from the format of the source data to the BIDS format
+(see [source vs. raw vs. derived data](./02-common-principles.md#source-vs-raw-vs-derived-data)).
+Extra care should be taken to avoid including original IDs or
+any identifiable information with the source code.
+There are no limitations or recommendations on the language and/or
 code organization of these scripts at the moment.
 
-<sup>1</sup>Storing actual source files with the data is preferred over links to
-external source repositories to maximize long term preservation (which would
-suffer if an external repository would not be available anymore).
+<!-- Link Definitions -->
+
+[objects]: https://www.json.org/json-en.html
+[object]: https://www.json.org/json-en.html