Revision of Profile part of manual

The last figures in the manual using the Unity desktop have been replaced
with equivalent figures using Gnome 3. There should now be no figures
remaining from Unity.

This is a revision of the profile part of the manual in the light of the
changes for V4.1. Text has been moved around, some new text added or
rewritten. Graphics has been replaced to reflect the UI for V4.1,
including Tomaz's button bar and Louisa's new buttons for that bar.

Signed-off-by: Willem Ferguson <willemferguson@zoology.up.ac.za>
Signed-off-by: Dirk Hohndel <dirk@hohndel.org>

6 files changed, 125 insertions, 60 deletions

diff --git a/Documentation/images/AddDive1.jpg b/Documentation/images/AddDive1.jpg
index 592ed66db..d70e330a5 100644
--- a/Documentation/images/AddDive1.jpg
+++ b/Documentation/images/AddDive1.jpg
diff --git a/Documentation/images/Ceilings.png b/Documentation/images/Ceilings.png
index b3eae8c04..55e53abf1 100644
--- a/Documentation/images/Ceilings.png
+++ b/Documentation/images/Ceilings.png
diff --git a/Documentation/images/MeasuringBar.png b/Documentation/images/MeasuringBar.png
index 8340d3716..4484bce03 100644
--- a/Documentation/images/MeasuringBar.png
+++ b/Documentation/images/MeasuringBar.png
diff --git a/Documentation/images/Profile2.png b/Documentation/images/Profile2.png
index 7acbbdfb7..689a2c8cb 100644
--- a/Documentation/images/Profile2.png
+++ b/Documentation/images/Profile2.png
diff --git a/Documentation/images/main_window.jpg b/Documentation/images/main_window.jpg
index 363ee17b2..c12f2651f 100644
--- a/Documentation/images/main_window.jpg
+++ b/Documentation/images/main_window.jpg
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 156f20342..f33ac677f 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1201,7 +1201,10 @@ water temperature and surface air consumption (SAC).
 image::images/Profile2.png["Typical dive profile",align="center"]
 
 Of all the panels in _Subsurface_, the Dive Profile contains the most detailed
-information about each dive. The main item in the Dive profile is the graph of
+information about each dive. The Dive Profile has a *button bar* on the laft hand side
+that allows control over several display options. The functions of these
+buttons are described below. The main item in the Dive
+Profile is the graph of
 dive depth as a function of time. In addition to the obvious information of
 the depth it also shows the ascent and descent rates compared to the recommended
 speed of going up or down in the water column. This information is given using
@@ -1219,6 +1222,34 @@ The profile also includes depth readings for the peaks and troughs in the graph.
 Thus, users should see the depth of the deepest point and other peaks. Mean depth
 is marked with a horizontal red line.
 
+[icon="images/icons/scale.jpg"]
+[NOTE]
+In some cases the dive profile does not fill the whole area of the *Dive Profile*
+panel. Clicking the *Scale* button in the toolbar on the left of the dive profile
+frequently increases the size of the dive profile to fill the area of the panel efficiently.
+
+*Water temperature* is displayed with its own blue line with temperature values
+placed adjacent to significant changes.
+
+The dive profile can include graphs of the *partial pressures*
+of O2, N2, and He during the dive (see figure above) as well as a calculated and dive computer
+reported deco ceilings (only visible for deep, long, or repetitive dives). Partial pressures of oxygen are indicated in green, those of nitrogen in black, and those of helium in dark red. These
+partial pressure graphs are shown below the profile data.
+
+[icon="images/icons/O2.jpg"]
+[NOTE]
+Clicking this button allows display of the partial pressure of *oxygen* during the
+dive. This is depicted below the dive depth and water temperature graphs.
+
+[icon="images/icons/N2.jpg"]
+[NOTE]
+Clicking this button allows display of the partial pressure of *nitrogen* during the dive.
+
+[icon="images/icons/He.jpg"]
+[NOTE]
+Clicking this button allows display of the partial pressure of *helium* during the dive.
+This is only of importance to divers using Trimix, Helitrox or similar breathing gasses.
+
 The *air consumption* graph displays the tank pressure and its change during the
 dive. The air consumption takes depth into account so that even when manually
 entering the start and end pressures the graph is not a straight line.
