doc: makeBoundary: Elaborate on the meaning of the key-value pairs.

* doc/fullswof-utils.texi (Boundary Definition File): Edit key descriptions.

1 files changed, 36 insertions, 10 deletions

diff --git a/doc/fullswof-utils.texi b/doc/fullswof-utils.texi
index eee21e9..e51292b 100644
--- a/doc/fullswof-utils.texi
+++ b/doc/fullswof-utils.texi
@@ -274,34 +274,60 @@ The keys are defined as follows:
 @table @asis
 @item type
 boundary type (1=imposed height, 2=wall, 3=Neumann, 4=periodic,
-5=imposed discharge)
+5=imposed discharge).  For cases 1 and 5, the height and imposed
+discharge are both specified for each cell along the boundary.  For
+sub-critical inflow the type value (1 or 5) determines which of the
+specified values are used.  For super-critical inflow both values are
+used.  For super-critical outflow neither value is used.
 
 @item plotting
-enable plotting (True or False)
+enable plotting (True or False).  The program can display plots of
+hydraulic radius, conveyance and discharge versus water level for each
+active panel.  To cycle through the plots press the @samp{q} key.
 
 @item printing
-enable printing (True or False)
+enable printing (True or False).  The program can write output files
+containing data for the @emph{rating curve} for each active panel.
+Rating curves express the relation between water level and discharge.
 
 @item slope
-local gradient
+local gradient.  This is the value normal to the boundary, derived
+from survey data or from running the @command{slope.py} program.
 
 @item target_flow
-imposed discharge (flow across boundary /@math{m@sup{3}/s})
+imposed discharge (/@math{m@sup{3}/s}).  This is the total flow
+crossing the boundary.
 
 @item markers
-panel marker co-ordinates (comma-separated list of distances /m)
+panel marker co-ordinates (/m).  This is a comma-separated list of
+distances.  The distances indicate the measurement from the left-hand
+edge of the domain to the internal marker points.  Markers at the
+corner points are automatically generated to complete the list.
 
 @item panel
-fill order (comma-separated list of panel indices)
+fill order.  The fill order is a comma-separated list of panel
+indices.  The list specifies the manner in which the wetted area
+changes as the flow increases.
 
 @item ztol
-channel overtopping tolerance (/m)
+channel overtopping tolerance (/m).  For the main channel, the
+overtopping tolerance sets the difference between the minimum ground
+elevation at the channel banks and the maximum water level.  When the
+flow is sufficiently high for the water level to reach this level the
+next panel, specified by the fill order, is activated.  This panel can
+then fill to the same maximum water level.  The panels are filled in
+sequence until one panel is part-filled so that the total flow across
+the boundary matches the target flow.
 
 @item n_co
-Manning's n coefficients (comma-separated list, ordered by panel index)
+Manning's @samp{n} coefficients.  This is a comma-separated list,
+ordered by panel index.  Each panel is allocated a coefficient
+representing the roughness value for that section of the boundary.
 
 @item numH
-number of height intervals
+number of height intervals.  The relation between water level and
+discharge is calculated at the specified number of points, for each
+active panel.
 @end table
 
 Comment lines are allowed in the boundary definition file.  Lines that