[GRASS5] Migration of GRASS Prog. manual into source code (doxygen)

[Markus Neteler]

Hi developers,

a student of our group, Paolo Armani, was so kind
to write a PERL script for migrating the Latex 
code of the GRASS 5 Programmer's manual into doxygen
style. His script automatically

- changes Latex -> doxygen
  (using HTML tags, keeping Latex formula etc)
- searches the function in the GRASS libes directories
- inserts the modified doxygen description on top of
  each function into the related source code file(s).
- works recursively in src/libes/

Example:

------------- Latex source code -------------

\Gfunc{int}{G\_read\_history (char *name, char *mapset, struct History
  *history)}{read raster history file}{This routine reads the history file for
  the raster file \textbf{name} in \textbf{mapset} into the \textbf{history}
  structure.

  A diagnostic message is printed and -1 is returned if there is an error
  reading the history file. Otherwise, 0 is returned.}

------------- End Latex source code ---------

The PERL script renders above to:

------------- New doxygen code -------------

/*!
 * \brief read raster history file
 *
 * This routine reads the history file for
 * the raster file <b>name</b> in <b>mapset</b> into the <b>history</b>
 * structure.
 * A diagnostic message is printed and -1 is returned if there is an error
 * reading the history file. Otherwise, 0 is returned.
 *
 *  \param name
 *  \param mapset
 *  \param history
 *  \return int
 */

 int G_read_history (

------------- END New doxygen code ---------

If there are no objections, I would like to submit this to CVS.

TODO (will do, help welcome):
- polish the existing internal non-doxygen-style comments and
  merge with the new doxygen-style comments
- also migrate the other (relevant) general GRASS programmers Latex pages
  into file.dox files.

OUTCOME
We can render the entire programmer's manual from the
source code as GDAL and many other projects do. No more
efforts will be necessary to maintain a separate documents
which easily gets outdated. We are already following this idea in
GRASS 5.7.

Thanks to Paolo Armani from IRST for his magic PERL script!

Cheers

 Markus