From ee4966b48240102d00738a2b57c0fe47b76c2900 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 07:34:35 +0100
Subject: [PATCH 01/17] enh: add compressed TSV files to the common principles

Their description is hedged within the physiological recordings so
upcasting them to the common principles seems important.
---
 src/common-principles.md                      | 26 +++++++++++++++++++
 ...logical-and-other-continuous-recordings.md | 24 +++++------------
 2 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 1b8c09a407..df007b12d7 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -542,6 +542,32 @@ like in the example below.
 }
 ```
 
+### Compressed tabular files
+
+Large tabular information such as physiological recordings MAY be stored with
+[compressed tab-delineated (TSVGZ) files](glossary.md#tsvgz-extensions).
+Rules for formatting plain-text tabular files apply to TSVGZ files with three exceptions:
+
+1.  The contents of TSVGZ files SHOULD be compressed with
+    [gzip](https://datatracker.ietf.org/doc/html/rfc1952).
+1.  Compressed tabular files SHOULD NOT contain a header in the first row
+    indicating the column names.
+1.  TSVGZ files SHOULD be accompanied by a JSON file with the same name as their
+    corresponding tabular file but with a `.json` extension.
+
+???+ warning "Columns of TSVGZ files MUST be defined in the corresponding JSON sidecar and the tabular content MUST NOT include a header line."
+
+    In contrast to plain-text TSV files, compressed tabular files files
+    MUST NOT include a header line.
+    Column names MUST be specified in the JSON file following the
+    [`Columns` metadata](glossary.md#columns-metadata) specifications.
+    As plain-text tabular data, column names MUST NOT be blank (that is, an empty string),
+    and MUST NOT be duplicated within a single JSON file describing a TSVGZ file.
+
+    TSVGZ are header-less to improve compatibility with existing software
+    (for example, FSL, or PNM), and to facilitate the support for other file formats
+    in the future.
+
 ### Key-value files (dictionaries)
 
 JavaScript Object Notation (JSON) files MUST be used for storing key-value
diff --git a/src/modality-specific-files/physiological-and-other-continuous-recordings.md b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
index 38f9842ae3..f3bc4f27e2 100644
--- a/src/modality-specific-files/physiological-and-other-continuous-recordings.md
+++ b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
@@ -2,12 +2,9 @@
 
 Physiological recordings such as cardiac and respiratory signals and other
 continuous measures (such as parameters of a film or audio stimuli) MAY be
-specified using two files:
-
-1.  a [gzip](https://datatracker.ietf.org/doc/html/rfc1952)
-    compressed TSV file with data (without header line)
-
-1.  a JSON file for storing metadata fields (see below)
+specified using a [compressed tabular file](../common-principles.md#compressed-tabular-files)
+([TSVGZ file](../glossary.md#tsvgz-extensions)) and a corresponding
+JSON file for storing metadata fields (see below).
 
 !!! example "Example datasets"
 
@@ -38,8 +35,10 @@ before the suffix.
 For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 `<matches>` would correspond to `sub-control01_task-nback_run-1`.
 
-Note that when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
-`*_<physio|stim>.json` MUST be supplied as well.
+!!! warning "TSVGZ files SHOULD NOT include a header line (as established by the [common-principles](../common-principles.md#compressed-tabular-files))"
+
+    As a result, when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
+    `*_<physio|stim>.json` MUST be supplied as well.
 
 The [`recording-<label>`](../appendices/entities.md#recording)
 entity MAY be used to distinguish between several recording files.
@@ -66,15 +65,6 @@ A guide for using macros can be found at
 Additional metadata may be included as in
 [any TSV file](../common-principles.md#tabular-files) to specify, for
 example, the units of the recorded time series.
-Please note that, in contrast to other TSV files in BIDS, the TSV files specified
-for physiological and other continuous recordings *do not* include a header
-line.
-Instead the name of columns are specified in the JSON file (see `Columns` field).
-This is to improve compatibility with existing software (for example, FSL, PNM)
-as well as to make support for other file formats possible in the future.
-As in any TSV file, column names MUST NOT be blank (that is, an empty string),
-and MUST NOT be duplicated within a single JSON file describing a headerless
-TSV file.
 
 Example `*_physio.tsv.gz`:
 

From a4c5adcad53eee44dbc85792a17258d3d935a237 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 11:37:00 +0100
Subject: [PATCH 02/17] fix: use semantic linebreaks and improve consistency
 with 'tabular files' subsection

---
 src/common-principles.md | 41 ++++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index df007b12d7..5e638404d8 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -430,36 +430,41 @@ NIfTI header.
 
 ### Tabular files
 
-Tabular data MUST be saved as tab delimited values (`.tsv`) files, that is, CSV
-files where commas are replaced by tabs. Tabs MUST be true tab characters and
-MUST NOT be a series of space characters. Each TSV file MUST start with a header
-line listing the names of all columns (with the exception of
-[physiological and other continuous recordings](modality-specific-files/physiological-and-other-continuous-recordings.md)
-as well as [motion recording data](modality-specific-files/motion.md)).
+Tabular data MUST be saved as plain-text, tab-delimited values (`.tsv`) files,
+that is, CSV files where commas are replaced by tab characters.
+Tabs MUST be true tab characters and MUST NOT be a series of space characters.
+Tabular data containing large numbers of rows MAY be saved as
+[compressed tabular files (with extension `.tsv.gz`)](#compressed-tabular-files)
+as prescribed below.
+Each TSV file MUST start with a header line listing the names of all columns
+with the exception of [compressed tabular files](#compressed-tabular-files)
+where column names are defined in a sidecar metadata
+[JSON object](https://www.json.org/json-en.html) described below.
+
 It is RECOMMENDED that the column names in the header of the TSV file are
 written in [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) with the
 first letter in lower case (for example, `variable_name`, not `Variable_name`).
-As for all other data in the TSV files, column names MUST be separated with tabs.
+Column names defined in the header MUST be separated with tabs as for the data contents.
 Furthermore, column names MUST NOT be blank (that is, an empty string) and MUST NOT
 be duplicated within a single TSV file.
-String values containing tabs MUST be escaped using double
-quotes. Missing and non-applicable values MUST be coded as `n/a`. Numerical
-values MUST employ the dot (`.`) as decimal separator and MAY be specified
+String values containing tabs MUST be escaped using double quotes.
+Missing and non-applicable values MUST be coded as `n/a`.
+Numerical values MUST employ the dot (`.`) as decimal separator and MAY be specified
 in scientific notation, using `e` or `E` to separate the significand from the
-exponent. TSV files MUST be in UTF-8 encoding.
+exponent.
+TSV files MUST be in UTF-8 encoding.
 
 Example:
 
 ```Text
 onset	duration	response_time	correct	stop_trial	go_trial
