Skip to content

Commit 2256222

Browse files
committed
Update user guide content for v1.15.0
- Document GSAK database import, GGZ export/send-to-GPS, double-click to open in browser, Trackables column/tab, custom icon packs, Support OpenSAK, and the hint-decode-by-default setting - Remove stale note claiming GGZ export wasn't available yet - Fix stale 'Last updated June 2026' footer date
1 parent 1f8a71a commit 2256222

1 file changed

Lines changed: 29 additions & 10 deletions

File tree

site/user-guide.html

Lines changed: 29 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -505,7 +505,7 @@
505505

506506
<div class="nav-section-heading">Export</div>
507507
<a href="#gps">Send to GPS</a>
508-
<a href="#file-export">File Export (GPX/LOC)</a>
508+
<a href="#file-export">File Export (GPX/LOC/GGZ)</a>
509509
<a href="#kml">Export to Google Maps (KML)</a>
510510
<a href="#trip-planner">Trip Planner</a>
511511

@@ -671,6 +671,11 @@ <h3>Supported Formats</h3>
671671
<tr><td>LOC</td><td><code>.loc</code></td><td>Lightweight coordinate-only format</td></tr>
672672
</tbody>
673673
</table>
674+
675+
<h3>Importing from a GSAK Database</h3>
676+
<p>Switching from GSAK? You don't have to re-download everything as GPX first. <strong>File → Import from GSAK Database…</strong> reads a GSAK backup ZIP or a raw <code>sqlite.db3</code> file directly, bringing in caches, waypoints, attributes, corrected coordinates, personal notes, trackables, and your <strong>full log history</strong> — not capped the way a GPX/PQ export is.</p>
677+
<div class="callout note"><div class="callout-icon">ℹ️</div><div>Re-importing the same GSAK database is safe — it works the same way as a GPX re-import. Notes containing GSAK's embedded local images are replaced with <code>[image: filename.ext]</code> placeholders, since those files live on your old machine and can't travel with the database.</div></div>
678+
674679
</section>
675680

676681
<!-- ══════════════════════════════════════════════════════════ -->
@@ -702,7 +707,7 @@ <h3>Columns</h3>
702707
<div class="callout note"><div class="callout-icon">ℹ️</div><div>Cache names appear in <strong>bold</strong> when the cache has child waypoints — see the Waypoints tab in the <a href="#detail-panel">Cache Detail Panel</a>.</div></div>
703708

704709
<h3>Clicking a Cache</h3>
705-
<p>Clicking a row selects the cache: the detail panel updates to show its full information, and the map pans to its pin.</p>
710+
<p>Clicking a row selects the cache: the detail panel updates to show its full information, and the map pans to its pin. <strong>Double-clicking</strong> a row opens the cache on geocaching.com in your browser — the same as GSAK.</p>
706711

707712
<h3>Right-Click Context Menu</h3>
708713
<p>Right-clicking a cache in the list shows:</p>
@@ -731,6 +736,7 @@ <h3>Sortable Columns (examples)</h3>
731736
<tr><td>Hidden date</td><td>Date cache was placed</td></tr>
732737
<tr><td>Placed by</td><td>Cache owner name</td></tr>
733738
<tr><td>Favorite pts</td><td>Community favorite points</td></tr>
739+
<tr><td>Trackables 🐞</td><td>Number of trackables (travel bugs/geocoins) logged in the cache</td></tr>
734740
<tr><td>📍</td><td>Corrected coordinates set indicator</td></tr>
735741
<tr><td>FTF 🥇</td><td>First to Find indicator</td></tr>
736742
<tr><td>Flag 🚩</td><td>User flag for batch operations</td></tr>
@@ -751,6 +757,7 @@ <h3>Tabs</h3>
751757
<li><strong>Logs</strong> — recent logs from all finders; includes a search box to find specific entries. Links in log text are clickable.</li>
752758
<li><strong>Attributes</strong> — all Groundspeak attributes set on the cache (dogs, parking, etc.)</li>
753759
<li><strong>Notes</strong> — your own free-text notes for this cache, separate from the published description and logs. Round-trips with GSAK: a note survives export → GSAK → re-import.</li>
760+
<li><strong>Trackables</strong> — travel bugs and geocoins logged in the cache, each with a clickable <code>coord.info</code> link.</li>
754761
<li><strong>Waypoints</strong> — child waypoints belonging to this cache (e.g. parking, stages), with prefix, type, name, coordinates, description and comment for each. Caches with waypoints show their name in <strong>bold</strong> in the cache list, and the waypoints appear as separate markers on the map when the cache is selected.</li>
755762
</ul>
756763

@@ -761,7 +768,7 @@ <h3>Tabs</h3>
761768
<figcaption>The Hint tab after clicking decode — geocaching.com hints are ROT13-encoded by default.</figcaption>
762769
</figure>
763770

