Skip to content

Improve -[trw] usage #1451

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
robertlipe wants to merge 3 commits into from
Closed

Improve -[trw] usage #1451

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a05c35b
Improve -[trw] usage
robertlipe Jul 19, 2025
ffac88d
fix tag breakage
robertlipe Jul 19, 2025
904b9f3
Tweak everal glossary terms..
robertlipe Jul 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 120 additions & 8 deletions xmldoc/chapters/glossary.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,67 @@
<glossary xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Glossary">
<?xml version="1.0" encoding="UTF-8"?>
<glossary xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="Glossary">
<title>Glossary</title>
<para>Terms that are used in conjunction with GPSBabel.</para>

<glossdiv xml:id="C">
<title>C</title>
<glossentry xml:id="gl_csv_format">
<glossterm>CSV (Comma Separated Values)</glossterm>
<glossdef>
<para>A ubiquitous text-based file format for tabular data.
GPSBabel includes multiple CSV <emphasis>modules</emphasis>
(<link linkend="gl_unicsv">unicsv</link>,
<link linkend="gl_xcsv">xcsv</link>, and a legacy
<link linkend="gl_csv_legacy">csv</link> module). See
<link linkend="csv_guide">Choosing the Right CSV Format</link>
for details.
</para>
</glossdef>
</glossentry>
<glossentry xml:id="gl_csv_legacy">
<glossterm>csv (legacy module)</glossterm>
<glossdef>
<para>GPSBabel's simplest CSV module, typically for files with
only Latitude, Longitude, and Name, and no header.
Generally not recommended for modern use. See
<link linkend="csv_guide">Choosing the Right CSV Format</link>.
</para>
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="F">
<title>F</title>
<glossentry xml:id="gl_filter">
<glossterm>Filter</glossterm>
<glossdef>
<para>A GPSBabel operation (<option>-x</option>) that
modifies or selects data as it flows through the program.
Examples include simplifying tracks, nuking certain data
types, or adding timestamps. For more details, see the
<link linkend="Advanced_Usage">Advanced Usage section</link>
and the <link linkend="Filters">Filters chapter</link>.
</para>
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="G">
<title>G</title>
<glossentry xml:id="gl_xml">
<glossentry xml:id="gl_geocaching">
<glossterm>Geocaching</glossterm>
<glossdef>
<para>GPS based "paper chase", see

<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://en.wikipedia.org/wiki/Geocaching">https://en.wikipedia.org/wiki/Geocaching</uri></para>
<uri xlink:href="https://en.wikipedia.org/wiki/Geocaching">
https://en.wikipedia.org/wiki/Geocaching
</uri>
</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv>

<glossdiv xml:id="I">
<title>I</title>
<glossentry xml:id="gl_itinerary">
<glossterm>Itinerary</glossterm>
Expand All @@ -21,6 +70,34 @@
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="O">
<title>O</title>
<glossentry xml:id="gl_option">
<glossterm>Option</glossterm>
<glossdef>
<para>A command-line argument that controls GPSBabel's
behavior (e.g., <option>-i</option>, <option>-o</option>).
Options are processed strictly from left to right. See the
<link linkend="Invocation">Invocation section</link> for
basic options and the
<link linkend="all_options">full options list</link>.
</para>
</glossdef>
</glossentry>
<glossentry xml:id="gl_suboption">
<glossterm>Suboption</glossterm>
<glossdef>
<para>Additional parameters that modify the behavior of a
specific format or filter module. They are typically
comma-separated and follow the main option (e.g.,
<option>-o kml,lines=0</option>). For more details, see the
<link linkend="Suboptions">Suboptions section</link>.
</para>
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="P">
<title>P</title>
<glossentry xml:id="gl_poi">
Expand All @@ -31,6 +108,7 @@
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="R">
<title>R</title>
<glossentry xml:id="gl_route">
Expand All @@ -41,10 +119,12 @@
defining the route you want to pass while traveling,
created by PC software, or generated inside a GPS device.
They can be composed of existing waypoints, or new
"routepoints" might be generated.</para>
"routepoints" might be generated.
</para>
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="T">
<title>T</title>
<glossentry xml:id="gl_track">
Expand All @@ -55,10 +135,26 @@
of trackpoints within the track is important. Usually a
trackpoint doesn't have a name or comment, but a
timestamp. This distinguishes a trackpoint from a
waypoint.</para>
waypoint.
</para>
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="U">
<title>U</title>
<glossentry xml:id="gl_unicsv">
<glossterm>unicsv (Universal CSV module)</glossterm>
<glossdef>
<para>GPSBabel's recommended CSV module for most modern files,
especially those with a header row. It intelligently detects
fields and preserves additional data. See
<link linkend="csv_guide">Choosing the Right CSV Format</link>.
</para>
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="W">
<title>W</title>
<glossentry xml:id="gl_waypoint">
Expand All @@ -69,8 +165,24 @@
entered before, while or after you actually visit the
place and might have tags like name, comment and the
like. Usually used to mark special locations as your
home, a hotel or a geocache.</para>
home, a hotel or a geocache.
</para>
</glossdef>
</glossentry>
</glossdiv>

