[LORENE] New documentation using doxygen

[Jerome Novak]

Dear LOREN-ers,

I have just comitted new versions of header files that can be used with
the documenting program doxygen (it comes with many Linux distributions,
see www.doxygen.org, for details about installation, etc...).

LORENE documentation is therefore now done using this program and doc++
should not work any more. :-(

The two main reasons for this change were:
_ we can have access to the source code (.C files) within the
documentation, which helps a lot,
_ doc++ does not seem to be a maintained project ...

To change the doc on your local machine, install doxygen, erase the
$HOME_LORENE/Doc/refguide directory, and type 'lorene_up'. The reference
manual is still at $HOME_LORENE/Doc/refguide/index.html

The changes in the LORENE web page (www.lorene.obspm.fr) should occur
during next night, so if you click now on the reference manual there, it
should be the same as before, made by doc++. Please, note that I did not
have the patience to change _all_ the comments of LORENE so that they be
compatible with doxygen. There are a few points where the documentation
does not look nice at all: General ellptic solvers, Time evolutions and
binary objects... If I find time one day I may change this, but please
feel free to do it, if you need this documentation.

doxygen has been built starting from doc++, so the spirit is roughly the
same. I give you some of the changes, but the best is to have a look at
the doxygen documentation that comes with
it: /usr/shar/doc/doxygen-1.2.14/html/index.html ). As you see, I have
used the 1.2.14 version of doxygen, but you could in principle use any
newer version.

_ replace '$' with '\f$' and \begin(\end){equation} with \f[ (\f])
_ no more need to write \_ to have an underscore, just type '_' (except
in formulas!)
_  to have lists, use \li (begins a new line and puts a bullet)
_ if you put comments at the end of a line, start with a '///<'
_ {\sl hello}, {\bf hello}, {\it hello} and {\tt hello} are replaced
with \a hello , \b hello , \e hello , \c hello ; respectively. Please
note, that (if I have understood well) the delimiter is the whitespace
(and no longer the braces {}  ). BUT if you want to use these styles
within formulas, keep the old way of doing.

Warnings issued by doxygen are kept in a file
$HOME_LORENE/Doc/doxy_warn.log.

Anyway, you can also have a look on what is written in the include files
I have modified and in $HOME_LORENE/Doc/lorene.C for how to make
compounds. Do not hesitate to correct any mistake you find there or to
send me a hint on how to use doxygen...

Now some problems I had:
_ a minus sign at the beginning of a comment is ignored... (I have put
'\c -' );
_ some formulas are concatenated in a strange way: doxygen suppresses
some white spaces, causing latex to crash... (maybe fixed in some later
version?);
_ a '///<' comment at the end of a line is ignored if this line contains
the inline definition of a function (I have put these comments before
the inlined function).

Please, consider now writing any documentation with the doxygen style
and accept our apologies if this gives you too much trouble.

Bon code,


--
Jerome Novak
Laboratoire de l'Univers et de ses THeories (LUTH)
Observatoire de Meudon       92195 Meudon FRANCE
tel: (33) 01 45 07 75 82     fax: (33) 01 45 07 79 71