Update to latest user manual

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

1 files changed, 112 insertions, 68 deletions

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 0235a47ea..2b2fb9f2b 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -505,6 +505,12 @@ box labelled _"Choose Bluetooth download mode"_, the dialogue below appears.
 
 image::images/DC_import_Bluetooth.jpg["FIGURE: Download Bluetooth",align="center"]
 
+Although the _Subsurface_ Bluetooth interface is intended to function without
+Bluetooth pairing at the operating system level, it is always prudent to follow up
+initial Bluetooth pairing problems by pairing the Bluetooth dive computer with the _Subsurface_ computer using the operating system services of the desktop computer. Delete all
+existing pairings and start by scanning for Bluetooth devices from an empty list (on the desktop) of Bluetooth devices. Once _Subsurface_ has recognised the Bluetooth dive
+computer, subsequent divelog downloads are likely to be simple.
+
 On the _Linux_ or _MacOS_ platforms the name
 of the _Subsurface_ computer and its Bluetooth address are shown on the right hand side.
 The power state (on/off) of the Bluetooth adapter is shown below
@@ -695,37 +701,31 @@ textbox labelled _Location_ on the *Notes* tab.
 *Using existing dive locations:* Type in the name of the dive site, e.g. "Tihany, Lake Balaton, Hungary".
 If several dives are
 made at the same location, the site information for the first dive is re-used.
-Existing dive locations
-can be edited by selecting (on the *Dive List* panel) a dive done at that site
-and by opening the location information. Click the globe button on the
-right of the location name (see image image *A* below).
-When typing the name of a dive site,
-a dropdown list appears showing all sites with similar names. If the dive
-site has been used before, click on the already-existing name.
-The dive site names in the dropdown list contain either a globe symbol (indicating
-existing dive sites in the _Subsurface_ database)
-or a *+* symbol (indicating dive site names that appear consistent with the
-current dive site name but which haven’t been added to the dive site database).
-If the present
-dive site has not been used before, a message appears as follows (image *A* below):
-
-image::images/Locations1_f22.jpg["FIGURE:Location description panel",align="center"]
-
-Click the globe button and a panel appears to enter the coordinates and
-other information about the site (image *B*, above). The most important
-items are the coordinates of the site. There are three ways to specify coordinates:
-
-a. Use the world map in the bottom right hand part
-   of the _Subsurface_ window. The map displays an orange bar indicating "No location
-   data - Move the map and double-click to set the dive location". Doubleclick
-   at the appropriate place, and the orange bar disappears and the coordinates are
-   stored.
-
-b. Use eiher the Subsurface-Mobile App or the _Subsurface_ Companion App on an
-   Android or iPhone device with GPS and if the dive site coordinates
-   were stored using one of these apps.
-   xref:S_Companion[Click here for more information]
-c. Enter coordiantes by hand if they are known, using one of
+Therefore, if a dive site has been used before, the name of that site (and sometimes
+the names of similar sites) appears below the dive site text box (image below). Double-click on
+the appropriate dive site name and the dive location will be associated with the
+dive being entered. Then select _Apply Changes_ (image below) to save the geolocation for this dive site.
+
+image::images/Location1.jpg["FIGURE:Location choice panel",align="center"]
+
+*Entering a new dive location:* On the other hand, having dived at a new dive location,
+a new record needs to be created
+that could be used for the new and for later dives at this new site. Type the name of the new dive site into the text box
+(image A below).
+
+image::images/Globe_image1.jpg["FIGURE:Location creation panel",align="center"]
+
+Double-click on the blue bar below the new dive location name. The blue bar disappears (image B above) and
+the globe icon on the right-hand of the location name text box turns blue.  In the Dive Map part of the _Subsurface_ window, a world map appears (image C above). Click on the
+blue globe icon to the right of the dive site name in the _Notes_ panel (image B above). This opens a window for entering the details of the new dive location (image A below).
+The globe icon changes to indicate that the location data are being edited. The only important
+data here are the geographic coordinates of the dive location. 
+
+image::images/Globe_image2.jpg["FIGURE:Location creation panel",align="center"]
+
+There are three ways of adding the the coordinates:
+
+*(1):* Enter coordinates by hand if they are known, using one of
    four formats with latitude followed by longitude:
 
 	ISO 6709 Annex D format e.g. 30°13'28.9"N 30°49'1.5"E
@@ -1105,14 +1105,16 @@ generated by SmartTrak to Subsurface's _.xml_ format. It can be built together
 with _Subsurface_ for Linux systems. Two dependencies need to be installed in
 your system before building: _libglib2.0_ and _libmdb2_.
 
