[GRASS-dev] r.flow and G_message

[Glynn Clements]

Jachym Cepicky wrote:

> i do not know, how to solve fprints in r.flow. 
> 
> The module use it's own function to print messages (diag) 
> 
> When i removed this function and rewrite everything with help of
> G_message, the result is not well-arranged:
> 
> r.flow elevin=elevation.dem aspin=aspect barin=roads flout=tmp1
> lgout=tmp2 dsout=tmp3 --o
> Opening output files...
> WARNING: The vector 'tmp1' already exists and will be overwritten.
> Done
> Allocating memory: elevation
> aspect
> barrier
> density
> flowline header
> e/w distances
> quantization tolerances
> Reading input files: elevation...
> aspect
> barrier

[snip]

> What to do? Should I remove all informations about reading, precomputing
> and  allocating for each raster map? I suggest, that the most verbose
> output could look like this:

In cases where the module currently outputs multiple distinct messages
on a single line, I would add the prefix to each call, so in the above
case you would get:

Allocating memory: elevation
Allocating memory: aspect
Allocating memory: barrier
Allocating memory: density
Allocating memory: flowline header
Allocating memory: e/w distances
Allocating memory: quantization tolerances
Reading input files: elevation
Reading input files: aspect
Reading input files: barrier

etc.

In this case, the "Allocating memory" messages should probably be
G_debug() rather than G_message(). The "Reading input files" messages
are more useful (and correspond to tasks which will typically take
longer), and so should use G_message().

[On that topic, I would suggest merging verbose/debug levels so that
higher settings of GRASS_VERBOSE enable debugging information, rather
than having a separate variable.]

Also, I would suggest an additional verbosity level between "message"
and "debug" which would be used for messages which are relatively
unimportant, yet still meant for users rather than developers, with
"debug" being reserved for information which is only useful for, well,
debugging.

FWIW, the Unix syslog mechanism has levels named emerg, alert, crit,
err, warning, notice, info, and debug. We don't distinguish between
different severities of error (all errors are fatal), so emerg, alert
and crit aren't particularly relevant, but the others roughly
correspond to:

	err		G_fatal_error
	warning		G_warning
	notice/info	G_message
	debug		G_debug

I suggest keeping G_message() for more useful messages ("notice")) and
adding a new G_{verbose,info,detail,<whatever>} function for the less
useful user-level messages ("info") generated by more verbose modules
such as r.flow.

Also, it may be worth making a distinction between progress
indications and other messages. Non-interactive environments (e.g. CGI
applications or cron jobs) don't really have any use for progress
information, even if you want a relatively high level of verbosity in
other regards (e.g. lots of information about the data being processed
and the results).

-- 
Glynn Clements <glynn at gclements.plus.com>