1:45 a.m.
Hello!
The current approach of invoking the command line without arguments to
list databases has various shortcomings:
* unusual "syntax"
* cannot limit the output to specific databases
* does not work for CalDAV/CardDAV, which needs credentials and/or
syncURL
Here's a proposal, written as patch for README.rst:
===================================================================
SYNOPSIS
========
-Show available sources:
- syncevolution
+List databases:
+ syncevolution --print-databases [<properties>] [<config> <source>]
Show information about configuration(s):
syncevolution --print-servers|--print-configs|--print-peers
@@ -114,15 +114,29 @@ 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
-
-If no arguments are given, then SyncEvolution will list all available
-data sources regardless whether there is a configuration file for them
-or not. The output includes the identifiers which can then be used to
-select those sources in a configuration file. For each source one can
-set a different synchronization mode in its configuration file. ::
+ syncevolution --print-databases [<properties>] [<config> <source>]
+
+If no additional arguments are given, then SyncEvolution will list all
+available backends and the databases that can be accessed through each
+backend. This works without existing configurations. However, some
+backends need additional information (like credentials or URL of a
+remote server) and/or cannot list databases (file backend). This
+additional information can be provided on the command line with
+property assignments (`username=...`) or in an existing configuration.
+The output in these cases explains the required information further.
+
+Otherwise the output starts with a heading that lists the values for
+the `backend` property which select the backend, followed by the databases.
+Each database has a name and a unique ID (in brackets). Typically
+both can be used as value of the 'database' property. One database
+might be marked as `default`. It will be used when `database` is not
+set explicitly.
+
+When selecting an existing source configuration or specifying the `backend`
+property on the command line, only the databases for that backend
+are listed, using the same output format.
=============================================================
Does this make sense?
I have partly implemented that because I wanted to test auto-discovery
of databases in CalDAV at the CalConnect interoperability test event. I
have used it like this to show all address books on a specific server:
syncevolution --print-databases \
syncURL=http://... \
username=... \
password=... \
backend=carddav
I'm undecided whether listing all databases of all sources in a config
should also be supported. Right now, if a config is specified, then a
source also must be given ([<config> <source>]). Would it be useful to
support the [<config> [<source>]] syntax also (= config without source)?
This is for the command line. In the D-Bus API, GetDatabases() already
is defined per source and can be used on a session where temporary
config changes were made, so it should already work without API changes.
Long term the returned information should be made a bit richer and also
include additional information:
* read-only databases => can be mirrored locally, but not be
written to
* large databases (for example, CardDAV gateways) => only access
them in queries, never sync them
Related to this change is the removal of <config> and <source> as
mandatory. Item operations can work without them, if backend and
possibly database are specified as properties on the command line. Not
written up yet, but I'll make the change soon.
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.