From c648d3bceba8729d1a6c60e4f99d72c5c4da2b08 Mon Sep 17 00:00:00 2001
From: Jakob Borg <jakob@nym.se>
Date: Fri, 29 Apr 2016 12:05:17 +0200
Subject: [PATCH] index: Logically group articles, undo renaming discosrv

---
 draft/syncing.rst                           | 53 +++++++++++++++++++++
 index.rst                                   | 16 ++++++-
 users/{custom-discosrv.rst => discosrv.rst} |  0
 users/foldermaster.rst                      |  4 +-
 users/{custom-relaysrv.rst => relaysrv.rst} |  0
 5 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 draft/syncing.rst
 rename users/{custom-discosrv.rst => discosrv.rst} (100%)
 rename users/{custom-relaysrv.rst => relaysrv.rst} (100%)

diff --git a/draft/syncing.rst b/draft/syncing.rst
new file mode 100644
index 000000000..f67cdb69d
--- /dev/null
+++ b/draft/syncing.rst
@@ -0,0 +1,53 @@
+.. _syncing:
+
+Understanding Synchronization
+=============================
+
+Blocks
+------
+
+Files are divided into *blocks*. The blocks are currently fixed size, 128 KiB,
+except the last one in the file which may be smaller. Each file is sliced into
+a number of these blocks, and the SHA256 hash of each block is computed. This
+results in a *block list* containing the offset, size and hash of all blocks
+in the file.
+
+To update a file, Syncthing compares the block list of the current version of
+the file to the block list of the desired version of the file. It then tries
+to find a source for each block that differs. This might be locally, if
+another file already has a block with the same hash, or it may be from another
+device in the cluster. In the first case the block is simply copied on disk,
+in the second case it is requested over the network from the other device.
+
+When a block is copied or recieved from another device, its SHA256 hash is
+computed and compared with the expected value. If it matches the block is
+written to a temporary copy of the file, otherwise it is discarded and
+Syncthing tries to find another source for the block.
+
+Scanning
+--------
+
+Syncthing detects changes to files by scanning. By default this happens every
+60 seconds, but this can be changed per folder. Increasing the scan interval
+uses less resources and is useful for example on large folders that changes
+infrequently. Syncthing-inotify can also be used, which tells Syncthing to
+scan changed files when changes are detected, thus reducing the need for
+periodic rescans.
+
+During a rescan the existing files are checked for changes to their
+modification time or size. The file is "rehashed" if a change is detected
+based on those attributes, that is a new block list is calculated for the
+file. It is not possible to know which parts of a file changed without reading
+the file and computing new SHA256 hashes for each block.
+
+Changes that were detected and hashed are transmitted to the other devices
+after a rescan.
+
+Temporary Files
+---------------
+
+Syncthing never writes directly to a file. Instead all changes are made to a
+temporary copy which is then moved in place over the old version. If an error
+occurrs during the copying or syncing, such as a necessary block not being
+available, the temporary file is kept around for up to a day. This is to avoid
+needlessly requesting data over the network.
diff --git a/index.rst b/index.rst
index d427e8f06..94290966b 100644
--- a/index.rst
+++ b/index.rst
@@ -57,9 +57,23 @@ can use the headings in the left sidebar to navigate the site.
    :glob:
 
    Command Line Operation <users/syncthing>
-   Configuration <users/config>
    users/faq
+
+   Configuration <users/config>
+   users/advanced
+   users/foldermaster
+
    users/firewall
+   users/relaying
+   users/proxying
+
+   users/ignoring
+   users/versioning
+
+   users/discosrv
+   users/relaysrv
+   users/custom-upgrades
+
    users/*
 
 .. toctree::
diff --git a/users/custom-discosrv.rst b/users/discosrv.rst
similarity index 100%
rename from users/custom-discosrv.rst
rename to users/discosrv.rst
diff --git a/users/foldermaster.rst b/users/foldermaster.rst
index 0753de1d5..3baa8f6e9 100644
--- a/users/foldermaster.rst
+++ b/users/foldermaster.rst
@@ -1,7 +1,7 @@
 .. _folder-master:
 
-Folder Master
-=============
+Folder Master Configuration
+===========================
 
 A folder can be set in "master mode" among the folder settings.
 
diff --git a/users/custom-relaysrv.rst b/users/relaysrv.rst
similarity index 100%
rename from users/custom-relaysrv.rst
rename to users/relaysrv.rst