maryjane
/
syncevolution
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

documentation + command line: unified source of usage information (MBC #690) 

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 commit is contained in:
Patrick Ohly 2010-06-30 17:36:54 +02:00
parent 99c9919b44
commit b7ef83d6ed
6 changed files with 3405 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
README.rst
View File

@ -199,13 +199,7 @@ These commands print information about existing configurations. When
printing a configuration a short version without comments can be
selected with --quiet. When sources are listed, only their
configuration is shown. `Main` instead or in combination with sources
lists only the main peer configuration.
With --print-session 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 --restore) and the synchronization report. In combination
with --quiet, only the paths are listed. ::
lists only the main peer configuration. ::
syncevolution --restore <session directory> --before|--after
[--dry-run] <config> <source> ...
@ -250,41 +244,6 @@ give via "--source-property type=<backend>", like this::
The desired backend database can be chosen via "--source-property
evolutionsource".
--print-items shows all existing items using one line per item using
the format "<luid>[: <short description>]". Whether the description
is available depends on the backend and the kind of data that it
stores.
--export writes all items in the source or all items whose <luid> is
given into a directory if the --export parameter exists and is a
directory. The <luid> of each item is used as file name. Otherwise it
creates a new file under that name and writes the selected items
separated by the chosen delimiter string. stdout can be selected with
a dash.
The default delimiter are two newline characters for a blank line. This
works for vCard 3.0 and iCalendar 2.0, which never contain blank lines.
Because items may or may not end in a newline, as a special case the
initial newline of a delimiter is skipped if the item ends in a newline.
--import adds all items found in the directory or input file to the
source. When reading from a directory, each file is treated as one
item. Otherwise the input is split at the chosen delimiter. "none" as
delimiter disables splitting of the input.
--update overwrites the content of existing items. When updating from
a directory, the name of each file is taken as its luid. When updating
from file or stdin, the number of luids given on the command line
must match with the number of items in the input.
--delete-items removes the specified items from the source. Most
backends print some progress information about this, but besides that,
no further output is produced. Trying to remove an item which does not
exist typically leads to an ERROR message, but is not reflected in a
non-zero result of the command line invocation itself because the
situation is not reported as an error by backends (removal of
non-existent items is not an error in SyncML).
OPTIONS
=======
@ -302,7 +261,7 @@ a list of valid values.
Prints the names of all configured peers to stdout. There is no
difference between these options, the are just aliases.
--print-config|-p
--print-servers|--print-configs|--print-peers|-p
Prints the complete configuration for the selected <config>
to stdout, including up-to-date comments for all properties. The
format is the normal .ini format with source configurations in
@ -315,6 +274,13 @@ a list of valid values.
When setting a --template, then the reference configuration for
that peer is printed instead of an existing configuration.
\--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
--restore) and the synchronization report. In combination with
--quiet, only the paths are listed.
--configure|-c
Modify the configuration files for the selected peer. If no such
configuration exists, then a new one is created using one of the
@ -339,22 +305,62 @@ a list of valid values.
layout and rename the <config> into <config>.old to prevent accidental use
of the old configuration. WARNING: old SyncEvolution releases cannot
use the new configuration!
The switch can also be used to migrate a configuration in the current
configuration directory: this preserves all property values, discards
obsolete properties and sets all comments exactly as if the configuration
had been created from scratch. WARNING: custom comments in the
configuration are not preserved.
--migrate implies --configure and can be combined with modifying
properties.
\--print-items
Shows all existing items using one line per item using
the format "<luid>[: <short description>]". Whether the description
is available depends on the backend and the kind of data that it
stores.
\--export
Writes all items in the source or all items whose <luid> is
given into a directory if the --export parameter exists and is a
directory. The <luid> of each item is used as file name. Otherwise it
creates a new file under that name and writes the selected items
separated by the chosen delimiter string. stdout can be selected with
a dash.
The default delimiter are two newline characters for a blank line. This
works for vCard 3.0 and iCalendar 2.0, which never contain blank lines.
Because items may or may not end in a newline, as a special case the
initial newline of a delimiter is skipped if the item ends in a newline.
\--import
Adds all items found in the directory or input file to the
source. When reading from a directory, each file is treated as one
item. Otherwise the input is split at the chosen delimiter. "none" as
delimiter disables splitting of the input.
\--update
Overwrites the content of existing items. When updating from a
directory, the name of each file is taken as its luid. When updating
from file or stdin, the number of luids given on the command line
must match with the number of items in the input.
\--delete-items
Removes the specified items from the source. Most backends print
some progress information about this, but besides that, no further
output is produced. Trying to remove an item which does not exist
typically leads to an ERROR message, but is not reflected in a
non-zero result of the command line invocation itself because the
situation is not reported as an error by backends (removal of
non-existent items is not an error in SyncML).
--sync-property|-y <property>=<value>|<property>=?|?
Overrides a source-independent configuration property for the
current synchronization run or permanently when --configure is used
to update the configuration. Can be used multiple times. Specifying
an unused property will trigger an error message.
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
@ -383,11 +389,11 @@ a list of valid values.
than the peer. `default` is an alias for `scheduleworld` and can be
used as the starting point for servers which do not have a built-in
template.
Each template contains a pseudo-random device ID. Therefore setting the
`deviceId` sync property is only necessary when manually recreating a
configuration or when a more descriptive name is desired.
The available templates for different known SyncML servers are listed when
using a single question mark instead of template name. When using the
`?<device>` format, a fuzzy search for a template that might be
@ -412,9 +418,9 @@ a list of valid values.
applies to *all* passwords in a configuration, so setting a single
password as follows moves the other passwords into the keyring, if
they were not stored there already::
--keyring --configure --sync-property proxyPassword=foo
When passwords were stored in the keyring, their value is set to a single
hyphen ("-") in the configuration. This means that when running a
synchronization without the --keyring argument, the password has to be
@ -427,7 +433,6 @@ a list of valid values.
\--version
Prints the SyncEvolution version.
EXAMPLES
========

