gui, man: Update docs & translations

man/syncthing-bep.7

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-BEP" "7" "Apr 18, 2018" "v0.14" "Syncthing"
+.TH "SYNCTHING-BEP" "7" "May 05, 2018" "v0.14" "Syncthing"
 .SH NAME
 syncthing-bep \- Block Exchange Protocol v1
 .
@@ -41,8 +41,10 @@ forms the \fIglobal model\fP\&. Each device strives to get its folders in sync
 with the global model by requesting missing or outdated blocks from the
 other devices in the cluster.
 .sp
-File data is described and transferred in units of \fIblocks\fP, each being
-128 KiB (131072 bytes) in size.
+File data is described and transferred in units of \fIblocks\fP, each being from
+128 KiB (131072 bytes) to 16 MiB in size, in steps of powers of two. The
+block size may vary between files but is constant in any given file, except
+for the last block which may be smaller.
 .sp
 The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
 “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
@@ -421,7 +423,8 @@ message FileInfo {
     bool         invalid        = 7;
     bool         no_permissions = 8;
     Vector       version        = 9;
-    int64        sequence      = 10;
+    int64        sequence       = 10;
+    int32        block_size     = 13;
 
     repeated BlockInfo Blocks         = 16;
     string             symlink_target = 17;
@@ -513,10 +516,16 @@ The \fBsequence\fP field is the value of a device local monotonic clock at the
 time of last local database update to a file. The clock ticks on every local
 database update, thus forming a sequence number over database updates.
 .sp
+The \fBblock_size\fP field is the size, in bytes, of each individual block in
+the block list (except, possibly, the last block). If this field is missing
+or zero, the block size is assumed to be 128 KiB (131072 bytes). Valid
+values of this field are the powers of two from 128 KiB through 16 MiB. See
+also \fI\%Selection of Block Size\fP\&.
+.sp
 The \fBblocks\fP list contains the size and hash for each block in the file.
-Each block represents a 128 KiB slice of the file, except for the last block
-which may represent a smaller amount of data. The block list is empty for
-directories and symlinks.
+Each block represents a \fBblock_size\fP\-sized slice of the file, except for
+the last block which may represent a smaller amount of data. The block list
+is empty for directories and symlinks.
 .sp
 The \fBsymlink_target\fP field contains the symlink target, for entries of
 symlink type. It is empty for all other entry types.
@@ -839,6 +848,83 @@ a connection close. This size was chosen to accommodate Index messages
 containing a large block list. It’s intended that the limit may be further
 reduced in a future protocol update supporting variable block sizes (and
 thus shorter block lists for large files).
+.SH SELECTION OF BLOCK SIZE
+.sp
+The desired block size for any given file is the smallest block size that
+results in fewer than 2000 blocks, or the maximum block size for larger
+files. This rule results in the following table of block sizes per file
+size:
+.TS
+center;
+|l|l|.
+_
+T{
+File Size
+T}	T{
+Block Size
+T}
+_
+T{
+0 \- 250 MiB
+T}	T{
+128 KiB
+T}
+_
+T{
+250 MiB \- 500 MiB
+T}	T{
+256 KiB
+T}
+_
+T{
+500 MiB \- 1 GiB
+T}	T{
+512 KiB
+T}
+_
+T{
+1 GiB \- 2 GiB
+T}	T{
+1 MiB
+T}
+_
+T{
+2 GiB \- 4 GiB
+T}	T{
+2 MiB
+T}
+_
+T{
+4 GiB \- 8 GiB
+T}	T{
+4 MiB
+T}
+_
+T{
+8 GiB \- 16 GiB
+T}	T{
+8 MiB
+T}
+_
+T{
+16 GiB \- up
+T}	T{
+16 MiB
+T}
+_
+.TE
+.sp
+An implementation MAY deviate from the block size rule when there is good
+reason to do so. For example, if a file has been indexed at a certain block
+size and grows beyond 2000 blocks it may be retained at the current block
+size for practical reasons. When there is no overriding reason to the
+contrary, such as when indexing a new file for the first time, the block
+size rule above SHOULD be followed.
+.sp
+An implementation MUST therefore accept files with a block size differing
+from the above rule. This does not mean that arbitrary block sizes are
+allowed. The block size used MUST be exactly one of the power\-of\-two block
+sizes listed in the table above.
 .SH EXAMPLE EXCHANGE
 .TS
 center;