User manual updates

Update:
1) Text dealing with SmartTrak import. Move text, some corrections,
   add image.
2) Text dealing with command-line arguments.

A few other small changes.

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

1 files changed, 96 insertions, 66 deletions

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index e5fc49faa..5cdd1b2d6 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1054,6 +1054,76 @@ using _www.divelogs.de_ as a gateway to extract the dive log information.
    from _divelogs.de_ to _Subsurface_, using the instructions below.
 
 
+[[S_SmartTrakImport]]
+==== Importing Scubapro _SmartTrak_ divelogs
+
+_SmartTrak_ stores the raw data from a Uwatec/Scubapro dive computer along with a plethora
+of other data manually added by the user, ranging from dive points to buddies data or DAN survey
+info. However, this is Microsoft Windows-based propietary software by Uwatec (today Scubapro)
+using Microsoft Access databases, preventing the integration the importer into the _Subsurface_
+core application.
+
+A stand alone tool for Linux has been developed to import the _.slg_ files
+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_.
+
+Feel free to contact the _Subsurface_ development team on mailto:subsurface@subsurface-divelog.org[our mailing list]
+for assistance in importing _SmartTrak_ dive logs.
+
+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).
+- Generate with [c] and save and exit with [g].
+- Build as you prefer, using the _build.sh_ script (recomended) or moving to build
+  directory and running _make_.
+- After a successful build, there will be an executable named _smtk2ssrf_ in the
+  _subsurface/build_ directory.
+  Copy or move it to a directory in your $PATH, e.g. _~/bin_.
+
+===== Running
+
+_smtk2ssrf_ accepts 0, 2 or more parameters. If it is launched without
+parameters in a graphical user interface, a simple window
+opens for choosing the _.slg_ file(s) to import and a destination file to store the
+_Subsurface_-formatted data into (see image below).
+
+image::images/smtk2ssrf.jpg["FIGURE:Download from SmartTrak",align="center"]
+
+[icon="images/icons/warning2.png"]
+[WARNING]
+Existing data in the destination file will be
+erased, so *DO NOT* use a regular subsurface divelog file as a destination:
+rather, specify a *new* filename as a destination.
+
+If launched from a command line with two or more parameters, the format is as follows:
+
+	$ smrtk2ssrf /input/file_1.slg /input/file_2.slg /output/file3.xml
+
+where _input_ is the directory containing the .slg file(s) and _output_ is the
+directory where the _Subsurface_-formatted output is written to.
+Files _file_1.slg_ and _file_2.slg_ in the _input_ directory are imported and stored
+in _file3.xml_ in the _output_ directory. Check any warning and error messages
+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.
+
+===== 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.
+If everything is fine, close the _.xml_ file and open your regular divelog.
+Then from the *Main Menu* select _Import -> Import log file_ and choose the
+_.xml_ file containing the imported dives: these will show in the *Dive List*, time
+ordered, along with the existing dives.
+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.
+
 [[S_ImportingDivelogsDe]]
 ==== Importing dives from *divelogs.de*
 
@@ -1231,7 +1301,6 @@ of the dives into _Subsurface_.
 
 ****
 
-
 [icon="images/icons/important.png"]
 [IMPORTANT]
 But, the _CSV_ import has a couple of caveats. Avoid some special characters
@@ -1243,70 +1312,6 @@ size of the _CSV_ file might cause problems. Importing 100 dives at a time
 the limits of the parser used. When encountering problems with _CSV_ imports, first try with
 a smaller file to make sure everything works.
 
