From 07695b3622c9dd3e67babea59d25ef6a5731cbae Mon Sep 17 00:00:00 2001
From: Alexander Neumann <alexander@bumpern.de>
Date: Sun, 5 Mar 2017 20:12:25 +0100
Subject: [PATCH] Documentation fixes

---
 doc/Design.md | 38 +++++++++++++++++++++++++++++---------
 doc/Manual.md | 19 +++++++++++++++----
 2 files changed, 44 insertions(+), 13 deletions(-)

diff --git a/doc/Design.md b/doc/Design.md
index e244245a2..52a228a93 100644
--- a/doc/Design.md
+++ b/doc/Design.md
@@ -295,7 +295,7 @@ The command `restic cat snapshot` can be used as follows to decrypt and
 pretty-print the contents of a snapshot file:
 
 ```console
-$ restic -r /tmp/restic-repo cat snapshot 22a5af1b
+$ restic -r /tmp/restic-repo cat snapshot 251c2e58
 enter password for repository:
 {
   "time": "2015-01-02T18:10:50.895208559+01:00",
@@ -307,19 +307,39 @@ enter password for repository:
   "gid": 100,
   "tags": [
     "NL"
+  ]
+}
+```
+
+Here it can be seen that this snapshot represents the contents of the directory
+`/tmp/testdata`. The most important field is `tree`. When the meta data (e.g.
+the tags) of a snapshot change, the snapshot needs to be re-encrypted and saved.
+This will change the storage ID, so in order to relate these seemingly
+different snapshots, a field `original` is introduced which contains the ID of
+the original snapshot, e.g. after adding the tag `DE` to the snapshot above it
+becomes:
+
+```console
+$ restic -r /tmp/restic-repo cat snapshot 22a5af1b
+enter password for repository:
+{
+  "time": "2015-01-02T18:10:50.895208559+01:00",
+  "tree": "2da81727b6585232894cfbb8f8bdab8d1eccd3d8f7c92bc934d62e62e618ffdf",
+  "dir": "/tmp/testdata",
+  "hostname": "kasimir",
+  "username": "fd0",
+  "uid": 1000,
+  "gid": 100,
+  "tags": [
+    "NL",
+    "DE"
   ],
   "original": "251c2e5841355f743f9d4ffd3260bee765acee40a6229857e32b60446991b837"
 }
 ```
 
-Here it can be seen that this snapshot represents the contents of the directory
-`/tmp/testdata` after its tags were changed to "NL". The most important field
-is `tree`.
-
-Another important field is `original`, if any modification is made to the
-snapshot, say because its tags changed, its SHA-256 hash changes and therefore
-the original snapshot id is lost. Retaining a stable id is especially important
-for caching.
+Once introduced, the `original` field is not modified when the snapshot's meta
+data is changed again.
 
 All content within a restic repository is referenced according to its SHA-256
 hash. Before saving, each file is split into variable sized Blobs of data. The
diff --git a/doc/Manual.md b/doc/Manual.md
index fe52735d9..513ef612c 100644
--- a/doc/Manual.md
+++ b/doc/Manual.md
@@ -397,28 +397,39 @@ enter password for repository:
 
 # Manage tags
 
-Managing tags on snapshots is simple. The existing set of tags can be either
-replaced completely, added to or removed from. The result is directly visible
-in the `snapshots` command.
+Managing tags on snapshots is done with the `tag` command. The existing set of
+tags can be replaced completely, tags can be added to removed. The result is
+directly visible in the `snapshots` command.
+
+Let's say we want to tag snapshot `590c8fc8` with the tags `NL` and `CH` and
+remove all other tags that may be present, the following command does that:
 
 ```console
 $ restic -r /tmp/backup tag --set NL,CH 590c8fc8
 Create exclusive lock for repository
 Modified tags on 1 snapshots
 ```
+
 Note the snapshot ID has changed, so between each change we need to look up
 the new ID of the snapshot. But there is an even better way, the `tag` command
-accepts `--tag`, so we can filter snapshots based on the tag we just added.
+accepts `--tag` for a filter, so we can filter snapshots based on the tag we
+just added.
+
+So we can add and remove tags incrementally like this:
+
 ```console
 $ restic -r /tmp/backup tag --tag NL --remove CH
 Create exclusive lock for repository
 Modified tags on 1 snapshots
+
 $ restic -r /tmp/backup tag --tag NL --add UK
 Create exclusive lock for repository
 Modified tags on 1 snapshots
+
 $ restic -r /tmp/backup tag --tag NL --remove NL
 Create exclusive lock for repository
 Modified tags on 1 snapshots
+
 $ restic -r /tmp/backup tag --tag NL --add SOMETHING
 No snapshots were modified
 ```