cmconvert - Man Page

cmconvert [-a] [-A] [-b] [-B] [-C] [-D] [-f] [-F] [-h] [-H] [-l] [-L] [-N max_log_count] [-o output_file] [-O] [-q] [-s] [-S] [-t] [-T] [-v]  [--owner=owner_name] [--country=country] [--state=state]  [--cont=container] [--sym=symbol] [--type=cache_type] [--excl=waypoint_list] [--radius=distance,lat,lon] [--radius=distance,waypoint] [--filter=filter_file] input_file1[,input_file2...] [waypoint ...]

cmconvert is a file converter, which takes one or more EasyGPS LOC or GPX XML files  as input and outputs a Palm database file that CacheMate (a geocaching  database for Palm OS) can import.  GPX file extensions specific to  Geocaching.com, Geocaching.com.au and TerraCaching.com are converted as  well.  These extensions are referred to as "site-specific" features  throughout this document.

Selection of waypoints to convert (and later import) is possible by specifying the waypoint names on the command line after the input file.   Waypoints contained in the input file may also be listed along with descriptive information.  Selection by certain criteria is also possible, using the filtering options documented below.

-B

Includes travel bug names from Geocaching.com GPX files in the description  field.

-C

Includes container type/size from site-specific GPX files in the description field.

-D

Includes date information from GPX files in the description field, if  available.

-h

Generates an HTML file, name based on the output PDB file name, which contains URLs for any links and images found in HTML descriptions for records that are converted.  The file will contain links to the cache page and any contained links for caches that have them (plain text descriptions and HTML descriptions that are just text are omitted).

-H

Prevents the encoding of hint text from site-specific GPX files.

-l

Lists waypoints names from input file, along with description, terrain and difficulty information if available.  If any filters are in place or waypoint names are specified, only those that are selected will be listed.

-L

Includes cache location (state/province and/or country) from site-specific  GPX files in the description field.

-N max_log_count

If specified with a count of at least 1, cache logs from a site-specific GPX file will be imported, until one of three per-cache limits is reached: specified log count, number of logs in the record, or 8k of log information.  Each log entry is trimmed to 3k in size, if it is larger than that.

-o output_file

Specifies the file to which cmconvert writes the resulting Palm database file.  The default name is based on the first input file name,  with a .pdb extension.

-O

Includes cache owner from site-specific GPX files in the description  field.

-q

Suppresses all output except error messages.

-s

Causes the parser to semi-intelligently strip quotes from cache names.

-S

Includes cache status (active/inactive) from site-specific GPX files in  description field.

-t

Adds items taken/left template to log notes field for each converted  record.

-T

Force old (pre-1.8.3) method of dealing with duplicate records (see  below).

-v

Displays version and copyright notice.

Versions of CMConvert older than 1.8.3 compared entire converted records  to determine whether or not records from different input files were  duplicates of each other.  If there were differences in records with  identical waypoint names, both records would be included and would then  appear to be duplicates.

The current behavior is to use file timestamps and compare waypoint names between old and new records.  If a match is found, the old record will be updated if the new record comes from a file with a later timestamp.  If an input file is in GPX format and contains a file-level timestamp, that will be used.  Otherwise, the last-modified time of the file is used.

The following options may be used to select waypoints for conversion based  on certain critera.  Most of the options only apply if supported  site-specific information is in the GPX file being converted, and may  otherwise result in no waypoints being converted.

Filters that use an argument, except for radius filters, do a case-insensitive search of the corresponding field for a match, to make them forgiving of incorrect case and allow for partial search strings.   For example, a cache type filter of "event" will match the text "Event Cache" from the GPX file.  Multiple search strings are also possible, when separated by colons (:).  Specifying one of these options more than once will add strings to that filter, instead of replacing it.

All filtering options, including waypoints specified on the command line, are additive in their effects.  For example, a search combining the "found" and "not found" filters on a Geocaching.com pocket query will result in no records being converted.

-a

Selects only caches that are active, according to site-specific  information in the GPX files.  If this information is not present in the  input file (as with LOC files), the cache is assumed to be active.

-A

Selects only caches that are inactive, using the same criteria as the -a  filter option.

-b

Selects only caches that have travel bugs.

-f

Selects only caches that have been found (symbol name = "Geocache Found").

-F

Selects only caches that have not been found (symbol name = "Geocache").

--cont=container_type

Filters caches based on container type (regular, micro, etc.).

--country=country

Filters caches based on the country where they are located.

--state=state

Filters caches based on the state or province where they are located.

--owner=owner_name

Filters caches based on the owner's name.

--type=type_name

Filters caches based on cache type (traditional, event, virtual, etc.).

--sym=symbol_name

Filters waypoints based on symbol name.

--radius=distance,lat,lon

Filters waypoints based on distance from a certain set of coordinates.   Distance is a number of kilometers (n.nnK, n.nnKM), statute miles (n.nnMI)   or nautical miles (n.nnM, n.nnNM).  If no unit is specified, nautical miles are assumed by default.  The latitude and longitude are expressed as decimal degrees.

--radius=distance,waypoint

Filters waypoints based on distance from a given waypoint.  Distance is  expressed in the same way as the more explicit radius filter.

--excl=waypoint_list

Allows an exclusion filter on waypoint names.

--filter=filter_file

Specifies a file from which to read name/value pairs, in the format name=value, which correspond to any of the string/radius filter types.  The options in the filter file will be applied as if they were expanded into command-line arguments where this option is specified.

Most fields in GPX files from TerraCaching.com are mapped to their  equivalent CacheMate fields, which are based on those used by  Geocaching.com.  Some that may not be so obvious are:

The "camo challenge" rating is prepended to the description text, if  present.

The following are various examples of cmconvert with different filtering  options.

To list all of the caches that you haven't found, that contain travel bugs  and are owned by bartacus or honeychile, you might do the following:

To list all caches located within 5 miles of the coordinates N36/W80, you  would enter:

A simpler example, this command would list all of the micro caches in the input file:

This command converts the caches listed above into a PDB file (caches.pdb) to import into CacheMate:

The following commands merges two GPX files into a single import file  (caches.pdb):

cmconvert is free; anyone may redistribute copies of it to anyone under the terms stated in the GNU General Public License, a copy of which accompanies each copy of cmconvert.

Brian Smith <brian@smittyware.com>