764-
<div class="callout note"><div class="callout-icon">ℹ️</div><div>Some hints are stored as plain text rather than ROT13 — OpenSAK detects this automatically and shows the hint directly, without a decode step.</div></div>
771+
<div class="callout note"><div class="callout-icon">ℹ️</div><div>Some hints are stored as plain text rather than ROT13 — OpenSAK detects this automatically and shows the hint directly, without a decode step. Prefer to always see hints decoded? Turn on <strong>Show hints decoded by default</strong> under <a href="#settings">Settings → Display</a>.</div></div>
765772

766773
<h3>Locking a Cache</h3>
767774
<p>Right-click a cache → <strong>Lock cache</strong>, or check the box in <strong>Edit cache…</strong>. Locking freezes the cache's own fields — name, type, container, coordinates, D/T, owner, status, descriptions, hint, country/state/county — so a later GPX/PQ re-import can't overwrite them. Logs, attributes and waypoints still refresh normally on re-import. A 🔒 column in the cache list shows locked status at a glance, and you can filter on it (see <a href="#filter-types">All Filter Types</a>).</p>
@@ -1100,9 +1107,12 @@ <h3>Sending to a Garmin Device</h3>
11001107
<li>Select <em>Send directly to GPS device</em>.</li>
11011108
<li>Click <strong>🔍 Scan</strong> to detect mounted Garmin devices.</li>
11021109
<li>Select your device from the list.</li>
1110+
<li>Choose a format — <strong>GPX</strong> or <strong>GGZ</strong> (see below).</li>
11031111
<li>Click <strong>Send</strong>.</li>
11041112
</ol>
1105-
<p>Caches are written to the <code>Garmin/GPX/</code> folder on the device as a standard GPX file.</p>
1113+
<p>GPX caches are written to the <code>Garmin/GPX/</code> folder on the device; GGZ caches go to <code>Garmin/GGZ/</code>.</p>
1114+
1115+
<div class="callout tip"><div class="callout-icon">💡</div><div><strong>GPX vs. GGZ:</strong> GGZ is Garmin's compressed format and supports an <strong>unlimited</strong> number of caches in one export — GPX-based transfers are capped by the device. If you have a large database, GGZ is the better choice.</div></div>
11061116

11071117
<h3>Saving as a GPX File</h3>
11081118
<p>Select <em>Save as GPX file</em>, choose a location, and click <strong>Send</strong>. This is useful for devices that are not automatically detected, or for copying to another location.</p>
@@ -1111,27 +1121,27 @@ <h3>Saving as a GPX File</h3>
11111121

11121122
<h3>Export Options</h3>
11131123
<ul>
1124+
<li>Choose GPX or GGZ format</li>
11141125
<li>Choose how many logs per cache to include</li>
11151126
<li>Corrected coordinates are exported as the primary coordinate (original stored separately)</li>
11161127
</ul>
11171128
</section>
11181129

11191130
<!-- ══════════════════════════════════════════════════════════ -->
11201131
<section id="file-export">
1121-
<h2><span class="section-num">21</span>File Export (GPX / LOC)</h2>
1132+
<h2><span class="section-num">21</span>File Export (GPX / LOC / GGZ)</h2>
11221133
<p>Export your filtered caches to standard geocaching file formats via <strong>File → Export</strong>:</p>
11231134

11241135
<table>
11251136
<thead><tr><th>Format</th><th>Best for</th></tr></thead>
11261137
<tbody>
11271138
<tr><td>GPX</td><td>Full export with descriptions, logs, and waypoints — compatible with most GPS apps</td></tr>
11281139
<tr><td>LOC</td><td>Lightweight coordinate-only format for basic GPS devices</td></tr>
1140+
<tr><td>GGZ</td><td>Garmin's compressed format — unlimited caches per export, matches GSAK's GGZ layout byte-for-byte</td></tr>
11291141
</tbody>
11301142
</table>
11311143

