Merge pull request #661 from datalad-handbook/boxrefs

Relax positioning of some boxes, where appropriate

docs/basics/101-102-populate.rst

@@ -175,6 +175,8 @@ the directory ``books/``, and thanks to that commit message we have a nice
 human-readable summary of that action.
 
 .. findoutmore:: DOs and DON'Ts for commit messages
+   :name: fom-commitmessage
+   :float:
 
     **DOs**
 

docs/basics/101-110-run2.rst

@@ -463,7 +463,7 @@ the ``--input`` and ``--output`` specification done before.
    can be accessed with an integer index, e.g., ``{inputs[0]}`` for the very first
    input.
 
-.. findoutmore:: ... wait, what if I need a { or } character in my datalad run call?
+.. findoutmore:: ... wait, what if I need a curly bracket in my datalad run call?
 
    If your command call involves a ``{`` or ``}`` character, you will need to escape
    this brace character by doubling it, i.e., ``{{`` or ``}}``.

docs/basics/101-115-symlinks.rst

@@ -86,14 +86,16 @@ This process is often referred to as a file being *annexed*, and the object
 tree is also known as the *annex* of a dataset.
 
 .. windowsworkarounds:: What happens on Windows?
+   :name: woa_objecttree
+   :float:
 
    Windows has insufficient support for :term:`symlink`\s and revoking write :term:`permissions` on files.
    Therefore, :term:`git-annex` classifies it as a :term:`crippled filesystem` and has to stray from its default behavior.
    While git-annex on Unix-based file operating systems stores data in the annex and creates a symlink in the data's original place, on Windows it moves data into the :term:`annex` and creates a *copy* of the data in its original place.
 
    **Why is that?**
    Data *needs* to be in the annex for version control and transport logistics -- the annex is able to store all previous versions of the data, and manage the transport to other storage locations if you want to publish your dataset.
-   But as the Findoutmore at the end of this section will show, the :term:`annex` is a non-human readable tree structure, and data thus also needs to exist in its original location.
+   But as the :ref:`Findoutmore in this section <fom-objecttree>` will show, the :term:`annex` is a non-human readable tree structure, and data thus also needs to exist in its original location.
    Thus, it exists in both places: its moved into the annex, and copied back into its original location.
    Once you edit an annexed file, the most recent version of the file is available in its original location, and past versions are stored and readily available in the annex.
    If you reset your dataset to a previous state (as is shown in the section :ref:`history`), the respective version of your data is taken from the annex and copied to replace the newer version, and vice versa.
@@ -202,6 +204,7 @@ to manage the file system in a DataLad dataset (:ref:`filesystem`).
 
 
 .. findoutmore:: more about paths, checksums, object trees, and data integrity
+   :name: fom-objecttree
 
    But why does the target path to the object tree needs to be so cryptic?
    Does someone want to create

docs/basics/101-123-config2.rst

@@ -455,6 +455,7 @@ with a dot, and finally converting all letters to lower case. The ``datalad.log.
 configuration option thus is the environment variable ``DATALAD_LOG_LEVEL``.
 
 .. findoutmore:: Some more general information on environment variables
+   :name: fom-envvar
 
      Names of environment variables are often all-uppercase. While the ``$`` is not part of
      the name of the environment variable, it is necessary to *refer* to the environment

docs/basics/101-124-procedures.rst

@@ -75,7 +75,7 @@ only modify ``.gitattributes``, but can also populate a dataset
 with particular content, or automate routine tasks such as
 synchronizing dataset content with certain siblings.
 What makes them a particularly versatile and flexible tool is
