[GRASS-SVN] r39388 - grass/branches/releasebranch_6_4/lib/gis

[svn_grass at osgeo.org]

Author: martinl
Date: 2009-10-03 02:57:26 -0400 (Sat, 03 Oct 2009)
New Revision: 39388

Modified:
   grass/branches/releasebranch_6_4/lib/gis/gislib.dox
Log:
gisprompt docs updated based on Glynn's notes in ML
         (merge r39386 from trunk)


Modified: grass/branches/releasebranch_6_4/lib/gis/gislib.dox
===================================================================
--- grass/branches/releasebranch_6_4/lib/gis/gislib.dox	2009-10-03 06:50:30 UTC (rev 39387)
+++ grass/branches/releasebranch_6_4/lib/gis/gislib.dox	2009-10-03 06:57:26 UTC (rev 39388)
@@ -2582,53 +2582,61 @@
 usage message as well as specify single or multiple required components of a 
 single option answer.
 
-
 \subsection gisprompt_Member gisprompt Member
 
-
-<P>
-The gisprompt Option structure item requires a bit more
+The <em>gisprompt</em> Option structure item requires a bit more
 description. The three comma-separated (no spaces allowed)
 sub-arguments are defined as follows:
 
-<P>
-First argument:
+ - First argument: "old" results in a call to the GRASS library
+subroutine G_open_old(), "new" to G_open_new(), otherwise "any" or
+"mapset".
 
-<P>
-"old" results in a call to the GRASS library subroutine 
-<I>G_ask_old()</I>, "new" to <I>G_ask_new(), "any" to 
-G_ask_any(), and "mapset" to G_ask_in_mapset().</I>
+  - If any option has "new" as the first component, the <tt>--o</tt>
+(overwrite) flag will be listed in the module's interface
+(<tt>--help</tt> output, manual page, GUI dialog, etc).
 
-<P>
-Second argument:
+  - If an option which has "new" as the first component is given, the
+parser checks whether the entity (map, etc.) already exists.
 
-<P>
-This is identical to the "element" argument in the above subroutine calls. 
-It specifies a directory inside the mapset that may contain the user's 
-response.
+ - Second argument: This is identical to the "element" argument in the
+above subroutine calls. It specifies a directory inside the mapset
+that may contain the user's response. In other words the second field
+is used to determine where to look for the file (i.e. if the option
+has "new,cell,...", it will look in the "cell" directory). The second
+field should be the name of one of the standard subdirectories of the
+mapset, as listed in $GISBASE/etc/element_list.
 
-<P>
-Third argument:
+ - Third argument: Identical to the "prompt" argument in the above
+subroutine calls. This is a string presented to the user that
+describes the type of data element being requested.
 
-<P>
-Identical to the "prompt" argument in the above subroutine calls. This is 
-a string presented to the user that describes the type of data element being 
-requested.
-
-<P>
 Here are two examples:
 
-<P>
-<B>gisprompt arguments Resulting call</B>
+\verbatim
+"new,cell,raster"   G_open_new("cell", "map")
+"old,vector,vector" G_open_old("vector", "map")
+\endverbatim
 
-<P>
-"new,cell,raster" G_ask_new("", buffer, "cell", "raster")
+If a module is run without arguments, and GRASS_UI_TERM is set
+(indicating that terminal-based interaction should be used rather than
+a GUI dialog), the gisprompt fields affect how the user is prompted
+for values.
 
-<P>
-"old,dig,vector" G_ask_old("", buffer, "dig", "vector")
+Specifically, the first field affects which of the G_ask_* functions
+are used, while the second and third fields are passed as arguments.
+The second field will be used to select the type of elements to list
+if the user enters "list", while the third field will typically be
+incorporated into the prompt.
 
-<P>
+The gisprompt values are passed to any GUI code, both self-contained
+dialogs generated by the parser for the <tt>--ui</tt> option, and
+stand-alone GUIs (gis.m, wxGUI) which use the <tt>--tcltk</tt> or
+<tt>--xml-description</tt> flags to obtain a machine-readable
+description of the module's interface. How the GUI interprets this is
+up to the GUI.
 
+
 \subsection Common_Questions Common Questions