171
src/syncevo/Cmdline.cpp
View File

@ -48,6 +48,9 @@ using namespace std;
#include <syncevo/declarations.h>
SE_BEGIN_CXX
// synopsis and options char strings
#include "CmdlineHelp.c"
Cmdline::Cmdline(int argc, const char * const * argv, ostream &out, ostream &err) :
m_argc(argc),
m_argv(argv),
@ -1391,175 +1394,11 @@ void Cmdline::usage(bool full, const string &error, const string &param)
{
ostream &out(error.empty() ? m_out : m_err);
out << "Show available sources:" << endl;
out << " " << m_argv[0] << endl;
out << "Show information about configuration(s) and sync sessions:" << endl;
out << " " << m_argv[0] << " --print-servers|--print-configs|--print-peers" << endl;
out << " " << m_argv[0] << " --print-config [--quiet] <config> [main|<source ...]" << endl;
out << " " << m_argv[0] << " --print-sessions [--quiet] <config>" << endl;
out << "Show information about SyncEvolution:" << endl;
out << " " << m_argv[0] << " --help|-h" << endl;
out << " " << m_argv[0] << " --version" << endl;
out << "Run a synchronization:" << endl;
out << " " << m_argv[0] << " <config> [<source> ...]" << endl;
out << " " << m_argv[0] << " --run <options for run> <config> [<source> ...]" << endl;
out << "Restore data from the automatic backups:" << endl;
out << " " << m_argv[0] << " --restore <session directory> --before|--after [--dry-run] <config> <source> ..." << endl;
out << "Remove a configuration:" << endl;
out << " " << m_argv[0] << " --remove <config>" << endl;
out << "Modify configuration:" << endl;
out << " " << m_argv[0] << " --configure <options for configuration> <config> [<source> ...]" << endl;
out << " " << m_argv[0] << " --migrate <config>" << endl;
out << synopsis;
if (full) {
out << endl <<
"Options:" << endl <<
"--sync|-s <mode>" << endl <<
"--sync|-s ?" << endl <<
" Temporarily synchronize the active sources in that mode. Useful" << endl <<
" for a \"refresh-from-server\" or \"refresh-from-client\" sync which" << endl <<
" clears all data at one end and copies all items from the other." << endl <<
"" << endl <<
"--print-servers|--print-configs|--print-peers" << endl <<
" Prints the names of all configured peers to stdout." << endl <<
"" << endl <<
"--print-config|-p" << endl <<
" Prints the complete configuration for the selected peer" << endl <<
" to stdout, including up-to-date comments for all properties. The" << endl <<
" format is the normal .ini format with source configurations in" << endl <<
" different sections introduced with [<source>] lines. Can be combined" << endl <<
" with --sync-property and --source-property to modify the configuration" << endl <<
" on-the-fly. When one or more sources are listed after the <config>" << endl <<
" name on the command line, then only the configs of those sources are" << endl <<
" printed. Using --quiet suppresses the comments for each property." << endl <<
" When setting a --template, then the reference configuration for" << endl <<
" that peer is printed instead of an existing configuration." << endl <<
"" << endl <<
"--print-sessions" << endl <<
" Prints a list of all previous log directories. Unless --quiet is used, each" << endl <<
" file name is followed by the original sync report." << endl <<
"" << endl <<
"--configure|-c" << endl <<
" Modify the configuration files for the selected peer. If no such" << endl <<
" configuration exists, then a new one is created using one of the" << endl <<
" template configurations (see --template option). When creating" << endl <<
" a new configuration only the active sources will be set to active" << endl <<
" in the new configuration, i.e. \"syncevolution -c scheduleworld addressbook\"" << endl <<
" followed by \"syncevolution scheduleworld\" will only synchronize the" << endl <<
" address book. The other sources are created in a disabled state." << endl <<
" When modifying an existing configuration and sources are specified," << endl <<
" then the source properties of only those sources are modified." << endl <<
"" << endl <<
"--migrate" << endl <<
" In older SyncEvolution releases a different layout of configuration files" << endl <<
" was used. Using --migrate will automatically migrate to the new" << endl <<
" layout and rename the <config> into <config>.old to prevent accidental use" << endl <<
" of the old configuration. WARNING: old SyncEvolution releases cannot" << endl <<
" use the new configuration!" << endl <<
"" << endl <<
" The switch can also be used to migrate a configuration in the current" << endl <<
" configuration directory: this preserves all property values, discards" << endl <<
" obsolete properties and sets all comments exactly as if the configuration" << endl <<
" had been created from scratch. WARNING: custom comments in the" << endl <<
" configuration are not preserved." << endl <<
"" << endl <<
"--restore" << endl <<
" Restores the data of the selected sources to the state from before or after the" << endl <<
" selected synchronization. The synchronization is selected via its log directory" << endl <<
" (see --print-sessions). Other directories can also be given as long as" << endl <<
" they contain database dumps in the format created by SyncEvolution." << endl <<
" The output includes information about the changes made during the" << endl <<
" restore, both in terms of item changes and content changes (which is" << endl <<
" not always the same, see manual for details). This output can be suppressed" << endl <<
" with --quiet." << endl <<
" In combination with --dry-run, the changes to local data are only simulated." << endl <<
" This can be used to check that --restore will not remove valuable information." << endl <<
"" << endl <<
"--remove" << endl <<
" Deletes the configuration. If the <config> refers to a specific" << endl <<
" peer, only that peer's configuration is removed. If it refers to" << endl <<
" a context, that context and all peers inside it are removed." << endl <<
" Note that there is no confirmation question. Neither local data" << endl <<
" referenced by the configuration nor the content of log dirs are" << endl <<
" deleted." << endl <<
"" << endl <<
"--sync-property|-y <property>=<value>" << endl <<
"--sync-property|-y ?" << endl <<
"--sync-property|-y <property>=?" << endl <<
" Overrides a source-independent configuration property for the" << endl <<
" current synchronization run or permanently when --configure is used" << endl <<
" to update the configuration. Can be used multiple times. Specifying" << endl <<
" an unused property will trigger an error message." << endl <<
"" << endl <<
" When using the configuration layout introduced with 1.0, some of the" << endl <<
" sync properties are shared between peers, for example the directory" << endl <<
" where sessions are logged. Permanently changing such a shared" << endl <<
" property for one peer will automatically update the property for all" << endl <<
" other peers in the same context because the property is stored in a" << endl <<
" shared config file." << endl <<
"" << endl <<
"--source-property|-z <property>=<value>" << endl <<
"--source-property|-z ?" << endl <<
"--source-property|-z <property>=?" << endl <<
" Same as --sync-property, but applies to the configuration of all active" << endl <<
" sources. \"--sync <mode>\" is a shortcut for \"--source-property sync=<mode>\"." << endl <<
"" << endl <<
"--template|-l <peer name>|default|?|?<device>" << endl <<
" Can be used to select from one of the built-in default configurations" << endl <<
" for known SyncML peers. Defaults to the <config> name, so --template" << endl <<
" only has to be specified when creating multiple different configurations" << endl <<
" for the same peer, or when using a template that is named differently" << endl <<
" than the peer. \"default\" is an alias for \"scheduleworld\" and can be" << endl <<
" used as the starting point for servers which do not have a built-in" << endl <<
" template." << endl <<
"" << endl <<
" Each template contains a pseudo-random device ID. Therefore setting the" << endl <<
" \"deviceId\" sync property is only necessary when manually recreating a" << endl <<
" configuration or when a more descriptive name is desired." << endl <<
"" << endl <<
" The available templates for different known SyncML servers are listed when" << endl <<
" using a single question mark instead of template name. When using the" << endl <<
" ?<device> format, a fuzzy search for a template that might be" << endl <<
" suitable for talking to such a device is done. The matching works best" << endl <<
" when using <device> = <Manufacturer>_<Model>. If you don't know the" << endl <<
" manufacturer, you can just keep it as empty. The output in this mode" << endl <<
" gives the template name followed by a short description and a rating how well" << endl <<
" the template matches the device (higher is better)." << endl <<
"" << endl <<
"--status|-t" << endl <<
" The changes made to local data since the last synchronization are" << endl <<
" shown without starting a new one. This can be used to see in advance" << endl <<
" whether the local data needs to be synchronized with the peer." << endl <<
"" << endl <<
" When used without configuration name, it shows the status of the background" << endl <<
" sync daemon or an error if no such daemon exists." << endl <<
"" << endl <<
"--quiet|-q" << endl <<
" Suppresses most of the normal output during a synchronization. The" << endl <<
" log file still contains all the information." << endl <<
"" << endl <<
"--keyring|-k[=yes/no/...]" << endl <<
" Save or retrieve passwords from the GNOME keyring when modifying the" << endl <<
" configuration or running a synchronization. Note that using this option" << endl <<
" applies to *all* passwords in a configuration, so setting a single" << endl <<
" password as follows moves the other passwords into the keyring, if" << endl <<
" they were not stored there already:" << endl <<
" --keyring --configure --sync-property proxyPassword=foo" << endl <<
"" << endl <<
" When passwords were stored in the keyring, their value is set to '-'" << endl <<
" in the configuration. This means that when running a synchronization" << endl <<
" without the --keyring argument, the password has to be entered" << endl <<
" interactively. The --print-config output always shows '-' instead of" << endl <<
" retrieving the password from the keyring." << endl <<
"" << endl <<
"--daemon[=yes/no/...]" << endl <<
" Run operations in cooperation with the background sync daemon;" << endl <<
" enabled by default if it is installed." << endl <<
"" << endl <<
"--help|-h" << endl <<
" Prints usage information." << endl <<
"" << endl <<
"--version" << endl <<
" Prints the SyncEvolution version." << endl;
options;
}
if (error != "") {

3277
src/syncevo/Cmdline.cpp.orig Normal file
View File

File diff suppressed because it is too large Load Diff

17
src/syncevo/Cmdline.cpp.rej Normal file
View File

@ -0,0 +1,17 @@
*************** bool Cmdline::run() {
*** 832,838 ****
}
if (total != m_luids.size()) {
SyncContext::throwError(StringPrintf("%lu items != %lu luids, must match => aborting"
- total, m_luids.size()));
}
}
list<string>::const_iterator luidit = m_luids.begin();
--- 832,838 ----
}
if (total != m_luids.size()) {
SyncContext::throwError(StringPrintf("%lu items != %lu luids, must match => aborting"
+ (unsigned long)total, (unsigned long) m_luids.size()));
}
}
list<string>::const_iterator luidit = m_luids.begin();

