User manual: Minor updates

Minor update of manual for consistency in terminology and improved style
including the section describing the companion app. No images were affected.

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

Documentation/user-manual.txt

@@ -4,7 +4,7 @@
 // Linus Torvalds, Miika Turkia, Amit Chaudhuri, Jan Schubert, Willem
 // Ferguson, Salvador Cuñat
 // :revnumber: 4.1
-// :revdate: April 2014
+// :revdate: May 2014
 :icons:
 :toc:
 :toc-placement: manual
@@ -18,7 +18,7 @@ image::images/Subsurface4Banner.png["Banner",align="center"]
 *Manual authors*: Willem Ferguson, Jacco van Koll, Dirk Hohndel, Reinout Hoornweg,
 Linus Torvalds, Miika Turkia, Amit Chaudhuri, Jan Schubert,  Salvador Cuñat
 
-[blue]#_Version 4.1,  April 2014_#
+[blue]#_Version 4.1,  May 2014_#
 
 
 Welcome as a user of _Subsurface_, an advanced dive logging programme with
@@ -1024,18 +1024,19 @@ appear in the *Dive List* area of _Subsurface_.
 
 
 [[S_Companion]]
-=== Importing GPS coordinates with the *Subsurface Companion App* for mobile phones
+=== Importing GPS coordinates with the _Subsurface Companion App_ for mobile phones
 
-If the user has an Android device with GPS, the coordinates for the diving
+Using the *Subsurface Companion App* on an Android device with a GPS, the coordinates
-location can be obtained and automatically passed to the _Subsurface_
+for the diving
-divelog. This takes place when the Companion App stores the dive locations on
+location can be automatically passed to the _Subsurface_
+divelog. The Companion App stores the dive locations on
 a dedicated Internet-based file server. _Subsurface_, in turn, can collect
 the localities from the file server.
 
-To do this, one needs to:
+To do this:
 
-- Register on the http://api.hohndel.org/login/[Subsurface companion web page].
+- Register on the http://api.hohndel.org/login/[_Subsurface companion web page_].
-A confirmation mail with instructions and a personal *DIVERID* will be send together with
+A confirmation email with instructions and a personal *DIVERID* will be send together with
 a long number that gives access to the file server and Companion App capabilities.
 
 - Download the app from
@@ -1049,7 +1050,7 @@ http://f-droid.org/repository/browse/?fdfilter=subsurface&fdid=org.subsurface[F-
 On first use the app has three options:
 
 * _Create a new account._  Equivalent to registering in _Subsurface_ companion
-page.
+page using an Internet browser.
 
 * _Retrieve an account._  If users forgot their DIVERID they will receive an email
 to recover the number.
@@ -1061,14 +1062,14 @@ option (see below).
 Now one is ready to get a dive position and send it to the server. The Android
 display will look like the left hand image (*A*) below, but without any dive.
 
-Touch the "+" icon on the top right to add a new dive site. Users will be
+Touch the "+" icon on the top right to add a new dive site, resulting in a prompt
-prompted for a place name (or asked to activate the GPS if it is turned off).
+for a place name (or a request to activate the GPS if it is turned off).
 The main screen shows a list of dive locations, each with a name, date and
