Skip to content

Commit

Permalink
Rough formatting of tuning chapter
Browse files Browse the repository at this point in the history
  • Loading branch information
mih committed Nov 15, 2023
1 parent 16d9ec5 commit 7ad3ee3
Show file tree
Hide file tree
Showing 3 changed files with 25 additions and 12 deletions.
14 changes: 9 additions & 5 deletions docs/basics/101-122-config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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' <fom-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
Expand Down Expand Up @@ -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 <fom_gitconfig>` 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 <fom-gitconfig>` 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
Expand Down
8 changes: 6 additions & 2 deletions docs/basics/101-123-config2.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <fom-envvar>`.

.. 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 <command>`` makes the variable ``THEANSWER`` available for the process in ``<command>``.
Expand Down
15 changes: 10 additions & 5 deletions docs/basics/101-124-procedures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -157,17 +157,22 @@ could thus be applied within a :dlcmd:`create` as
- ``datalad create -c text2git <DSname>``

.. 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 <fom-subds-procedures>` 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
Expand Down

0 comments on commit 7ad3ee3

Please sign in to comment.