Move findoutmore and examples to the end to preserve similar flow between html and pdf

Author: adswa

docs/basics/101-132-advancednesting.rst

@@ -50,6 +50,67 @@ should be up to you to decide whether you want record something or not --,
 but it is worth repeating: If you modify a subdataset, you will need to save
 this *in the superdataset* in order to have a clean superdataset status.
 
+Let's save the modification of the subdataset into the history of the
+superdataset. For this, to avoid confusion, you can specify explicitly to
+which dataset you want to save a modification. ``-d .`` specifies the current
+dataset, i.e., ``DataLad-101``, as the dataset to save to:
+
+.. runrecord:: _examples/DL-101-132-103
+   :language: console
+   :workdir: dl-101/DataLad-101/
+
+   $ datalad save -d . -m "finished my midterm project" midterm_project
+
+.. index::
+   pair: save modification in nested dataset; with DataLad
+.. find-out-more:: More on how 'datalad save' can operate on nested datasets
+
+   In a superdataset with subdatasets, :dlcmd:`save` by default
+   tries to figure out on its own which dataset's history of all available
+   datasets a :dlcmd:`save` should be written to. However, it can reduce
+   confusion or allow specific operations to be very explicit in the command
+   call and tell DataLad where to save what kind of modifications to.
+
+   If you want to save the current state of the subdataset into the superdataset
+   (as necessary here), start a ``save`` from the superdataset and have the
+   ``-d/--dataset`` option point to its root:
+
+   .. code-block:: bash
+
+      # in the root of the superds
+      $ datalad save -d . -m "update subdataset"
+
+   If you are in the superdataset, and you want to save an unsaved modification
+   in a subdataset to the *subdatasets* history, let ``-d/--dataset`` point to
+   the subdataset:
+
+   .. code-block:: bash
+
+      # in the superds
+      $ datalad save -d path/to/subds -m "modified XY"
+
+   The recursive option allows you to save any content underneath the specified
+   directory, and recurse into any potential subdatasets:
+
+   .. code-block:: bash
+
+      $ datalad save . --recursive
+
+Let's check which subproject commit is now recorded in the superdataset:
+
+.. runrecord:: _examples/DL-101-132-104
+   :language: console
+   :workdir: dl-101/DataLad-101/
+   :emphasize-lines: 14
+
+   $ git log -p -n 1
+
+As you can see in the log entry, the subproject commit changed from the
+first commit hash in the subdataset history to the most recent one. With this
+change, therefore, your superdataset tracks the most recent version of
+the ``midterm_project`` dataset, and your dataset's status is clean again.
+
+
 This point in time in DataLad-101 is a convenient moment to dive a bit deeper
 into the functions of the :dlcmd:`status` command. If you are
 interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
@@ -92,7 +153,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    subdataset contains a modification. For this, let's add an empty text file into
    the ``midterm_project`` subdataset:
 
-   .. runrecord:: _examples/DL-101-132-103
+   .. runrecord:: _examples/DL-101-132-105
       :language: console
       :workdir: dl-101/DataLad-101
 
@@ -102,7 +163,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    *within* the subdataset, simply provide a path (relative to your current location)
    to the command:
 
-   .. runrecord:: _examples/DL-101-132-104
+   .. runrecord:: _examples/DL-101-132-106
       :language: console
       :workdir: dl-101/DataLad-101
 
@@ -112,7 +173,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    and provide a path to the subdataset *with a trailing path separator* like
    this:
 
-   .. runrecord:: _examples/DL-101-132-105
+   .. runrecord:: _examples/DL-101-132-107
       :language: console
       :workdir: dl-101/DataLad-101
 
@@ -127,7 +188,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    path to the dataset (without a trailing path separator). This can be used
    to specify a specific subdataset in the case of a dataset with many subdatasets:
 
-   .. runrecord:: _examples/DL-101-132-106
+   .. runrecord:: _examples/DL-101-132-108
       :language: console
       :workdir: dl-101/DataLad-101
 
