CM2GPX(1)

NAME
cm2gpx - CacheMate PDB-to-GPX file converter

SYNOPSIS
cm2gpx [-b] [-c] [-C category_list] [-e] [-f] [-n] [-o output_file] [-q] [-s symbol] [-t wpt_type] [-T] [-v] [-z] input_file

DESCRIPTION
cm2gpx allows conversion of a CacheMate backup or import PDB files into equivalent GPX files, automatically using GPX extensions specific to Geocaching.com and CacheMate.

Exceptions to the data converted, all Groundspeak-specific, are cache logs, hints, and travel bug names. The reason is that they may be formatted differently in different cases, depending on CMConvert options. Travel bugs are shown in CacheMate as a comma-separated list of names, making parsing of that list into the source list unreliable in the case of a bug name containing a comma.

OPTIONS

-b  Convert only those records that have been bookmarked. This option applies only to CacheMate backup databases.

-c  Direct GPX output to standard output. This option implies quiet mode, automatically turning on that option.

-C category_list
    Convert only those records matching the provided category list. The list is specified as a colon-separated list of category names, which are matched in a case-insensitive manner. For import databases, the only valid category is "Unfiled".

-e  Normally, the category matching is done using substrings, so that only a portion of the category name needs to be specified. This option allows for exact, but still case-insensitive, matching.

-f  Convert only those records that have been marked as Found in CacheMate. This option applies only to CacheMate backup databases.

-n  Normally, for non-geocache records where the record name is different from the waypoint ID, the description field will be used for the GPX <desc> element if it is not empty, instead of the record name. This option cancels that behavior, using the record name for the <desc> element in those cases.

-o output_file
    Specifies the file to which cm2gpx writes the resulting GPX file. The default name is based on the input file name, with a .gpx extension.

-q  Suppresses all output except error messages.

-s symbol
    Specifies the default waypoint symbol, for when a waypoint cannot be determined to be a geocache. If not specified, the default symbol is Waypoint.

-t wpt_type
    Specifies the default waypoint type, for when a waypoint cannot be determined to be a geocache and a type is not defined in the waypoint record. If not specified, the default type is Waypoint.

-T  Causes each record's category name, as taken from the PDB file, to be appended to the GPX <type> element for that record.

-v  Displays version and copyright notice.

-z  Fudge a UTC time zone for waypoint timestamps. No time zone information is encoded in CacheMate files, and is not required by the GPX format, but certain programs (such as EasyGPS) throw an error if it is not defined.

NOTES
Date parsing in CM2GPX should be able to handle all existing numeric date formats, as long as the format in the CacheMate record descriptions match the local date format defined on the computer where CM2GPX is running. When the program starts, it takes a known date formatted using the current locale setting, and attempts to find the separator and parse 3 numbers from the formatted date. If that is successful, it determines the order of the numbers and uses that to parse dates in the CacheMate file.

When a log is entered in CacheMate and the backup database containing that log is converted to a GPX file, it is included within a GPX extension to the <wpt> element. The schema definition for this extension is located at:

http://www.smittyware.com/schema/cmlog/1/0/cmlog.xsd

UNRESTRICTIONS
cm2gpx 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 cm2gpx.

AUTHOR
Brian Smith <brian@smittyware.com>