Everyone, I'm updating the documentation. Feedback please - I'm not
doing this for myself ;-)
Mike, I have a question about Drupal - see last paragraph.
Keeping separate chunks of documentation in sync is an ongoing effort. Perhaps
we can simplify that task by keeping a single set of source files and generate
all other documentation from it automatically.
The documentation that would be nice to have is:
* README: plain text, the file that is currently maintained in git
* man pages for syncevolution, synccompare, sync-ui: doesn't exist at the
* the "Usage" page on syncevolution.org
for the command line
As a first step (BMO#4633) the docs which have already diverged need to be
merged again. Then we need a single source format and corresponding make rules
which will generate the rest.
Today I look into this issue a bit more seriously. Originally, I
suggested Perl POD as that shared format, primarily because it is old
and typically installed on build systems.
But I never really liked the format. reStructuredText seems so much
nicer, so I did some more experiments with it and rst2man (in
python-docutils >= 0.6 (?)).
I was pleasantly surprised how easy it was to copy text from the README
into a README.rst. Very little changes were necessary to the markup. For
the most part, README.rst can still be read like a normal text, one of
the big strengths of rST. Question: should I strip the suffix when
preparing a release (install as README), replace with .txt (install as
README.txt) or leave it as it is?
The advantage of .rst is that Emacs and other tools (GNOME) recognize
the format. The disadvantage is that it might not always be recognized,
thus forcing to select a plain text reader.
The only part where markup is non-intuitive are some extra :: colons to
get the following text marked as a literal block and quoting a hyphen
where it was mistaken for something else:
In older SyncEvolution releases a different layout of configuration files
was used. ...
I find good enough to simply replace README with README.rst, without
doing any modifications to it.
The other change that I made is to reorganize the content so that it is
more like a reference man page. First, this minimizes the overlap with
instructions found elsewhere on syncevolution.org
. Second, it was an
incentive to document some aspects (environment variables!) which were
not documented before.
Attached is a copy. What do you think about these changes? Any spelling
mistakes, unclear statements, etc.?
The conversion to man format works fine. Because rst2man is not always
installed, the man page would be optional. I'm attaching the man page
(syncevolution.1) and a rendered output (without escape codes, use "man
-l syncevolution.1" in a terminal if you want bold and underlined text).
Conversion to HTML also works and the result can be copied almost
verbatim into Drupal with "Full HTML" as format:
The goal is to replace the "Usage" page
) with this
rendered man page.
"Copied almost verbatim" because that format differs from HTML in one
aspect: line breaks inside a paragraph are turned into a <br/>. I find
that inconvenient, because it also forces me to remove line breaks from
my announcement emails when I copy/paste them into Drupal. To me, it
also seems to deviate from normal Markdown syntax which normally uses
extra whitespace at the end of a line to insert <br/>
Mike, is this a Drupal-specific extension? Can it be turned off?
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.