Fwd: docs addition - section on the dive planner

[Amit Chaudhuri]

Nearly forgot...

Signed of by Amit Chaudhuri <amit.k.chaudhuri at gmail.com>

---------- Forwarded message ----------
From: Amit Chaudhuri <amit.k.chaudhuri at gmail.com>
Date: Thu, Feb 14, 2013 at 8:39 AM
Subject: docs addition - section on the dive planner
To: Subsurface Mailing List <subsurface at hohndel.org>
Cc: Dirk Hohndel <dirk at hohndel.org>


I have taken the liberty of writing up a documentation section on the dive
planner. ect....
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.hohndel.org/pipermail/subsurface/attachments/20130214/098cb17b/attachment.html>
-------------- next part --------------
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 08e298f..f94e2cc 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -538,6 +538,45 @@ can import them with the command:
 And with the menu 'File - Save' you can save your dives into the
 Subsurface format.
 
+[S_DivePlanning]
+The Dive Planner
+----------------
+
+The dive planner is a recent addition and implements a version of the decompression algorithm by Buhlmann.
+As the warning text in the dialogue makes clear, we do not believe this is sufficiently tested to be used
+as your sole method of planning dives.  Indeed the warning makes clear that you SHOULD NOT do this. If your
+have comments on the performance of the planner compared to other dive planning software we would be
+interested in receiving them via our mailing list.  With time we hope to improve this facility.
+
+When invoked from the menu, the dive plan dialogue opens to show the planner input area. This can be thought
+of as having an area for inputing parameters (such as you SAC rate and the surface pressure) and another for
+entering the various dive segments. Dive segments are defined in terms of an end depth and the time to get
+to that depth, relative to the start of the previous segment (or the dive start for the first segment).
+
+Once all segments are complete, clicking on the OK button shows the familiar dive view where you can see
+the dive profile and read notes about the plan. For example, the notes will report the total gas requirement
+as well as restating some of the key parameters, such as GFlow and GFlowHigh and reporting the dive segments
+and transitions between them.  The plan will include what it considers to be mandatory decompression stops on
+the way back to the surface. If you follow the dive profile with the mouse you will see the decompression
+ceiling the algorithm calculates alter as dive proceeds (assuming the plan takes you into decompression).
+
+Please take particular note, of the limitations of the air consumption figure. Although this is reported in
+the notes section, and is based upon the two SAC rates chosen for the dive and decompression phases, no cross
+check is made against the equipment you plan to take.  It is entirely possible to plan a dive in which you
+run out of gas and subsurface will not warn you.
+
+Once a plan has been added (click OK from the planner dialogue) it will appear in the dive list. From here
+it can be double clicked to add items such as cylinders, weight details and details about the dive location etc.
+At present, it is not possible to edit the profile itself, instead you can input another plan.
+
+By default, the planner uses specific values for SAC, GFlow and surface pressure and the dialogue displays
+space for entry 4 planned dive segments. These can all be altered by editing the value in place, or in the
+case of adding more dive segments, by pressing the Add Waypoints button.
+
+More technically advanced dives can be planned using the Gas Used and - for rebreather divers - CC Set Point
+settings. The current choice of gases is limited to Nitrox 32 and 36 in addition to the default of air.
+
+
 [[S_Menu]]
 The menu and sub-menus
 ----------------------
@@ -591,6 +630,13 @@ When you enable ascent for your dives, within the dive profile, a yellow
 marker with exclamation sign (!) will show on the points where you have
 ascended.
 
+The Planner menu
+~~~~~~~~~~~~~~~~
+
+This menu has a single entry to an experimental dive plan simulation.  Be careful to read the warning about the
+usage and status of this facility. In particular, you are told not to rely on this as your sole method of dive
+planning.
+
 The Help menu
 ~~~~~~~~~~~~~