-200	200	0	n/a	n/a	n/a
+200     200         0               n/a     n/a         n/a
 ```
 
-**Note**: The TSV examples in this document (like the one above this note)
-are occasionally formatted using space characters instead of tabs to improve
-human readability.
-Directly copying and then pasting these examples from the specification
-for use in new BIDS datasets can lead to errors and is discouraged.
+!!! warning "The TSV examples in this document (like the one above this note) are occasionally formatted using space characters instead of tabs to improve human readability."
+
+    Directly copying and then pasting these examples from the specification
+    for use in new BIDS datasets can lead to errors and is discouraged.
 
 Tabular files MAY be optionally accompanied by a simple data dictionary
 in the form of a JSON [object](https://www.json.org/json-en.html)
@@ -536,7 +541,7 @@ like in the example below.
             "F": {
                 "Description": "Female",
                 "TermURL": "https://www.ncbi.nlm.nih.gov/mesh/68005260"
-            },
+            }
         }
     }
 }

From c4ee8d68cdff253055f86ed82c3992de8562bd35 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 13:58:08 +0100
Subject: [PATCH 03/17] enh: harmonize with motion specs

see https://github.com/bids-standard/bids-specification/pull/1749#issuecomment-2017854619
---
 src/common-principles.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 5e638404d8..156546b982 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -430,16 +430,22 @@ NIfTI header.
 
 ### Tabular files
 
-Tabular data MUST be saved as plain-text, tab-delimited values (`.tsv`) files,
+Tabular data MUST be saved as plain-text, tab-delimited values (TSV) files
+(with [extension `.tsv`](glossary.md#tsv-extensions)),
 that is, CSV files where commas are replaced by tab characters.
 Tabs MUST be true tab characters and MUST NOT be a series of space characters.
 Tabular data containing large numbers of rows MAY be saved as
 [compressed tabular files (with extension `.tsv.gz`)](#compressed-tabular-files)
 as prescribed below.
 Each TSV file MUST start with a header line listing the names of all columns
-with the exception of [compressed tabular files](#compressed-tabular-files)
-where column names are defined in a sidecar metadata
-[JSON object](https://www.json.org/json-en.html) described below.
+with two exceptions:
+
+1.  [compressed tabular files](#compressed-tabular-files),
+    for which column names are defined in a sidecar metadata
+    [JSON object](https://www.json.org/json-en.html) described below; and
+1.  [motion recording data](modality-specific-files/motion.md),
+    which use plain-text TSV and columns are defined as described
+    in its corresponding of the specifications.
 
 It is RECOMMENDED that the column names in the header of the TSV file are
 written in [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) with the

From 4eadad536ca962c9a113b4f4aeaa6f195938f20f Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 13:58:55 +0100
Subject: [PATCH 04/17] enh: exercise formatting in example

---
 src/common-principles.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 156546b982..3fe4c6355e 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -463,8 +463,8 @@ TSV files MUST be in UTF-8 encoding.
 Example:
 
 ```Text