+In addition, a web service is available for divelog convertions from SmartTrak to _Subsurface_ (see below).
+
 Feel free to contact the _Subsurface_ development team on mailto:subsurface@subsurface-divelog.org[our mailing list]
 for assistance in importing _SmartTrak_ dive logs.
 
+===== Building _smtk2ssrf_
+
 Assuming the above dependencies
 have been installed and the _Subsurface_ source tree is in the directory _~/src/subsurface_, then:
 
-===== Building _smtk2ssrf_
-
 - Move to the source tree directory.
 - Run  " $ ccmake build " and set SMARTTRAK_IMPORT option to *on* (off by
   default).
@@ -1150,6 +1152,20 @@ in the console or in the graphical window: some may be
 relevant as support for Galileo family of dive computers is still a work in
 progress.
 
+===== For the lazy: a web service to convert _SmartTrak_ to _Subsurface_
+
+Open the website at:
+
+_https://thetheoreticaldiver.org/rch-cgi-bin/smtk2ssrf.pl_ 
+
+This is a no-frills
+web service for converting _SmartTrak_ dive logs to _Subsurface_. Select the browse button. This allows
+you to browse your computer directories and to select the _SmartTrak_ divelog to be converted. Once it has been selected,
+click the _Submit query_ button. After a short while, a dialog box appears (image below) for saving the converted file to
+the local computer.
+
+image::images/strk2ssrf_web.jpg["FIGURE:Web service to convert SmartTrak divelog",align="center"]
+
 ===== Merging the imported dives with the existing divelog
 
 Open the new file (generated in the previous steps) using _Subsurface_ and check the dives and data.
@@ -1161,16 +1177,6 @@ The new dives, although time ordered, will keep the numbering system from
 _SmartTrak_, so a renumbering action is needed. See the section on xref:S_Renumber[Renumbering
 the dives] for instructions on this topic.
 
-===== For the lazy: a web service to convert _SmartTrak_ to _Subsurface_
-
-Open the website _https://thetheoreticaldiver.org/rch-cgi-bin/smtk2ssrf.pl_. This is a no-frills
-web service for converting _SmartTrak_ dive logs to _Subsurface_. Select the browse button. This allows
-you to browse your computer and to select the _SmartTrak_ dive log to be converted. Once it has been selected,
-click the _Submit query_ button. After a short while, a dialog box appears (image below) for saving the converted file to
-the local computer.
-
-image::images/strk2ssrf_web.jpg["FIGURE:Web service to convert SmartTrak divelog",align="center"]
-
 [[S_ImportingDivelogsDe]]
 ==== Importing dives from *divelogs.de*
 
@@ -1372,7 +1378,7 @@ automatically collecting dive site coordinate information.
 3) Syncronising the dives in the _Subsurface_ dive list with the coordinates stored
 on the _Subsurface_ Internet server.
 
-_Subsurface has two tools for achieving this:
+_Subsurface_ has two tools for achieving this:
 
 - The _Subsurface Companion App_ (Android and iOS).
 