@@ -1234,9 +1265,6 @@ when the diver was using less gas than average. The colour coding is obviously
 only possible when a tank sensor is connected and tank pressure readings during
 the dive are available.
 
-*Water temperature* is displayed with its own blue line with temperature values
-placed adjacent to significant changes.
-
 It is possible to *zoom* into the profile graph. This is done either by using
 the scroll wheel / scroll gesture of your mouse or trackpad. By default
 _Subsurface_ always shows a profile area large enough for at least 30 minutes
@@ -1247,53 +1275,73 @@ that free divers clearly won’t care about.
 
 image::images/MeasuringBar.png["FIGURE: Measuring Bar",align="center"]
 
-Measurements of *depth differences* can be achieved by using the button with
-two vertical bars at the right of the dive profile panel (users should refer to
-the above figure,
-bottom right). The measurement is done by dragging the red dots to the two points
+[icon="images/icons/ruler.jpg"]
+[NOTE]
+Measurements of *depth or time differences* can be achieved by using the
+*ruler button* on the left of the dive profile panel.
+The measurement is done by dragging the red dots to the two points
 on the dive profile that the user wishes to measure. Information is then given
-along the line connecting the
+in the horizontal white area underneath the
 two red dots.
 
-The dive profile can include further information that is typically more
-interesting for tec divers. Enabling these is described in the section entitled
-_Setting up Preferences_. Basically, users can include graphs of the *partial
-pressures*
-of O2, N2, and He during the dive as well as a calculated and dive computer
-reported deco ceilings (only visible for deep, long, or repetitive dives). The
-partial pressure graphs are added below the profile data, the calculated ceiling
-is shown as a green overlay on top of the dive profile. Above the profile the
-currently used gradient factors are shown (e.g. GF 35/75). Please note that
-these are NOT the gradient factors in use by the dive computer in question,
-but the gradient factors used by _Subsurface_ to calculate deco obligations
-during the dive.
-
-The graph can also include the dive computer reported *ceiling* (or more
-precisely, the first deco stop that the dive computer recorded – users are reminded that not
+The profile can also include the dive computer reported *ceiling* (more
+precisely, the deepest deco stop that the dive computer calculated for each particular moment in time) as a red overlay on  the dive profile. Ascent ceilings arise when a direct ascent to the surface increases
+the risk of a diver suffering from decompression sickness (DCS) and it is necessary to either ascend
+slower or to perform decompression stop(s) before ascending to the surface. Not
 all dive computers record this information and make it available for download;
 for example all of the Suunto dive computers fail to make this very useful data
-available to divelog software). Because of the differences in used algorithms
-and amount of data available (and factors taken into consideration) at the time
-of the calculation it is unlikely that both of these are the same; this can be
-true even if the same algorithm and _gradient factors_ (see below) are used.
+available to divelog software. _Subsurface_ also calculates ceilings independently,
+shown as a green overlay on the dive profile.
+Because of the differences in algorithms used
+and amount of data available (and other factors taken into consideration at the time
+of the calculation) it is unlikely that ceilings from dive computers and from _Subsurface_ are the same, even if the same algorithm and _gradient factors_ (see below) are used.
 It is also quite common that _Subsurface_ calculates a ceiling for
 non-decompression dives when the dive computer stayed in non-deco mode during
 the whole dive (represented by the [green]#dark green# section in the profile
 at the beginning of this section). This is caused by the fact that
 _Subsurface’s_
-calculations describe the deco obligation at that point in time during a dive,
+calculations describe the deco obligation at each moment during a dive,
 while dive computers usually take the upcoming ascent into account. During the
-ascent some excess Nitrogen (and possibly Helium) are already breathed off so
+ascent some excess nitrogen (and possibly helium) are already breathed off so
 even
 though the diver technically encountered a ceiling at depth, the dive still does
 not require an explicit deco stop. This feature allows dive computers to offer
-longer non-stop bottom time.
+longer non-stop bottom times.
 
-For a more detailed explanation of _gradient factors_, use the following links:
+[icon="images/icons/cceiling.jpg"]
+[NOTE]
+If the dive computer itself calculates a ceiling and makes it available to
+_Subsurface_ during upload of dives, this can be
+shown as a red area by checking *Dive computer reported ceiling* button on the Profile Panel.
 
