wxGUI/doc: add manual page on module dialogs

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

gui/wxpython/docs/wxGUI.components.html

@@ -4,6 +4,7 @@
 List of available <em><a href="wxGUI.html">wxGUI</a></em> components:
 
 <ul>
+  <li><a href="wxGUI.modules.html">Module dialogs</a></li>
   <li><a href="wxGUI.nviz.html">3D Viewer</a> (nviz)</li>
   <li><a href="wxGUI.animation.html">Animation tool</a>,
     available as a command line tool <em><a href="g.gui.animation.html">g.gui.animation</a></em></li>

gui/wxpython/docs/wxGUI.html

@@ -7,7 +7,7 @@ in 2D and 3D, calling GRASS GIS modules, and interacting with data.
 
 
 <h3>Overview</h3>
-The GUI is composed of <em>two</em> main components:
+The GUI is composed of <em>three</em> main components:
 
 <ul>
   <li>The <b>Layer Manager</b> includes map layer management, integrated
@@ -18,6 +18,7 @@ The GUI is composed of <em>two</em> main components:
   set of map layers in the layer manager. The user may start multiple map 
   displays during a session. The map layers for each display are grouped
   under different tabs in the Layer Manager.</li>
+  <li><a href="wxGUI.modules.html">Module dialogs</a> enable running GRASS modules.</li>
 </ul>
 
 <h3>Layer Manager</h3>
@@ -688,6 +689,7 @@ using <a href="http://www.wxpython.org">wxPython</a> library.
 
 <em>
   <a href="wxGUI.components.html">wxGUI components</a><br>
+  <a href="wxGUI.modules.html">wxGUI module dialogs</a>
   <a href="wxGUI.toolboxes.html">wxGUI toolboxes (menu customization)</a>
 </em>
 

gui/wxpython/docs/wxGUI.modules.html