-time. Some dives may have an arrow-up icon on the selection box to the left (see
+time. Some locations may have an arrow-up icon on the selection box to the left (see
 image B in the middle, below) indicating that they require upload to the server.
 
-There are several ways to send dives to the server; the easiest is by simply
+There are several ways to send locationd to the server; the easiest is by simply
-selecting the dive. See middle image below (*B*):
+selecting the location. See middle image below (*B*):
 
 image::images/Companion.jpg["FIGURE: Screen shots (A-C) of companion app",align="center"]
 
@@ -1076,24 +1077,24 @@ Touching the right arrow will send it to the server.
 
 [icon="images/icons/important.png"]
 [IMPORTANT]
-Users must be careful, as the trash icon on the right means exactly what it is supposed to mean,
+Users must be careful, as the trash icon on the right means exactly what it should mean:
 it deletes the dive location(s).
 
-The new dive points are now stored on the server and can be downloaded to the
+New dive locations are now stored on the server and can be downloaded to the
 _Subsurface_ dive log whenever users upload or add dives to _Subsurface_.
-After a dive trip using the Companion app, all dive locations are ready to be
+After a dive trip using the Companion App, all dive locations are ready to be
 saved on a _Subsurface_ dive log (see below).
 
 When you click on a dive (*not* selecting the check button as shown in the images above), the
-name given to it, date/time and GPS coordinates will be shown, and you'll have two options:
+name given to it, date/time and GPS coordinates will be shown, with two options:
 
-- Edit:  Lets you change the name given to the dive point.
+- Edit:  Change the text name of the dive location.
 
-- Maps:  Will display a map showing the dive location (you'll be prompted to
+- Maps:  Display a map showing the dive location (you'll be prompted to
-choose which helper app use from your installed apps). At this date this feature is
+choose which helper app use from your installed apps). Currently this feature is
-a bit of a proof of concept, is expected to be fully functional soon.
+non fully functional, but is under active development.
 
-If you edit the dive, after saving it, you'll need to upload it to the web
+After editing and saving a dive location, one needs to upload it to the web
 service, as explained above.
 
 ===== Settings on the Companion app
@@ -1104,42 +1105,42 @@ Selecting the _Settings_ menu option results in the right hand image above (*C*)
 
 - _Web-service URL._ This is predefined (http://api.hohndel.org/)
 
-- _User ID._ Obtained by registering as indicated above. The easiest way to
+- _User ID._ The DIVERID obtained by registering as described above. The easiest way to
-obtain it is simply to copy and paste from the confirmation mail but, of
+obtain it is simply to copy and paste from the confirmation email but, of
 course, users can also type this information.
 
 ===== Synchronization
 
-- _Synchronize on startup._ If selected, dives in the Android device and those
+- _Synchronize on startup._ If selected, dive locations in the Android device and those
-on the web service will synchronize each time the app is started.
+on the web service synchronize each time the app is started.
 
-- _Upload new dives._ If selected, each time the user adds a dive location it will
+- _Upload new dives._ If selected, each time the user adds a dive location it is
-automatically be sent to the server.
+automatically sent to the server.
 
 ===== Background service
 Instead of entering a unique dive location, users can leave the service running
-in the background of their device, thus allowing the continuous collection of GPS locations.
+in the background of their Android device, allowing the continuous collection of GPS locations.
 
 
 The settings below define the behaviour of the service:
 
-- _Min duration._ In minutes. The app will try to get a position each X minutes
+- _Min duration._ In minutes. The app will try to get a location every X minutes
-until it's stopped by the user.
+until stopped by the user.
 
-- _Min distance._ In meters. Minimum distance between two position fixes.
+- _Min distance._ In meters. Minimum distance between two locations.
 
-- _Name template._ The name the app will use when saving the position fixes.
+- _Name template._ The name the app will use when saving the locations.
 
 [icon="images/icons/info.jpg"]
 [TIP]
-_How does the background service work?_ Assuming that the user set 5 minutes and 50
+_How does the background service work?_ Assuming the user sets 5 minutes and 50
-meters in the settings above, the app will start by taking a fix at the current
+meters in the settings above, the app will start by recording a location at the current
-location, followed by another one at every 5 minutes *or* every time you move 50m
+location, followed by another one at every 5 minutes *or* every time one moves 50m
-from previous fix.
+from previous location.
 If subsequent locations are within a radius of 50 meters from the previous one,
-then this new fix is not saved. If the user is not moving, only one fix is saved,
+a new location is not saved. If the user is not moving, only one location is saved,
-but if the user is moving, then a trace of the journey is obtained, by saving a
+but if the user is moving, a trace of the route is obtained by saving a
-position every 50 meters.
+location every 50 meters.
 
 ===== Other
 
@@ -1148,23 +1149,23 @@ Subsurface mailing list.
 
 - _Subsurface website._ A link to the URL of Subsurface web
 
-- _Version._ Displays the current version of the companion app.
+- _Version._ Displays the current version of the Companion App.
 
 ===== Search
 
-Here one can search one's saved dive locations by the name or by date and hour.
+Search the saved dive locations by name or by date and time.
 
 ===== Start service
 
-Initiates the _background service_ depending on the previously defined settings.
+Initiates the _background service_ following the previously defined settings.
 
 ===== Disconnect
 
-This is a badly named option. It disconnects the app from the server by
+This is a badly named option that disconnects the app from the server by
 resetting the user ID in the app, showing the first screen where an account
 can be created, retrieve the ID for an existing account or use the users own
 ID. The disconnect option
-is useful if a user's Android device was used to download the dive positions
+is useful if a user's Android device was used to download the dive locations
 of another registered diver.
 
 ===== Send all locations
@@ -1178,51 +1179,48 @@ Download dive(s) from a dive computer or enter them manually into
 _Subsurface_ before obtaining the GPS coordinates from the server. The download
 dialog can be reached via _Ctrl+G_ or from the _Subsurface_ Main Menu _Import
 -> Import GPS data from Subsurface Service_, resulting in the image on the
-left (*A*), below. On first use the DIVERID text box will be blank. Users must provide their
+left (*A*), below. On first use the DIVERID text box is blank. Provide a
-DIVERID and then select the _Download_ button to initiate the download process. When this
+DIVERID, then select the _Download_ button to initiate the download process, after
-is completed, users will see the screen on the right (*B*), below:
+which the screen on the right (*B*) below appears:
 
 image::images/DownloadGPS.jpg["FIGURE: Downloading Companion app GPS data",align="center"]
 
 Note that the _Apply_ button is now active. By clicking on it, users can update the locations
 of the newly entered or uploaded dives in _Subsurface_ which applies the
 coordinates and names entered on the app for all the new dives that match the
-date-times of the uploaded GPS localities. If you had entered the name of the dive
+date-times of the uploaded GPS localities. If one has entered the name of the dive
-location in _Subsurface_ before downloading the GPS coordinates, this one will take
+location in _Subsurface_ before downloading the GPS coordinates, this name will take
 precedence over downloaded one.
 
 Since _Subsurface_ matches GPS locations from the Android device and dive information from the
 dive computer based on date-time data, automatic assignment of GPS data to dives is dependent
-on agreement of date and time between these two devices. If there is a large difference between
+on agreement of the date-time information between these two devices. Although _Subsurface_ has
-the time in the dive computer and the time in the Android device, although _Subsurface_ has a
+a wide range tolerance, it may be unable to identify the appropriate dive if there is
-wide range tolerance, it may be unable to identify the dive matching a location and nothing
+a large difference between the time in the dive computer and that of the Android device,
-happens.
+resulting in no updates.
 
-Similar date-times may not always be possible, and there may be many different reasons for this, or
+Similar date-times may not always be possible and there may be many reasons for this (e.g. time zones), or
 _Subsurface_ may be unable to decide which is the correct position for a dive (e.g. on repetitive
-dives while running _background service_ you may end with a lot of position fixes that would be
+dives while running _background service_ there may be several locations that would be
-included in the time range that fit not only for first dive, but for second too).
+included in the time range that fit not only the first dive, but one or more subsequent dives as well).
-
+A workaround for this situation to manually edit the date-time of a dive in the _Subsurface_
-A workaround for this situation is manually editing the date-time of a dive in Subsurface's
+Dive List *before* downloading the GPS data and then to change the date-time back again *after*
-Dive List _before_ downloading the GPS data and then to edit the date-time back again _after_
 downloading GPS data.
 
 [icon="images/icons/info.jpg"]
 [NOTE]
 TIPS:
 
-- _Background service_, being a very powerful tool, may fill your register in web service with
+- _Background service_, being a very powerful tool, may fill the location list with
-lots of useless coordinates (those not corresponding to the exact dive point, but positions on the
+many unnecessary locations not corresponding to the exact dive point but reflecting the boat's route.
-boat's course). Right now these positions are somewhat dificult to delete from the server. Although
+Currently these locations are dificult to delete from the server. In some situations it
-not mandatory, as Subsurface's logic will choose the correct dive position, in some situations it
+is therefore prudent to clean up the list on the Android device before sending the dive points to the web
-may make sense to clean up the list on your android device before sending the dive points to the web
+server by simply deleting the inappropriate locations. This might be necesary, for
-server, by simply deleting the "fake" positions in the device. This cleaning would be necesary, for
+instance, if one wants to keep the location list clear to see dives in the web service map display (see above).
-instace, if you want to keep your register clear to see your dives in the web service page's map.
 
-- Also it may make sense to give significant names to the dives sent to the web server, or at least
+- It may also make sense to give informative names to the locations sent to the web server, or at least
-to use a significant name in the _Name Template_ setting while running _background service_,
+to use an informative name in the _Name Template_ setting while running the _background service_,
-especially if you are on a dive trip and you are piling up lots of dives and dive points waiting to
+especially on a dive trip with many dives and dive locations.
-come back home to download them to _Subsurface_.
 
 == Obtaining more information about dives entered into the logbook