r.volume manual: example and screenshot added (#903)

- water basin example added

Note: there is a discrepancy in the results of r.lake and r.volume!

raster/r.volume/r.volume.html

@@ -66,35 +66,77 @@ water volumes in potential reservoirs.
 
 <h2>EXAMPLE</h2>
 
-The following report was generated by the command (North Carolina dataset):
+<h3>Computation of a water basin volume</h3>
+
+The example is based on the North Carolina sample dataset:
+
+<div class="code"><pre>
+# set computational region to small basin within extent of LiDAR elevation model
+g.region n=220361 s=220123 w=638527 e=638894 align=elev_lid792_1m -p
+# generate shared relief map for better terrain visualization 
+r.relief input=elev_lid792_1m output=elev_lid792_1m_shaded
+d.shade shade=elev_lid792_1m_shaded color=elev_lid792_1m
+
+# query terrain height at a position within the basin
+r.what map=elev_lid792_1m coordinates=638684.0,220210.0
+# 638684.0|220210.0||112.2362
+
+# fill the basin with water, approx 1.5m above terrain
+r.lake elevation=elev_lid792_1m water_level=113.7 lake=mylake coordinates=638684.0,220210.0
+#  Lake depth from 0.000000 to 1.622047 (specified water level is taken as zero)
+#  Lake area 764.000000 square meters
+#  Lake volume 648.875328 cubic meters
+
+# compute water volume
+r.volume input=elev_lid792_1m clump=mylake
+#
+# Category   Average   Data   # Cells        Centroid             Total
+# Number     in clump  Total  in clump   Easting     Northing     Volume
+# -----------------------------------------------------------------------------
+#        1    112.66     54188     481   638683.50   220210.50         54188.35
+#        2    112.14      6504      58   638679.50   220215.50          6504.14
+# -----------------------------------------------------------------------------
+#                                                 Total Volume =       60692.49
+</pre></div>
+
+
+<div align="center" style="margin: 10px">
+<a href="r_volume_lake.png">
+<img src="r_volume_lake.png" width="600" height="389" alt="r.volume lake example" border="0">
+</a><br>
+<i>Figure: Water filled based shown on shaded elevation map</i>
+</div>
+
+<h3>Report of geological data</h3>
+The following report was generated by the command (North Carolina sample dataset):
 
 <div class="code"><pre>
 # set computational region
-g.region raster=elevation
+g.region raster=elevation -p
 
 # compute volume
 r.volume input=elevation clump=geology_30m
-
-Volume report on data from &lt;elevation&gt; using clumps on &lt;geology_30m&gt; raster map
-
-Category   Average   Data   # Cells        Centroid             Total
-Number     in clump  Total  in clump   Easting     Northing     Volume
------------------------------------------------------------------------------
-     217    118.93  86288828  725562   635325.00   221535.00    8628882798.63
-     262    108.97  21650560  198684   638935.00   222495.00    2165056037.02
-     270     92.23  63578874  689373   642405.00   221485.00    6357887443.53
-     405    132.96  33732662  253710   631835.00   224095.00    3373266208.59
-     583    139.35   3011288   21609   630205.00   224665.00     301128821.55
-     720    124.30    599618    4824   634075.00   227995.00      59961816.06
-     766    132.43    936791    7074   631425.00   227845.00      93679120.08
-     862    118.31   7302317   61722   630505.00   218885.00     730231746.74
-     910     94.20   4235816   44964   639215.00   216365.00     423581613.11
-     921    135.22   1693985   12528   630755.00   215445.00     169398523.05
-     945    127.24      1145       9   630015.00   215015.00        114512.03
-     946     89.91    365748    4068   639085.00   215255.00      36574833.85
-     948    129.02    112632     873   630185.00   215115.00      11263181.57
------------------------------------------------------------------------------
-                                                Total Volume = 22351026655.81
+#
+# Volume report on data from &lt;elevation&gt; using clumps on &lt;geology_30m&gt; raster map
+#
+# Category   Average   Data   # Cells        Centroid             Total
+# Number     in clump  Total  in clump   Easting     Northing     Volume
+# -----------------------------------------------------------------------------
+#      217    118.93  86288828  725562   635325.00   221535.00    8628882798.63
+#      262    108.97  21650560  198684   638935.00   222495.00    2165056037.02
+#      270     92.23  63578874  689373   642405.00   221485.00    6357887443.53
+#      405    132.96  33732662  253710   631835.00   224095.00    3373266208.59
+#      583    139.35   3011288   21609   630205.00   224665.00     301128821.55
+#      720    124.30    599618    4824   634075.00   227995.00      59961816.06
+#      766    132.43    936791    7074   631425.00   227845.00      93679120.08
+#      862    118.31   7302317   61722   630505.00   218885.00     730231746.74
+#      910     94.20   4235816   44964   639215.00   216365.00     423581613.11
+#      921    135.22   1693985   12528   630755.00   215445.00     169398523.05
+#      945    127.24      1145       9   630015.00   215015.00        114512.03
+#      946     89.91    365748    4068   639085.00   215255.00      36574833.85
+#      948    129.02    112632     873   630185.00   215115.00      11263181.57
+# -----------------------------------------------------------------------------
+#                                                 Total Volume = 22351026655.81
 </pre></div>
 
 The <tt>Data Total</tt> column is the sum of the elevations for each