-onset	duration	response_time	correct	stop_trial	go_trial
-200     200         0               n/a     n/a         n/a
+onset   duration    response_time   trial_type        trial_extra
+200     20.0        127.34e-1       ⌂ (UTF-8 char)    n/a
 ```
 
 !!! warning "The TSV examples in this document (like the one above this note) are occasionally formatted using space characters instead of tabs to improve human readability."

From aa60678f9eeb51b59883c097973a92f572e31c7c Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 15:30:06 +0100
Subject: [PATCH 05/17] Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/common-principles.md                                    | 6 +++---
 .../physiological-and-other-continuous-recordings.md        | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 3fe4c6355e..5cb84aa779 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -559,11 +559,11 @@ Large tabular information such as physiological recordings MAY be stored with
 [compressed tab-delineated (TSVGZ) files](glossary.md#tsvgz-extensions).
 Rules for formatting plain-text tabular files apply to TSVGZ files with three exceptions:
 
-1.  The contents of TSVGZ files SHOULD be compressed with
+1.  The contents of TSVGZ files MUST be compressed with
     [gzip](https://datatracker.ietf.org/doc/html/rfc1952).
-1.  Compressed tabular files SHOULD NOT contain a header in the first row
+1.  Compressed tabular files MUST NOT contain a header in the first row
     indicating the column names.
-1.  TSVGZ files SHOULD be accompanied by a JSON file with the same name as their
+1.  TSVGZ files MUST be accompanied by a JSON file with the same name as their
     corresponding tabular file but with a `.json` extension.
 
 ???+ warning "Columns of TSVGZ files MUST be defined in the corresponding JSON sidecar and the tabular content MUST NOT include a header line."
diff --git a/src/modality-specific-files/physiological-and-other-continuous-recordings.md b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
index f3bc4f27e2..d0ee9976b5 100644
--- a/src/modality-specific-files/physiological-and-other-continuous-recordings.md
+++ b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
@@ -35,7 +35,7 @@ before the suffix.
 For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 `<matches>` would correspond to `sub-control01_task-nback_run-1`.
 
-!!! warning "TSVGZ files SHOULD NOT include a header line (as established by the [common-principles](../common-principles.md#compressed-tabular-files))"
+!!! warning "TSVGZ files MUST NOT include a header line (as established by the [common-principles](../common-principles.md#compressed-tabular-files))"
 
     As a result, when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
     `*_<physio|stim>.json` MUST be supplied as well.

From 3811a8c4262a3ef32d7f37e5675ffdc5f41351c6 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 16:09:11 +0100
Subject: [PATCH 06/17] fix: deduplicate prescriptions for columns in tsvgz

---
 src/common-principles.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 5cb84aa779..712cebcff5 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -571,9 +571,11 @@ Rules for formatting plain-text tabular files apply to TSVGZ files with three ex
     In contrast to plain-text TSV files, compressed tabular files files
     MUST NOT include a header line.
     Column names MUST be specified in the JSON file following the
-    [`Columns` metadata](glossary.md#columns-metadata) specifications.
-    As plain-text tabular data, column names MUST NOT be blank (that is, an empty string),
-    and MUST NOT be duplicated within a single JSON file describing a TSVGZ file.
+    [`Columns` metadata](glossary.md#columns-metadata) specifications
+    provided with plain-text tabular data.
+    Similarly, specific column metadata stored with dictionaries such as
+    the `sex` column in the example above MUST be specified following the
+    plain-text tabular metadata prescriptions.
 
     TSVGZ are header-less to improve compatibility with existing software
     (for example, FSL, or PNM), and to facilitate the support for other file formats

From 8cedfe114f899b1d37b1ca3038b0f5aea98d2a30 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 17:43:22 +0100
Subject: [PATCH 07/17] Update src/common-principles.md

Co-authored-by: Remi Gau <remi_gau@hotmail.com>
---
 src/common-principles.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 712cebcff5..40ed87da82 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -445,7 +445,7 @@ with two exceptions:
     [JSON object](https://www.json.org/json-en.html) described below; and
 1.  [motion recording data](modality-specific-files/motion.md),
     which use plain-text TSV and columns are defined as described
-    in its corresponding of the specifications.
+    in its corresponding section of the specifications.
 
 It is RECOMMENDED that the column names in the header of the TSV file are
 written in [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) with the

From 784f60fba669245bb887acada50784c9b3280b4b Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 20:00:09 +0100
Subject: [PATCH 08/17] Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/common-principles.md                      | 21 ++++++++++---------
 ...logical-and-other-continuous-recordings.md |  4 +++-
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 40ed87da82..502e80c777 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -467,8 +467,10 @@ onset   duration    response_time   trial_type        trial_extra
 200     20.0        127.34e-1       ⌂ (UTF-8 char)    n/a
 ```
 
