From 4f09f7a9e8673a9454012bf4ea6b7e664ebe65ef Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Tue, 31 Oct 2023 10:39:53 +0100 Subject: [PATCH 1/6] mention annex UUID --- docs/basics/101-116-sharelocal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/basics/101-116-sharelocal.rst b/docs/basics/101-116-sharelocal.rst index 6e1a3e915..b7a925b19 100644 --- a/docs/basics/101-116-sharelocal.rst +++ b/docs/basics/101-116-sharelocal.rst @@ -178,7 +178,7 @@ let's query git-annex where its content is stored: $ git annex whereis books/TLCL.pdf -Oh, another :term:`shasum`! This time however not in a symlink... +Oh, another :term:`shasum` - or, more specifically, a :term:`annex UUID`. This time however not in a symlink... "That's hard to read -- what is it?" your room mate asks. You can recognize a path to the dataset on your computer, prefixed with the user and hostname of your computer. "This", you exclaim, excited about your own realization, From 5ad99bae6845a7ad0a63248d0a8a7bd672be4367 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Tue, 31 Oct 2023 15:10:19 +0100 Subject: [PATCH 2/6] adjust wording to current action summary output --- docs/basics/101-118-sharelocal3.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/basics/101-118-sharelocal3.rst b/docs/basics/101-118-sharelocal3.rst index e3da1bb14..4665d9050 100644 --- a/docs/basics/101-118-sharelocal3.rst +++ b/docs/basics/101-118-sharelocal3.rst @@ -74,8 +74,7 @@ command: file content from the subdataset and it tried to unlock the output prior to the command execution. Note that because you did not retrieve the output, ``recordings/salt_logo_small.jpg``, yet, the missing content -could not be unlocked. DataLad warns you about this, but proceeds -successfully. +could not be "unlocked", but is reportedly "removed" prior to the successful rerun. Your room mate now not only knows how exactly the resized file came into existence, but he can also reproduce your exact steps to From 2a9236a868df24b7fe397a85b89032e5e8a81a23 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Tue, 31 Oct 2023 15:10:39 +0100 Subject: [PATCH 3/6] Two typos in the installation section --- docs/intro/installation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/intro/installation.rst b/docs/intro/installation.rst index 24ea6090f..317ee9432 100644 --- a/docs/intro/installation.rst +++ b/docs/intro/installation.rst @@ -102,7 +102,7 @@ Python: Such alternative installations may even be or become the default. This can cause confusing behavior, because each Python installation will have different package versions installed. - To verify if there are multiple installation, open the windows command line ``cmd.exe`` and run ``where python``. + To verify if there are multiple installations, open the windows command line ``cmd.exe`` and run ``where python``. This will list all variants of ``python.exe``. There will be one in ``WindowsApps``, which is only a link to the Windows app store. Make sure the Python version that you installed is listed too. @@ -138,8 +138,8 @@ Git: Git-annex: There are two convenient ways to install git-annex. The first is `downloading the installer from git-annex' homepage `_. The other is to deploy git-annex via the `DataLad installer`_. - The latter option requires the installation of the datalad-installer, Once - Python is available, it can be done with the Python package manager + The latter option requires the installation of the datalad-installer. + Once Python is available, it can be done with the Python package manager :shcmd:`pip`. Open a command prompt and run: .. code-block:: bat From 801308a768c7511dcbde2851024d14c5500d6327 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Tue, 31 Oct 2023 15:11:07 +0100 Subject: [PATCH 4/6] Remove 10 version specification for Windows, we also have 11 --- docs/intro/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/intro/installation.rst b/docs/intro/installation.rst index 317ee9432..7d762e623 100644 --- a/docs/intro/installation.rst +++ b/docs/intro/installation.rst @@ -181,7 +181,7 @@ One attractive alternative approach is Conda_, a completely different approach i :name: ww-wsl2 With the Windows Subsystem for Linux, you will be able to use a Unix system - despite being on Windows. You need to have a recent build of Windows 10 in + despite being on Windows. You need to have a recent build of Windows in order to get WSL2 -- we do not recommend WSL1. You can find out how to install the Windows Subsystem for Linux at @@ -199,7 +199,7 @@ look different from what is displayed in the code examples of the book, and that some dependencies for additional functionality are not available for Windows. Dedicated notes, "``Windows-wit``\s", contain important information, alternative commands, or -warnings. If you on a native Windows 10 system, you should pay close +warnings. If you on a native Windows system, you should pay close attention to them. .. _mac: From 485c5fd9db7c6ff6781957abae0e41043a53bd94 Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Tue, 31 Oct 2023 15:21:26 +0100 Subject: [PATCH 5/6] Add a dedicated section on copyright and licenses All other information is only available in the sources. Including them in the book itself has the advantage that appropriate term declarations are also available in each (offline) PDF. --- docs/book_appendix.rst | 1 + docs/index.rst | 1 + docs/licenses.rst | 51 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 53 insertions(+) create mode 100644 docs/licenses.rst diff --git a/docs/book_appendix.rst b/docs/book_appendix.rst index 9f6ba03ff..d0750dc3f 100644 --- a/docs/book_appendix.rst +++ b/docs/book_appendix.rst @@ -13,6 +13,7 @@ Appendix contributing teaching acknowledgements + licenses .. raw:: latex diff --git a/docs/index.rst b/docs/index.rst index 118ff50a4..93cdc88a5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -89,6 +89,7 @@ Appendix contributing teaching acknowledgements + licenses intro/user_types OHBMposter usecases/openneuro diff --git a/docs/licenses.rst b/docs/licenses.rst new file mode 100644 index 000000000..4198358a4 --- /dev/null +++ b/docs/licenses.rst @@ -0,0 +1,51 @@ +.. index:: copyright, licenses + +Copyright and licenses +---------------------- + +This handbook is made available under the terms of the `Creative Commons Attribution-ShareAlike 4.0 International Public License (CC-BY-SA)`_. +The copyright holders for the book content are the respective individual contributors of particular content, as recorded in the version history of the handbook's Git repository. + +This book may contain copyrighted and/or trademarked materials, the use of which may not have been specifically authorized by the respective owner. +These are included for educational purposes in an effort to explain issues relevant to decentralized data management and other topics covered in this book. +We believe that this constitutes a "fair use" of the materials as provided for in section 107 of the US Copyright Law. +Use of these materials that go beyond "fair use" may require permissions to be obtained from the respective owner. +These copyright/trademark holders are not affiliated with the authors or any of the authors’ representatives. +They do not sponsor or endorse the contents, materials, or processes discussed within this book. + +The remainder of this sections amends the general copyright and license declaration of the book with additional information on used 3rd-party materials. + +.. the following content descriptions shall also work in an offline/paper + context, hence need to use references to book structures rather then + deep-links to some file content + +unDraw illustrations +~~~~~~~~~~~~~~~~~~~~ + +The handbook includes numerous illustrations obtained from Katerina Limpitsouni's https://undraw.co project, covered by the following terms: + + Copyright 2023 Katerina Limpitsouni + + All images, assets and vectors published on unDraw can be used for free. + You can use them for noncommercial and commercial purposes. + You do not need to ask permission from or provide credit to the creator or unDraw. + + More precisely, unDraw grants you an nonexclusive, worldwide copyright license to download, copy, modify, distribute, perform, and use the assets provided from unDraw for free, including for commercial purposes, without permission from or attributing the creator or unDraw. + This license does not include the right to compile assets, vectors or images from unDraw to replicate a similar or competing service, in any form or distribute the assets in packs or otherwise. + This extends to automated and non-automated ways to link, embed, scrape, search or download the assets included on the website without our consent. + + Regarding brand logos that are included: + + Are registered trademarks of their respected owners. + Are included on a promotional basis and do not represent an association with unDraw or its users. + Do not indicate any kind of endorsement of the trademark holder towards unDraw, nor vice versa. + Are provided with the sole purpose to represent the actual brand/service/company that has registered the trademark and must not be used otherwise. + + +YODA illustration +~~~~~~~~~~~~~~~~~ + +The "YODA" cartoon used in chapter :ref:`chapter_yoda` is derived from https://openclipart.org/detail/227445/yoda, which was made available under `CC0`_ terms. + +.. _Creative Commons Attribution-ShareAlike 4.0 International Public License (CC-BY-SA): https://creativecommons.org/licenses/by-sa/4.0 +.. _CC0: http://creativecommons.org/publicdomain/zero/1.0 From 0c0e7a2a1914f25e3d4e906334e44700375d1a39 Mon Sep 17 00:00:00 2001 From: Adina Wagner Date: Tue, 31 Oct 2023 16:46:17 +0100 Subject: [PATCH 6/6] Standardize capitalization of headings --- docs/basics/101-109-rerun.rst | 2 +- docs/basics/101-126-intro.rst | 2 +- docs/basics/101-132-advancednesting.rst | 2 +- docs/basics/101-180-FAQ.rst | 2 +- docs/basics/basics-run.rst | 2 +- docs/beyond_basics/101-147-riastores.rst | 2 +- docs/intro/howto.rst | 8 ++++---- docs/intro/philosophy.rst | 4 ++-- 8 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/basics/101-109-rerun.rst b/docs/basics/101-109-rerun.rst index 6a4c97a9c..f2eb9d622 100644 --- a/docs/basics/101-109-rerun.rst +++ b/docs/basics/101-109-rerun.rst @@ -1,6 +1,6 @@ .. _run2: -DataLad, Re-Run! +DataLad, re-run! ---------------- .. index:: ! datalad command; rerun diff --git a/docs/basics/101-126-intro.rst b/docs/basics/101-126-intro.rst index d249507df..1824c3712 100644 --- a/docs/basics/101-126-intro.rst +++ b/docs/basics/101-126-intro.rst @@ -1,6 +1,6 @@ .. _intromidterm: -A Data Analysis Project with DataLad +A data analysis project with DataLad ------------------------------------ diff --git a/docs/basics/101-132-advancednesting.rst b/docs/basics/101-132-advancednesting.rst index 080151a81..adc32a484 100644 --- a/docs/basics/101-132-advancednesting.rst +++ b/docs/basics/101-132-advancednesting.rst @@ -1,6 +1,6 @@ .. _nesting2: -More on Dataset nesting +More on dataset nesting ^^^^^^^^^^^^^^^^^^^^^^^ .. index:: ! nesting diff --git a/docs/basics/101-180-FAQ.rst b/docs/basics/101-180-FAQ.rst index 5ce2a9a17..317fdeebb 100644 --- a/docs/basics/101-180-FAQ.rst +++ b/docs/basics/101-180-FAQ.rst @@ -1,6 +1,6 @@ .. _FAQ: -Frequently Asked Questions +Frequently asked questions -------------------------- This section answers frequently asked questions about high-level DataLad diff --git a/docs/basics/basics-run.rst b/docs/basics/basics-run.rst index 89d2a6e8e..2eac25402 100644 --- a/docs/basics/basics-run.rst +++ b/docs/basics/basics-run.rst @@ -1,7 +1,7 @@ .. _1-002: .. _chapter_run: -DataLad, Run! +DataLad, run! ------------- .. index:: ! Chapter; 2. DataLad Run diff --git a/docs/beyond_basics/101-147-riastores.rst b/docs/beyond_basics/101-147-riastores.rst index a628ce11f..ca8b10efb 100644 --- a/docs/beyond_basics/101-147-riastores.rst +++ b/docs/beyond_basics/101-147-riastores.rst @@ -1,6 +1,6 @@ .. _riastore: -Remote Indexed Archives for dataset storage and backup +Remote indexed archives for dataset storage and backup ------------------------------------------------------ If DataLad datasets should be backed-up, made available for collaborations diff --git a/docs/intro/howto.rst b/docs/intro/howto.rst index 19397afd1..caf48cd2c 100644 --- a/docs/intro/howto.rst +++ b/docs/intro/howto.rst @@ -32,7 +32,7 @@ On Windows systems, several different interfaces exist: The "CMD" Command Prompt We recommend using CMD, or, if you have them installed already and prefer them over the CMD, the Git Bash or Anaconda prompt. As later parts in this section will show, shells under Windows may use different commands than shells under Linux and macos systems. -Command Syntax +Command syntax ============== Interactions with the shell take the form of commands, text-based instructions to your computer. @@ -78,7 +78,7 @@ and the rest you will lookup in their documentation or via your favorite search DataLad commands naturally also come with many options, and in the next chapters and later examples you will get to see many of them. -Basic Commands +Basic commands ============== The following commands, split between Unix-like (e.g., Linux, macos) and Windows environments, can appear in our examples or are generally useful to know: They can help you to *explore and navigate* in your file system, copy, move, or remove files, or create new directories. @@ -134,7 +134,7 @@ Windows systems Set an :term:`environment variable` ``NAME`` to ``Value`` for your current terminal session -The Prompt +The prompt ========== When you first login on the command line, you are greeted with "the prompt", and it will likely look similar to this: @@ -260,7 +260,7 @@ In order to quickly get home, you could use More information on Windows paths can be found `here `_. -Text Editors +Text editors ============ Text editors are a crucial tool for any Linux user, but regardless of your operating system, diff --git a/docs/intro/philosophy.rst b/docs/intro/philosophy.rst index 456ea3a2c..ec714becd 100644 --- a/docs/intro/philosophy.rst +++ b/docs/intro/philosophy.rst @@ -29,7 +29,7 @@ As built-in, but *optional* features, DataLad yields FAIR_ resources -- for exam can be easily shared *should the user want this*. -On Data +On data ^^^^^^^ Everyone uses data. But once it exists, it does not suffice for most data @@ -85,7 +85,7 @@ managing the evolution of digital objects in a way that fulfills the FAIR_ principles. -The DataLad Philosophy +The DataLad philosophy ^^^^^^^^^^^^^^^^^^^^^^ From a software point of view, DataLad is a command line tool, with an additional Python API to use its features within your software and scripts.