Added hint from Glynn on doing as much as possible in each r.mapcalc command to NOTES

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

raster/r.mapcalc/r.mapcalc.html

@@ -4,7 +4,7 @@ New raster map layers can be created which are arithmetic expressions
 involving existing raster map layers, integer or floating point constants,
 and functions.
 
-<h2>PROGRAM USE</h2>
+<h3>PROGRAM USE</h3>
 
 <em>r.mapcalc</em> expects its input to have the form:
 <p>
@@ -77,7 +77,7 @@ should be enclosed within single quotes.  See NOTES, below.
 <p>
 
 
-<h2>OPERATORS AND ORDER OF PRECEDENCE</h2>
+<h3>OPERATORS AND ORDER OF PRECEDENCE</h3>
 The following operators are supported:
 <div class="code"><pre>
      Operator   Meaning                    Type        Precedence
@@ -122,7 +122,7 @@ The logical operators give a 1 result if the comparison is true, 0 otherwise.
 <p>
 
 
-<h2>RASTER MAP LAYER NAMES</h2>
+<h3>RASTER MAP LAYER NAMES</h3>
 Anything in the expression which is not a number, operator, or function name
 is taken to be a raster map layer name.
 Examples:
@@ -191,7 +191,7 @@ GRASS commands, not just <em>r.mapcalc</em>.)
 <p>
 
 
-<h2>THE NEIGHBORHOOD MODIFIER</h2>
+<h3>THE NEIGHBORHOOD MODIFIER</h3>
 Maps and images are data base files stored in raster format, i.e.,
 two-dimensional matrices of integer values.
 In <em>r.mapcalc</em>, maps may be followed by a <em>neighborhood</em> modifier that
@@ -206,7 +206,7 @@ map or across multiple maps.
 <p>
 
 
-<h2>RASTER MAP LAYER VALUES FROM THE CATEGORY FILE</h2>
+<h3>RASTER MAP LAYER VALUES FROM THE CATEGORY FILE</h3>
 Sometimes it is desirable to use a value associated with a category's
 <em>label</em> instead of the category value itself.  If a raster
 map layer name is preceded by the <b>@</b>
@@ -247,7 +247,7 @@ with a number or is missing, it will be represented by NULL
 (no data) in the resulting raster map. 
 
 
-<h2>GREY SCALE EQUIVALENTS AND COLOR SEPARATES</h2>
+<h3>GREY SCALE EQUIVALENTS AND COLOR SEPARATES</h3>
 It is often helpful to manipulate the colors assigned to map categories.
 This is particularly useful when the spectral properties of cells have meaning
 (as with imagery data), or when the map category values represent real
@@ -327,7 +327,7 @@ red
 <p>
 
 
-<h2>FUNCTIONS</h2>
+<h3>FUNCTIONS</h3>
 The functions currently supported are listed in the table below.
 The type of the result is indicated in the last column.
 <em>F</em>
@@ -388,7 +388,7 @@ Internal variables:
 Note, that the row() and col() indexing starts with 1.
 
 
-<h2>FLOATING POINT VALUES IN THE EXPRESSION</h2>
+<h3>FLOATING POINT VALUES IN THE EXPRESSION</h3>
 Floating point numbers are allowed in the expression. A floating point
 number is a number which contains a decimal point:
 <div class="code"><pre>
@@ -414,7 +414,7 @@ produce a floating-point result, as will using float():
 </pre></div>
 
 
-<h2>NULL support</h2>
+<h3>NULL support</h3>
 <ul>
 <li>Division by zero should result in NULL. 
 <li>Modulus by zero should result in NULL. 
@@ -524,6 +524,57 @@ unknown quantity. E.g. if x and y are both unknown, then the values of
 "x == y" and "x != y" are also unknown; if they both have unknown
 values, the user doesn't know whether or not they both have the same value.
 
