g.message: explain -i/-v flags

           note python wrapper in the manual


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@51463 15284696-431f-4ddb-bdfa-cd5b030d7da7

general/g.message/g.message.html

@@ -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 @@ message at the given level.
 
 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 @@ is set using the <tt>--quiet</tt> or <tt>--verbose</tt> command line options.
 </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 @@ Recommended levels:
 
 <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>

general/g.message/main.c

@@ -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 @@ int main(int argc, char *argv[])
     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";