make it easier to read (merge from devbr6)

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

lib/python/README.txt

@@ -1,3 +1,10 @@
+GRASS scripting tasks for Python provided by "grass.py".
+
+Usage: "import grass"
+
+
+
+
 def make_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **options):
 
 Return a list of strings suitable for use as the args parameter to
@@ -6,6 +13,9 @@ Popen() or call(). Example:
 >>> grass.make_command("g.message", flags = 'w', message = 'this is a warning')
 ['g.message', '-w', 'message=this is a warning']
 
+
+
+
 def start_command(prog, flags = "", overwrite = False, quiet = False, verbose = False, **kwargs):
 
 Returns a Popen object with the command created by make_command.
@@ -23,6 +33,9 @@ GRASS_DB_ENCODING='ascii';
 GRASS_GUI='text';
 MONITOR='x0';
 
+
+
+
 def pipe_command(*args, **kwargs):
 
 Passes all arguments to start_command, but also adds
@@ -39,17 +52,26 @@ GRASS_DB_ENCODING='ascii';
 GRASS_GUI='text';
 MONITOR='x0';
 
+
+
+
 def run_command(*args, **kwargs):
 
 Passes all arguments to start_command, then waits for the process to
 complete, returning its exit code. Similar to subprocess.call(), but
 with the make_command() interface.
 
+
+
+
 def read_command(*args, **kwargs):
 
 Passes all arguments to start_command, then waits for the process to
 complete, returning its stdout (i.e. similar to shell "backticks").
 
+
+
+
 def message(msg, flag = None):
 def debug(msg):
 def verbose(msg):
@@ -59,10 +81,16 @@ def error(msg):
 
 These all run g.message, differing only in which flag (if any) is used.
 
+
+
+
 def fatal(msg):
 
 Like error(), but also calls sys.exit(1).
 
+
+
+
 def parser():
 
 Interface to g.parser, intended to be run from the top-level, e.g.:
@@ -76,10 +104,16 @@ dictionaries containing option/flag values, keyed by lower-case
 option/flag names. The values in "options" are strings, those in
 "flags" are Python booleans.
 
+
+
+
 def tempfile():
 
 Returns the name of a temporary file, created with g.tempfile.
 
+
+
+
 def gisenv():
 
 Returns the output from running g.gisenv (with no arguments), as a
@@ -89,6 +123,9 @@ dictionary. Example:
 >>> print env['GISDBASE']
 /opt/grass-data
 
+
+
+
 def region():
 
 Returns the output from running "g.region -g", as a dictionary. 
@@ -100,16 +137,25 @@ Example:
 >>> (region['nsres'], region['ewres'])
 ('30', '30')
 
+
+
+
 def use_temp_region():
 
 Copies the current region to a temporary region with "g.region save=",
 then sets WIND_OVERRIDE to refer to that region. Installs an atexit
 handler to delete the temporary region upon termination.
 
+
+
+
 def del_temp_region():
 
 Unsets WIND_OVERRIDE and removes any region named by it.
 
+
+
+
 def find_file(name, element = 'cell'):
 
 Returns the output from running g.findfile as a dictionary. Example:
@@ -120,6 +166,9 @@ fields@PERMANENT
 >>> print result['file']
 /opt/grass-data/spearfish57/PERMANENT/vector/fields
 
+
+
+
 def list_grouped(type):
 
 Returns the output from running g.list, as a dictionary where the keys
@@ -129,6 +178,9 @@ Example:
 >>> grass.list_grouped('rast')['PERMANENT']
 ['aspect', 'erosion1', 'quads', 'soils', 'strm.dist', ...
 
+
+
+
 def list_pairs(type):
 
 Returns the output from running g.list, as a list of (map, mapset)
@@ -137,6 +189,9 @@ pairs. Example:
 >>> grass.list_pairs('rast')
 [('aspect', 'PERMANENT'), ('erosion1', 'PERMANENT'), ('quads', 'PERMANENT'), ...
 
+
+
+
 def list_strings(type):
 
 Returns the output from running g.list, as a list of qualified names. 
@@ -145,6 +200,9 @@ Example:
 >>> grass.list_strings('rast')
 ['aspect@PERMANENT', 'erosion1@PERMANENT', 'quads@PERMANENT', 'soils@PERMANENT', ...
 
+
+
+
 def parse_color(val, dflt = None):
 
 Parses the string "val" as a GRASS colour, which can be either one of