@@ -0,0 +1,191 @@
+<!-- meta page description: wxGUI Module dialogs -->
+<!-- meta page index: wxGUI -->
+<h2>DESCRIPTION</h2>
+
+GRASS GIS functionality is organized into modules, which are standalone programs
+with defined interface. Their graphical user interface (GUI) is a dialog
+with several tabs which organize module parameters into groups.
+<p>
+Each parameter can have different type of input fields,
+for example text entry or drop-down list.
+Flags are represented as checkboxes. The parameter (or flag) name
+is visible on the right side of each input field
+so that it is simple to understand how the module dialog
+relates to the command representation which is used in the manuals and tutorials.
+The commands can be used to call the module in the command line, Shell scripts
+or, with a slight modification, in a Python script.
+
+
+<center>
+  <img src="wxGUI_module_parameters.png" border="0" alt="r.neighbors dialog">
+</center>
+
+
+<h3>Tabs</h3>
+Module parameters and flags are organized in tabs. Their names can depend on a module,
+however every module has <i>Command output</i> tab where the progress can be observed,
+and the module output including text results or warnings are printed.
+The last <i>Manual</i> tab contains description of module's parameters
+and examples. The same information can be found in the online manual as well.
+
+<p>
+The style of the tabs can be changed through <i>GUI settings</i> - 
+<i>Appearance</i> - <i>Module dialog style</i>. Note that the style appearance
+depends on the platform and some styles might be more suitable
+for different platforms.
+
+<center>
+  <img src="wxGUI_module_style_left.png" border="0" alt="dialog style left">
+  <img src="wxGUI_module_style_top.png" border="0" alt="dialog style top">
+  <br>
+  Figure: Example of style "left" and "top" on Ubuntu.
+</center>
+
+<h3>Flags</h3>
+Module flags are represented as checkboxes with description. There
+are three special flags - <i>overwrite</i>, <i>verbose</i> and <i>quiet</i>.
+Flags <i>verbose</i> and <i>quiet</i> set the level of verbosity of the module
+(how detailed the messages should be).
+<center>
+  <img src="wxGUI_modules_flags.png" border="0" alt="dialog flags">
+  <br>
+</center>
+<p>
+Modules which output a new map or a new file have the flag <i>overwrite</i>
+which must be used when the specified output map or file is already present.
+If the map or file of the specified name already exist and <i>overwrite</i>
+flag is not used, an error message appears:
+<pre>
+r.slope.aspect elevation=elevation slope=slope
+ERROR: option &lt;slope&gt;: &lt;slope&gt; exists. To overwrite, use the --overwrite flag
+</pre>
+
+If using the command instead of GUI, these flags are unlike other flags
+prefixed with double dash:
+<div class="code"><pre>
+r.slope.aspect elevation=elevation slope=slope --overwrite --quiet
+</pre></div>
+
+<h3>Current working directory</h3>
+Certain modules require a file as input or output.
+Either the full path to the file needs to be specified
+or a path relative
+to the current working directory is enough, for example only the name of the file.
+<b>Current working directory</b> is a directory where GRASS would look 
+for or output files to if the full path is not specified.
+By default working directory is user's home folder.
+It can be changed in wxGUI menu
+<i>Settings</i> - <i>GRASS working environment</i> -
+<i>Change working directory</i>,
+or by typing <tt>cd</tt> and pressing Enter in the wxGUI Command console.
+If the working directory is changed to a directory where the input files are,
+then it is enough to specify just the name of the file instead of the full path.
+
+<p>
+This applies to external files such as text files or GeoTiff files.
+This does not apply to raster maps, vector maps
+and other geospatial data stored in GRASS database
+which do not need any path to be specified.
+
+
+<h3>Special widgets</h3>
+For raster, vector or 3D raster input, there is a special
+widget which after clicking on the arrow to the right pops up
+a list of existing maps from different mapsets.
+Selecting a map from the popup list will add it to the entry field.
+In case multiple maps can be specifed (denoted by <i>[multiple]</i> label),
+selecting a map from the popup list will append the map names with
+comma in between.
+
+<center>
+  <img src="wxGUI_modules_widget_selection.png" border="0" alt="widget for selecting maps">
+  <br>
+</center>
+
+<p>
+If the input file is supposed to be a text file
+(for example color rules in r.colors),
+it is possible to type the text in the provided box directly instead
+of creating a new file in a text editor and saving it.
+A temporary file is created in this case. By pressing the <i>Save as</i>
+button, the content of the box is then saved into user specified file,
+so that user's workflow can be reproduced later. With <i>Load</i>
+button we can display the content of selected file and edit it 
+directly in the box.
+
+<center>
+  <img src="wxGUI_modules_widget_file1.png" border="0" alt="widget for input files">
+  <img src="wxGUI_modules_widget_file2.png" border="0" alt="widget for input files">
+  <br>
+  <p> Figure: In the first image, user specified a full path to a file.
+      In the second image, user typed color rules conveniently
+      into the box below, however the rules will not be stored permanently.
+</center>
+
+
+<h2>NOTES</h2>
+Dialogs are generated automatically based on module interface defined using <a href="g.parser.html">g.parser</a>.
+Command line interface can be obtained when running the module with a <i>--help</i>
+flag. The options and flags are the same as in the module GUI.
+<pre>
+r.neighbors --help
+
+Description:
+ Makes each cell category value a function of the category
+values assigned to the cells around it, and stores new cell
+values in an output raster map layer.
+Keywords:
+ raster, algebra, statistics, aggregation, neighbor, focal
+statistics, filter
+Usage:
+ r.neighbors [-ac] input=name [selection=name]
+output=name[,name,...]
+   [method=string[,string,...]] [size=value] [title=phrase]
+[weight=name]
+   [gauss=value] [quantile=value[,value,...]] [--overwrite]
+[--help]
+   [--verbose] [--quiet] [--ui]
+Flags:
+  -a   Do not align output with the input
+  -c   Use circular neighborhood
+ --o   Allow output files to overwrite existing files
+ --h   Print usage summary
+ --v   Verbose module output
+ --q   Quiet module output
+ --ui  Force launching GUI dialog
+Parameters:
+      input   Name of input raster map
+  selection   Name of an input raster map to select the
+cells which should be processed
+     output   Name for output raster map
+     method   Neighborhood operation
+              options:
+average,median,mode,minimum,maximum,range,stddev,sum,
+count,variance,diversity,interspersion,quart1,quart3,
+                       perc90,quantile
+              default: average
+       size   Neighborhood size
+              default: 3
+      title   Title for output raster map
+     weight   Text file containing weights
+      gauss   Sigma (in cells) for Gaussian filter
+   quantile   Quantile to calculate for method=quantile
+              options: 0.0-1.0
+</pre>
+
+<h2>SEE ALSO</h2>
+
+<em>
+  <a href="wxGUI.html">wxGUI</a><br>
+  <a href="wxGUI.components.html">wxGUI components</a>
+</em>
+
+<h2>AUTHORS</h2>
+GRASS Development Team<br>
+manual by Anna Petrasova, OSGeoREL, Faculty of Civil Engineering, Czech Technical University in Prague<br>
+Vaclav Petras, OSGeoREL, Faculty of Civil Engineering, Czech Technical University in Prague<br>
+
+
+
+<p>
+<em>$Date$</em>