[GRASS5] Draft GRASS 5.1 documentation available now

[Markus Neteler]

Ciao Roberto and Radim,
GRASS developers,

the last days I have started to implement GRASS 5.1 documentation
using doxygen. It is pretty easy :-) And we can generate
- HTML,
- Latex,
- PDF
(- XML, RTF etc)

from the GRASS source. Basic idea is to add some commands into the
source code which are then interpreted by 'doxygen'. An example:

-------------------------------------------------------
/*!
 \fn int db_fetch (dbCursor *cursor, int position, int *more)
 \brief fetches something from somewhere
 \return 0 on success, -1 on error
 \param dbCursor, position in table, somethingelse
*/
int
db_fetch (dbCursor *cursor, int position, int *more)
{
  C code of function;
}
-------------------------------------------------------
(note the exclamation mark above which is needed)

See for real world examples:
 grass51/lib/vector/Vlib/* 
 grass51/lib/db/dbmi/*    [only placeholders added]

Overview pages can be easily written, see for example:
 grass51/lib/vector/vector_arch.dox
which is now the "GRASS 5.1 Architecture" start page.

The major advantages are
 - documenting in the source code (keeps things in sync)
 - no extra programmer's manual to write and update
 - possibility to auto-generate PDF manual by cronjob
 - doxygen is a maintained project (http://www.doxygen.org)

To try GRASS-51-doc generation at home, enter (after updating from CVS):
 cd grass51/lib/vector/

Now following commands are available:
 
- Generate HTML document:
        make htmldocs
 
- Generate Latex-DVI document (requires Latex):
        make latexdocs
 
- Generate PDF document (requires Latex):
        make pdfdocs
 
- Delete ./latex and ./html docs directories:
        make cleandocs


Let me kindly invite everybody to use and extend the GRASS documentation.
Roberto, you may also use it for DGLib...

For advanced tricks (Latex formula etc) see the doxygen site.

A today's PDF version is here:
http://mpa.itc.it/markus/tmp/grass51_2002_10_18refman.pdf
(520kb, please don't print as it will change)

A today's HTML version is here:
http://mpa.itc.it/markus/tmp/html/

Of course everything can be nicer, but it is a starting point.

Cheers

 Markus