8
src/syncevo/Makefile.am
View File

@ -1,6 +1,7 @@
AM_CPPFLAGS = @BACKEND_CPPFLAGS@ @GLIB_CFLAGS@ -I$(top_srcdir)/test -I$(top_srcdir)/src -DSYNCEVO_BACKEND=\"$(backendsearchdir)\"
SUBDIRS = configs
BUILT_SOURCES =
# applies to sources in SyncEvolution repository, but not
# the Funambol C++ client library
@ -173,6 +174,13 @@ GenSyncEvolutionXML:
echo ";" >>SyncEvolutionXML.c.new
if cmp SyncEvolutionXML.c SyncEvolutionXML.c.new >/dev/null; then rm SyncEvolutionXML.c.new; else mv SyncEvolutionXML.c.new SyncEvolutionXML.c; fi
# turn README.rst into a file with plain text strings for
# "Synopsis" and "Usage"
CLEANFILES += CmdlineHelp.c
BUILT_SOURCES += CmdlineHelp.c
EXTRA_DIST += readme2c.pl
CmdlineHelp.c: readme2c.pl $(top_srcdir)/README.rst
perl $+ >$@
# include boost in distribution
#dist-hook:

42
src/syncevo/readme2c.pl Normal file
View File

@ -0,0 +1,42 @@
#!/usr/bin/perl
#
# Turn reStructuredText README.rst into C file with
# static const char *synopsis, *options;
$_ = join("", <>);
# trailing :: is only needed for reST
s/ :://g;
# simplify colon
s/::/:/g;
# avoid special \-- which was necessary for some options
s/^\\--/--/gm;
# extract parts
/SYNOPSIS\n===+\n\n(.*?)\nDESCRIPTION/s || die "no synopsis";
my $synopsis = $1;
/OPTIONS\n===+\n\n.*?(^--.*?)\nEXAMPLES/ms || die "no options";
my $options = $1;
# condense synopsis
$synopsis =~ s/\n\n/\n/g;
sub text2c {
my $text = shift;
foreach $_ (split ('\n', $text)) {
s/\\/\\\\/g;
s/"/\\"/g;
print " \"", $_, "\\n\"\n";
}
}
# now print as C code
print "static const char synopsis[] =\n";
text2c($synopsis);
print ";\nstatic const char options[] =\n";
text2c($options);
print ";\n";