On 08/04/2017 11:21, Davide DB wrote:
#2 User manual mentions user/password procedure at chapter 9 but the first time I find how to create a cloud account is at chapter 5.4.1. "Storing and and using GPS locations using Subsurface-mobile". Then at Chapter 8 it explain how to export your dives to Facebook. IMHO order of importance is completely wrong: 9. "Keeping a Subsurface dive log in the Cloud" and 9.1. "Create a cloud storage account" should be the first mention. Even if i don't read the user manual sequentially as a novel, I would expect to find as the first search occurrence. Instead the first occurence speak about Subsurface mobile that (AFAIK) it's not compulsory to use the cloud. I would expect a sequence like: 1) configure completely Subsurface desktop 2) configure other apps
davide
[PATCH] Update user manual with more explicit information about the Internet setup requirements for different Subsurface services. Signed-off-by: Willem Ferguson <[email protected]> Some context about this patch. I am very open to suggestions and/or alternative points of view on these topics. My general approach with the user manual has been to start with the simple operations first, then move to more advanced topics. This means one should be able to start using Subsurface more or less with the default configuration, only altering the Preferences or setup when more advanced use of the software requires this. For this reason I do not currently deal with the Preferences (e.g. involving network setup, multigas options, dive planner, etc) before the user has even read the part of the manual to create a new dive log. For me, this would be totally confusing. My approach has been to only refer to the Preferences when required and only to the extent for performing a specific function with Subsurface being discussed at a particular place in the user manual. So, the general flow goes from: 1) Creating a dive log 2) Adding dives to a dive log (None of the above are critically dependent on any Preference settings) 3) Entering more advanced information for the dive log, e.g. coordinates and photos. 4) Logging more advanced types of dives e.g. multigas or CCR dives. (only when dealing with these types of topics do Prefences become relevant) Attached is a patch that I hope improves the text so the the problems that Davide encountered are more or less solved. I did this by expanding some of the text at places in the user manual where the Preferences options are referenced. I hope this is acceptable. Any comments welcome. Kind regards, willem
>From 561dd70226d8857727270c08dc5a7014731aa864 Mon Sep 17 00:00:00 2001 From: Willem Ferguson <[email protected]> Date: Sun, 9 Apr 2017 12:46:54 +0200 Subject: [PATCH 2/2] [PATCH] Update user manual with more explicit information about the Internet setup requirements for different Subsurface services. Signed-off-by: Willem Ferguson <[email protected]> --- Documentation/user-manual.txt | 79 +++++++++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 17 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 656b4f0..f7249af 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1319,8 +1319,22 @@ a smaller file to make sure everything works. === Importing Dive coordinates from a mobile device with GPS. -A smartphone with built-in GPS facilities can be used to store the locations of dives. -This is performed by: +A smartphone with GPS facilities as well as Internet access can be used to store the locations of dives. +The general mechanism is as follows: + +- Dive site coordinates are collected and stored locally by the smartphone. + +- These co-ordinates are transfered from the smartphone to the _Subsurface_ Internet server. + +- When using _Subsurface_-desktop, one can find the coordinates of existing dive sites by + downloading the coordinates that have been stored on the _Subsurface_ Internet server. + +For this mechanism to work, both the smartphone and _Subsurface_-desktop must have access to the +_Subsurface_ Internet server. Select _File -> Preferences -> Network_ and set up the appropriate +Proxy parameters for _Sunsurface_-desktop to connect to the Internet. See xref:S_Network_preferences[Setting Network Preferences]. +In addition, the smartphone as well as _Subsurface_-desktop need access to the _Subsurface_ Internet site, discussed below. + +Obtaining dive site coordinates is achieved by: 1) Taking the mobile device along on the dive boat / liveabord while automatically collecting dive site coordinate information. @@ -1330,7 +1344,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). @@ -1365,11 +1379,20 @@ _Subsurface_ Internet server to the e-mail address that has been provided. Type the PIN into the appropriate text field in the Credentials screen (see image below). The _Subsurface_ Internet server notifies the user that a new user has been registered. -*N.B.:* To successfully create a user account, the mobile device must have Internet connectivity, -either through the cellular network or via wifi. +[icon="images/icons/important.png"] +[IMPORTANT] +To successfully create a user account, the mobile device must have Internet connectivity, +either through the cellular network or via wifi. If the login data have been lost, send an e-mail to +mailto:[email protected][our mailing list] requesting this information to be sent to your +e-mail address. Due to problems with hackers, users cannot currently reset or recover their login details. image::images/MobileCredentials.jpg["FIGURE: Subsurface-mobile, credentials screen",align="center"] +In addition, _Subsurface_-desktop needs to be initialised with the same e-mail address and password +obtained obtained in the _Subsurface-mobile_ Credentials screen, decribed in the section on +xref:S_Network_preferences[Setting Network Preferences]. This allows both smartphone and _Subsurface_desktop +to access the same account on the _Subsurface_ Internet server in order to pass coordinates from +smartphone to _Subsurface_desktop. ===== Configure auto-collecting of GPS coordinates @@ -1434,11 +1457,12 @@ synchronising this information. ==== Importing GPS coordinates with the _Subsurface Companion App_ for mobile phones Using the *Subsurface Companion App* on an _Android device_ or -xref:S_iphone[_iPhone_] with GPS, the coordinates +xref:S_iphone[_iPhone_] with GPS and Internet access, the coordinates for the diving location can be automatically passed to the _Subsurface_ dive log. The Companion App stores dive locations on a dedicated Internet server. _Subsurface_ can collect the locations from the server. + To do this: ===== Create a Companion App account @@ -1452,6 +1476,13 @@ To do this: or from https://f-droid.org/repository/browse/?fdfilter=subsurface&fdid=org.subsurface[F-Droid]. +In addition, _Subsurface_-desktop needs to be initialised with the same *DIVERID* +obtained obtained during the above registration process, as decribed in the section on +xref:S_Network_preferences[Setting Network Preferences]. This allows both smartphone and _Subsurface_-desktop +to access the same account on the _Subsurface_ Internet server in order to pass coordinates from +Companion App to _Subsurface_-desktop. The http://api.hohndel.org/login/[_Subsurface companion web page_] +allows one to recover lost login information. + ===== Using the Subsurface companion app on an Android smartphone On first use the app has three options: @@ -1463,7 +1494,7 @@ On first use the app has three options: activate the account. * _Retrieve an account._ If you forget your *DIVERID* you will receive an email - to recover the ID string. + to recover the *DIVERID* string. * _Use an existing account._ You are prompted for your *DIVERID*. The app saves this *DIVERID* and doesnât ask for it again unless you use the _Disconnect_ menu @@ -2823,6 +2854,9 @@ There are two ways to export dive information from Subsurface: [[S_Facebook]] === Exporting dive information to _Facebook_ +For exporting dives to the Internet, an Internet connection is required. Select and specify the +appropriate proxy settings as explained in the xref:S_Network_preferences[Network Preferences] dialog. + Export of dives to _Facebook_ is handled differently from other types of export because a connection to _Facebook_ is required, needing a _Facebook_ userID and password. From the *Main Menu*, select _Share on -> Connect to -> Facebook_ (image *A* below) @@ -2956,14 +2990,14 @@ log from anywhere in the world. For this reason, facilities such as _divelogs.de dive log information on the Internet. _Subsurface_ includes access to a transparently integrated cloud storage -back end that is available to all Subsurface users. Storing and retrieving a dive log +back end that is available free of charge to all Subsurface users. Storing and retrieving a dive log from the cloud is no more difficult than accessing the dives on the local hard disk. The only requirement is that you should first register as a user on the cloud. To use _Subsurface cloud storage_ , follow these steps: === Create a cloud storage account -** Open the *Network Preferences* by selecting _File_ -> _Preferences_ -> _Network_. +** Open the the xref:S_Network_preferences[Network Preferences] dialog by selecting _File_ -> _Preferences_ -> _Network_. ** In the section headed _Subsurface cloud storage_, enter an email address that _Subsurface_ can use for user registration. ** Enter a novel password that _Subsurface_ will use to store the @@ -2971,11 +3005,10 @@ To use _Subsurface cloud storage_ , follow these steps: ** Click _Apply_ to send the above email address and password to the (remote) cloud server. The server responds by sending a verification PIN to the above email address (This is the *only* occasion that _Subsurface_ uses the - email address provided above). The *Network Preferences* dialog now has a new PIN text + email address provided above). The xref:S_Network_preferences[Network Preferences] dialog now has a new PIN text box, not visible previously. -** Enter the PIN in the corresponding text box in the *Network Preferences* dialog -(this field is only visible while the server is waiting for email -address confirmation) +** Enter the PIN in the corresponding text box in the xref:S_Network_preferences[Network Preferences] dialog +(this field is only visible while the server is waiting for email address confirmation) ** Click _Apply_ again. The _Subsurface cloud storage_ account will be marked as verified and the _Subsurface cloud storage_ service is initialised for use. @@ -3340,13 +3373,13 @@ effect*. In this section also specify appropriate date and time formats for showing dive details. +[[S_Network_preferences]] === Network This panel facilitates communication between _Subsurface_ and data sources on the Internet. This is important, for instance, when _Subsurface_ needs to communicate with web services such as Cloud storage, the <<S_Companion,_Subsurface Companion app_>> or when you want to communicate through a proxy. - image::images/Pref5_f23.jpg["FIGURE: Preferences Network page",align="center"] This dialogue has three sections: @@ -3368,9 +3401,21 @@ from your ISP. - _Save password locally_: This allows local storage of the cloud storage password. Note that this information is saved in raw text form, not encoded in any way. -** _Subsurface web service_: When you subscribe to the <<S_Companion,Subsurface web service>>, a very - long and hard-to-remember userID is issued. This is the place to save that userID. By - checking the option _Save User ID locally?_, you ensure a local copy of that userID is saved. +[icon="images/icons/important.png"] +[IMPORTANT] +To successfully create a user account, _Subsurface_ must have Internet connectivity. If the login data for +the cloud service or for _Subsurface-mobile_ access to the cloud have +been lost, send an e-mail to +mailto:[email protected][our mailing list] requesting this information to be sent to your +e-mail address. Due to problems with hackers, users cannot currently reset or recover their login details. + + +** _Subsurface web service_: When you subscribe to the <<S_Companion,Subsurface Companion service>> by + using the Companion App, a very + long and hard-to-remember *DIVERID* is issued. This is the place to save that *DIVERID*. By + checking the option _Save User ID locally?_, you ensure a local copy of that *DIVERID* is saved. Lost + login information for the Companion App can be recovered by accessing the + http://api.hohndel.org/login/[_Subsurface companion web page_]. === Georeference -- 2.7.4
_______________________________________________ subsurface mailing list [email protected] http://lists.subsurface-divelog.org/cgi-bin/mailman/listinfo/subsurface
