Remove duplicate entity definitions in specification text

[tsalo]

In #568 we created a new appendix with the entity definitions. Whenever the entities are referenced in the text, a hyperlink is used to point to the appropriate section of the appendix. The appendix definitions should be considered the "canonical" definitions for these entities, with text in the rest of the specification used only to provide modality-specific context and examples. We did not, however, edit the specification text much in #568, so there are a lot of duplicate definitions and elaborations that could be removed or at least cut down.

[Remi-Gau]

Was thinking I could do some of that.

Just to be sure: any mention of any of the entities from the appendix should have a hyperlink?

But only if it is "on its own" and not in an example of a "path".

For example:

Add a hyperlink to sub-<label> in the example below.

The purpose of this RECOMMENDED file is to describe properties of participants
such as age, sex, handedness.
In case of single-session studies, this file has one compulsory column
`participant_id` that consists of `sub-<label>`, followed by a list of optional
columns describing participants.
Each participant MUST be described by one and only one row.

But obviously not sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json

In this particular case, the sidecar JSON file
`sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json`
MUST define the time of two echos used to map the phase and finally calculate
the phase-difference map.

[tsalo]

I wish we could render code snippets with hyperlinks, but I don't think it's possible in Markdown (it was something I looked into for #610).

In addition to the linking, there are actual definitions that could be eliminated or reduced, such as this one in MEG:

The proc- entity is analogous to rec- for MR and denotes a variant of a file that was a result of particular processing performed on the device. This is useful for files produced in particular by Elekta’s MaxFilter (for example, sss, tsss, trans, quat, mc), which some installations impose to be run on raw data because of active shielding software corrections before the MEG data can actually be exploited.

I don't know what the updated text should be, but since the description in the text is a complete duplicate of the definition of the entity, it would be great to reduce it. I think the main text should provide some section-specific context, rather than fully defining the entity. Plus, duplications in the text will make it harder to update entity definitions, since we'll have multiple places we have to change.

[tsalo]

Here is a gist that may make it possible to add hyperlinks to code blocks: https://gist.github.com/jesstelford/cb4dd6fafc18221ce27250e84fd19327

[Remi-Gau]

probably needs another pass to see how many duplicates are left