[GRASS5] Draft GRASS 5.1 documentation available now

GRASS GRASS developer
1

Ciao Roberto and Radim,
GRASS developers,

the last days I have started to implement GRASS 5.1 documentation
using doxygen. It is pretty easy :slight_smile: 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

2

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 :slight_smile: 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@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass5

3

Markus Neteler wrote:

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 '('?

It's normally better to specify which characters *are* part of the
name rather than those which aren't. E.g.

  Vect_[a-zA-Z0-9_]*

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.

Try e.g.:

/^ *\\fn .*\(Vect_[a-zA-Z0-9_]*\).*$/s//\1/p

--
Glynn Clements <glynn.clements@virgin.net>

4

On Mon, Oct 21, 2002 at 09:39:44AM +0100, Glynn Clements wrote:

Markus Neteler wrote:

> 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 '('?

It's normally better to specify which characters *are* part of the
name rather than those which aren't. E.g.

  Vect_[a-zA-Z0-9_]*

that's of course better.

> 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.

Try e.g.:

/^ *\\fn .*\(Vect_[a-zA-Z0-9_]*\).*$/s//\1/p

Works perfectly. I have submitted to CVS.

Thanks,

Markus