-- link:http://www.tek-dive.com/portal/upload/M-Values.pdf[Understanding M-values, by Erik Baker, 1988, _Immersed_ Vol. 3, No. 3.]
+[icon="images/icons/ceiling1.jpg"]
+[NOTE]
+If the *Calculated ceiling* button on the Profile Panel is clicked, then a ceiling, calculated by _Subsurface_, is shown in green if it exists for
+a particular dive (*A* in figure below). This setting can be modified in two ways:
+
+[icon="images/icons/ceiling2.jpg"]
+[NOTE]
+If, in addition, the *show all tissues* button on the Profile Panel is clicked, the ceiling is shown for the tissue
+compartments following the Bühlmann model (*B* in figure below).
+
+[icon="images/icons/ceiling3.jpg"]
+[NOTE]
+If, in addition, the *3m increments* button on the Profile Panel is clicked, then the ceiling is indicated in 3 m increments
+(*C* in figure below).
+
+image::images/Ceilings2.jpg["Figure: Ceiling with 3m resolution",align="center"]
+
+Gradient Factor settings strongly affect the calculated ceilings and their depths.
+For more information about Gradient factors, see the section on xref:S_GradientFactors[Gradient Factor Preference settings]. The
+currently used gradient factors (e.g. GF 35/75) are shown above the depth profile if the appropriate toolbar buttons are activated.
+*N.B.:* The indicated gradient factors are NOT the gradient factors in use by the dive computer,
+but those used by _Subsurface_ to calculate deco obligations
+during the dive. For more information external to this manual see:
+
+ ** http://www.tek-dive.com/portal/upload/M-Values.pdf[Understanding M-values by Erik Baker, _Immersed_ Vol. 3, No. 3.]
+
+ ** link:http://www.rebreatherworld.com/general-and-new-to-rebreather-articles/5037-gradient-factors-for-dummies.html[Gradient factors for dummies, by Kevin Watts]
 
-- link:http://www.rebreatherworld.com/general-and-new-to-rebreather-articles/5037-gradient-factors-for-dummies.html[Gradient factors for dummies, by Kevin Watts]
 
 
 === The Dive Profile context menu
@@ -1316,16 +1364,16 @@ The Information box displays a large range of information pertaining to the dive
 profile. Normally the Information Box is located to the top left of the *Dive
 Profile* panel. If the mouse points outside of the *Dive Profile* panel, then
 only the top line of the Information Box is visible (see left-hand part of
-figure (A) below). The Information Box can be moved around in the *Dive Profile*
+figure (*A*) below). The Information Box can be moved around in the *Dive Profile*
 panel by click-dragging it with the mouse so that it is not obstructing
 important detail. The position of the Information Box is saved and used again
 during subsequent dive analyses.
 
 image::images/InfoBox2.jpg["Figure: Information Box",align="center"]
 
-The moment the mouse points inside the *Dive Profile* panel, it expands and
+The moment the mouse points inside the *Dive Profile* panel, the information box  expands and
 shows many data items. In this situation, the data reflect the time point along
