[GRASS-SVN] r51463 - grass/trunk/general/g.message
svn_grass at osgeo.org
svn_grass at osgeo.org
Tue Apr 17 16:15:12 EDT 2012
Author: martinl
Date: 2012-04-17 13:15:12 -0700 (Tue, 17 Apr 2012)
New Revision: 51463
Modified:
grass/trunk/general/g.message/g.message.html
grass/trunk/general/g.message/main.c
Log:
g.message: explain -i/-v flags
note python wrapper in the manual
Modified: grass/trunk/general/g.message/g.message.html
===================================================================
--- grass/trunk/general/g.message/g.message.html 2012-04-17 18:37:59 UTC (rev 51462)
+++ grass/trunk/general/g.message/g.message.html 2012-04-17 20:15:12 UTC (rev 51463)
@@ -1,12 +1,13 @@
<h2>DESCRIPTION</h2>
-<p>This program is to be used in shell/perl/python scripts, so the author does not
+<p>This program is to be used in Shell/Perl/Python scripts, so the author does not
need to use the <tt>echo</tt> program. The advantage of <em>g.message</em> is
that it formats messages just like other GRASS modules do and that its
functionality is influenced by the <tt>GRASS_VERBOSE</tt> and
<tt>GRASS_MESSAGE_FORMAT</tt> environment variables.
-<p>The program can be used for standard informative messages as well as warnings
+<p>
+The program can be used for standard informative messages as well as warnings
(<b>-w</b> flag) and fatal errors (<b>-e</b> flag). For debugging
purposes, the <b>-d</b> flag will cause <em>g.message</em> to print a debugging
message at the given level.
@@ -16,28 +17,66 @@
Messages containing "<tt>=</tt>" must use the full <b>message=</b> syntax so
the parser doesn't get confused.
-<p>If you want a long message (multi-line) to be dealt with as a single
+<p>
+If you want a long message (multi-line) to be dealt with as a single
paragraph, use a single call to <em>g.message</em> with text split in the
script using the backslash as the last character. (In shell scripts don't
close the "quote")
-<p>A blank line may be obtained with: <tt>g.message ""</tt>
-<p>Redundant whitespace will be stripped away.
-<p>It's advisable to single quote the messages that are to be printed literally.
+<p>
+A blank line may be obtained with
+<div class="code"><pre>
+g.message message=""
+</pre></div>
+<p>
+Redundant whitespace will be stripped away.
+<p>
+It's advisable to single quote the messages that are to be printed literally.
It prevents a number of characters (most notably, space and the dollar sign
-'<tt>$</tt>') from being treated specifically by the Shell.
-<p>When it is necessary to include, for example, a variable's value as part of
+'<tt>$</tt>') from being treated specifically by the shell.
+<p>
+When it is necessary to include, for example, a variable's value as part of
the message, the double quotes may be used, which do not deprive the
dollar sign of its special variable-expansion powers.
-<p>While it is known that the interactive Bash instances may treat the
+<p>
+While it is known that the interactive Bash instances may treat the
exclamation mark '<tt>!</tt>' character specifically (making single quoting
of it necessary), it shouldn't be the case for the non-interactive
instances of Bash. None the less, to avoid context-based confusion later on
you are enouraged to single-quote messages that do not require
<tt>$VARIABLE</tt> expansion.
-<p>
+
+<h3>Usage in Python scripts</h3>
+
+<a href="http://grass.osgeo.org/programming7/pythonlib.html">GRASS
+Python Scripting Library</a> defines special wrappers
+for <em>g.message</em>.
+
+<ul>
+ <li><tt>debug()</tt> for <tt>g.message -d</tt>
+ <li><tt>error()</tt> for <tt>g.message -e</tt>
+ <li><tt>fatal()</tt> for <tt>g.message -e</tt> + <tt>exit()</tt>
+ <li><tt>info()</tt> for <tt>g.message -i</tt>
+ <li><tt>message()</tt> for <tt>g.message</tt>
+ <li><tt>verbose()</tt> for <tt>g.message -v</tt>
+ <li><tt>warning()</tt> for <tt>g.message -w</tt>
+</ul>
+
+Eg.
+
+<div class="code"><pre>
+import grass.script as grass
+grass.warning("This is a warning")
+</pre></div>
+
+is identical with
+
+<div class="code"><pre>
+g.message -w message="This is a warning"
+</pre></div>
+
<h3>VERBOSITY LEVELS</h3>
Controlled by the "<tt>GRASS_VERBOSE</tt>" environment variable. Typically this
-is set using the <tt>--quiet</tt> or <tt>--verbose</tt> command line options.
+is set using the <b>--quiet</b> or <b>--verbose</b> command line options.
<ul>
<li>0 - only errors and warnings are printed
<li>1 - progress messages are printed
@@ -46,8 +85,8 @@
</ul>
<h3>DEBUG LEVELS</h3>
-Controlled by the "<tt>DEBUG</tt>" GRASS <i>gisenv</i> variable. (set with
-<em><a href="g.gisenv.html">g.gisenv</a></em>)
+Controlled by the "<tt>DEBUG</tt>" GRASS <i>gisenv</i> variable (set with
+<em><a href="g.gisenv.html">g.gisenv</a></em>).
<br>
Recommended levels:
<ul>
@@ -58,14 +97,14 @@
<h2>SEE ALSO</h2>
<em>
-<a href="variables.html">GRASS variables and environment variables</a>,<br>
+<a href="variables.html">GRASS variables and environment variables</a><br>
<a href="g.gisenv.html">g.gisenv</a>,
<a href="g.parser.html">g.parser</a>
</em>
-
<h2>AUTHOR</h2>
Jachym Cepicky
-<p><i>Last changed: $Date$</i>
+<p>
+<i>Last changed: $Date$</i>
Modified: grass/trunk/general/g.message/main.c
===================================================================
--- grass/trunk/general/g.message/main.c 2012-04-17 18:37:59 UTC (rev 51462)
+++ grass/trunk/general/g.message/main.c 2012-04-17 20:15:12 UTC (rev 51463)
@@ -8,7 +8,7 @@
* PURPOSE: Provides a means of reporting the contents of GRASS
* projection information files and creating
* new projection information files.
- * COPYRIGHT: (C) 2007,2010 by the GRASS Development Team
+ * COPYRIGHT: (C) 2007,2010,2012 by the GRASS Development Team
*
* This program is free software under the GNU General Public
* License (>=v2). Read the file COPYING that comes with GRASS
@@ -60,19 +60,22 @@
important = G_define_flag();
important->key = 'i';
important->guisection = _("Level");
- important->description = _("Print message in all but full quiet mode");
-
+ important->label = _("Print message in all modes except of quiet mode");
+ important->description = _("Message is printed on GRASS_VERBOSE>=1");
+
verbose = G_define_flag();
verbose->key = 'v';
verbose->guisection = _("Level");
- verbose->description = _("Print message only in verbose mode");
+ verbose->label = _("Print message only in verbose mode");
+ verbose->description = _("Message is printed only on GRASS_VERBOSE>=3");
message = G_define_option();
message->key = "message";
message->type = TYPE_STRING;
message->key_desc = "string";
message->required = YES;
- message->description = _("Text of the message to be printed");
+ message->label = _("Text of the message to be printed");
+ message->description = _("Message is printed on GRASS_VERBOSE>=2");
debug_opt = G_define_option();
debug_opt->key = "debug";
More information about the grass-commit
mailing list