Matthijs Kooijman recently started using SyncEvolution and took notes
about unclear explanations and missing information (--daemon!). This
useful feedback allowed to improve the documentation.
This patch adds an utility script (readme2c.pl) which extracts the
SYNOPSIS and OPTIONS part of README.rst and puts it into C
strings. These are then used inside the SyncEvolution command line for
short help (just the synopsis) and --help (also all options).
This patch also cleans up README.rst so that the OPTIONS part really
documents most options in sufficient detail for --help to be useful.
The USAGE section remains part of the README and the man page where
the different operations are introduced in a more task-oriented way.
This separation is not always easy to make. The --restore operation
and related parameters are only described in the USAGE part because I
couldn't find a way to introduce them briefly and then add a thorough
explanation under OPTIONS.
This complements --import/update/export/list-items. --remove was
already taken, for deleting a configuration.
Because the removal is done via the normal m_deleteItem operation, we
inherit the normal SyncML behavior (logging, no error return code for
non-existent items). It would have been nice to let the user choose
how to handle that situation (like --force in rm), but that can't be
done without SyncSource API changes.
These operations provide a common interface for manipulating
databases supported by SyncEvolution backends. --delete is
an obvious gap, will be added soon.
The implementation supports all backends offering the SyncSourceRaw
interface (Evolution, Akonadi, XMLRPC, file, but not the sqlite demo),
which is determined via a dynamic cast. SyncSourceRaw is necessary
because it allows direct access to the native data format without
going through the Synthesis engine.
Because the Synthesis engine is not activated, printing the short
description (SyncSourceLogging interface) mentioned in the README.rst
is not possible yet. Having such an engine would be useful also for
importing/exporting data which is not in the native format of the
backend; additional command line parameters will be needed to define
that format.
All of the new operations have in common that they work on one source
and multiple LUIDs. This is a slight deviation from other command line
synopsises where all arguments after the server config refer to sources.
The new m_accessItems flag is set for these special operations; they
also share much of the setup code.
The implementation itself tries to use the generic SyncSource
interface as much as possible. It only falls back to more specialized
implementations where necessary (SyncSourceRaw).
The builtin synopsis and usage was intentionally not updated. The
expection is that before this patch lands in the "master" branch, the
builtin text will come directly from README.rst (which was updated).
Reorganized the content so that it is more like a man reference page.
Known problems, setup, feature overview are meant to be maintained
at syncevolution.org.
Changed the format to reStructuredText (http://docutils.sourceforge.net/rst.html).
It can already be converted to man format (rst2man) and HTML for the
Drupal installation on syncevolution.org. Line breaks are problematic
when copying the HTML source because Drupal turns line breaks into <br/>.
The goal is that the README.rst is the authoritative copy of the
syncevolution.org "Usage" page and a "syncevolution/synccompare" man
page.