@@ -138,7 +199,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    the state of the subdataset within the superdataset, you can combine the
    two paths:
 
-   .. runrecord:: _examples/DL-101-132-107
+   .. runrecord:: _examples/DL-101-132-109
       :language: console
       :workdir: dl-101/DataLad-101
 
@@ -147,7 +208,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    Finally, if these subtle differences in the paths are not easy to memorize,
    the ``-r/--recursive`` option will also report you both status aspects:
 
-   .. runrecord:: _examples/DL-101-132-108
+   .. runrecord:: _examples/DL-101-132-110
       :language: console
       :workdir: dl-101/DataLad-101
 
@@ -156,7 +217,7 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    Importantly, the regular output from a :dlcmd:`status` command in the commandline is "condensed" to the most important information by a tailored result renderer.
    You can, however, also get ``status``' unfiltered full output by switching the ``-f``/``--output-format`` from ``tailored`` (the default) to ``json`` or, for the same infos as ``json`` but better readability, ``json_pp``:
 
-   .. runrecord:: _examples/DL-101-132-108a
+   .. runrecord:: _examples/DL-101-132-111
       :language: console
       :workdir: dl-101/DataLad-101
 
@@ -172,74 +233,13 @@ interested in this, checkout the :ref:`dedicated Findoutmore <fom-status>`.
    Before we leave this Find-out-more, lets undo the modification of the subdataset
    by removing the untracked file:
 
-   .. runrecord:: _examples/DL-101-132-109
+   .. runrecord:: _examples/DL-101-132-112
       :language: console
       :workdir: dl-101/DataLad-101
 
       $ rm midterm_project/an_empty_file
       $ datalad status --recursive
 
-Let's save the modification of the subdataset into the history of the
-superdataset. For this, to avoid confusion, you can specify explicitly to
-which dataset you want to save a modification. ``-d .`` specifies the current
-dataset, i.e., ``DataLad-101``, as the dataset to save to:
-
-.. runrecord:: _examples/DL-101-132-110
-   :language: console
-   :workdir: dl-101/DataLad-101/
-
-   $ datalad save -d . -m "finished my midterm project" midterm_project
-
-.. index::
-   pair: save modification in nested dataset; with DataLad
-.. find-out-more:: More on how 'datalad save' can operate on nested datasets
-
-   In a superdataset with subdatasets, :dlcmd:`save` by default
-   tries to figure out on its own which dataset's history of all available
-   datasets a :dlcmd:`save` should be written to. However, it can reduce
-   confusion or allow specific operations to be very explicit in the command
-   call and tell DataLad where to save what kind of modifications to.
-
-   If you want to save the current state of the subdataset into the superdataset
-   (as necessary here), start a ``save`` from the superdataset and have the
-   ``-d/--dataset`` option point to its root:
-
-   .. code-block:: bash
-
-      # in the root of the superds
-      $ datalad save -d . -m "update subdataset"
-
-   If you are in the superdataset, and you want to save an unsaved modification
-   in a subdataset to the *subdatasets* history, let ``-d/--dataset`` point to
-   the subdataset:
-
-   .. code-block:: bash
-
-      # in the superds
-      $ datalad save -d path/to/subds -m "modified XY"
-
-   The recursive option allows you to save any content underneath the specified
-   directory, and recurse into any potential subdatasets:
-
-   .. code-block:: bash
-
-      $ datalad save . --recursive
-
-Let's check which subproject commit is now recorded in the superdataset:
-
-.. runrecord:: _examples/DL-101-132-112
-   :language: console
-   :workdir: dl-101/DataLad-101/
-   :emphasize-lines: 14
-
-   $ git log -p -n 1
-
-As you can see in the log entry, the subproject commit changed from the
-first commit hash in the subdataset history to the most recent one. With this
-change, therefore, your superdataset tracks the most recent version of
-the ``midterm_project`` dataset, and your dataset's status is clean again.
-
-
 .. only:: adminmode
 
     Add a tag at the section end.