diff options
| -rw-r--r-- | README.rst | 379 | ||||
| -rw-r--r-- | src/syncevo/Cmdline.cpp | 19 | ||||
| -rw-r--r-- | src/syncevo/SyncConfig.cpp | 149 | ||||
| -rw-r--r-- | src/syncevo/SyncConfig.h | 2 |
4 files changed, 362 insertions, 187 deletions
@@ -39,6 +39,7 @@ Restore data from the automatic backups: Create, update or remove a configuration: syncevolution --configure <options> [--] <config> [<source> ...] + syncevolution --remove|--migrate <options> [--] <config> List items: @@ -50,12 +51,15 @@ Export item(s): Add item(s): syncevolution [--delimiter <string>|none] --import <dir>|<file>|- [--] <config> <source> -Update item(s) +Update item(s): syncevolution --update <dir> [--] <config> <source> + syncevolution [--delimiter <string>|none] --update <file>|- [--] <config> <source> <luid> ... + Remove item(s): - syncevolution --delete-items [--] <config> <source> (<luid> ... | \*) + syncevolution --delete-items [--] <config> <source> (<luid> ... | '*') + DESCRIPTION =========== @@ -76,44 +80,212 @@ development), for MeeGo (formerly Moblin) and for Maemo 5/Nokia N900. The source code can be compiled for Unix-like systems and provides a framework to build custom SyncML clients or servers. +TERMINOLOGY +=========== + +peer + A peer is the entity that data is synchronized with. This can be + another device (like a phone), a server (like Google) or + even the host itself (useful for synchronizing two different + databases). + +host + The device or computer that SyncEvolution runs on. + +database + Each peer has one or more databases that get synchronized (Google Calendar, + Google Contacts). Conceptually a database is a set of items where each + item is independent of the others. + +data source + A name for something that provides access to data. Primarily used for + the configuration which combines backend and database settings, sometimes + also instead of these two terms. + +local/remote + Synchronization always happens between a pair of databases and thus + has two sides. One database or side of a sync is remote (the one + of the peer) or local (SyncEvolution). For the sake of consistency (and + lack of better terms), these terms are used even if the peer is another + instance of SyncEvolution and/or all data resides on the same storage. + +sync config + A sync configuration defines how to access a peer: the protocol + which is to be used, how to find the peer, credentials, etc. Peers + might support more than one protocol, in which case multiple + sync configs have to be created. + + Sync configs can be used to initiate a sync (like contacting a + SyncML server) or to handle an incoming sync request (when acting + as SyncML server which is contacted by the peer). + +source config + Each data source corresponds to a local database. A source config + defines how to access that database, like a sync config does for + peers. This information about a local database is independent + of the peers that the database might be synchronized with. + + Sync configs use these shared source configs and add additional, + per-peer settings to each of them that define how that local + database maps to a remote database in the peer. By default a source + config is inactive inside a sync config and thus ignored. It must be + activated by setting the unshared `sync` property to something other + than `none` (aka `disabled`). + + In SyncEvolution's predefined configuration templates, the following + names for sources are used. Different names can be chosen for sources + that are defined manually. + + * addressbook: a list of contacts + * calendar: calendar *events* + * memo: plain text notes + * todo: task list + * calendar+todo: a virtual source combining one local "calendar" and + one "todo" source (required for synchronizing with some phones) + +backend + Access to databases is provided by SyncEvolution backends. It does + not matter where that data is stored. Some backends provide access + to data outside of the host itself (`CalDAV and CardDAV`_, ActiveSync). + +configuration property + Sync and source configs contain configuration properties. Each + property is a name/value pair. Sync properties are used in sync configs, + source properties in source configs. The names were chosen so that + they are unique, i.e., no sync property has the same name as a source + property. + + A property can be *unshared* (has separate values for each peer, therefore + sometimes also called *per-peer*; for example the `uri` property which + defines the remote database), *shared* (same value for all peers; for + example the `database` property for selecting the local database) or + *global* (exactly one value). + +context + Sync and source configs are defined inside a configuration context. + Typically each context represents a certain set of sources. The values + of shared properties are only shared inside their context. That way + it is possible to define a second `work` context with a `work calendar` + source using one database and use the implicit `default` context for + a private `calendar` source with a different database. + +context config + The shared and global properties of a certain context. + +configuration template + Templates define the settings for specific peers. Some templates + are packaged together with SyncEvolution, others may be added by + packagers or users. Settings from templates are copied once into + the sync config when creating it. There is no permanent link back + to the template, so updating a template has no effect on configs + created from it earlier. + + A template only contains unshared properties. Therefore it is + possible to first set shared properties (for example, choosing + which databases to synchronize in the default context), then + add sync configs for different peers to that context without + reseting the existing settings. + +local sync + Traditionally, a sync config specifies SyncML as the synchronization + protocol. The peer must support SyncML for this to work. When the + peer acts as SyncML server, conflict resolution happens on the + peer, outside of the control of SyncEvolution. + + In a so called `local sync`_, SyncEvolution connects two of its own + backends and runs all of the synchronization logic itself on the host. + +target config + In addition to the normal sync config, a local sync also uses a target + config. This target config is a special kind of sync config. It defines + sync properties that are necessary to access databases on the other + side of the local sync. Sync configs can have arbitrary names while + a target config must be named `target-config`. + + +COMMAND LINE CONVENTIONS +======================== + +The ``<config>`` and the ``<source>`` strings in the command line synopsis are +used to find the sync resp. source configs. Depending on which +other parameters are given, different operations are executed. + +A config name has the format ``[<peer>][@<context>]``. When the context +is not specified explicitly, SyncEvolution first searches for an +existing configuration with the given name. If not found, it uses the +``@default`` context as fallback. Thus the empty config name is an alias +for ``@default``. + +The ``<peer>`` part identifies a specific sync or target config inside +the context. It is optional and does not have to be specified when not +needed, for example when configuring the shared settings of sources +(``--configure @default addressbook``) or accessing items inside a +source (``--print-items @work calendar``). + +Listing sources on the command line limits the operation to those +sources (called *active sources* below). If not given, all sources +defined for the config are active. Some operations require +the name of exactly one source. + +Properties are set with key/value assignments and/or the +``--sync/source-property`` keywords. Those keywords are only needed for +the hypothetical situation that a sync and source property share the +same name (not normally the case). Without them, SyncEvolution +automatically identifies which kind of property is meant based on the +name. + +A ``<property>`` assignment has the following format:: + + [<source>/]<name>[@<context>|@<peer>@<context>]=<value> + +The optional ``<context>`` or ``<peer>@<context>`` suffix limits the scope +of the value to that particular configuration. This is useful when +running a local sync, which involves a sync and a target +configuration. For example, the log level can be specified separately +for both sides:: + + --run loglevel@default=1 loglevel@google-calendar=4 google-calendar@default + +A string without a second @ sign inside is always interpreted as a +context name, so in contrast to the ``<config>`` string, ``foo`` cannot be +used to reference the ``foo@default`` configuration. Use the full name +including the context for that. + +When no config or context is specified explicitly, a value is +changed in all active configs, typically the one given with +``<config>``. The priority of multiple values for the same config +is `more specific definition wins`, so ``<peer>@<context>`` +overrides ``@<context>``, which overrides `no suffix given`. +Specifying some suffix which does not apply to the current operation +does not trigger an error, so beware of typos. + +Source properties can be specified with a ``<source>/`` prefix. This +allows limiting the value to the selected source. For example:: + + --configure "addressbook/database=My Addressbook" \ + "calendar/database=My Calendar" \ + @default addressbook calendar + +Another way to achieve the same effect is to run the ``--configure`` +operation twice, once for ``addressbook`` and once for ``calendar``:: + + --configure "database=My Addressbook" @default addressbook + --configure "calendar/database=My Calendar" @default calendar + +If the same property is set both with and without a ``<source>/`` prefix, +then the more specific value with that prefix is used for that source, +regardless of the order on the command line. The following command +enables all sources except for the addressbook:: + + --configure --source-property addressbook/sync=none \ + --source-property sync=two-way \ + <sync config> + + USAGE ===== -The <config> and the <source> strings are used to find the -configuration files which determine how synchronization is going to -proceed. Each source corresponds to one local address book, calendar, -task list or set of memos and the corresponding database on the -peer. Depending on which parameters are given, different operations -are executed. - -Starting with SyncEvolution 1.0, <config> strings can have different -meanings. Typically, a simple string like `memotoo` refers to -the configuration for that peer, as it did in previous releases. A -peer is either a SyncML server (the traditional usage of -SyncEvolution) or a client (the new feature in 1.0). - -Each peer configuration exists inside a specific context, typically -the `@default` context. All peers in the same context share some parts -of their configuration, for example, which local databases are to be -synchronized. In that sense, a configuration context can be seen as a -set of local databases plus the peer configurations that are -synchronized against those databases. - -The peer-independent properties of a source can be configured by -giving the context name as <config> parameter ("@default -addressbook"). Operations manipulating the local data also accept -the context name. - -When different peers are meant to synchronize different local -databases, then different contexts have to be used when setting up the -peers by appending a context name after the `at` sign, as in -`memotoo2@other-context`. Later on, if `memotoo2` is -unique, the `@other-context` suffix becomes optional. - -Sometimes it is also useful to change configuration options of a -context, without modifying a specific peer. This can be done by using -`@default` (or some other context name) without anything before the -`at` sign. The empty string "" is the same as `@default`. :: +:: syncevolution @@ -136,27 +308,16 @@ synchronization: if the synchronization mode of a source is set to `disabled`, the source will be ignored. Explicitly listing such a source will synchronize it in `two-way` mode once. -In SyncEvolution's predefined configuration templates, the following -names for sources are used. Different names can be chosen for sources -that are defined manually. - - * addressbook: a list of contacts - * calendar: calendar *events* - * memo: plain text notes - * todo: task list - * calendar+todo: a virtual source combining one local "calendar" and - one "todo" source (required for synchronizing with some phones) - Progress and error messages are written into a log file that is preserved for each synchronization run. Details about that is found in the `Automatic Backups and Logging` section below. All errors and warnings are printed directly to the console in addition to writing them into the log file. Before quitting SyncEvolution will print a summary of how the local data was modified. This is done with the -`synccompare` utility script described in the `Exchanging Data` +`synccompare` utility script described in the `Exchanging Data`_ section. -When the `logdir` option is enabled (since v0.9 done by default for +When the ``logdir`` property is enabled (since v0.9 done by default for new configurations), then the same comparison is also done before the synchronization starts. @@ -205,8 +366,8 @@ on the command line. :: syncevolution --status <config> [<source> ...] Prints what changes were made locally since the last synchronization. -Depends on access to database dumps from the last run, so using the -`logdir` option is recommended. :: +Depends on access to database dumps from the last run, so enabling the +``logdir`` property is recommended. :: syncevolution --print-servers|--print-configs|--print-peers syncevolution --print-config [--quiet] <config> [main|<source> ...] @@ -255,11 +416,11 @@ only alphanumeric characters, dash and underscore. A star * in <config> and <source> must be given, but they do not have to refer to existing configurations. In that case, the desired backend and must be -give via "--source-property type=<backend>", like this:: +give via the ``backend`` property, like this:: - syncevolution --print-items --source-property type=evolution-contacts dummy-config dummy-source + syncevolution --print-items backend=evolution-contacts dummy-config dummy-source -The desired backend database can be chosen via "--source-property database". +The desired backend database can be chosen via ``database=<identifier>``. OPTIONS ======= @@ -274,7 +435,7 @@ a list of valid values. for a `refresh-from-server` or `refresh-from-client` sync which clears all data at one end and copies all items from the other. - **Warning:** in local sync (CalDAV/CardDAV/ActiveSync, ...) and + **Warning:** in local sync (`CalDAV and CardDAV`_/ActiveSync, ...) and direct sync with a phone, the sync is started by the side which acts as server. Therefore the ``from-server`` variants (``one-way-from-server``, ``refresh-from-server``) transfer data @@ -302,8 +463,8 @@ a list of valid values. \--print-sessions Prints information about previous synchronization sessions for the - selected peer or context are printed. This depends on the `logdir` - option. The information includes the log directory name (useful for + selected peer or context are printed. This depends on the ``logdir`` + property. The information includes the log directory name (useful for --restore) and the synchronization report. In combination with --quiet, only the paths are listed. @@ -409,71 +570,10 @@ a list of valid values. to update the configuration. Can be used multiple times. Specifying an unused property will trigger an error message. - The <property> has the following format: ``<name>[@<context>|@<peer>@<context>]`` - - The optional <context> or <peer>@<context> suffix limits the scope - of the value to that particular configuration. This is currently - only useful for a local sync, which involves a source and a target - configuration. - - A string without a second @ sign inside is always interpreted as a - context name, so in contrast to the <server> string, "foo" cannot be - used to reference the "foo@default" configuration. Use the full name - including the context for that. - - When no config or context is specified explicitly, a value is - changed in all active configs, typically the one given with - ``<server>``. The priority of multiple values for the same config - is `more specific definition wins`, so ``<peer>@<context>`` - overrides ``@<context>``, which overrides `no suffix given`. - Specifying some suffix which does not apply to the current operation - does not trigger an error, so beware of typos. - - When using the configuration layout introduced with 1.0, some of the - sync properties are shared between peers, for example the directory - where sessions are logged. Permanently changing such a shared - property for one peer will automatically update the property for all - other peers in the same context because the property is stored in a - shared config file. When printing a config in verbose mode, a summary - comment shows which properties are shared in which way. - --source-property|-z <property>=<value>|<property>=?|? Same as --sync-property, but applies to the configuration of all active sources. `--sync <mode>` is a shortcut for `--source-property sync=<mode>`. - The <property> has the following format: ``[<source>/]<name>[@<context>|@<peer>@<context>]`` - - In it's simplest form without <source>, <context> or <config>, - the name specifies one of the know properties. - When combined with `--configure`, the configuration of all sources - is modified. The value is applied to all sources unless sources are - listed explicitly on the command line. So if you want to change a - source property of just one specific sync source, then use - `--configure --source-property ... <server> <source>`. - - Adding the <source>/ prefix makes it possible to set the same - property differently for different sources in one command:: - - --configure --source-property addressbook/sync=two-way \ - --source-property calendar/sync=one-way-from-server \ - <server> - - If the same property is set both with and without a <source>/ prefix, - then the more specific value with that prefix is used for that source, - regardless of the order on the command line. The following command - disables all sources except for the addressbook:: - - --configure --source-property addressbook/sync=none \ - --source-property sync=two-way \ - <server> - - As with sync properties, some properties are shared between peers, - in particular the selection of which local data to synchronize. The - optional configuration suffix in ``<property>`` also has the same - meaning as for sync properties. That suffix is checked first, so - "sync@foo@default" overrides "addressbook/sync", even though - "addressbook/sync" normally overrides "sync". - --template|-l <peer name>|default|?<device> Can be used to select from one of the built-in default configurations for known SyncML peers. Defaults to the <config> name, so --template @@ -540,6 +640,35 @@ a list of valid values. \--version Prints the SyncEvolution version. + +CONFIGURATION PROPERTIES +======================== + +This section lists predefined properties. Backends can add their own +properties at runtime if none of the predefined properties are +suitable for a certain setting. Those additional properties are not +listed here. Use ``--sync/source-property ?`` to get an up-to-date +list. + +The predefined properties may also be interpreted slightly differently +by each backend and sync protocol. Sometimes this is documented in the +comment for each property, sometimes in the documentation of the +backend or sync protocol. + +Properties are listed together with all recognized aliases (in those +cases where a property was renamed at some point), its default value, +sharing state (unshared/shared/global). Some properties must be +defined, which is marked with the word `required`. + +Sync properties +--------------- +<<insert sync-property>> + +Source properties +----------------- +<<insert source-property>> + + EXAMPLES ======== @@ -626,6 +755,8 @@ created anew with the current syncevolution:: syncevolution --migrate memotoo +.. _local sync: + Synchronization beyond SyncML ============================= @@ -742,7 +873,7 @@ Exchanging Data --------------- SyncEvolution transmits address book entries as vCard 2.1 or 3.0 -depending on the type chosen in the configuration. Evolution uses +depending on the sync format chosen in the configuration. Evolution uses 3.0 internally, so SyncEvolution converts between the two formats as needed. Calendar items and tasks can be sent and received in iCalendar 2.0 as well as vCalendar 1.0, but vCalendar 1.0 should be avoided if @@ -835,7 +966,7 @@ can create the following files during a synchronization: automatic comparison of the before/after state with `synccompare` -If the server configuration option "logdir" is set, then +If the sync configuration property ``logdir`` is set, then a new directory will be created for each synchronization in that directory, using the format `<peer>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>]` with the various fields filled in with the time when the @@ -845,7 +976,7 @@ SyncEvolution will never delete any data in that log directory unless explicitly asked to keep only a limited number of previous log directories. -This is done by setting the "maxlogdirs" limit to something +This is done by setting the ``maxlogdirs`` limit to something different than the empty string and 0. If a limit is set, then SyncEvolution will only keep that many log directories and start removing the "less interesting" ones when it reaches @@ -853,8 +984,8 @@ the limit. Less interesting are those where no data changed and no error occurred. To avoid writing any additional log file or database dumps during -a synchronization, the "logdir" can be set to "none". To reduce -the verbosity of the log, set "loglevel". If not set or 0, then +a synchronization, the ``logdir`` can be set to ``none``. To reduce +the verbosity of the log, set ``loglevel``. If not set or 0, then the verbosity is set to 3 = DEBUG when writing to a log file and 2 = INFO when writing to the console directly. To debug issues involving data conversion, level 4 also dumps the content of diff --git a/src/syncevo/Cmdline.cpp b/src/syncevo/Cmdline.cpp index 03bc9309..3af58a06 100644 --- a/src/syncevo/Cmdline.cpp +++ b/src/syncevo/Cmdline.cpp @@ -1720,20 +1720,37 @@ bool Cmdline::listProperties(const ConfigPropertyRegistry &validProps, // Remember that comment and print it as late as possible, // that way related properties preceed their comment. string comment; + bool needComma = false; BOOST_FOREACH(const ConfigProperty *prop, validProps) { if (!prop->isHidden()) { string newComment = prop->getComment(); if (newComment != "") { if (!comment.empty()) { + m_out << endl; dumpComment(m_out, " ", comment); m_out << endl; + needComma = false; } comment = newComment; } - m_out << prop->getMainName() << ":" << endl; + std::string def = prop->getDefValue(); + if (def.empty()) { + def = "no default"; + } + ConfigProperty::Sharing sharing = prop->getSharing(); + if (needComma) { + m_out << ", "; + } + m_out << boost::join(prop->getNames(), " = ") + << " (" << def << ", " + << ConfigProperty::sharing2str(sharing) + << (prop->isObligatory() ? ", required" : "") + << ")"; + needComma = true; } } + m_out << endl; dumpComment(m_out, " ", comment); return true; } diff --git a/src/syncevo/SyncConfig.cpp b/src/syncevo/SyncConfig.cpp index a07fe6f2..24c2e3cd 100644 --- a/src/syncevo/SyncConfig.cpp +++ b/src/syncevo/SyncConfig.cpp @@ -168,6 +168,22 @@ void ConfigProperty::throwValueError(const ConfigNode &node, const string &name, SyncContext::throwError(node.getName() + ": " + name + " = " + value + ": " + error); } +std::string ConfigProperty::sharing2str(Sharing sharing) +{ + switch (sharing) { + case GLOBAL_SHARING: + return "global"; + break; + case SOURCE_SET_SHARING: + return "shared"; + break; + case NO_SHARING: + return "unshared"; + break; + } + return "???"; +} + string SyncConfig::normalizeConfigString(const string &config, NormalizeFlags flags) { string normal = config; @@ -1092,20 +1108,20 @@ SyncSourceNodes SyncConfig::getSyncSourceNodesNoTracking(const string &name) static ConfigProperty syncPropSyncURL("syncURL", "Identifies how to contact the peer,\n" - "best explained with some examples:\n" - "HTTP(S) SyncML servers:\n" + "best explained with some examples.\n\n" + "HTTP(S) SyncML servers::\n\n" " http://my.funambol.com/sync\n" " http://sync.scheduleworld.com/funambol/ds\n" - " https://m.google.com/syncml\n" + " https://m.google.com/syncml\n\n" "OBEX over Bluetooth uses the MAC address, with\n" - "the channel chosen automatically:\n" - " obex-bt://00:0A:94:03:F3:7E\n" - "If the automatism fails, the channel can also be specified:\n" - " obex-bt://00:0A:94:03:F3:7E+16\n" + "the channel chosen automatically::\n\n" + " obex-bt://00:0A:94:03:F3:7E\n\n" + "If the automatism fails, the channel can also be specified::\n\n" + " obex-bt://00:0A:94:03:F3:7E+16\n\n" "For peers contacting us via Bluetooth, the MAC address is\n" "used to identify it before the sync starts. Multiple\n" - "urls can be specified in one syncURL property:\n" - " obex-bt://00:0A:94:03:F3:7E obex-bt://00:01:02:03:04:05\n" + "urls can be specified in one syncURL property::\n\n" + " obex-bt://00:0A:94:03:F3:7E obex-bt://00:01:02:03:04:05\n\n" "In the future this might be used to contact the peer\n" "via one of several transports; right now, only the first\n" "one is tried." // MB #9446 @@ -1125,10 +1141,10 @@ static PasswordConfigProperty syncPropPassword("password", "password used for authorization with the peer;\n" "in addition to specifying it directly as plain text, it can\n" "also be read from the standard input or from an environment\n" - "variable of your choice:\n" - " plain text: password = <insert your password here>\n" - " ask: password = -\n" - "env variable: password = ${<name of environment variable>}\n"); + "variable of your choice::\n\n" + " plain text : password = <insert your password here>\n" + " ask : password = -\n" + " env variable: password = ${<name of environment variable>}\n"); static BoolConfigProperty syncPropPreventSlowSync("preventSlowSync", "During a slow sync, the SyncML server must match all items\n" "of the client with its own items and detect which ones it\n" @@ -1142,7 +1158,7 @@ static BoolConfigProperty syncPropPreventSlowSync("preventSlowSync", "are not allowed to proceed. Instead, the affected sources are\n" "skipped, allowing the user to choose a suitable sync mode in\n" "the next run (slow sync selected explicitly, refresh sync).\n" - "The following situations are handled:\n" + "The following situations are handled:\n\n" "- running as client with no local data => unproblematic,\n" " slow sync is allowed to proceed automatically\n" "- running as client with local data => client has no\n" @@ -1152,15 +1168,15 @@ static BoolConfigProperty syncPropPreventSlowSync("preventSlowSync", " was deleted (done by Memotoo and Mobical, because they treat\n" " this as 'user wants to start from scratch') => the sync would\n" " recreate all the client's data, even if the user really wanted\n" - " to have it deleted, therefore slow sync is prevented\n" - "Slow syncs are not yet detected when running as server.\n", - "1"); + " to have it deleted, therefore slow sync is prevented\n", + "TRUE"); static BoolConfigProperty syncPropUseProxy("useProxy", "set to T to choose an HTTP proxy explicitly; otherwise the default\n" "proxy settings of the underlying HTTP transport mechanism are used;\n" - "only relevant when contacting the peer via HTTP"); + "only relevant when contacting the peer via HTTP", + "FALSE"); static ConfigProperty syncPropProxyHost("proxyHost", - "proxy URL (http://<host>:<port>)"); + "proxy URL (``http://<host>:<port>``)"); static ConfigProperty syncPropProxyUsername("proxyUsername", "authentication for proxy: username"); static ProxyPasswordConfigProperty syncPropProxyPassword("proxyPassword", @@ -1191,7 +1207,7 @@ static ULongConfigProperty syncPropMaxMsgSize("maxMsgSize", "150000"); static UIntConfigProperty syncPropMaxObjSize("maxObjSize", "", "4000000"); -static BoolConfigProperty syncPropCompression("enableCompression", "enable compression of network traffic (not currently supported)"); +static BoolConfigProperty syncPropCompression("enableCompression", "enable compression of network traffic (not currently supported)", "FALSE"); static BoolConfigProperty syncPropWBXML("enableWBXML", "use the more compact binary XML (WBXML) for messages between client and server;\n" "not applicable when the peer is a SyncML client, because then the client\n" @@ -1221,11 +1237,11 @@ static UIntConfigProperty syncPropLogLevel("loglevel", static BoolConfigProperty syncPropPrintChanges("printChanges", "enables or disables the detailed (and sometimes slow) comparison\n" "of database content before and after a sync session", - "1"); + "TRUE"); static BoolConfigProperty syncPropDumpData("dumpData", "enables or disables the automatic backup of database content\n" "before and after a sync session (always enabled if printChanges is enabled)", - "1"); + "TRUE"); static SecondsConfigProperty syncPropRetryDuration("RetryDuration", "The total amount of time in seconds in which the SyncML\n" "client tries to get a response from the server.\n" @@ -1260,7 +1276,7 @@ static SecondsConfigProperty syncPropRetryInterval("RetryInterval", static BoolConfigProperty syncPropPeerIsClient("PeerIsClient", "Indicates whether this configuration is about a\n" "client peer or server peer.\n", - "0"); + "FALSE"); static SafeConfigProperty syncPropPeerName("PeerName", "An arbitrary name for the peer referenced by this config.\n" "Might be used by a GUI. The command line tool always uses the\n" @@ -1299,13 +1315,13 @@ static BoolConfigProperty syncPropSSLVerifyServer("SSLVerifyServer", "option considerably reduces the security of SSL\n" "(man-in-the-middle attacks become possible) and is not\n" "recommended.\n", - "1"); + "TRUE"); static BoolConfigProperty syncPropSSLVerifyHost("SSLVerifyHost", "The client refuses to establish the connection unless the\n" "server's certificate matches its host name. In cases where\n" "the certificate still seems to be valid it might make sense\n" "to disable this option and allow such connections.\n", - "1"); + "TRUE"); static ConfigProperty syncPropWebURL("WebURL", "The URL of a web page with further information about the server.\n" @@ -1323,7 +1339,7 @@ static BoolConfigProperty syncPropConsumerReady("ConsumerReady", "for normal users. Used by the GUI to limit the choice\n" "of configurations offered to users.\n" "Has no effect in a user's server configuration.\n", - "0"); + "FALSE"); /** * Some guidelines for peerType = WebDAV: @@ -1381,13 +1397,13 @@ static StringConfigProperty syncPropAutoSync("autoSync", "Because a peer might be reachable via different\n" "transports at some point, this option provides\n" "detailed control over which transports may\n" - "be used for automatic synchronization:\n" - "0 - don't do auto sync\n" - "1 - do automatic sync, using whatever transport\n" + "be used for automatic synchronization:\n\n" + "0\n don't do auto sync\n" + "1\n do automatic sync, using whatever transport\n" " is available\n" - "http - only via HTTP transport\n" - "obex-bt - only via Bluetooth transport\n" - "http,obex-bt - pick one of these\n", + "http\n only via HTTP transport\n" + "obex-bt\n only via Bluetooth transport\n" + "http,obex-bt\n pick one of these\n", "0"); static SecondsConfigProperty syncPropAutoSyncInterval("autoSyncInterval", @@ -2103,16 +2119,25 @@ SyncSourceConfig::SyncSourceConfig(const string &name, const SyncSourceNodes &no } StringConfigProperty SyncSourceConfig::m_sourcePropSync("sync", - "Requests a certain synchronization mode when initiating a sync:\n" - " two-way = only send/receive changes since last sync\n" - " slow = exchange all items\n" - " refresh-from-client = discard all remote items and replace with\n" - " the items on the client\n" - " refresh-from-server = discard all local items and replace with\n" - " the items on the server\n" - " one-way-from-client = transmit changes from client\n" - " one-way-from-server = transmit changes from server\n" - " disabled (or none) = synchronization disabled\n" + "Requests a certain synchronization mode when initiating a sync:\n\n" + " two-way\n" + " only send/receive changes since last sync\n" + " slow\n" + " exchange all items\n" + " refresh-from-client\n" + " discard all remote items and replace with the items on the client\n" + " refresh-from-server\n" + " discard all local items and replace with the items on the server\n" + " one-way-from-client\n" + " transmit changes from client\n" + " one-way-from-server\n" + " transmit changes from server\n" + " disabled (or none)\n" + " synchronization disabled\n\n" + + "**WARNING**: which side is `client` and which is `server` depends on\n" + "the value of the ``peerIsClient`` property in the configuration.\n\n" + "When accepting a sync session in a SyncML server (HTTP server), only\n" "sources with sync != disabled are made available to the client,\n" "which chooses the final sync mode based on its own configuration.\n" @@ -2150,8 +2175,8 @@ public: "Right now such a virtual backend is limited to\n" "combining one calendar source with events and one\n" "task source. They have to be specified in the\n" - "'database' property, typically like this:\n" - " calendar,todo\n" + "``database`` property, typically like this:\n" + "``calendar,todo``\n" "\n" "Different sources combined in one virtual source must\n" "have a common format. As with other backends,\n" @@ -2181,20 +2206,19 @@ public: SourceRegistry ®istry(SyncSource::getSourceRegistry()); BOOST_FOREACH(const RegisterSyncSource *sourceInfos, registry) { - const string &comment = sourceInfos->m_typeDescr; + string comment = boost::trim_right_copy_if(sourceInfos->m_typeDescr, + boost::is_any_of(" \t\n")); stringstream *curr = sourceInfos->m_enabled ? &enabled : &disabled; - *curr << comment; - if (comment.size() && comment[comment.size() - 1] != '\n') { - *curr << '\n'; - } + boost::replace_all(comment, "\n", "\n "); + *curr << " " << comment << "\n"; } res << StringConfigProperty::getComment(); if (enabled.str().size()) { - res << "\nCurrently active:\n" << enabled.str(); + res << "\n\nCurrently active::\n\n" << enabled.str(); } if (disabled.str().size()) { - res << "\nCurrently inactive:\n" << disabled.str(); + res << "\n\nCurrently inactive::\n\n" << disabled.str(); } return boost::trim_right_copy(res.str()); @@ -2236,30 +2260,31 @@ static BoolConfigProperty sourcePropForceSyncFormat("forceSyncFormat", "In such a case, setting this property enforces that the\n" "preferred format specified with 'syncFormat' is\n" "really used.", - "0"); + "FALSE"); static ConfigProperty sourcePropDatabaseID(Aliases("database") + "evolutionsource", - "Picks one of backend data sources:\n" - "enter either the name or the full URL.\n" - "Most backends have a default data source,\n" + "Picks one of the backend's databases:\n" + "depending on the backend, one can set the name\n" + "and/or a unique identifier.\n\n" + "Most backends have a default database,\n" "like for example the system address book.\n" "Not setting this property selects that default\n" - "data source.\n" + "database.\n\n" "If the backend is a virtual data source,\n" "this field must contain comma seperated list of\n" "sub datasources actually used to store data.\n" "If your sub datastore has a comma in name, you\n" "must prevent taht comma from being mistaken as the\n" "separator by preceding it with a backslash, like this:\n" - " database=Source1PartA\\,PartB,Source2\\\\Backslash\n" + "``database=Source1PartA\\,PartB,Source2\\\\Backslash``\n" "\n" - "To get a full list of available data sources,\n" - "run syncevolution without parameters. The name\n" + "To get a full list of available databases,\n" + "run ``syncevolution --print-databases``. The name\n" "is printed in front of the colon, followed by\n" - "the URL. Usually the name is unique and can be\n" + "an identifier in brackets. Usually the name is unique and can be\n" "used to reference the data source. The default\n" - "data source is marked with <default> after the\n" - "URL, if there is a default.\n"); + "data source is marked with <default> at the end\n" + "of the line, if there is a default.\n"); static StringConfigProperty sourcePropDatabaseFormat("databaseFormat", "Defines the data format to be used by the backend for its\n" diff --git a/src/syncevo/SyncConfig.h b/src/syncevo/SyncConfig.h index afc3d432..a4593a27 100644 --- a/src/syncevo/SyncConfig.h +++ b/src/syncevo/SyncConfig.h @@ -342,6 +342,8 @@ class ConfigProperty { logdir property */ NO_SHARING /**< each peer has his own values */ }; + /** "global", "shared", "unshared" */ + static std::string sharing2str(Sharing sharing); Sharing getSharing() const { return m_sharing; } void setSharing(Sharing sharing) { m_sharing = sharing; } |