From 75b2fcc4a4b7e5a18ad73db30d64cd37717d79a8 Mon Sep 17 00:00:00 2001 From: Dirk Hohndel Date: Fri, 4 Mar 2022 12:03:46 -0800 Subject: [PATCH] user-manual: update the bundled html version This is used if someone builds from source and doesn't have asciidoc installed. Signed-off-by: Dirk Hohndel --- Documentation/user-manual.html.git | 179 +++++++++++++++++++++-------- 1 file changed, 130 insertions(+), 49 deletions(-) diff --git a/Documentation/user-manual.html.git b/Documentation/user-manual.html.git index 3c55574ee..b3551c73e 100644 --- a/Documentation/user-manual.html.git +++ b/Documentation/user-manual.html.git @@ -642,7 +642,7 @@ Spreadsheet or CSV files containing dive profiles.

This is usually the approach for dives without a dive computer. The basic record of information within Subsurface is a dive. The most important information in a simple dive logbook usually includes dive type, date, time, duration, -depth, the names of your dive buddy and the divemaster or dive guide, and +depth, the names of your dive buddy and the dive guide, and some remarks about the dive. Subsurface can store much more information for each dive. To add a dive to a dive log, select Log → Add Dive from the Main Menu. The program then shows three panels @@ -1163,12 +1163,11 @@ you might like to call one "Alice’s Suunto D4" and the other "Bob’s Suunto D4". Alternatively, consider a technical diver who dives with two or more dive computers of the same model, the logs of both (or all) being uploaded. In this case it might be prudent to call one of them -"Suunto D4 (1)" and another "Suunto D4 (2)". This is easily done in Subsurface. -On the Main Menu, select Log → Edit device names. A dialog box opens, showing the -current Model, ID and Nickname of the dive computers used for upload. Edit the Nickname -field for the appropriate dive computer. After saving the Nickname, the dive logs -show the nickname for that particular device instead of the model name, -allowing easy identification of devices.

+"Suunto D4 (1)" and another "Suunto D4 (2)".

+

To achieve this, display a dive downloaded from this dive computer, right click on its name +in the profile and select the option to set a new nickname. If this option isn’t shown, then +Subsurface cannot reliably identify this specific dive computer (not all models support this +feature, but most modern ones do).

4.2.4. Uploading data for a specific dive from more than one dive computer

@@ -1209,7 +1208,7 @@ increase in the amount of information stored for a dive.

The Notes tab holds basic information about the dive, the date and time, locality, -buddy, divemaster and some dive notes. This is about the minimum amount of +buddy, dive guide and some dive notes. This is about the minimum amount of information required for a coherent dive log.

@@ -1285,7 +1284,7 @@ to a specific dive and changes to multiple dives can be undone.

Dive locations are managed as a separate part of the dive log (See the section entitled Manipulating Dive Site Information). The dive information in the Notes and Equipment tabs can therefore NOT be edited at the same time as the dive site information. Save all the other dive information (e.g. -divemaster, buddy, protective gear, notes about the dive) by selecting Apply changes on the +dive guide, buddy, protective gear, notes about the dive) by selecting Apply changes on the Notes tab BEFORE editing the dive site information. Then supply a dive site name in the textbox labelled Location on the Notes tab. @@ -1496,9 +1495,8 @@ The dive site information can later be edited by clicking the globe icon to the dive site name in the Notes tab.

Having entered information about the dive site into the Notes tab, the following additional information can be typed in:

-

Divemaster: The name of the divemaster or dive guide should be -entered in this field -which offers auto selection based on the list of divemasters in +

Dive guide: The name of the dive guide should be entered in this field +which offers auto selection based on the list of dive guides in the current logbook.

