Hello! 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. Quoting http://bugs.meego.com/show_bug.cgi?id=690: 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 moment * 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: \--migrate 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: http://syncevolution.org/wiki/main-page The goal is to replace the "Usage" page (http://syncevolution.org/documentation/syncevolution-usage) 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/> (http://daringfireball.net/projects/markdown/syntax#p). 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.