+<h2>NOTES</h2>
+Extra care must be taken if the expression is given on the command line.
+Some characters have special meaning to the UNIX shell.
+These include, among others:
+<p>
+* ( ) &gt; &amp; |
+<p>
+It is advisable to put single quotes around the expression; e.g.:
+<div class="code"><pre>
+'result = elevation * 2'
+</pre></div>
+Without the quotes, the *, which has special meaning to the UNIX shell,
+would be altered and <em>r.mapcalc</em> would see something other than the *.
+<p>
+
+In general, it's preferable to do as much as possible in each
+r.mapcalc command. E.g. rather than:
+<div class="code"><pre>
+        r.mapcalc "$GIS_OPT_OUTPUT.r = r#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * r#$GIS_OPT_SECOND"
+        r.mapcalc "$GIS_OPT_OUTPUT.g = g#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * g#$GIS_OPT_SECOND"
+        r.mapcalc "$GIS_OPT_OUTPUT.b = b#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * b#$GIS_OPT_SECOND"
+</pre></div>
+use:
+<div class="code"><pre>
+		r.mapcalc &#60&#60EOF
+        $GIS_OPT_OUTPUT.r = r#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * r#$GIS_OPT_SECOND
+        $GIS_OPT_OUTPUT.g = g#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * g#$GIS_OPT_SECOND
+        $GIS_OPT_OUTPUT.b = b#$GIS_OPT_FIRST * .$GIS_OPT_PERCENT + (1.0 - .$GIS_OPT_PERCENT) * b#$GIS_OPT_SECOND
+        EOF
+</pre></div>
+as the latter will read each input map only once.
+</p>
+
+For formulas that the user enters from standard input
+(rather than from the command line), a line continuation feature now exists.
+If the user adds \e to the end of an input line, <em>r.mapcalc</em> assumes that
+the formula being entered by the user continues on to the next input line.
+There is no limit to the possible number of input lines
+or to the length of a formula.
+<p>
+If the <em>r.mapcalc</em> formula entered by the user is very long,
+the map title will contain only some of it, but most (if not all) of
+the formula will be placed into the history file for the <em>result</em> map.
+<p>
+When the user enters input to <em>r.mapcalc</em> non-interactively on
+the command line, the program will not warn the user not to overwrite
+existing map layers.  Users should therefore take care to assign program
+outputs raster map names that do not yet exist in their current mapsets.
+<p>
+The environment variable GRASS_RND_SEED is read to initialise the
+random number generator.
 
 <h2>EXAMPLES</h2>
 To compute the average of two raster map layers
@@ -580,38 +631,6 @@ X (map) values supplied and y (newmap) values returned:
 </pre></div>
 
 
-<h2>NOTES</h2>
-Extra care must be taken if the expression is given on the command line.
-Some characters have special meaning to the UNIX shell.
-These include, among others:
-<p>
-* ( ) &gt; &amp; |
-<p>
-It is advisable to put single quotes around the expression; e.g.:
-<div class="code"><pre>
-'result = elevation * 2'
-</pre></div>
-Without the quotes, the *, which has special meaning to the UNIX shell,
-would be altered and <em>r.mapcalc</em> would see something other than the *.
-<p>
-For formulas that the user enters from standard input
-(rather than from the command line), a line continuation feature now exists.
-If the user adds \e to the end of an input line, <em>r.mapcalc</em> assumes that
-the formula being entered by the user continues on to the next input line.
-There is no limit to the possible number of input lines
-or to the length of a formula.
-<p>
-If the <em>r.mapcalc</em> formula entered by the user is very long,
-the map title will contain only some of it, but most (if not all) of
-the formula will be placed into the history file for the <em>result</em> map.
-<p>
-When the user enters input to <em>r.mapcalc</em> non-interactively on
-the command line, the program will not warn the user not to overwrite
-existing map layers.  Users should therefore take care to assign program
-outputs raster map names that do not yet exist in their current mapsets.
-<p>
-The environment variable GRASS_RND_SEED is read to initialise the
-random number generator.
 
 
 <h2>BUGS</h2>