1132-
<p>All exports use the caches currently visible in the list (respecting the active filter).</p>
1133-
1134-
<div class="callout note"><div class="callout-icon">ℹ️</div><div><strong>GGZ export (Garmin's native compressed format) is planned but not yet available</strong> — it isn't in this build. Follow <a href="https://github.com/OpenSAK-Org/opensak/issues/348">issue #348</a> on GitHub for progress.</div></div>
1144+
<p>All exports use the caches currently visible in the list (respecting the active filter). If a file with the chosen name already exists, you'll be prompted for a new one instead of silently overwriting it.</p>
11351145
</section>
11361146

11371147
<!-- ══════════════════════════════════════════════════════════ -->
@@ -1258,6 +1268,7 @@ <h3>General Tab</h3>
12581268
<tr><td>Coordinate format</td><td>DMM, DMS, or Decimal Degrees — used throughout the interface</td></tr>
12591269
<tr><td>Date format</td><td>OS locale, dd.mm.yyyy, mm/dd/yyyy, or yyyy-mm-dd</td></tr>
12601270
<tr><td>Text and icon size</td><td>Small, Medium, or Large — affects the cache list grid (font and row height), the detail panel, and the tab labels</td></tr>
1271+
<tr><td>Show hints decoded by default</td><td>Skip the decode-click and show hints already readable when you open a cache. Off by default (hints start hidden, as before).</td></tr>
12611272
<tr><td>Theme</td><td>Automatic (follow OS), Light, or Dark</td></tr>
12621273
<tr><td>Language</td><td>Choose UI language (restart required)</td></tr>
12631274
</tbody>
@@ -1293,6 +1304,11 @@ <h4>Folders</h4>
12931304
<tr><td>Distance calculation method</td><td>Haversine (default) or Vincenty (WGS84) — Vincenty is up to ~0.3% more accurate over long ranges, at a small performance cost</td></tr>
12941305
</tbody>
12951306
</table>
1307+
1308+
<h4>Custom Icon Packs</h4>
1309+
<p>Want cache-type or found-smiley icons that look different from the bundled set? Click <strong>Open icons folder</strong> to reveal a folder alongside your settings file where you can drop replacement SVG files — no code changes or rebuilding required. File names must match the bundled assets exactly; click <strong>View icon naming guide</strong> for the full list of file names, recommended canvas sizes, and export tips. A missing or invalid custom file automatically falls back to the bundled default — it's never a crash. This folder lives alongside your settings, so it survives future OpenSAK updates.</p>
1310+
1311+
<div class="callout tip"><div class="callout-icon">💡</div><div>Enjoying OpenSAK? Look for the <strong>♥ Support OpenSAK…</strong> entry in the <a href="#help">Help menu</a> — it takes you straight to the project's Open Collective page, which covers costs like code signing so releases keep arriving safely.</div></div>
12961312
</section>
12971313

12981314
<!-- ══════════════════════════════════════════════════════════ -->
@@ -1342,13 +1358,15 @@ <h2><span class="section-num">32</span>Theme</h2>
13421358
<!-- ══════════════════════════════════════════════════════════ -->
13431359
<section id="updates">
13441360
<h2><span class="section-num">33</span>Updates</h2>
1345-
<p>OpenSAK checks for new versions automatically 5 seconds after startup (can be disabled in Settings). When a new version is found, a notification dialog offers three options:</p>
1361+
<p>OpenSAK checks for new versions automatically 5 seconds after startup (can be disabled in Settings). When a new version is found, a notification dialog offers:</p>
13461362
<ul>
13471363
<li><strong>Open releases page</strong> — go to GitHub to download</li>
1364+
<li><strong>♥ Support OpenSAK…</strong> — opens the project's Open Collective page; doesn't affect your update decision, you can still choose one of the other options afterwards</li>
13481365
<li><strong>Skip this version</strong> — suppress notifications for this specific version</li>
13491366
<li><strong>Later</strong> — dismiss until next launch</li>
13501367
</ul>
13511368
<p>You can also check manually via <strong>Help → Check for updates…</strong></p>
1369+
<div class="callout note"><div class="callout-icon">ℹ️</div><div>Running a beta version? You're checked against both the latest beta <em>and</em> the latest stable release, and offered whichever is newer — so you'll always hear about a stable release too, not just newer betas.</div></div>
13521370
</section>
13531371

13541372
<!-- ══════════════════════════════════════════════════════════ -->
@@ -1427,14 +1445,15 @@ <h3>Debug Log</h3>
14271445
<tr><td>Releases &amp; downloads</td><td><a href="https://github.com/OpenSAK-Org/opensak/releases">github.com/OpenSAK-Org/opensak/releases</a></td></tr>
14281446
<tr><td>Changelog</td><td><a href="https://github.com/OpenSAK-Org/opensak/blob/v1.15.0/CHANGELOG.md">CHANGELOG.md on GitHub</a></td></tr>
14291447
<tr><td>Contributing</td><td><a href="https://github.com/OpenSAK-Org/opensak/blob/main/CONTRIBUTING.md">CONTRIBUTING.md on GitHub</a></td></tr>
1448+
<tr><td>Support the project</td><td><a href="https://opencollective.com/opensak">opencollective.com/opensak</a></td></tr>
14301449
<tr><td>Website</td><td><a href="https://opensak.com">opensak.com</a></td></tr>
14311450
</tbody>
14321451
</table>
14331452

14341453
<div class="callout tip"><div class="callout-icon">💡</div><div>OpenSAK is free and open-source software released under the MIT licence. Contributions of any kind — code, translations, documentation, or testing — are very welcome.</div></div>
14351454

14361455
<p style="margin-top:2rem;color:var(--ink-light);font-size:0.85rem;font-style:italic;">
1437-
This guide was generated from the OpenSAK source code (v1.15.0). Last updated June 2026.
1456+
This guide was generated from the OpenSAK source code (v1.15.0). Last updated July 2026.
14381457
</p>
14391458
</section>
14401459

0 commit comments

Comments
 (0)