Merge pull request #679 from datalad-handbook/ww

windowsworkarounds -> windows-wit

dataladhandbook_support/directives.py

@@ -164,36 +164,36 @@ class FindOutMore(HandbookAdmonition):
     hba_label = 'findoutmore'
 
 
-class windowsworkarounds(nodes.container):
-    """Custom "windowsworkarounds" container."""
+class windowswit(nodes.container):
+    """Custom "windowswit" container."""
     pass
 
 
-class WindowsWorkArounds(HandbookAdmonition):
-    """windowsworkaround RST directive
+class WindowsWit(HandbookAdmonition):
+    """windows-wit RST directive
 
     This is identical to the FindOutMore directive, and allows a custom markup
     for notes targeted at Windows users
     """
-    hba_cls = windowsworkarounds
-    hba_label = 'windowsworkarounds'
+    hba_cls = windowswit
+    hba_label = 'windows-wit'
 
 
-def visit_windowsworkarounds_html(self, node):
+def visit_windowswit_html(self, node):
     self.visit_container(node)
 
 
-def depart_windowsworkarounds_html(self, node):
+def depart_windowswit_html(self, node):
     self.depart_container(node)
 
 
-def visit_windowsworkarounds_latex(self, node):
-    self.body.append(_get_counted_boxstart('windowsworkaround', node))
+def visit_windowswit_latex(self, node):
+    self.body.append(_get_counted_boxstart('windowswit', node))
     _add_label(self.body, node)
 
 
-def depart_windowsworkarounds_latex(self, node):
-    self.body.append('\n\n\\end{windowsworkaround}\n')
+def depart_windowswit_latex(self, node):
+    self.body.append('\n\n\\end{windowswit}\n')
 
 
 class importantnote(nodes.container):
@@ -244,6 +244,27 @@ def depart_findoutmoreref_latex(self, node):
     pass
 
 
+class windowswitref(nodes.inline):
+    pass
+
+
+def visit_windowswitref_html(self, node):
+    self.visit_inline(node)
+    self.body.append('Windows-wit ')
+
+
+def depart_windowswitref_html(self, node):
+    self.depart_inline(node)
+
+
+def visit_windowswitref_latex(self, node):
+    self.body.append('{\\windowswiticoninline}Windows-wit ')
+
+
+def depart_windowswitref_latex(self, node):
+    pass
+
+
 def setup(app):
     app.add_node(
         gitusernote,
@@ -258,11 +279,11 @@ def setup(app):
     )
     app.add_directive('find-out-more', FindOutMore)
     app.add_node(
-        windowsworkarounds,
-        html=(visit_windowsworkarounds_html, depart_windowsworkarounds_html),
-        latex=(visit_windowsworkarounds_latex, depart_windowsworkarounds_latex),
+        windowswit,
+        html=(visit_windowswit_html, depart_windowswit_html),
+        latex=(visit_windowswit_latex, depart_windowswit_latex),
     )
-    app.add_directive('windowsworkarounds', WindowsWorkArounds)
+    app.add_directive('windows-wit', WindowsWit)
     app.add_node(
         importantnote,
         html=(visit_importantnote_html, depart_importantnote_html),
@@ -274,5 +295,10 @@ def setup(app):
         html=(visit_findoutmoreref_html, depart_findoutmoreref_html),
         latex=(visit_findoutmoreref_latex, depart_findoutmoreref_latex),
     )
+    app.add_node(
+        windowswitref,
+        html=(visit_windowswitref_html, depart_windowswitref_html),
+        latex=(visit_windowswitref_latex, depart_windowswitref_latex),
+    )
 
 # vim: set expandtab shiftwidth=4 softtabstop=4 :

dataladhandbook_support/roles.py

@@ -1,7 +1,10 @@
 # -*- coding: utf-8 -*-
 
 from docutils.parsers.rst import roles
-from .directives import findoutmoreref
+from .directives import (
+    findoutmoreref,
+    windowswitref,
+)
 from sphinx.roles import (
     XRefRole,
 )
@@ -35,8 +38,15 @@ class FindOutMoreRole(HandbookRefRole):
     refnodeclsname = 'findoutmoreref'
 
 
+class WindowsWitRole(HandbookRefRole):
+    """:windows-wit: ref"""
+    refnodecls = windowswitref
+    refnodeclsname = 'windowswitref'
+
+
 hb_roles = {
     'find-out-more': FindOutMoreRole(),
+    'windows-wit': WindowsWitRole(),
 }
 
 

docs/_static/custom.css

@@ -93,14 +93,14 @@ div.importantnote .header {
     color: #ffffff;
 }
 
-div.windowsworkarounds {
+div.windows-wit {
     background-color: #f3f3f3;
     border: 3px solid #509f26;
     box-shadow: 5px 5px 15px 0px #111;
     padding: 5px 10px 5px 10px;
     margin-bottom: 15px;
 }
-div.windowsworkarounds .header {
+div.windows-wit .header {
     background-color: #66cc33;
     border: 0px solid #000;
     margin: -6px -11px -6px -11px;
@@ -109,13 +109,13 @@ div.windowsworkarounds .header {
 div.importantnote .header:before {
     content: "⚠ ";
 }
-div.windowsworkarounds .header:before {
-    content: "⤵ Windows-Workaround: ";
+div.windows-wit .header:before {
+    content: "⤵ Windows-wit: ";
     color: #333;
     font-weight: bold;
 }
-div.windowsworkarounds .header.open:before {
-    content: "⤴ Windows-Workaround: ";
+div.windows-wit .header.open:before {
+    content: "⤴ Windows-wit: ";
     color: #333;
     font-weight: bold;
 }

docs/basics/101-101-create.rst

@@ -44,7 +44,7 @@ Note the command structure of :command:`datalad create` (optional bits are enclo
 
 Let's start:
 
-.. windowsworkarounds:: Windows-Users need to start here instead
+.. windows-wit:: Windows-Users need to start here instead
 
    Hey there!
    If you are using **Windows 10** with a **native** (i.e., not `Windows Subsystem for Linux (WSL) <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`_-based) installation of DataLad and its underlying tools, and you are **not using** the custom :term:`git-annex` installer from `http://datasets.datalad.org/datalad/packages/windows/ <http://datasets.datalad.org/datalad/packages/windows/>`_ starting into this narrative will be slightly different.
@@ -161,7 +161,7 @@ We can see two :term:`commit`\s in the history of the repository.
 Each of them is identified by a unique 40 character sequence, called a
 :term:`shasum`.
 
-.. windowsworkarounds:: Your Git log may be more extensive - use "git log master" instead!
+.. windows-wit:: Your Git log may be more extensive - use "git log master" instead!
 
    The output of ``git log`` shown in the handbook and the output you will see in your own datasets when executing the same commands may not always match -- many times you might see commits about a "git-annex adjusted branch" in your history.
    This is expected, and if you want to read up more about this, please progress on to chapter 3 and afterwards take a look at `this part of git-annex documentation <https://git-annex.branchable.com/design/adjusted_branches/>`_.

docs/basics/101-102-populate.rst

@@ -36,14 +36,16 @@ are all free, in total about 15 MB), and save them in ``DataLad-101/books``.
 
 You can either visit the links and save them in ``books/``,
 or run the following commands [#f2]_ to download the books right from the terminal.
-Note that we line break the command with ``\`` signs. You can copy them as they
-are presented here into your terminal, but in your own work you can write commands
-like this into a single line.
+Note that we line break the command with ``\`` signs. In your own work you can write
+commands like this into a single line. If you copy them into your terminal as they
+are presented here, make sure to check the :windows-wit:`on peculiarities of its terminals
+<ww-no-multiline-commands>`.
 
-.. windowsworkarounds:: Windows terminals other than Git Bash can't handle multi-line commands
+.. windows-wit:: Terminals other than Git Bash can't handle multi-line commands
+   :name: ww-no-multiline-commands
 
    In Unix shells, ``\`` can be used to split a command into several lines, for example to aid readability.
-   Standard Windows terminals (inlcuding the Anaconda prompt) do not support this.
+   Standard Windows terminals (including the Anaconda prompt) do not support this.
    They instead use the ``^`` character::
 
      $ datalad download-url http://www.tldp.org/LDP/Bash-Beginners-Guide/Bash-Beginners-Guide.pdf ^
@@ -68,7 +70,12 @@ like this into a single line.
    # get back into the root of the dataset
    $ cd ../
 
-.. windowsworkarounds:: You may want to use curl instead of wget
+Some machines will not have :command:`wget` available by default, but any command that can
+download a file can work as an alternative. See the :windows-wit:`for the popular alternative
+curl <ww-curl-instead-wget>`.
+
+.. windows-wit:: You can use curl instead of wget
+   :name: ww-curl-instead-wget
 
    Many versions of Windows do not ship with the tool ``wget``.
    You can install it, but it may be easier to use the pre-installed ``curl`` command::
@@ -227,16 +234,6 @@ Luckily, we can point :command:`datalad save` to exactly the changes we want it
 Let's try this by adding yet another book, a good reference work about git,
 `Pro Git <https://git-scm.com/book/en/v2>`_:
 
-.. windowsworkarounds:: You may want to use curl instead of wget
-
-   Many versions of Windows do not ship with the tool ``wget``.
-   You can install it, but it may be easier to use the pre-installed ``curl`` command::
-
-      $ cd books
-      $ curl -L https://github.com/progit/progit2/releases/download/2.1.154/progit.pdf \
-        -o progit.pdf
-      $ cd ../
-
 .. runrecord:: _examples/DL-101-102-108
    :language: console
    :workdir: dl-101/DataLad-101

docs/basics/101-103-modify.rst

@@ -57,7 +57,7 @@ terminal to write this note from the terminal (without any editor) into ``notes.
 Running the command below will create ``notes.txt`` in the
 root of your ``DataLad-101`` dataset:
 
-.. windowsworkarounds:: Heredocs don't work under non-Git-Bash Windows terminals
+.. windows-wit:: Heredocs don't work under non-Git-Bash Windows terminals
 
    Heredocs rely on Unix-type redirection and multi-line commands -- which is not supported on most native Windows terminals or the Anaconda prompt on Windows.
    If you are using an Anaconda prompt or a Windows terminal other than Git Bash, instead of executing heredocs, please open up an editor and paste and save the text into it.

docs/basics/101-105-install.rst

@@ -140,7 +140,7 @@ chapters in this handbook will demonstrate how useful this information can be.
 
 Here is the repository structure:
 
-.. windowsworkarounds:: tree -d may fail
+.. windows-wit:: tree -d may fail
 
    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``.

docs/basics/101-108-run.rst

@@ -71,7 +71,7 @@ write out speaker names and talk titles in a very basic fashion.
 The content of this script is written below -- the ``cat`` command
 will write it into the script.
 
-.. windowsworkarounds:: Here's a script for Windows users
+.. windows-wit:: Here's a script for Windows users
 
    Please use an editor of your choice to create a file ``list_titles.sh`` inside of the ``code`` directory.
    These should be the contents::

docs/basics/101-109-rerun.rst

@@ -31,7 +31,7 @@ in the ``Long_Now__Conversations_at_The_Interval/`` directory.
 Let's fix this in the script. Replace the contents in ``code/list_titles.sh``
 with the following, fixed script:
 
-.. windowsworkarounds:: Here's a script adjustment for Windows users
+.. windows-wit:: Here's a script adjustment for Windows users
 
    Please use an editor of your choice to replace the contents of ``list_titles.sh`` inside of the ``code`` directory with the following::
 
@@ -170,7 +170,7 @@ and another state from the dataset's history (a commit specified with
 ``-t``/``--to``). Let's do a :command:`datalad diff` between the current state
 of the dataset and the previous commit (called "``HEAD~1``" in Git terminology [#f1]_):
 
-.. windowsworkarounds:: please use datalad diff --from master --to HEAD~1
+.. windows-wit:: please use datalad diff --from master --to HEAD~1
 
    While this example works on Unix file systems, it will not provide the same output on Windows.
    This is due to different file handling on Windows.
@@ -253,7 +253,7 @@ other tools than from the machine-readable ``run record``.
 For example, to find out who (or what) created or modified a file,
 give the file path to :command:`git log` (prefixed by ``--``):
 
-.. windowsworkarounds:: use "git log master -- recordings/podcasts.tsv"
+.. windows-wit:: use "git log master -- recordings/podcasts.tsv"
 
    A previous Windows-Workaround already advised to append ``master``, the common "default :term:`branch`", to any command that starts with ``git log``.
    Here, the last part of the command specifies a file (``-- recordings/podcasts.tsv``).

docs/basics/101-110-run2.rst

@@ -56,7 +56,7 @@ resized image will be saved.
 To resize one image to 400x400 px, the command would thus be
 ``convert -resize 400x400 path/to/file.jpg path/to/newfilename.jpg``.
 
-.. windowsworkarounds:: Tool installation
+.. windows-wit:: Tool installation
 
    `ImageMagick <https://imagemagick.org/index.php>`_ is not installed on Windows systems by default.
    To use it, you need to install it, using the provided `Windows Binary Release on the Download page <https://imagemagick.org/script/download.php>`_.
@@ -157,7 +157,7 @@ specifying inputs even though they are already present will not do any harm.
 If outputs already exist...
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. windowsworkarounds:: Good news! Here is something that is easier on Windows
+.. windows-wit:: Good news! Here is something that is easier on Windows
 
    The section below describes something that is very confusing for people that have just started with DataLad: Some files in a dataset can't be modified, and if one tries, it results in a "permission denied" error.
    Why is that?
@@ -238,7 +238,7 @@ and thus making locked files modifiable again: :command:`datalad unlock`
 (:manpage:`datalad-unlock` manual).
 Let us check out what it does:
 
-.. windowsworkarounds:: What happens if I run this on Windows?
+.. windows-wit:: What happens if I run this on Windows?
 
    Nothing. All of the files in your dataset are always unlocked, and actually *can* not be locked at all.
    Consequently, there will be nothing to show for ``datalad status`` afterwards (as shown a few paragraphs below).
@@ -319,7 +319,7 @@ the ``-o``/``--output`` option.
 In order to execute :command:`datalad run` with both the ``-i``/``--input`` and ``-o``/``--output``
 flag and see their magic, let's crop the second logo, ``logo_interval.jpg``:
 
-.. windowsworkarounds:: Wait, would I need to specify outputs, too?
+.. windows-wit:: Wait, would I need to specify outputs, too?
 
    Given that nothing in your dataset is locked, is there a *need* for you to bother with creating ``--output`` flags?
    Not for you personally, if you only stay on your Windows machine.

docs/basics/101-115-symlinks.rst

@@ -19,7 +19,7 @@ You might have noticed already that an ``ls -l`` or ``tree`` command in your dat
 Maybe your shell also displays these files in a different color than text files when listing them.
 We'll take a look together, using the ``books/`` directory as an example:
 
-.. windowsworkarounds:: This will look different to you
+.. 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.
@@ -85,7 +85,7 @@ creates a symlink with the original file name, pointing to the new location.
 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?
+.. windows-wit:: What happens on Windows?
    :name: woa_objecttree
    :float:
 
@@ -355,7 +355,7 @@ Cross-OS filesharing with symlinks (WSL2 only)
 Are you using DataLad on the Windows Subsystem for Linux?
 If so, please take a look into the Windows-Workaround below.
 
-.. windowsworkarounds:: Accessing symlinked files from your Windows system
+.. windows-wit:: Accessing symlinked files from your Windows system
 
    If you are using WSL2 you have access to a Linux kernel and POSIX filesystem, including symlink support.
    Your DataLad experience has therefore been exactly as it has been for macOS or Linux users.

docs/basics/101-121-siblings.rst

@@ -227,7 +227,7 @@ do a ``diff`` between the branch (your drawer) and the dataset as it
 is currently in front of you (your desk). We will do the latter, and leave
 the former for a different lecture:
 
-.. windowsworkarounds:: Please use datalad diff --from master --to remotes/roommate/master
+.. windows-wit:: Please use datalad diff --from master --to remotes/roommate/master
 
    Please use the following command instead::
 
@@ -247,7 +247,7 @@ This shows us that there is an additional file, and it also shows us
 that there is a difference in ``notes.txt``! Let's ask
 :command:`git diff` to show us what the differences in detail (note that it is a shortened excerpt, cut in the middle to reduce its length):
 
-.. windowsworkarounds:: Please use git diff master..remotes/roommate/master
+.. windows-wit:: Please use git diff master..remotes/roommate/master
 
    Please use the following command instead::
 

docs/basics/101-123-config2.rst

@@ -24,7 +24,7 @@ section by looking into it.
 
 This file lies right in the root of your superdataset:
 
-.. windowsworkarounds:: Your file contents are slightly different
+.. windows-wit:: Your file contents are slightly different
 
    Windows users that did not use the custom :term:`git-annex` installer from `http://datasets.datalad.org/datalad/packages/windows/ <http://datasets.datalad.org/datalad/packages/windows/>`_ had to modify the ``.gitattributes`` file at the start of the Basics.
    Instead of a line that contains "``mimencoding``", There should be the following two lines::

docs/basics/101-124-procedures.rst

@@ -28,7 +28,7 @@ nothing more than a simple script that
 - writes the relevant configuration (``annex_largefiles = '((mimeencoding=binary)and(largerthan=0))'``,  i.e., "Do not put anything that is a text file in the annex") to the ``.gitattributes`` file of a dataset, and
 - saves this modification with the commit message "Instruct annex to add text files to Git".
 
-.. windowsworkarounds:: Why this configuration does not work for Windows users
+.. windows-wit:: Why this configuration does not work for Windows users
 
    If you're on a **Windows 10** machine with a **native** (i.e., non :term:`WSL` based installation) of DataLad and did **not** use the custom :term:`git-annex` installer from `http://datasets.datalad.org/datalad/packages/windows/ <http://datasets.datalad.org/datalad/packages/windows/>`_ at the start of the Basics, the ``text2git`` configuration will lead to errors upon a :command:`datalad save`.
    This is because MagicMime (used in ``mimeencoding=binary`` to determine the file type of any given file by searching for `magic numbers <https://en.wikipedia.org/wiki/List_of_file_signatures>`_) is not natively available on Windows.