[Reuse] Draft of REUSE tutorial

[Carmen Bianca Bakker]

Hi Peter,

Je ĵaŭ, 2019-03-14 je 10:53 +0000, Peter Moser (NOI Südtirol/Alto Adige) skribis:
> Hi Carmen,
> finally I got some time to read your work.
> 
> On 2/21/19 2:32 PM, Carmen Bianca Bakker wrote:
> > I have created a draft of the tutorial. 
>  
> It is nicely written and I specially like the story telling. It makes
> it much more fun to read and understand.

Thanks for the kind feedback :)

> Some remarks:
> - I would start with "By the end of this tutorial, all your files will clearly have their copyright and licensing marked." and a title like "Our Goal" (or something similar)
> - I would say "Assume that your project looks like this"... (This may also be clearer for non-native speakers; I was a little confused by "invariably")
> - I would add a description in parentheses for each abbreviation at its very first occurrence, for example, "FSF (Free Software Foundation)"
> - I would remove "(though they may also begin with ©)", because it is just a detail
> - I would remove ": Perhaps these files inexplicably break your build process.", because it is unlikely to happen and the sentence before already describes the reason somehow
> - "We followed the FSF's recommendations here." Maybe we could add a link to the recommendations? (...and, I would always use present tense)
> - "[...] ---the rest you can fill in as you like" <-- Is that true?

Agreed on all accounts, except the last.  Kind of.  I changed the
phrasing to say "the rest is up to your discretion".  The blurb text
differs _a lot_ from project to project, so there are no hard rules
there.

But you're right that "as you like" sounds too free-form.  Some
consideration needs to go into the blurb text, so I rephrased it.

On a separate note: I've just re-read the draft, and I notice two things
missing.  I'm half-sure they're worth adding:

- How to ignore files (i.e., mark them with CC0, because this gets asked
  a lot).

- How to lint the project automagically.

I think the second subject is worthy of being mentioned.  The first
subject might also be put in a FAQ, however.

In any case, find below the suggested patch for now.

With kindness,
Carmen



diff --git a/content/reuse.en.md b/content/reuse.en.md
index d10a0c1..216ca41 100644
--- a/content/reuse.en.md
+++ b/content/reuse.en.md
@@ -4,9 +4,15 @@ subtitle: "!!!THIS IS A ROUGH DRAFT!!!"
 type: "page"
 ---
 
+# Our goal
+
+By the end of this tutorial, all your files will clearly have their copyright
+and licensing marked.
+
 # Your project
 
-The directory of your project will invariably look something like this:
+For the purpose of this tutorial, we will assume that the directory of your
+project looks like this:
 
 ```
 project/
@@ -26,19 +32,16 @@ project/
 └── README.md
 ```
 
-By the end of this tutorial, all your files will clearly have their copyright
-and licensing marked.
-
 # A licence
 
 The first thing you need is a licence.  There are many good licences, but we
-will pick the GNU General Public Licence v3.0.  More than simply choosing a
-licence, you need to put the licence in your project directory.
+will pick the GNU General Public Licence v3.0 (GPL).  More than simply choosing
+a licence, you need to put the licence in your project directory.
 
 In the [SPDX License List](https://spdx.org/licenses/), we notice that the SPDX
 Identifier of the licence is `GPL-3.0-or-later`.  As such, we create a directory
-`LICENSES`, and put the [licence text from the
-FSF](https://www.gnu.org/licenses/gpl-3.0.txt) in a file called
+`LICENSES`, and put the [licence text from the Free Software Foundation
+(FSF)](https://www.gnu.org/licenses/gpl-3.0.txt) in a file called
 `GPL-3.0-or-later.txt`.
 
 # Header blurb
@@ -68,11 +71,11 @@ these files fall under that licence.  We edit `src/main.c` as such:
  */
 ```
 
-Only the first three lines are relevant for REUSE compliance---the rest you can
-fill in as you like.  We followed the FSF's recommendations here.
+Only the first three lines are relevant for REUSE compliance---the rest is up to
+your discretion.  In this blurb, we use the text that the GPL proposes.
 
-- The first and second lines begin with `Copyright` (though they may also begin
-  with `©`) and record the publication years and copyright holders.
+- The first and second lines begin with `Copyright` and record the publication
+  years and copyright holders.
 
 -  The third line begins with `SPDX-License-Identifier:` and is followed up by a
   [valid SPDX License Expression](https://spdx.org/specifications), typically
@@ -123,8 +126,7 @@ files.  You could edit the headers of these files yourself, but there are a lot
 of them, and you do not feel comfortable manually editing the translation files.
 
 You could use `.license` files like you did for the images, but for some reason
-you wish to opt against this: Perhaps these files inexplicably break your build
-process.
+you wish to opt against this.
 
 For these files, you can use a configuration file.  In your project root, create
 the file `.reuse/dep5`.  This file uses Debian's

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part
URL: <https://lists.fsfe.org/mailman/private/reuse/attachments/20190314/7b370602/attachment.sig>