mifr/subsurface
1
0
Fork 0
mirror of https://github.com/subsurface/subsurface.git synced 2024-11-30 22:20:21 +00:00
Code Issues Projects Releases Packages Wiki Activity

User manual updates

Browse source 
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>
This commit is contained in:
Willem Ferguson 2017-01-07 13:02:23 +02:00 committed by Dirk Hohndel
parent 913fa85926
commit a6f9a37831
2 changed files with 96 additions and 66 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
Documentation/images/smtk2ssrf.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

162
Documentation/user-manual.txt
View file

@ -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