-!!! warning "The TSV examples in this document (like the one above this note) are occasionally formatted using space characters instead of tabs to improve human readability."
+!!! warning "TSV example formatting"
 
+    The TSV examples in this document (like the one above this note) are occasionally
+    formatted using space characters instead of tabs to improve human readability.
     Directly copying and then pasting these examples from the specification
     for use in new BIDS datasets can lead to errors and is discouraged.
 
@@ -566,16 +568,15 @@ Rules for formatting plain-text tabular files apply to TSVGZ files with three ex
 1.  TSVGZ files MUST be accompanied by a JSON file with the same name as their
     corresponding tabular file but with a `.json` extension.
 
-???+ warning "Columns of TSVGZ files MUST be defined in the corresponding JSON sidecar and the tabular content MUST NOT include a header line."
 
-    In contrast to plain-text TSV files, compressed tabular files files
-    MUST NOT include a header line.
-    Column names MUST be specified in the JSON file following the
-    [`Columns` metadata](glossary.md#columns-metadata) specifications
-    provided with plain-text tabular data.
-    Similarly, specific column metadata stored with dictionaries such as
-    the `sex` column in the example above MUST be specified following the
-    plain-text tabular metadata prescriptions.
+!!! note "Column definitions in compressed tabular files"
+
+    In contrast to plain-text TSV files,
+    compressed tabular files files MUST NOT include a header line.
+    Column names MUST be provided in the JSON file with the
+    [`Columns`](glossary.md#columns-metadata) field.
+    Each column MAY additionally be described with a column description,
+    as described in [Tabular files](#tabular-files).
 
     TSVGZ are header-less to improve compatibility with existing software
     (for example, FSL, or PNM), and to facilitate the support for other file formats
diff --git a/src/modality-specific-files/physiological-and-other-continuous-recordings.md b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
index d0ee9976b5..5bd86694f8 100644
--- a/src/modality-specific-files/physiological-and-other-continuous-recordings.md
+++ b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
@@ -35,8 +35,10 @@ before the suffix.
 For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 `<matches>` would correspond to `sub-control01_task-nback_run-1`.
 
-!!! warning "TSVGZ files MUST NOT include a header line (as established by the [common-principles](../common-principles.md#compressed-tabular-files))"
+!!! note "TSVGZ headers are specified in metadata files."
 
+    TSVGZ files MUST NOT include a header line,
+    as established by the [common-principles](../common-principles.md#compressed-tabular-files)).
     As a result, when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
     `*_<physio|stim>.json` MUST be supplied as well.
 

From a67e4f0cdf0d7ee8e10e2c1908c85fd7c6feccfb Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Mon, 25 Mar 2024 20:07:34 +0100
Subject: [PATCH 09/17] fix: checking if chinese characters are accepted by
 pandoc

---
 src/common-principles.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 502e80c777..536d765a0d 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -464,7 +464,8 @@ Example:
 
 ```Text
 onset   duration    response_time   trial_type        trial_extra
-200     20.0        127.34e-1       ⌂ (UTF-8 char)    n/a
+200     20.0        15.8            word              中国人
+240     5.0         17.34e-1        visual            n/a
 ```
 
 !!! warning "TSV example formatting"

From 4d37239a62d6b8ddb3f60cb5d9386173c5d0b388 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 26 Mar 2024 14:48:40 +0100
Subject: [PATCH 10/17] Apply suggestions from code review

---
 src/common-principles.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 536d765a0d..7754d69b3c 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -468,7 +468,7 @@ onset   duration    response_time   trial_type        trial_extra
 240     5.0         17.34e-1        visual            n/a
 ```
 
-!!! warning "TSV example formatting"
+!!! warning "Attention"
 
     The TSV examples in this document (like the one above this note) are occasionally
     formatted using space characters instead of tabs to improve human readability.
@@ -570,7 +570,7 @@ Rules for formatting plain-text tabular files apply to TSVGZ files with three ex
     corresponding tabular file but with a `.json` extension.
 
 
-!!! note "Column definitions in compressed tabular files"
+!!! warning "Attention"
 
     In contrast to plain-text TSV files,
     compressed tabular files files MUST NOT include a header line.

From 4cf56945e3cb5b43e44ea1b7dfaea66922dfdb03 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Tue, 26 Mar 2024 21:06:40 +0100
Subject: [PATCH 11/17] Apply suggestions from code review

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
---
 .../physiological-and-other-continuous-recordings.md            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modality-specific-files/physiological-and-other-continuous-recordings.md b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
index 5bd86694f8..1cde990e41 100644
--- a/src/modality-specific-files/physiological-and-other-continuous-recordings.md
+++ b/src/modality-specific-files/physiological-and-other-continuous-recordings.md
@@ -38,7 +38,7 @@ For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 !!! note "TSVGZ headers are specified in metadata files."
 
     TSVGZ files MUST NOT include a header line,
-    as established by the [common-principles](../common-principles.md#compressed-tabular-files)).
+    as established by the [common-principles](../common-principles.md#compressed-tabular-files).
     As a result, when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying
     `*_<physio|stim>.json` MUST be supplied as well.
 

From 48ffe9d1a920b4fe9bde3be69063b703e8ebd3ed Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 27 Mar 2024 11:28:45 +0100
Subject: [PATCH 12/17] Apply suggestions from code review

---
 src/common-principles.md | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 7754d69b3c..1c7165d0a5 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -434,9 +434,13 @@ Tabular data MUST be saved as plain-text, tab-delimited values (TSV) files
 (with [extension `.tsv`](glossary.md#tsv-extensions)),
 that is, CSV files where commas are replaced by tab characters.
 Tabs MUST be true tab characters and MUST NOT be a series of space characters.
-Tabular data containing large numbers of rows MAY be saved as
-[compressed tabular files (with extension `.tsv.gz`)](#compressed-tabular-files)
-as prescribed below.
+Tabular data such as continuous physiology recordings typically containing
+large numbers of rows MAY be saved as
+[compressed tabular files (with extension `.tsv.gz`)](#compressed-tabular-files),
+which are introduced below.
+Plain-text TSV and compressed TSV are not interchangeable, that is, each section
+of the specification prescribes which one SHOULD be used for the data type at
+hand.
 Each TSV file MUST start with a header line listing the names of all columns
 with two exceptions:
 
@@ -558,8 +562,9 @@ like in the example below.
 
 ### Compressed tabular files
 
-Large tabular information such as physiological recordings MAY be stored with
-[compressed tab-delineated (TSVGZ) files](glossary.md#tsvgz-extensions).
+Large tabular information, such as physiological recordings, SHOULD be stored with
+[compressed tab-delineated (TSVGZ) files](glossary.md#tsvgz-extensions) when
+so established by the specifications.
 Rules for formatting plain-text tabular files apply to TSVGZ files with three exceptions:
 
 1.  The contents of TSVGZ files MUST be compressed with

From bf397183816fcd02cb6b65d56657337f5b943125 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Wed, 27 Mar 2024 13:53:57 +0100
Subject: [PATCH 13/17] fix: replace SHOULD with MUST in last changes (cc
 @effigies)

Please revert if these should not be replaced.
---
 src/common-principles.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 1c7165d0a5..0bd9b5891c 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -439,7 +439,7 @@ large numbers of rows MAY be saved as
 [compressed tabular files (with extension `.tsv.gz`)](#compressed-tabular-files),
 which are introduced below.
 Plain-text TSV and compressed TSV are not interchangeable, that is, each section
-of the specification prescribes which one SHOULD be used for the data type at
+of the specification prescribes which one MUST be used for the data type at
 hand.
 Each TSV file MUST start with a header line listing the names of all columns
 with two exceptions:
@@ -562,7 +562,7 @@ like in the example below.
 
 ### Compressed tabular files
 
-Large tabular information, such as physiological recordings, SHOULD be stored with
+Large tabular information, such as physiological recordings, MUST be stored with
 [compressed tab-delineated (TSVGZ) files](glossary.md#tsvgz-extensions) when
 so established by the specifications.
 Rules for formatting plain-text tabular files apply to TSVGZ files with three exceptions:

From cf1435ce52443de6bc1fa7d455f5f180ee1a12f6 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 28 Mar 2024 21:34:36 +0100
Subject: [PATCH 14/17] Update src/common-principles.md

---
 src/common-principles.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 0bd9b5891c..6d341f42f2 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -571,8 +571,7 @@ Rules for formatting plain-text tabular files apply to TSVGZ files with three ex
     [gzip](https://datatracker.ietf.org/doc/html/rfc1952).
 1.  Compressed tabular files MUST NOT contain a header in the first row
     indicating the column names.
-1.  TSVGZ files MUST be accompanied by a JSON file with the same name as their
-    corresponding tabular file but with a `.json` extension.
+1.  TSVGZ files MUST have an associated JSON file that defines the columns in the tabular file.
 
 
 !!! warning "Attention"

From 8489d3ff9505a232cca994004b0a63ca069acf19 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Thu, 28 Mar 2024 21:35:41 +0100
Subject: [PATCH 15/17] Update src/common-principles.md

---
 src/common-principles.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 6d341f42f2..433efb5786 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -573,7 +573,6 @@ Rules for formatting plain-text tabular files apply to TSVGZ files with three ex
     indicating the column names.
 1.  TSVGZ files MUST have an associated JSON file that defines the columns in the tabular file.
 
-
 !!! warning "Attention"
 
     In contrast to plain-text TSV files,

From 7cb126a5064c40e08abb6e1916de39a52624bf63 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 30 Mar 2024 22:12:56 +0100
Subject: [PATCH 16/17] Update src/common-principles.md

Co-authored-by: Yaroslav Halchenko <debian@onerussian.com>
---
 src/common-principles.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index 433efb5786..e1bafd9a0f 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -432,7 +432,7 @@ NIfTI header.
 
 Tabular data MUST be saved as plain-text, tab-delimited values (TSV) files
 (with [extension `.tsv`](glossary.md#tsv-extensions)),
-that is, CSV files where commas are replaced by tab characters.
+that is, [CSV files](https://en.wikipedia.org/wiki/Comma-separated_values) where commas are replaced by tab characters.
 Tabs MUST be true tab characters and MUST NOT be a series of space characters.
 Tabular data such as continuous physiology recordings typically containing
 large numbers of rows MAY be saved as

From cab6e9d19ca660230df14acbd587f3ea0a3423e9 Mon Sep 17 00:00:00 2001
From: Oscar Esteban <code@oscaresteban.es>
Date: Sat, 30 Mar 2024 23:11:27 +0100
Subject: [PATCH 17/17] Update src/common-principles.md

Co-authored-by: Yaroslav Halchenko <debian@onerussian.com>
---
 src/common-principles.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/common-principles.md b/src/common-principles.md
index e1bafd9a0f..461842ddfc 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -563,7 +563,7 @@ like in the example below.
 ### Compressed tabular files
 
 Large tabular information, such as physiological recordings, MUST be stored with
-[compressed tab-delineated (TSVGZ) files](glossary.md#tsvgz-extensions) when
+[compressed tab-delineated (TSV.GZ) files](glossary.md#tsvgz-extensions) when
 so established by the specifications.
 Rules for formatting plain-text tabular files apply to TSVGZ files with three exceptions: