gui, man: Update docs and translations

2016-10-07 11:09:19 +09:00
parent cb1b53cfb5
commit 54d4010f1a
27 changed files with 256 additions and 191 deletions
--- a/man/stdiscosrv.1
+++ b/man/stdiscosrv.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "STDISCOSRV" "1" "August 22, 2016" "v0.14" "Syncthing"
+.TH "STDISCOSRV" "1" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 stdiscosrv \- Syncthing Discovery Server
 .
@@ -122,7 +122,7 @@ This guide assumes that you have already set up Syncthing. If you
 haven\(aqt yet, head over to getting\-started first.
 .SS Installing
 .sp
-Go to \fI\%releases\fP <\fBhttps://github.com/syncthing/stdiscosrv/releases\fP> and
+Go to \fI\%releases\fP <\fBhttps://build.syncthing.net/job/stdiscosrv\fP> and
 download the file appropriate for your operating system. Unpacking it will
 yield a binary called \fBstdiscosrv\fP (or \fBstdiscosrv.exe\fP on Windows). Start
 this in whatever way you are most comfortable with; double clicking should
--- a/man/strelaysrv.1
+++ b/man/strelaysrv.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "STRELAYSRV" "1" "August 22, 2016" "v0.14" "Syncthing"
+.TH "STRELAYSRV" "1" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 strelaysrv \- Syncthing Relay Server
 .
--- a/man/syncthing-bep.7
+++ b/man/syncthing-bep.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-BEP" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-BEP" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-bep \- Block Exchange Protocol v1
 .
--- a/man/syncthing-config.5
+++ b/man/syncthing-config.5
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-CONFIG" "5" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-CONFIG" "5" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-config \- Syncthing Configuration
 .
@@ -75,7 +75,7 @@ site request forgery).
 .UNINDENT
 .SH CONFIG FILE FORMAT
 .sp
-The following shows the default configuration file:
+The following shows an example of the default configuration file (IDs will differ):
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -207,7 +207,7 @@ The folder is in default mode. Sending local and accepting remote changes.
 .TP
 .B readonly
 The folder is in "master" mode \-\- it will not be modified by
-syncthing on this device.
+Syncthing on this device.
 .UNINDENT
 .TP
 .B rescanIntervalS
@@ -358,11 +358,7 @@ should copy their list of devices per folder when connecting.
 .sp
 In addition, one or more \fBaddress\fP child elements must be present. Each
 contains an address or host name to use when attempting to connect to this device and will
-be tried in order. Entries other than \fBdynamic\fP must be prefixed with \fBtcp://\fP (dual\-stack), \fBtcp4://\fP (IPv4 only) or 
-.nf
-\(ga\(ga
-.fi
-tcp6://\(ga (IPv6 only). Note that IP addresses need not use tcp4/tcp6; these are optional. Accepted formats are:
+be tried in order. Entries other than \fBdynamic\fP must be prefixed with \fBtcp://\fP (dual\-stack), \fBtcp4://\fP (IPv4 only) or \fBtcp6://\fP (IPv6 only). Note that IP addresses need not use tcp4/tcp6; these are optional. Accepted formats are:
 .INDENT 0.0
 .TP
 .B IPv4 address (\fBtcp://192.0.2.42\fP)
@@ -439,18 +435,18 @@ The following child elements may be present:
 .INDENT 0.0
 .TP
 .B address
-Set the listen addresses. One or more address elements must be present.
+Set the listen addresses. One or more address elements must be present. Entries must have the protocol prefix \fBtcp://\fP\&.
 Allowed address formats are:
 .INDENT 7.0
 .TP
-.B IPv4 address and port (\fB127.0.0.1:8384\fP)
+.B IPv4 address and port (\fBtcp://127.0.0.1:8384\fP)
 The address and port is used as given.
 .TP
-.B IPv6 address and port (\fB[::1]:8384\fP)
+.B IPv6 address and port (\fBtcp://[::1]:8384\fP)
 The address and port is used as given. The address must be enclosed in
 square brackets.
 .TP
-.B Wildcard and port (\fB0.0.0.0:12345\fP, \fB[::]:12345\fP, \fB:12345\fP)
+.B Wildcard and port (\fBtcp://0.0.0.0:12345\fP, \fBtcp://[::]:12345\fP, \fBtcp://:12345\fP)
 These are equivalent and will result in Syncthing listening on all
 interfaces via both IPv4 and IPv6.
 .UNINDENT
@@ -565,7 +561,7 @@ Sets the interval, in minutes, between relay reconnect attempts.
 Whether to attempt to start a browser to show the GUI when Syncthing starts.
 .TP
 .B natEnabled
-Whether to attempt to perform an UPnP and NAT\-PMP port mapping for
+Whether to attempt to perform a UPnP and NAT\-PMP port mapping for
 incoming sync connections.
 .TP
 .B natLeaseMinutes
--- a/man/syncthing-device-ids.7
+++ b/man/syncthing-device-ids.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-DEVICE-IDS" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-DEVICE-IDS" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-device-ids \- Understanding Device IDs
 .
--- a/man/syncthing-event-api.7
+++ b/man/syncthing-event-api.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-EVENT-API" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-EVENT-API" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-event-api \- Event API
 .
@@ -61,6 +61,7 @@ Each event is represented by an object similar to the following:
 .ft C
 {
    "id": 2,
+    "globalID": 3,
    "type": "DeviceConnected",
    "time": "2014\-07\-13T21:04:33.687836696+02:00",
    "data": {
@@ -73,7 +74,7 @@ Each event is represented by an object similar to the following:
 .UNINDENT
 .UNINDENT
 .sp
-The top level keys \fBid\fP, \fBtime\fP, \fBtype\fP and \fBdata\fP are always present,
+The top level keys \fBid\fP, \fBglobalID\fP, \fBtime\fP, \fBtype\fP and \fBdata\fP are always present,
 though \fBdata\fP may be \fBnull\fP\&.
 .INDENT 0.0
 .TP
@@ -81,6 +82,9 @@ though \fBdata\fP may be \fBnull\fP\&.
 A monotonically increasing integer. The first event generated has id \fB1\fP,
 the next has id \fB2\fP etc.
 .TP
+.B globalID
+Also a monotonically increasing integer. And might not be the same as id but will always be either equal or greater in value.
+.TP
 .B time
 The time the event was generated.
 .TP
@@ -561,6 +565,33 @@ The \fBaction\fP field is either \fBupdate\fP (contents changed), \fBmetadata\fP
 .sp
 New in version 0.11.10: The \fBmetadata\fP action.

+.SS LocalChangeDetected
+.sp
+Generated upon scan whenever the local disk has discovered an updated file from the
+previous scan.  This does NOT include events that are discovered and copied from
+other nodes, only files that were changed on the local filesystem.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+  "id": 7,
+  "globalID": 59,
+  "time": "2016\-09\-26T22:07:10.7189141\-04:00",
+  "type": "LocalChangeDetected",
+  "data": {
+    "action": "deleted",
+    "folderID": "vitwy\-zjxqt",
+    "label": "TestSync",
+    "path": "C:\e\eUsers\e\eNate\e\eSync\e\etestfolder\e\etest file.rtf",
+    "type": "file"
+  }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SS LocalIndexUpdated
 .sp
 Generated when the local index information has changed, due to
--- a/man/syncthing-faq.7
+++ b/man/syncthing-faq.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-FAQ" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-FAQ" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-faq \- Frequently Asked Questions
 .
@@ -82,7 +82,7 @@ requires administrator privileges. Links are synced as is and are not
 followed.)
 .UNINDENT
 .sp
-The following is \fInot\fP synchronized;
+The following are \fInot\fP synchronized;
 .INDENT 0.0
 .IP \(bu 2
 File or Directory Owners and Groups (not preserved)
@@ -97,7 +97,7 @@ Windows, POSIX or NFS ACLs (not preserved)
 .IP \(bu 2
 Devices, FIFOs, and Other Specials (ignored)
 .IP \(bu 2
-Sparse file sparseness (will become unsparse)
+Sparse file sparseness (will become sparse, when supported by the OS & filesystem)
 .UNINDENT
 .SS Is synchronization fast?
 .sp
@@ -209,6 +209,24 @@ everywhere else and we don\(aqt know which of the conflicting files is the "best
 from the user point of view. Moreover, if there\(aqs something that automatically
 causes a conflict on change you\(aqll end up with \fBsync\-conflict\-...sync\-conflict
 \-...\-sync\-conflict\fP files.
+.SS How do I rename/move a synced folder?
+.sp
+Syncthing doesn\(aqt have a direct way to do this, as it\(aqs potentially
+dangerous to do so if you\(aqre not careful \- it may result in data loss if
+something goes wrong during the move and is synchronized to your other
+devices.
+.sp
+The easy way to rename or move a synced folder on the local system is to
+remove the folder in the Syncthing UI, move it on disk, then re\-add it using
+the new path.
+.sp
+It\(aqs best to do this when the folder is already in sync between your
+devices, as it is otherwise unpredictable which changes will "win" after the
+move. Changes made on other devices may be overwritten, or changed made
+locally may be overwritten by those on other devices.
+.sp
+An alternative way is to shut down Syncthing, move the folder on disk, edit
+the path directly in the configuration file and then start Syncthing again.
 .SS How to configure multiple users on a single machine?
 .sp
 Each user should run their own Syncthing instance. Be aware that you might need
@@ -300,6 +318,29 @@ $ ssh \-L 9090:127.0.0.1:8384 user@othercomputer.example.com
 .sp
 will log you into othercomputer.example.com, and present the \fIremote\fP
 Syncthing GUI on \fI\%http://localhost:9090\fP on your \fIlocal\fP computer.
+.SS Why do I get "Host check error" in the GUI/API?
+.sp
+Syncthing since version 0.14.6 does an extra security check when the GUI/API
+is bound to localhost \- namely that the browser is talking to localhost.
+This protects against most forms of \fI\%DNS rebinding attack\fP <\fBhttps://en.wikipedia.org/wiki/DNS_rebinding\fP> against the GUI.
+.sp
+To pass this test, ensure that you are accessing the GUI using an URL that
+begins with \fIhttp://localhost\fP, \fIhttp://127.0.0.1\fP or \fIhttp://[::1]\fP\&. HTTPS
+is fine too, of course.
+.sp
+If you are using a proxy in front of Syncthing you may need to disable this
+check, after ensuring that the proxy provides sufficient authentication to
+protect against unauthorized access. Either:
+.INDENT 0.0
+.IP \(bu 2
+Make sure the proxy sets a \fIHost\fP header containing \fIlocalhost\fP, or
+.IP \(bu 2
+Set \fIinsecureSkipHostcheck\fP in the advanced settings, or
+.IP \(bu 2
+Bind the GUI/API to a non\-localhost listen port.
+.UNINDENT
+.sp
+In all cases, username/password authentication and HTTPS should be used.
 .SS Why do I see Syncthing twice in task manager?
 .sp
 One process manages the other, to capture logs and manage restarts. This
--- a/man/syncthing-globaldisco.7
+++ b/man/syncthing-globaldisco.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-GLOBALDISCO" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-GLOBALDISCO" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-globaldisco \- Global Discovery Protocol v3
 .
--- a/man/syncthing-localdisco.7
+++ b/man/syncthing-localdisco.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-LOCALDISCO" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-LOCALDISCO" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-localdisco \- Local Discovery Protocol v4
 .
--- a/man/syncthing-networking.7
+++ b/man/syncthing-networking.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-NETWORKING" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-NETWORKING" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-networking \- Firewall Setup
 .
--- a/man/syncthing-relay.7
+++ b/man/syncthing-relay.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-RELAY" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-RELAY" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-relay \- Relay Protocol v1
 .
--- a/man/syncthing-rest-api.7
+++ b/man/syncthing-rest-api.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-REST-API" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-REST-API" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-rest-api \- REST API
 .
@@ -38,12 +38,12 @@ Syncthing. In most cases both the input and output data is in JSON format. The
 interface is subject to change.
 .SH API KEY
 .sp
-To use the POST methods, or \fIany\fP method when authentication is enabled, an API
-key must be set and used. The API key can be generated in the GUI, or set in the
-\fBconfiguration/gui/apikey\fP element in the configuration file. To use an API
-key, set the request header \fBX\-API\-Key\fP to the API key value. For example,
-\fBcurl \-X POST \-H "X\-API\-Key: abc123" http://localhost:8384/rest/...\fP can be
-used to invoke authenticated POST methods via \fBcurl\fP\&.
+To use the REST AP an API key must be set and used. The API key can be
+generated in the GUI, or set in the \fBconfiguration/gui/apikey\fP element in
+the configuration file. To use an API key, set the request header
+\fBX\-API\-Key\fP to the API key value. For example, \fBcurl \-X POST \-H
+"X\-API\-Key: abc123" http://localhost:8384/rest/...\fP can be used to invoke
+with \fBcurl\fP\&.
 .SH SYSTEM ENDPOINTS
 .SS GET /rest/system/config
 .sp
--- a/man/syncthing-security.7
+++ b/man/syncthing-security.7
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-SECURITY" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-SECURITY" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-security \- Security Principles
 .
--- a/man/syncthing-stignore.5
+++ b/man/syncthing-stignore.5
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING-STIGNORE" "5" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-STIGNORE" "5" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing-stignore \- Prevent files from being synchronized to other nodes
 .
--- a/man/syncthing-versioning.7
+++ b/man/syncthing-versioning.7
@@ -1,8 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "TODO" "7" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING-VERSIONING" "7" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
-Todo \- Keep automatic backups of deleted files by other nodes
+syncthing-versioning \- Keep automatic backups of deleted files by other nodes
 .
 .nr rst2man-indent-level 0
 .
@@ -30,12 +30,6 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.INDENT 0.0
-.INDENT 3.5
-.sp
-External versioning needs example for Windows.
-.UNINDENT
-.UNINDENT
 .SH DESCRIPTION
 .sp
 Syncthing supports archiving the old version of a file when it is deleted or
@@ -93,9 +87,12 @@ For the first day, the most recent version is kept every hour.
 For the first 30 days, the most recent version is kept every day.
 .TP
 .B Until Maximum Age
+Until maximum age, the most recent version is kept every week.
+.TP
+.B Maximum Age
 The maximum time to keep a version in days. For example, to keep replaced or
 deleted files in the ".stversions" folder for an entire year, use 365. If
-only or 10 days, use 10. \fBNote: Set to 0 to keep versions forever.\fP
+only for 10 days, use 10. \fBNote: Set to 0 to keep versions forever.\fP
 .UNINDENT
 .SH EXTERNAL FILE VERSIONING
 .sp
--- a/man/syncthing.1
+++ b/man/syncthing.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SYNCTHING" "1" "August 22, 2016" "v0.14" "Syncthing"
+.TH "SYNCTHING" "1" "October 05, 2016" "v0.14" "Syncthing"
 .SH NAME
 syncthing \- Syncthing
 .