Re: [ESPResSo-devel] Developer's documentation format

[Christoph Junghans]

Am 03/14/2011 12:29 PM, schrieb Olaf Lenz:
> Hi!
>
> > > * In the ESPResSo-wiki on http://espressomd.org * Pro: easy to
> > > edit * Pro: always up-to-date * Con: only available when online *
> > > Con: yet another account, yet another format
> > I tend to disagree here, the old espresso wiki was always out of
> > sync and outdated. Also the workflow, change something in the code,
> > go to wiki and change it there again is quite inconvenient.
>
> I believe you may have misunderstood the intention of my mailing. I'm
> *not* talking about the documentation of the source code itself - that
> will most probably stay in doxygen. I am talking about the additional
> developer's docs, like the git primer etc.
True, but I like the all-in-one-repository-style even for developer's docs.
> > > I believe that I would prefer either the wiki or the LaTeX
> > > document, but I'm open for other ideas.
> > For votca we are using txt2tags (t2t) for some parts of the
> > documentation. The big advantage is that once you have written
> > something in t2t, you can convert it to html, mediawiki or latex.
> > That makes it easy to keep documentation in different places/formats
> > in sync. txt2tags is just one python script, no other dependencies.
> > However, yet another format ;-)
>
> Indeed, that would just be another format. I am not sure whether I agree
> that having a tools that can generate output in several formats makes it
> easy to sync documentation - you still need to sync it in the first place.
The idea is that, one can easily append parts of the dev documentation 
to the latex user guide and upload other/same parts to the wiki using 
Perl's MediaWikiBot and include other parts as extra html pages in doxygen.

Christoph

--
Dr. Christoph Junghans
Max Planck Institute for Polymer Research
Theory Group
POBox 3148
D 55021 Mainz, Germany

Phone: +49 6131 379 335
Web: http://www.mpip-mainz.mpg.de/~junghans