Buddy: In this field, enter the name(s) of the buddy or buddies (separated with commas) who were on the @@ -1773,7 +1771,7 @@ and gas composition). Other fields remain empty. It may be useful to simultaneously edit some of the fields in the Notes and Equipment tabs. For instance, it’s possible that a diver performed several dives during a single day, using identical equipment at the same -dive site, or with the same divemaster and/or buddy or tags. Instead +dive site, or with the same dive guide and/or buddy or tags. Instead of completing the information for each dive separately, select all the dives for that day in the Dive List and insert the same information in the Notes and Equipment fields that need @@ -2217,7 +2215,7 @@ columns, followed by the data, one record per line.

CSV dive details: This dive log format contains similar information to that of a typical written dive log, e.g. dive date and time, dive depth, dive duration, names of - buddy and divemaster and information about cylinder pressures before and + buddy and dive guide and information about cylinder pressures before and after the dive, as well as comments about the dive. All the data for a single dive go on a single line of text, following the order of the column headings.

@@ -3840,7 +3838,7 @@ restored to view by selecting Unhide all events from the context menu.

5.6. Filtering the dive list

The dives in the Dive List can be filtered, selecting only some -of the dives based on attributes such as dive tags, dive site, divemaster or buddy. +of the dives based on attributes such as dive tags, dive site, dive guide or buddy. For instance, filtering lets you list the dives during a particular year at a specific dive site, or otherwise the cave dives with a particular buddy. Filtering can be performed based on virtually any information in the Info panel.

@@ -4466,7 +4464,7 @@ Universal Dive Data Format (UDDF). Refer to http://uddf.org fo

When the "Anonymize" option is selected for xml-based file formats, the letters A-Z -are all replaced by the letter X in the notes, buddy, divemaster, divesite name +are all replaced by the letter X in the notes, buddy, dive guide, divesite name and divesite description fields. This way, you can share dive log files for debugging purposes without revealing personal information. Please note, though, that other characters are not replaced, so this is not useful for languages with non-latin @@ -7557,8 +7555,7 @@ explained on the section Importing CSV dives.

20. APPENDIX E: Writing a custom print template

Subsurface has a way to create or modify templates for printing dive logs to -produce customized printouts of them. Templates written in HTML, as well as a simple -Grantlee instruction set, are rendered to the print device by Subsurface.

+produce customized printouts of them. Templates written in HTML are rendered to the print device by Subsurface.

Templates are accessed using the print dialog (see image B below).

@@ -7581,14 +7578,11 @@ a template, select one of the templates from the template dropdown list in the p

2) The Colors tab (image B above) allows editing the colors used for printing the dive log. The colors are highly customizable: the Edit buttons in the Colors tab allows choosing arbitrary colors for different components of the dive log printout.

-

3) The Template tab of the Edit Panel (see image below) allows creating a template using HTML as well as a few - Grantlee programming primitives. Grantlee can create and format HTML code in - a highly simple but efficient way (see below). The HTML of the template can be edited and saved. The saved - template is stored in the same directory as the dive being processed. By default, a Custom - template is a skeleton with no specific print instructions. The information printed - needs to be specified and formatted in the template by replacing the section marked with: - "<!-- Template must be filled -→". Writing HTML code with Grantlee instructions allows unlimited - freedom in determining what is printed and in which way it should be rendered.

+

3) The Template tab of the Edit Panel (see image below) allows creating a template using HTML. The HTML of the + template can be edited and saved. The saved template is stored in the same directory as the dive being processed. + By default, a Custom template is a skeleton with no specific print instructions. The information printed needs to + be specified and formatted in the template by replacing the section marked with: + "<!-- Template must be filled -→".

FIGURE:Template tab @@ -7600,7 +7594,8 @@ dialog to save the new template using a new template name.

To write a custom template, the following elements must exist so the template will be correctly handled and rendered.

20.1. Main dive loop

-

Subsurface exports a dive list called (dives) to the Grantlee back end. It is possible to iterate over the list as follows: +

Subsurface exports a dive list called (dives) as well as a list of cylinders called (cylinderObjects) to the back end. It is +possible to iterate over the list as follows: .template.html

@@ -7615,10 +7610,9 @@ dialog to save the new template using a new template name.

<h1> 2 </h1> <h1> 3 </h1>
-

Additional information about Grantlee can be found here

