[GRASS5] Draft GRASS 5.1 documentation available now

[Markus Neteler]

Hi,

an updated version of the draft GRASS 5.1 programmer's manual
is available now here:

 http://mpa.itc.it/markus/grass51/index.html

A new "modules" section is added which organizes the
Vect_*() functions by topic (open functions, close functions,
network functions etc).

To improve the function detection, I need some regex assistance for
'sed' (compare
grass51/lib/vector/Vlib/generate_dox.sh
). In general I grep all '\\fn' from all *.c files, then I want
to extract the function names:
So, how can I extract words starting with 'Vect_' and ending with either
space or '('? The current solution in above script is not error free.
Examples:

 \fn int Vect_tin_get_z( struct Map_info *Map
    -> Vect_tin_get_z
or
 \fn struct line_cats *Vect_new_cats_struct ()
    -> Vect_new_cats_struct

etc. Unfortunately I don't know REGEX enough to write a 'sed' instruction.

Thanks,

 Markus

On Fri, Oct 18, 2002 at 07:23:27PM +0200, Markus Neteler wrote:
> 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
> 
> _______________________________________________
> grass5 mailing list
> grass5 at grass.itc.it
> http://grass.itc.it/mailman/listinfo/grass5