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

[Axel Arnold]

Hi,

I vote for LaTeX.. Being Up-To-Date is not a question of medium, even a wiki 
can be fairly outdated, as Christoph already pointed out. And LaTeX is the 
format all physicists are used to.

Axel

-- 
JP Dr. Axel Arnold
ICP, Universität Stuttgart
Pfaffenwaldring 27
70569 Stuttgart, Germany
Email: address@hidden
Phone: +49 711 685 67609
----- Original message -----
> Hi everybody!
> 
> Besides the pure source code docs of ESPResSo, there are a number of
> other documentation pieces for ESPResSo that partly exist and partly
> should be written:
>     * How to use git for ESPResSo development
>     * Coding conventions for ES
>     * How to add files to ES
>     * Using and modifying the build system
>     * Programmer's Guide ("Under the hood")
> 
> However, at the moment I am not sure in what format and where to put
> this kind of documentation. So far, this kind of stuff was supposed to
> go into the "Developer's Guide" which was written in the Doxygen format
> and bundled with the source code documentation. However, I have the
> feeling that it was very hard to access the Developer's Guide and also
> to modify it, as Doxygen has a very strange format for additional
> information.
> 
> I can think of a number of options, but I do not know which one to use:
> 
> * Using doxygen (as it was so far)
>     * Pro: code documentation and developer's docs together
>     * Con: nasty doxygen format
>     * Con: confusing doxygen docs
>     * Con: hard to edit
>     * Con: not always up-to-date
> 
> * 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
> 
> * In an extra LaTeX-PDF-document, or as part of the UG
>     * Pro: comes with source code
>     * Pro: same format as UG
>     * Con: hard to edit
>     * Con: not always up-to-date
> 
> * Using GNU Savannah's documentation features ("Cookbook")
>     * https://savannah.nongnu.org/cookbook/?group=espressomd
>     * Pro: location where it would belong to "naturally"
>     * Con: yet another format format
>     * Con: confusing page
> 
> Does anyone of you have suggestions which one of these options to
> choose? Or does anyone have another idea?
> 
> I believe that I would prefer either the wiki or the LaTeX document, but
> I'm open for other ideas.
> 
> Olaf
> 
> -- 
> Dr. rer. nat. Olaf Lenz
> Institut für Computerphysik, Pfaffenwaldring 27, D-70569 Stuttgart
> Phone: +49-711-685-63607
<Attachment>   olenz.vcf