Make readers aware of broken-symlink-and-BIDS-validator-issues

docs/basics/101-115-symlinks.rst

@@ -303,15 +303,14 @@ the content isn't yet present locally, and are thus *broken*. This state,
 however, is not problematic at all. Once the content is retrieved via
 :command:`datalad get`, the symlink is functional again.
 
-Nevertheless, it may be important to know that some file managers (e.g., OSX's
-Finder) may not display broken symlinks. In these cases, it will be
-impossible to browse and explore the file hierarchy of not-yet-retrieved
-files with the file manager. You can make sure to always be able to see the
-file hierarchy in two seperate ways: Upgrade your file manager to display
-file types in a DataLad datasets (e.g., the
-`git-annex-turtle extension <https://github.com/andrewringler/git-annex-turtle>`_
-for Finder). Alternatively, use the :command:`ls` command in a terminal instead
-of a file manager GUI.
+Nevertheless, it may be important to know that some tools that you would expect to work in a dataset with not yet retrieved file contents can encounter unintuitive problems.
+Some **file managers** (e.g., OSX's Finder) may not display broken symlinks.
+In these cases, it will be impossible to browse and explore the file hierarchy of not-yet-retrieved files with the file manager.
+You can make sure to always be able to see the file hierarchy in two separate ways:
+Upgrade your file manager to display file types in a DataLad datasets (e.g., the `git-annex-turtle extension <https://github.com/andrewringler/git-annex-turtle>`_ for Finder).
+Alternatively, use the :command:`ls` command in a terminal instead of a file manager GUI.
+Other tools may be more more specialized, smaller, or domain-specific, and may fail to correctly work with broken symlinks, or display unhelpful error messages when handling them, or require additional flags to modify their behavior (such as the :ref:`BIDS Validator <bidsvalidator>`, used in the neuroimaging community).
+When encountering unexpected behavior or failures, try to keep in mind that a dataset without retrieved content appears to be a pile of broken symlinks to a range of tools, consult a tools documentation with regard to symlinks, and check whether data retrieval fixes persisting problems.
 
 Finally, if you are still in the ``books/`` directory, go back into the root of
 the superdataset.

docs/basics/101-180-FAQ.rst

@@ -471,8 +471,22 @@ MEG, EEG, iEEG, and ECoG data. It publishes hosted data as DataLad datasets on
 obtain the datasets just as any other DataLad datasets with :command:`datalad clone`
 or :command:`datalad install`.
 
+
+.. _bidsvalidator:
+
+BIDS validator issues in datasets with missing file content
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As outlined in section :ref:`symlink`, all unretrieved files in datasets are broken symlinks.
+This is desired, and not a problem per se, but some tools, among them the `BIDS validator <https://github.com/bids-standard/bids-validator>`_, can be confused by this.
+Should you attempt to validate a dataset in which all or some file contents are missing, for example after cloning a dataset or after dropping file contents, the validator may fail to report on the validity of the complete dataset or the specific unretrieved files.
+If you aim for a complete validation of your dataset, re-do the validation after retrieving all necessary file contents.
+If you only aim to validate file names and structure, invoke the bids validator with the additional flags ``--ignoreNiftiHeaders`` and  ``--ignoreSymlinks``.
+
+
 .. _gitannexbranch:
 
+
 What is the git-annex branch?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 If your DataLad dataset contains an annex, there is also a ``git-annex`` :term:`branch`