From 7ad3ee35737d4929b2063a1408456760b2725481 Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Wed, 15 Nov 2023 11:28:00 +0100 Subject: [PATCH] Rough formatting of tuning chapter --- docs/basics/101-122-config.rst | 14 +++++++++----- docs/basics/101-123-config2.rst | 8 ++++++-- docs/basics/101-124-procedures.rst | 15 ++++++++++----- 3 files changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/basics/101-122-config.rst b/docs/basics/101-122-config.rst index 17fded51f..396923c64 100644 --- a/docs/basics/101-122-config.rst +++ b/docs/basics/101-122-config.rst @@ -197,11 +197,15 @@ command. By specifying the ``name`` option with ``section.variable`` a value, one can configure Git, git-annex, and DataLad. *Most* of these configurations will be written to a ``config`` file of Git, depending on the scope (local, global, system-wide) -specified in the command. +specified in the command. Should you happen to make a mistake, +it is typically simple to rectify things again. Check the +:find-out-more:`on 'git config' `. .. index:: pair: unset configuration; with Git .. find-out-more:: If things go wrong during Git config + :name: fom-git-config + :float: tb If something goes wrong during the :gitcmd:`config` command, for example, you end up having two keys of the same name because you @@ -245,13 +249,13 @@ or identify necessary changes. And indeed, most of the sections and variables or values in there are irrelevant for understanding the book, your dataset, or DataLad, and can just be left as they are. The previous section merely served to de-mystify the :gitcmd:`config` command and the configuration files. -Nevertheless, it might be helpful to get an overview about the meaning of the -remaining sections in that file, and the :ref:`that dissects this config file further ` can give you a glimpse of this. +Nevertheless, it can be helpful to get an overview on the meaning of the +remaining sections in that file, and the :find-out-more:`on the Git config file ` offers a glimpse at that. .. index:: dataset configuration .. find-out-more:: Dissecting a Git config file further - :name: fom_gitconfig - :float: + :name: fom-gitconfig + :float: tb Let's walk through the Git config file of ``DataLad-101``: As mentioned above, git-annex will use the diff --git a/docs/basics/101-123-config2.rst b/docs/basics/101-123-config2.rst index 82bb34591..0bc8672b6 100644 --- a/docs/basics/101-123-config2.rst +++ b/docs/basics/101-123-config2.rst @@ -398,17 +398,21 @@ will be available as the corresponding ``datalad.`` configuration variable, replacing any ``__`` (two underscores) with a hyphen, then any ``_`` (single underscore) with a dot, and finally converting all letters to lower case. The ``datalad.log.level`` configuration option thus is the environment variable ``DATALAD_LOG_LEVEL``. +If you are new to the concept of environment variables, check out the +:find-out-more:`on them `. .. index:: operating system concept; environment variable .. find-out-more:: Some more general information on environment variables :name: fom-envvar + :float: tb - Names of environment variables are often all-uppercase. While the ``$`` is not part of + Names of environment variables are often all-uppercase, but they need not be. + While the ``$`` is not part of the name of the environment variable, it is necessary to *refer* to the environment variable: To reference the value of the environment variable ``HOME``, for example, you would need to use ``echo $HOME`` and not ``echo HOME``. However, environment variables are set without a leading ``$``. There are several ways to set an environment variable - (note that there are no spaces before and after the ``=`` !), leading to different + (note that there are no spaces before and after the equals sign!), leading to different levels of availability of the variable: - ``THEANSWER=42 `` makes the variable ``THEANSWER`` available for the process in ````. diff --git a/docs/basics/101-124-procedures.rst b/docs/basics/101-124-procedures.rst index c1010da89..a958621a9 100644 --- a/docs/basics/101-124-procedures.rst +++ b/docs/basics/101-124-procedures.rst @@ -157,17 +157,22 @@ could thus be applied within a :dlcmd:`create` as - ``datalad create -c text2git `` .. index:: dataset procedure; apply more than one configuration -.. find-out-more:: Applying multiple procedures - If you want to apply several configurations at once, feel free to do so, - for example like this: +You can also apply multiple configuration procedures at once. However, +the need to be compatible and complement each other. DataLad does not +guarantee that per-se. This is how it could look: - .. code-block:: console +.. code-block:: console + + $ datalad create -c yoda -c text2git - $ datalad create -c yoda -c text2git +And lastly, procedures can also be applied to subdatasets. See the +:find-out-more:`on this topic ` for details. .. index:: dataset procedure; apply to subdatasets .. find-out-more:: Applying procedures in subdatasets + :name: fom-subds-procedures + :float: tb Procedures can be applied in datasets on any level in the dataset hierarchy, i.e., also in subdatasets. Note, though, that a subdataset will show up as being