@@ -1960,17 +1966,17 @@ image::images/multicylinder_dive.jpg["FIGURE: Multicylinder profile",align="cent
 
 Several dive computers perform automatic recording of cylinder pressure. In this case no manual intervention is needed.
 Older dive computers (e.g. Uwatec Galileo, several Suunto models) handle more than one pressure transducer on cylinders,
-switching from one sensor to another as the diver switches among cylinders and providing a sequential record of cylinders pressures during a dive. Some of the latest models (e.g. Shearwater Perdix AI, Scubapro G2) record two or more pressure transducers concurrently and continuously during the whole dive. In these cases the same situation applied as for the older technology.
+switching from one sensor to another as the diver switches among cylinders and providing a sequential record of cylinders pressures during a dive. Some of the latest models (e.g. Shearwater Perdix AI, Scubapro G2) record two or more pressure transducers concurrently and continuously during the whole dive. In these cases _Suburface correctly interprets the data.
 There is continuous effort within the _Subsurface_ development team to add new dive computer models to those that can be
 downloaded from and to represent cylinder pressures correctly. Regardless of the type of sensor handling of dive computers, technical divers are likely to use both automated and manual methods of cylinder pressure logging when more than two gases are used. However,
-automated recording of cylinder pressure makes logging of sidemount dives (where two cylinders are used) much more simple. See the
+automated recording of cylinder pressure simplifies logging of sidemount dives (where two cylinders are used). See the
 link:https://subsurface-divelog.org/documentation/supported-dive-computers/[list of supported dive computers].
 
 ==== Sidemount dives
 
 Sidemount diving is just another form of multi-cylinder diving, often with both or all cylinders having
 the same gas mixture. Although it’s a popular configuration for cave divers, sidemount
-diving can be done by recreational divers who???ve completed the appropriate training. See the comments in the
+diving can be done by recreational divers who have completed the appropriate training. See the comments in the
 last paragraph, above, about automated recording of cylinder pressures. Manual
 logging of cylinder pressures during sidemount involves three steps, exactly as with multi-cylinder dives above:
 
@@ -2043,7 +2049,7 @@ The CCR interface of _Subsurface_ is currently experimental
 and under active development. Subsurface currently supports Poseidon MkVI
 and APD Discovery/Evolution dive computers, as well as Shearwater dive computers connected
 to CCR systems. In contrast to a conventional recreational
-dive computer, a CCR system computer does not allow the download of a log
+dive computer, a CCR system computer usually does not allow the download of a log
 containing multiple dives. Rather, each dive is stored independently. This
 means that _Subsurface_ cannot download a dive log directly from a CCR
 dive computer, but that it imports individual CCR dive profiles in the same way it
@@ -2163,6 +2169,40 @@ Poseidon MkVI and APD equipment can be found in xref:_appendix_b_dive_computer_s
 
 == Obtaining more information about dives entered into the logbook
 
+=== Using the Dive Map to obtain more dive information
+
+The Dive Map has a number of buttons useful for manipulation several aspects of a dive. These are:
+
+[icon="images/icons/MapViewMode.jpg"]  
+[NOTE]
+Select this button to show the Dive Map as a satellite image or as a Google Maps
+representation.
+
+[icon="images/icons/MapViewPlus.jpg"]
+[NOTE]
+Zoom in. Select a smaller area of the map.
+
+[icon="images/icons/MapViewMinus.jpg"]
+[NOTE]
+Zoom out. Select a larger area of the map.
+
+image::images/MapMenu.jpg["FIGURE: Map menu",align="left"]
+
+The "Hamburger" button on the top right-hand of the Dive Map
+activates the Map menu. The items are:
+
+* Open location in _Google Maps_. Open the location of the active dive in a separate Google Maps window with the
+  dive site indicated by a Google Maps teardrop marker.
+
+* Copy location to clipboard (decimal). Copy the coordinates of the active dive to the clipboard in decimal degrees
+  e.g. -25.933905 30.710572
+
+* Copy location to clipboard (sexagesimal). Copy the coordinates of the active dive to the clipboard in sexagecimal, e.g. 25°56'02.058"S
+  30°42'38.059"E
+
+* Select visible dive locations. In the Dive List panel, highlight all the dive sites visible in the Dive Map. This allows easy
+  selection of the dives within a particular geographical area to inspect them or to calculate statistics for them.
+
 === The *Info* tab (for individual dives)
 
 The Info tab gives some summary information about a particular dive that
@@ -3453,7 +3493,7 @@ of gradient factors as implemented by Erik Baker, or using the VPM-B model.
 [icon="images/icons/warning2.png"]
 [WARNING]
 
-The _Subsurface_ dive planner IS CURRENTLY EXPERIMENTAL
+The _Subsurface_ dive planner IS EXPERIMENTAL
 and assumes the user is already familiar with the _Subsurface_
 user interface. It is explicitly used under the following conditions:
 
@@ -3677,17 +3717,7 @@ In addition to calculating the total gas consumption for every cylinder the plan
 of calculating the recommended volume of bottom gas which is needed for safe asscent to the
 first deco gas change depth or the surface. This procedure is called the "minimum gas" or "rock bottom"
 consideration and it is used by various (but not all)
-technical diving organisations. The calculation assumes that in worst case an out of gas (OoG)
-situation could occur at the end of the planned bottom time at maximum depth. This OoG event forces
-the buddy team the share the gas of one diver and to stay at maximum depth for an additional
-time of n minutes (preferences option "problem solving time").
-At the same moment the combined SAC of both divers is increased by a estimated factor (preferences option
-"SAC factor") compared to the SAC factor of a single diver under normal conditions.
-The result of the minimum gas calculation for the bottom gas is printed to the planner output as an
-additional information. No automatic checks are performed based on this result.
-Please take care that the feature only gives valid results for simple, rectengular shaped single
-level dive profiles. For multi level dives one would need to check every leg of the profile independently.
-
+technical diving organisations. See the text below for a detailed explanation.
 
 Now you can start the detailed time-depth planning of the dive. _Subsurface_ offers an unique
 graphical interface for doing planning. The mechanics are
@@ -3744,7 +3774,7 @@ automatically to take into account this new segment of the dive plan (image B be
 
 image::images/planner1.jpg["FIGURE: Planning a dive: segments",align="center"]
 
-Below is an example of a dive plan to 55m using Tx20/30 and the B??hlmann algorithm,
+Below is an example of a dive plan to 55m using Tx20/30 and the Bühlmann algorithm,
 followed by an ascent using EAN50 and using the settings as described above.
 
 image::images/Planner_OC_deco.jpg["FIGURE: Planning a dive: setup",align="center"]
@@ -3775,7 +3805,7 @@ where the dive duration is indicated. Checking this option creates a lot of addi
 to such a degree that the planner is slower than otherwise. The information is typically
 given as:
 
-    Runtime: 53min + 0:52 /m + 4:21 /min
+    Runtime: 53min + 0:52/m + 4:21/min
 
 This indicates:
 
@@ -3786,11 +3816,23 @@ This indicates:
    would probably require that each deco stop is 10:42/53:00 = 20% longer than planned. These calculations
    are only applicable for small deviations from the dive plan, not for larger deviations.
 
+* Minimum gas requirements*
+
 The planner also estimates the *minimum gas* pressure required for safe ascent after an event that causes the dive
-to be aborted. There are two selector boxes on the left of the _Dive plan details_:
+to be aborted. The calculation assumes that in worst case an out of gas (OoG)
+situation could occur at the end of the planned bottom time at maximum depth. This OoG event forces
+the buddy team the share the gas of one diver and to stay at maximum depth for an additional
+number of minutes.
+At the same moment the combined SAC of both divers is increased by a estimated factor compared to the SAC factor of a single diver under normal conditions.
+The result of the minimum gas calculation for the bottom gas is printed to the planner output. No automatic checks are performed based on this result.
+The feature only gives valid results for simple, rectengular shaped single
+level dive profiles. For multi level dives one would need to check every leg of the profile independently.
+
+There are two selector boxes on the left of the _Dive plan details_:
 
  * *SAC factor*. This is your estimate of the degree to which your SAC increases if a critical problem arises underwater,
-   e.g. gas sharing or entanglement. Realistic values probably range from 1.5 to 3.
+   e.g. gas sharing or entanglement. Realistic values range from 2 to 5, reflecting the gas use of two divers sharing
+   a single gas cylinder after an OoG situation.
  * *Problem solving time*. This is your estimate of how long you would take to solve the problem before starting the ascent
    to terminate the dive. The default value is 2 minutes.
 
@@ -3798,15 +3840,16 @@ Using the above information, the planner then estimates what the minimum botoom
 safe ascent. This information is given near the bottom of the _Dive plan details_, following the calculation of
 bottom gas used during the dive if it exactly follows the plan. the minimum gas is typically given as:
 
-  Minimum gas (based on 2.0xSAC/+1min@81m): 2130???/90bar/??:+80bar
+  Minimum gas (based on 2.0xSAC/+1min@81m): 2130 l/90bar/Δ:+80bar
 
 This indicates:
 
  * Within parentheses, the *SAC factor* and *Problem solving time* specified.
- * The number of liters of back gas required for a safe ascent (2130??? in the example above)
+ * The number of liters of back gas required for a safe ascent (2130 litres in the example above)
  * The number of bars of back gas required for a safe ascent (90 bars in the example above).
- * The number of bars of back gas available at the end of the bottom section of the dive, _over and above_ the minimum
-   gas requirement (80 bars in the above example).
+ * The delta-value: number of bars of back gas available at the end of the bottom section of the dive, _over and above_ the minimum
+   gas requirement (80 bars in the above example). A positive delta reflects a safe plan; a negative delta indicates insufficient gas for a
+   safe ascent. 
 
 ****
 [icon="images/icons/warning2.png"]
@@ -4672,6 +4715,7 @@ Organize dive data following a few simple rules:
 3. Unit system: only one unit system should be used (no mix of imperial and metric units)
 4. Tags and buddies: values should be separated using a comma.
 5. GPS position: use decimal degrees, e.g. 30.22496 30.821798
+
 === _LibreOffice Calc_ and _OpenOffice Calc_
 
 These are open source spreadsheet applications forming parts of larger open source office suite applications. The user interaction with _LibreOffice_ and _OpenOffice_ is very similar.