gisprompt docs updated based on Glynn's notes in ML

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

lib/gis/gislib.dox

@@ -1806,8 +1806,7 @@ components of a single option answer.
 
 \subsection gisprompt_Member gisprompt Member
 
-
-The <b>gisprompt</b> 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:
 
@@ -1815,9 +1814,20 @@ sub-arguments are defined as follows:
 subroutine G_open_old(), "new" to G_open_new(), otherwise "any" or
 "mapset".
 
+  - 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).
+
+  - If an option which has "new" as the first component is given, the
+parser checks whether the entity (map, etc.) already exists.
+
  - 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.
+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.
 
  - Third argument: Identical to the "prompt" argument in the above
 subroutine calls. This is a string presented to the user that
@@ -1830,6 +1840,13 @@ Here are two examples:
 "old,vector,vector" G_open_old("vector", "map")
 \endverbatim
 
+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 (wxGUI) which use the <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