-the dive profile indicated by the mouse (see right-hand part of figure (B) above
+the dive profile indicated by the mouse cursor (see right-hand part of figure (*B*) above
 where the Information Box reflects the situation at the position of the cursor
 [arrow] in that image). Therefore, moving the cursor in the horizontal
 direction allows the Information Box to show information for any point along the
@@ -1339,6 +1387,44 @@ maximum operating depth, effective air depth (EAD), effective narcotic depth
 instant in time (Deco), time to surface (TTS), the calculated ceiling, as well
 as the calculated ceiling for several Bühlmann tissue compartments.
 
+The user has control over the display of several statstics, represented as four
+buttons on the left of the profile panel. These are:
+
+[icon="images/icons/MOD.jpg"]
+[NOTE]
+Clicking this button causes the Information Box to display the *Maximum Operating Depth
+(MOD)* of the dive, given the
+gas mixture used. MOD is dependent on the oxygen concentration in the breathing gas.
+For air (21% oxygen) it is around 57 m. Below the MOD there is a markedly increased
+risk of exposure to the dangers associated with oxygen toxicity.
+
+[icon="images/icons/NDL.jpg"]
+[NOTE]
+Clicking this button causes the Information Box to display the *No-deco Limit (NDL)* or the
+*Total Time to Surface (TTS)*. NDL is the time duration that a diver can continue with a
+dive, given the present depth, that does not require decompression (that is, before an
+ascent ceiling appears). Once one has exceeded the NDL and decompression is required (that
+is, there is an ascent ceiling above the diver, then TTS gives the number of minutes
+required before the diver can surface. TTS includes ascent time as well as decompression
+time.
+
+[icon="images/icons/SAC.jpg"]
+[NOTE]
+Clicking this button causes the Information Box to display the *Surface Air Consumption (SAC)*.
+SAC is an indication of the surface-normalised respiration rate of a diver. The value of SAC
+is less than the real
+respiration rate because a diver at 10m uses breathing gas at a rate roughly double that of
+the equivalent rate at the surface. SAC gives an indication of breathing gas consumption rate
+independent of the depth of the dive so that the respiratory rates of different dives
+can be compared. The units for SAC is litres/min or cub ft/min.
+
+[icon="images/icons/EAD.jpg"]
+[NOTE]
+Clicking this button displays the *Effective Air Depth (EAD)* as well as the *Effective
+Narcotic Depth (END)* for the dive. These are numbers of importance to divers who use Nitrox or
+Trimix as breathing gases. Their values are dependent on the composition of the breathing gas.
+
+Figure (*B*) above shows an information box with a nearly complete set of data.
 
 == Organising the logbook (Manipulating groups of dives)
 
@@ -1600,6 +1686,7 @@ independently, with some units in the metric system and other in the imperial.
 === Graph
 image::images/Preferences3.jpg["FIGURE: Preferences Graph page",align="center"]
 
+[[S_GradientFactors]]
 This panel allows two type of selections:
 
 * *Show*: Here users can specify the amount of information shown as part of
@@ -1610,27 +1697,6 @@ panel. If any of the graphs go above this threshold level, the graph is
 highlighted in red, indication that the threshold value has been exceeded (see
 figure below).
 
-** Ceiling: Ascent ceilings arise when a direct ascent to the surface increases
-the risk of a diver suffering from decompression sickness (DCS) and it is necessary to either ascend
-slower or to perform decompression stop(s) before ascending to the surface.
-_Subsurface_ can indicate these ceilings above which the diver should not ascend
-at a particular point in time (see the green-shaded areas in the figure in the
-section on <<S_DiveProfile,Dive Profiles>>) and in the figure below:
-
-*** If the *Calculated ceiling* option is checked, then a ceiling is shown if it exists for
-a particular dive (*A* in figure below)
-
-*** If the *show all tissues* option is checked, the ceiling is shown for the tissue
-compartments following the Bühlmann model (*B* in figure below).
-
-*** If the *3m increments* option is checked, then the ceiling is indicated in 3 m increments
-(*C* in figure below).
-
-*** If the dive computer itself calculates a ceiling and makes it available to
-_Subsurface_ during upload of dives, this can be
-shown by checking *Dive computer reported ceiling* and it can be drawn in red by
-checking *Draw ceiling red*.
-
 ** If a _Maximum operating depth (MOD)_ or an _Equivalent air depth (EAD)_
 applies to a dive profile, these can be shown by checking the appropriate boxes.
 
@@ -1639,9 +1705,8 @@ this can be specified in the appropriate text box. In addition, if a
 _no-decompression limit (NDL)_ is to be shown in the *info* box, then users must check the
 appropriate box.
 
-image::images/Ceilings.png["Figure: Ceiling with 3m resolution",align="center"]
 
-* *Misc*: Here users can set the _gradient factors_ used while diving. GF_Low is
+* *Misc*: *Gradient Factors:* Here users can set the _gradient factors_ used while diving. GF_Low is
 the gradient factor at deep and GF_High is used just below the surface.
 At intermediate depths gradient factors between GF_Low and GF_High are used.
 Gradient factors add conservatism to the nitrogen exposure during a dive, in a