Merge branch 'main' of github.com:datalad-handbook/book into tmp

dataladhandbook_support/__init__.py

@@ -9,6 +9,5 @@ def setup(app):
     directives.setup(app)
 
 
-from ._version import get_versions
-__version__ = get_versions()['version']
-del get_versions
+from . import _version
+__version__ = _version.get_versions()['version']

docs/basics/101-102-populate.rst

@@ -386,9 +386,8 @@ Well done! Your ``DataLad-101`` dataset and its history are slowly growing.
 .. [#f1] ``tree`` is a Unix command to list file system content. If it is not yet installed,
    you can get it with your native package manager (e.g.,  ``apt``, ``brew``, or conda).
    For example, if you use OSX, ``brew install tree``  will get you this tool.
-   On Windows, if you have the Miniconda-based installation described in :ref:`install`, you can install the ``m2-base`` package (``conda install m2-base``), which contains tree along with many other Unix-like commands.
-   Note that this tree works slightly different than its Unix equivalent - it will only display directories, not files, and it doesn't accept common options or flags.
-   It will also display *hidden* directories, i.e., those that start with a ``.`` (dot).
+   Windows has its own ``tree`` command.
+   Note that this ``tree`` works slightly different than its Unix equivalent - by default, it will only display directories, not files, and the command options it accepts are either ``/f`` (display file names) or ``/a`` (change display of subdirectories to text instead of graphic characters).
 
 .. [#f2] ``wget`` is a Unix command for non-interactively downloading files from the
    web. If it is not yet installed, you can get it with your native package manager (e.g.,

docs/basics/101-105-install.rst

@@ -139,10 +139,9 @@ chapters in this handbook will demonstrate how useful this information can be.
 
 Here is the repository structure:
 
-.. windows-wit:: tree -d may fail
+.. windows-wit:: use tree
 
-   If you have installed :term:`conda`\s ``m2-base`` package for access to Unix commands such as tree, you will have the tree command.
-   However, this version of tree does not support the use of any command flags, so please just run ``tree`` instead of ``tree -d``.
+   The Windows version of tree requires different parametrization, so please run ``tree`` instead of ``tree -d``.
 
 .. runrecord:: _examples/DL-101-105-103
    :language: console

docs/basics/101-115-symlinks.rst

@@ -20,8 +20,8 @@ We'll take a look together, using the ``books/`` directory as an example:
 
 .. windows-wit:: This will look different to you
 
-   First of all, the ``tree`` equivalent provided by :term:`conda`\s ``m2-base`` package doesn't list individual files, only directories.
-   And, secondly, even if you list the individual files (e.g., with ``ls -l``), you would not see the :term:`symlink`\s shown below.
+   First of all, the Windows ``tree`` command lists only directories by default, unless you parametrize it with ``/f``.
+   And, secondly, even if you list the individual files, you would not see the :term:`symlink`\s shown below.
    Due to insufficient support of symlinks on Windows, git-annex does not use them.
    Please read on for a basic understanding of how git-annex usually works -- a Windows Wit at the end of this section will then highlight the difference in functionality on Windows.
 

docs/basics/101-139-hostingservices.rst

@@ -38,12 +38,14 @@ How to add a sibling on a Git repository hosting site: The manual way
    It does not need to have the same name as your local dataset, but it helps to associate local dataset and remote siblings.
 
 .. figure:: ../artwork/src/GIN_newrepo.png
+   :width: 80%
 
    Webinterface of :term:`GIN` during the creation of a new repository.
 
 .. figure:: ../artwork/src/newrepo-github.png
+   :width: 80%
 
-	Webinterface of :term:`GitHub` during the creation of a new repository.
+   Webinterface of :term:`GitHub` during the creation of a new repository.
 
 #. Afterwards, copy the :term:`SSH` or :term:`HTTPS` URL of the repository. Usually, repository hosting services will provide you with a convenient way to copy it to your clipboard. An SSH URL takes the form ``git@<hosting-service>:/<user>/<repo-name>.git`` and an HTTPS URL takes the form ``https://<hosting-service>/<user>/<repo-name>.git``. The type of URL you choose determines whether and how you will be able to ``push`` to your repository. Note that many services will require you to use the SSH URL to your repository in order to do :dlcmd:`push` operations, so make sure to take the :term:`SSH` and not the :term:`HTTPS` URL if this is the case.
 
@@ -152,6 +154,7 @@ The most convenient way to generate tokens is typically via the webinterface of
 Often, you can specifically select which set of permissions a specific token has in a drop-down menu similar (but likely not identical) to this screenshot from GitHub:
 
 .. figure:: ../artwork/src/github-token.png
+   :width: 80%
 
    Webinterface to generate an authentication token on GitHub. One typically has to set a name and
    permission set, and potentially an expiration date.
@@ -202,6 +205,10 @@ Once this configuration is in place, ``create-sibling-gitlab``'s ``--site`` para
 Ensure that the token for each instance has appropriate permissions to create new groups and projects under your user account using the GitLab API.
 
 .. figure:: ../artwork/src/gitlab-token.png
+   :width: 80%
+
+   Webinterface to generate an authentication token on GitLab. One typically has to set a name and
+   permission set, and potentially an expiration date.
 
 Step 2: Create or select a group
 """"""""""""""""""""""""""""""""
@@ -214,9 +221,14 @@ In the screenshots below, a new group ``my-datalad-root-level-group`` is created
 The group name as shown in the URL bar is what DataLad needs in order to create sibling datasets.
 
 .. figure:: ../artwork/src/gitlab-rootgroup.png
+   :width: 80%
+
+   Webinterface to create a root-level group on GitLab.
 
 .. figure:: ../artwork/src/gitlab-rootgroup2.png
+   :width: 80%
 
+   A created root-level group in GitLab's webinterface.
 
 Step 3: Select a layout
 """""""""""""""""""""""
@@ -250,6 +262,7 @@ Consider the ``DataLad-101`` dataset, a superdataset with a several subdatasets
 The ``collection`` and ``flat`` layouts for this dataset look like this in practice:
 
 .. figure:: ../artwork/src/gitlab-layouts.png
+   :width: 50%
 
    The ``collection`` layout has a group (``DataLad-101_collection``, defined by the user with a configuration) with four projects underneath. The ``project`` project contains the root-level dataset, and all contained subdatasets are named according to their location in the dataset. The ``flat`` layout consists of projects in the root-level group. The project name for the superdataset (``DataLad-101_flat``) is defined by the user with a configuration, and the names of the subdatasets extend this project name based on their location in the dataset hierarchy.
 
@@ -271,6 +284,9 @@ For a **flat** layout, the ``--project`` parameter determines the project name:
      create_sibling_gitlab (ok: 1)
 
 .. figure:: ../artwork/src/gitlab-layout-flat.png
+   :width: 50%
+
+   An example dataset using GitLab's "flat" layout.
 
 For a **collection** layout, the ``--project`` parameter determines the group name:
 
@@ -284,6 +300,9 @@ For a **collection** layout, the ``--project`` parameter determines the group na
       create_sibling_gitlab (ok: 1)
 
 .. figure:: ../artwork/src/gitlab-layout-collection.png
+   :width: 50%
+
+   An example dataset using GitLab's "collection" layout.
 
 Publishing datasets recursively
 """""""""""""""""""""""""""""""

docs/basics/101-146-gists.rst

@@ -16,8 +16,9 @@ take a look at the :ref:`cheat`. The
 `tips collection of git-annex <https://git-annex.branchable.com/tips>`_ is also
 a very valuable resource.
 
-.. figure:: ../artwork/src/gists.svg
+.. image:: ../artwork/src/gists.svg
    :width: 50%
+   :align: center
 
 
 .. _parallelize:

docs/glossary.rst

@@ -8,8 +8,8 @@ Glossary
 .. glossary::
 
    absolute path
-      The complete path from the root of the file system. Absolute paths always start with ``/``.
-      Example: ``/home/user/Pictures/xkcd-webcomics/530.png``. See also :term:`relative path`.
+      The complete path from the root of the file system. On Unix-like systems, absolute paths always start with ``/``, and on Windows systems, they start with a ``/`` (likely prefixed by a disk identifier).
+      Examples: ``/home/user/Pictures/xkcd-webcomics/530.png``, ``C:\Users\user\Pictures\xkcd-webcomics\530.png``. See also :term:`relative path`.
 
    adjusted branch
       git-annex concept: a special :term:`branch` in a dataset.
@@ -302,8 +302,8 @@ Glossary
       Git concept. A "Git Reference", typically shortened to "ref", is a text file containing a :term:`commit` :term:`shasum` as a human-readable reference to a specific version of your dataset or Git repository. Thanks to refs, Git users do not need to memorize or type shasums when switching between dataset states, and can use simple names instead: For example, a :term:`branch` such as ``main`` is a ref, and a :term:`tag` is one, too. In both cases, those refs are text files that contain the shasum of the commit at the tip of a branch, or the shasum of the commit you added the tag to. Refs are organized in the directory ``.git/refs`` and Git commands and configurations can use refs to perform updating operations or determine their behavior. More details can be found at `at git-scm.com <https://git-scm.com/book/en/v2/Git-Internals-Git-References>`_
 
    relative path
-      A path related to the present working directory. Relative paths never start with ``/``.
-      Example: ``../Pictures/xkcd-webcomics/530.png``. See also :term:`absolute path`.
+      A path related to the present working directory. Relative paths never start with ``/`` or ``\``.
+      Examples on Unix and Windows: ``../Pictures/xkcd-webcomics/530.png``, ``..\Pictures\xkcd-webcomics\530.png``. See also :term:`absolute path`.
 
    remote
       Git-terminology: A repository (and thus also :term:`DataLad dataset`) that a given repository

docs/index.rst

@@ -7,27 +7,6 @@
    :scale: 100%
    :alt: Animated DataLad logo
 
-|
-
-===========================
-Join us at distribits 2024!
-===========================
-
-############################################
-Technologies for distributed data management
-############################################
-
-.. image:: _static/distribits-teaser.jpg
-   :width: 100%
-   :align: left
-
-The first distribits meeting will happen on April 18th to April 20th, 2024, at
-"Haus der Universität", Düsseldorf, Germany, with the aim of bringing together
-enthusiasts of tools and workflows in the domain of distributed data.
-
-Go to `distribits.live <https://distribits.live>`_ for more information and to register!
-
-
 ============
 The Handbook
 ============