-[[S_SmartTrakImport]]
-==== Importing SmartTrak divelogs
-
-SmartTrak is a Windows based propietary software by Uwatec (today Scubapro).
-It works through Access databases, which makes it difficult to integrate the
-importer in _Subsurface_ core application, and stores the full raw data from
-the DC along with a plethora of other data manually added by the user, ranging
-from dive points to buddies data or DAN survey info.
-
-A little stand alone tool has been developed to import the .slg files
-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.
-
-Assuming installed those dependencies and _Subsurface_ source tree placed in a
-directory like ~/src/subsurface, then:
-
-*BUILDING*
-
-- Move to the source tree directory.
-- Run  " $ ccmake build " and set SMARTTRAK_IMPORT option to *on* (off by
-  default).
-- Generate with [c] and save and exit with [g].
-- Build as you prefer, using build.sh script (recomended) or moving to build
-  directory and running make.
-- After a successful build, there will be an executable in the build directory
-  named smtk2ssrf, copy or move it to a directory in your $PATH, e.g. ~/bin
-
-*RUNNING*
-
-smtk2ssrf accepts 0, 2 or more parameters. If it's launched without
-parameters and you are on a graphical environment a simple window will be
-displayed letting you choose the file(s) to import and a file to store the
-subsurface formatted data.
-
-[icon="images/icons/warning2.png"]
-[WARNING]
-Previous data in the output file will be
-erased, so *DO NOT* use your regular subsurface divelog file as output. It's
-advisable to set a brand new file to do the import.
-
-If launched from command line with 2 or more parameters like:
-
-	$ smrtk2ssrfc /input/file_1.slg /input/file_2.slg /output/file.xml
-
-Files file_1.slg and file_2.slg in input directory will be imported and stored
-in file.xml in output directory.
-
-Check warning and error messages in console or graphical window, some may be
-interesting, as support for Galileo and family DCs is still a work in
-progress.
-
-*MERGING*
-
-Open the brand new imported file in _Subsurface_ and check the dives and data.
-If everything is fine, close the .xml file and open your regular divelog.
-Then from _Main menu_ select _Import -> Import log file_ and choose the
-imported .xml file.  The imported dives will show in the _Dive List_, time
-ordered, along with the previous dives.
-The new dives, although time ordered, will keep the numbering system from
-SmartTrak, so a renumbering action is needed. See xref:S_Renumber[Renumbering
-the dives] section in this manual for instructions about this topic.
-
-
 === 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.
@@ -3012,9 +3017,11 @@ _Open_ button.
 Several paid services exist on the Internet (e.g. Google, Amazon) where the same
 process could be used for the Cloud-based storage of dive logs.
 
+[[S_user_space]]
 == Several _Subsurface_ users on one desktop computer
 A frequent need is for two or more persons to use _Subsurface_ on the same desktop computer. For instance
-members of a household may use the same computer. There are two approaches for doing this.
+members of a household may use the same computer or one family member may perform dive uploads for other
+family members/friends. There are two approaches for doing this.
 
 *A)* If the different users of a desktop computer do not log onto the desktop/laptop under different user names
   then the simplest way is for each person to use her/his own divelog file within Subsurface. In this case John
@@ -3767,6 +3774,29 @@ The text version of the dive plan is appended to the Notes in the _Notes Tab_. W
 merged dive highlighted in the _Dive List_, switch
 between the planned profile and the real-life profile using the righ-arrow/left-arrow keyboard keys.
 
+== Running _Subsurface_ from the command-line
+_Subsurface_ can be launched from the command-line to set some specialised settings or as
+part of an script-based automated process for manipulating a dive log. The format for launching _Subsurface_ from the
+command-line is:
+
+	subsurface [options] [logfile ...] [--import logfile ...]
+
+The options include:
+|====================
+|*Command-line option*|*Description*
+|--help|Print a summary of the command-line options
+| -h|Print a summary of the command-line options
+|--import logfile ...|A file name before this option is treated as an existing dive log, everything after is imported into the existing dive log
+|--verbose|Print debug information while running _Subsurface_
+| -v|Print debug information while running _Subsurface_
+| -v -v| Print even more debug information while running _Subsurface_
+|--version|Prints the current version of _Subsurface_.
+|--survey|Opens the xref:S_UserSurvey[user survey] immediately after starting _Subsurface_
+|--user=<username>|Choose the xref:S_user_space[configuration space] of user <username>
+|--cloud-timeout=<duration>|Set the timeout for cloud connection (0 < duration < 60). This enables longer timeouts for slow Internet connections
+|--win32console|Create a dedicated console if needed (Windows only). Add this option before everything else
+|====================
+
 == Description of the Subsurface Main Menu items
 
 This section describes the functions and operation of the items in the Main Menu