<glossdiv xml:id="X">
<title>X</title>
<glossentry xml:id="gl_xcsv">
<glossterm>xcsv (Extended CSV module)</glossterm>
<glossdef>
<para>An advanced, highly customizable CSV module that
requires a separate "style file" to define its structure.
Useful for complex or non-standard CSV layouts. See
<link linkend="csv_guide">Choosing the Right CSV Format</link>.
</para>
</glossdef>
</glossentry>
</glossdiv>

</glossary>
80 changes: 66 additions & 14 deletions xmldoc/chapters/use.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,29 @@
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Usage">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="Usage">
<title>Usage</title>
<section xml:id="Invocation">
<title>Invocation</title>
<para>If you're using GPSBabel, you will need to know how to do at least two things:
read data from a file, and write it to another file. There are four basic
options you need to know to do those things:
</para>
<para>
If you're using GPSBabel, you will need to know how to do
at least two things: read data from a file, and write it
to another file. There are four basic options you need
to know to do those things:
</para>

<note>
<para>
<emphasis role="strong">For Most Users:</emphasis> If you prefer
a visual interface over command-line arguments, GPSBabel also
provides a user-friendly
<link xlink:href="https://www.gpsbabel.org/gui/">Graphical User
Interface (GUI)</link> for Windows, macOS, and Linux. The GUI
simplifies common tasks like converting file formats and
applying basic filters without needing to memorize commands.
Most users find the GUI the easiest way to get started with
GPSBabel.
</para>
</note>

<segmentedlist>
<?dbhtml list-presentation="table"?>
<segtitle>Command</segtitle>
Expand Down Expand Up @@ -430,17 +448,50 @@ merged data to multiple destinations.
<filename>gpsbabel.ini</filename>
containing preferences you have provided. This option lets you pick a different file. See
<xref linkend="inifile"/>
for more info.</para>
<para>
<option>-s</option> Write "smart" names. This option influences some - but not all - of our writers to try to build "smart" waypoint names. For example, in modules that know about geocaching, it may replace "GC1234" with the actual name of the geocache.</para>
for more info.
</para>
<para>
<option>-r</option> Work on routes. This option has a subtly different meaning in different cases. As the very first formats in GPSBabel were for serial GPSes and routes and tracks were large and thus time-consuming to transfer, the default was waypoints only with this option to turn on the extra data. Some of our file formats use this option to mean "work only on routes, even if you have tracks/waypoints", but we're trying to discourage that behavior and in most cases, consider it a bug. </para>
<option>-s</option> Write "smart" names. This option influences
some - but not all - of our writers to try to build "smart"
waypoint names. For example, in modules that know about
geocaching, it may replace "GC1234" with the actual name of
the geocache.
<note>
<para>
<emphasis role="strong">Important Note:</emphasis> The use
of <option>-s</option> is generally not recommended for
modern file-to-file conversions, especially when dealing
with tracks or routes. It was primarily useful for older
serial GPS devices with very limited display capabilities
that needed short, synthesized names. For preserving rich
waypoint data or when working with tracks and routes,
avoid using this option. As noted in
<xref linkend="Route_And_Track_Modes"/>, <option>-s</option>
can create havoc on tracks and routes due to its renaming
behavior breaking internal linkages.
</para>
</note>

<option>-r</option> Work on routes. This option primarily tells
GPSBabel to process routes. In most modern file-to-file
conversions, GPSBabel attempts to process all available data
types (waypoints, tracks, and routes) by default. Therefore,
specifying <option>-r</option>, <option>-t</option>, or
<option>-w</option> is generally only necessary if you
explicitly wish to <emphasis>restrict</emphasis> the data being
processed to *only* routes, tracks, or waypoints respectively,
or when interacting with older serial devices or specific
formats that require these flags (such as
<link linkend="fmt_garmin">garmin</link> for tracks/routes).
</para>
<para>
<option>-t</option> Work on tracks. See
<option>-r</option>
for usage.</para>
<option>-t</option> Work on tracks. See <option>-r</option>
for usage.
</para>
<para>
<option>-w</option> Work on waypoints. This is the default. </para>
<option>-w</option> Work on waypoints. This is the default.
See <option>-r</option> for usage.
</para>
<para>
<option>-T</option> Enable Realtime tracking. This option isn't supported by the majority of our file formats, but repeatedly reads location from a GPS and writes it to a file as described in
<xref linkend="tracking"/></para>
Expand All @@ -455,6 +506,7 @@ merged data to multiple destinations.
<option>-h</option>,
<option>-?</option> Print help. </para>
<para>
<option>-V</option> Print version number. </para>
<option>-V</option> Print version number.
</para>
</section>
</chapter>
Loading