-

20.2. Grantlee exported variables

+

20.2. Exported dive variables

Only a subset of the dive data is exported:

+ + + + + + + + + + + + + + + + + + + + + + + + @@ -7653,6 +7671,14 @@ cellspacing="0" cellpadding="4"> + + + + + + + + @@ -7669,6 +7695,10 @@ cellspacing="0" cellpadding="4"> + + + + @@ -7685,14 +7715,6 @@ cellspacing="0" cellpadding="4"> - - - - - - - - @@ -7701,6 +7723,18 @@ cellspacing="0" cellpadding="4"> + + + + + + + + + + + + @@ -7713,14 +7747,6 @@ cellspacing="0" cellpadding="4"> - - - - - - - - @@ -7755,6 +7781,61 @@ cellspacing="0" cellpadding="4">

(int) unique dive ID, should be used to fetch the dive profile

rating

(int) dive rating which ranges from 0 to 5

visibility

(int) dive visibility which ranges from 0 to 5

wavesize

(int) wave size during the dive which ranges from 0 to 5

current

(int) current during the dive which ranges from 0 to 5

surge

(int) surge during the dive which ranges from 0 to 5

chill

(int) chill during the dive which ranges from 0 to 5

date

(string) date of the dive

(string) location of the dive

gps

(string) GPS coordinates of the dive

gps_decimal

(string) GPS coordinates of the dive in decimal format

duration

(string) duration of the dive

(string) divemaster for the dive

diveguide

(string) dive guide for the dive

buddy

(string) buddy for the dive

(string) dive notes

rating

(int) dive rating which ranges from 0 to 5

sac

(string) SAC value for the dive

tags

(string) list of dive tags for the dive

(string) list of gases used in the dive

sac

(string) SAC value for the dive

weights

(string) complete information of all used weight systems

weight0-5

(string) information about a specific weight system

suit

(string) the suit used for the dive

(string) information about a specific cylinder

weights

(string) complete information of all used weight systems

weight0-5

(string) information about a specific weight system

maxcns

(string) maxCNS value for the dive
+
+
+

20.3. Exported cylinder object variables

+

Only a subset of the cylinder data is exported:

+
+ +++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Name

Description

description

(string) cylinder description

size

(string) cylinder size

workingPressure

(string) cylinder working pressure

startPressure

(string) start pressure of cylinder

endPressure

(string) end pressure of cylinder

gasMix

(string) gas mix of cylinder

gasO2

(int) oxygen percentage of gas mix

gasHe

(int) helium percentage of gas mix

gasN2

(int) nitrogen percentage of gas mix

+

Please note that some of the variables like notes need to be extended with |safe to support HTML tags:

@@ -7864,7 +7945,7 @@ cellspacing="0" cellpadding="4">
-

20.3. Defined CSS selectors

+

20.4. Defined CSS selectors

As the dive profile is placed after rendering, Subsurface uses special CSS selectors to search in the HTML output. The CSS selectors in the following table should be added.

@@ -7910,7 +7991,7 @@ in flow layout templates only (when data-numberofdives = 0)

-

20.4. Special attributes

+

20.5. Special attributes

There are two ways of rendering- either rendering a specific number of dives in each page or make Subsurface try to fit as many dives as possible into one page (flow rendering).

The data-numberofdives data attribute is added to the body tag to set the rendering mode.

@@ -8079,7 +8160,7 @@ contain twice as much air as a 200 bar one. At lower pressures, air acts pretty but then come back up and wait five minutes for your buddies, your dive computer may say that your dive is 50 minutes long - because you have fifty minutes worth of samples - but subsurface will say it’s 45 minutes - because you were actually diving for 45 minutes. -It’s even more noticeable if you do things like divemastering the initial OW dives, when +It’s even more noticeable if you do things like guiding the initial OW dives, when you may stay in the water for a long time, but spend most of it at the surface. And then you don’t want that to count as some kind of long dive”.

@@ -8108,7 +8189,7 @@ cannot be salvaged after being overwritten by new dives.