-that anyone can write their own procedures. If a workflow is
+that anyone can write their own procedures (find a tutorial :ref:`here <fom-procedures>`. If a workflow is
 a standard in a team and needs to be applied often, turning it into
 a script can save time and effort. By pointing DataLad
 to the location the procedures reside in they can be applied, and by
@@ -184,6 +184,8 @@ was applied.
 
 
 .. findoutmore:: Write your own procedures
+   :name: fom-procedures
+   :float:
 
    Procedures can come with DataLad or its extensions, but anyone can
    write their own ones in addition, and deploy them on individual machines,

docs/basics/101-130-yodaproject.rst

@@ -12,10 +12,11 @@ In principle, you can prepare YODA-compliant data analyses in any programming
 language of your choice. But because you are already familiar with
 the `Python <https://www.python.org/>`__ programming language, you decide
 to script your analysis in Python. Delighted, you find out that there is even
-a Python API for DataLad's functionality that you can read about in the hidden
-section below:
+a Python API for DataLad's functionality that you can read about in :ref:`a Findoutmore <fom-pythonapi>`.
 
 .. findoutmore:: DataLad's Python API
+   :name: fom-pythonapi
+   :float:
 
     .. _python:
 
@@ -159,9 +160,11 @@ For the purpose of this analysis, the DataLad handbook provides an ``iris_data``
 dataset at `https://github.com/datalad-handbook/iris_data <https://github.com/datalad-handbook/iris_data>`_.
 
 You can either use this provided input dataset, or find out how to create an
-independent dataset from scratch in the hidden section below.
+independent dataset from scratch in a :ref:`dedicated Findoutmore <fom-iris>`.
 
 .. findoutmore:: Creating an independent input dataset
+   :name: fom-iris
+   :float:
 
    If you acquire your own data for a data analysis, it will not magically exist as a
    DataLad dataset that you can simply install from somewhere -- you'll have
@@ -186,16 +189,9 @@ independent dataset from scratch in the hidden section below.
       $ datalad create iris_data
 
    and subsequently got the data from a publicly available
-   `GitHub Gist <https://gist.github.com/netj/8836201>`_ with a
+   `GitHub Gist <https://gist.github.com/netj/8836201>`_, a code snippet or other short standalone information (more on Gists `here <https://help.github.com/en/github/writing-on-github/creating-gists#about-gists>`__), with a
    :command:`datalad download-url` command:
 
-    .. findoutmore:: What are GitHub Gists?
-
-       GitHub Gists are a particular service offered by GitHub that allow users
-       to share pieces of code snippets and other short/small standalone
-       information. Find out more on Gists
-       `here <https://help.github.com/en/github/writing-on-github/creating-gists#about-gists>`__.
-
     .. runrecord:: _examples/DL-101-130-102
        :workdir: dl-101
        :language: console
@@ -765,9 +761,11 @@ an additional :command:`git push` [#f6]_ with the ``--tags`` option is required:
 
 Yay! Consider your midterm project submitted! Others can now install your
 dataset and check out your data science project -- and even better: they can
-reproduce your data science project easily from scratch!
+reproduce your data science project easily from scratch (take a look into the :ref:`Findoutmore <fom-midtermclone>` to see how)!
 
 .. findoutmore:: On the looks and feels of this published dataset
+   :name: fom-midtermclone
+   :float:
 
    Now that you have created and published such a YODA-compliant dataset, you
    are understandably excited how this dataset must look and feel for others.

docs/basics/101-132-advancednesting.rst

@@ -52,9 +52,11 @@ this *in the superdataset* in order to have a clean superdataset status.
 
 This point in time in DataLad-101 is a convenient moment to dive a bit deeper
 into the functions of the :command:`datalad status` command. If you are
-interested in this, checkout the hidden section below.
+interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
 
 .. findoutmore:: More on datalad status
+   :name: fom-status
+   :float:
 
    First of all, let's start with a quick overview of the different content *types*
    and content *states* various :command:`datalad status` commands in the course

docs/basics/101-135-help.rst

@@ -200,7 +200,7 @@ To get extensive information on what :command:`datalad status` does underneath t
        $ datalad status
        $ ...
 
-   You can find out a bit more on environment variable :ref:`in this footnote <envvars>`.
+   You can find out a bit more on environment variable :ref:`in this Findoutmore <fom-envvar>`.
 
    The configuration variable can be used to set the log level on a user (global) or system-wide level with the :command:`git config` command::
 

docs/basics/101-141-push.rst

@@ -243,13 +243,7 @@ for more information).
    In practice, this default will most likely lead to the same outcome as when
    specifying ``none``: only your datasets history, but no annexed contents
    will be published.
-
-   .. gitusernote:: Impact of auto-mode on git-annex
-
-       On a technical level, the ``auto`` option leads to adding ``auto`` to the underlying
-       ``git annex copy`` command, which in turn publishes annexed contents based on the
-       `git-annex preferred content configuration <https://git-annex.branchable.com/git-annex-preferred-content/>`_
-       of the sibling.
+   On a technical level, the ``auto`` option leads to adding ``auto`` to the underlying ``git annex copy`` command, which in turn publishes annexed contents based on the `git-annex preferred content configuration <https://git-annex.branchable.com/git-annex-preferred-content/>`_ of the sibling.
 
    In order to publish all annexed contents, one needs to specify ``--transfer-data all``.
    Alternatively, adding paths to the ``publish`` call will publish the specified

docs/beyond_basics/101-147-riastores.rst

@@ -402,6 +402,7 @@ a single :command:`datalad push` to the RIA sibling suffices:
     .. runrecord:: _examples/DL-101-147-108
        :language: console
        :workdir: dl-101/DataLad-101
+       :lines: 1-25, 38-
 
        $ tree /home/me/myriastore
 
@@ -426,7 +427,7 @@ As a demonstration, we'll do it for the ``midterm_project`` subdataset:
     With creating a RIA sibling to the RIA store and publishing the contents of
     the ``midterm_project`` subdataset to the store, a second dataset has been
     added to the datastore. Note how it is represented on the same hierarchy
-    level as the previous dataset, underneath its dataset ID:
+    level as the previous dataset, underneath its dataset ID (note that the output is cut off for readability):
 
 
     .. runrecord:: _examples/DL-101-147-111
@@ -438,6 +439,7 @@ As a demonstration, we'll do it for the ``midterm_project`` subdataset:
     .. runrecord:: _examples/DL-101-147-112
        :language: console
        :workdir: dl-101/DataLad-101
+       :lines: 1-25, 38-58
 
        $ tree /home/me/myriastore