command line: introduced --print-databases

Listing databases is now a dedicated operation, instead of being done
whenever syncevolution was invoked without parameters.

Advantages:
- can be combined with property assignments for backends
  which do not work without that additional information
- can be done for configured sources

1 files changed, 28 insertions, 9 deletions

diff --git a/README.rst b/README.rst
index 7e3ddd40..a03c2494 100644
--- a/README.rst
+++ b/README.rst
@@ -13,8 +13,8 @@ synchronize personal information management data
 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
@@ -115,13 +115,32 @@ 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, like for example the CalDAV backend, need additional
+information (like credentials or URL of a remote server). This
+additional information can be provided on the command line with
+property assignments (`username=...`) or in an existing configuration.
+
+When listing all databases of all active sources, 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 and the initial line shows how that backend was selected
+(<config>/<source> resp. backend value).
+
+Some backends do not support listing of databases. For example, the
+file backend synchronizes directories with one file per item and
+always needs an explicit `database` configuration because it cannot guess
+which directory it is meant to use.
 
    syncevolution <config>