1CMCONVERT(1)                General Commands Manual               CMCONVERT(1)
2
3
4

NAME

6       cmconvert - CacheMate waypoint file converter
7

SYNOPSIS

9       cmconvert  [-a]  [-A] [-b] [-B] [-C] [-D] [-f] [-F] [-h] [-H] [-l] [-L]
10       [-N max_log_count] [-o output_file] [-O] [-q] [-s] [-S] [-t] [-T]  [-v]
11       [--owner=owner_name]  [--country=country]  [--state=state] [--cont=con‐
12       tainer]   [--sym=symbol]   [--type=cache_type]   [--excl=waypoint_list]
13       [--radius=distance,lat,lon] [--radius=distance,waypoint] [--filter=fil‐
14       ter_file] input_file1[,input_file2...] [waypoint ...]
15

DESCRIPTION

17       cmconvert is a file converter, which takes one or more EasyGPS  LOC  or
18       GPX  XML files as input and outputs a Palm database file that CacheMate
19       (a geocaching database for Palm OS) can import.   GPX  file  extensions
20       specific  to Geocaching.com, Geocaching.com.au and TerraCaching.com are
21       converted as well.  These extensions are referred to as "site-specific"
22       features throughout this document.
23
24       Selection  of  waypoints  to  convert (and later import) is possible by
25       specifying the waypoint names on the command line after the input file.
26       Waypoints  contained  in  the  input file may also be listed along with
27       descriptive information.  Selection by certain criteria is also  possi‐
28       ble, using the filtering options documented below.
29

OPTIONS

31       -B     Includes  travel  bug names from Geocaching.com GPX files in the
32              description field.
33
34       -C     Includes container type/size from site-specific GPX files in the
35              description field.
36
37       -D     Includes  date  information  from  GPX  files in the description
38              field, if available.
39
40       -h     Generates an HTML file, name based on the output PDB file  name,
41              which  contains  URLs  for  any  links  and images found in HTML
42              descriptions for records that are converted.  The file will con‐
43              tain  links to the cache page and any contained links for caches
44              that have them (plain text descriptions  and  HTML  descriptions
45              that are just text are omitted).
46
47       -H     Prevents the encoding of hint text from site-specific GPX files.
48
49       -l     Lists  waypoints  names from input file, along with description,
50              terrain and difficulty information if available.  If any filters
51              are  in  place  or waypoint names are specified, only those that
52              are selected will be listed.
53
54       -L     Includes cache location  (state/province  and/or  country)  from
55              site-specific GPX files in the description field.
56
57       -N max_log_count
58              If specified with a count of at least 1, cache logs from a site-
59              specific GPX file will be imported, until one of three per-cache
60              limits  is  reached:  specified log count, number of logs in the
61              record, or 8k of log information.  Each log entry is trimmed  to
62              3k in size, if it is larger than that.
63
64       -o output_file
65              Specifies  the file to which cmconvert writes the resulting Palm
66              database file.  The default name is based  on  the  first  input
67              file name, with a .pdb extension.
68
69       -O     Includes  cache  owner  from  site-specific  GPX  files  in  the
70              description field.
71
72       -q     Suppresses all output except error messages.
73
74       -s     Causes the parser to semi-intelligently strip quotes from  cache
75              names.
76
77       -S     Includes  cache  status (active/inactive) from site-specific GPX
78              files in description field.
79
80       -t     Adds items taken/left template to log notes field for each  con‐
81              verted record.
82
83       -T     Force  old  (pre-1.8.3) method of dealing with duplicate records
84              (see below).
85
86       -v     Displays version and copyright notice.
87

DUPLICATE RECORD RESOLUTION

89       Versions of  CMConvert  older  than  1.8.3  compared  entire  converted
90       records  to determine whether or not records from different input files
91       were duplicates of each other.  If there were  differences  in  records
92       with identical waypoint names, both records would be included and would
93       then appear to be duplicates.
94
95       The current behavior is to use file  timestamps  and  compare  waypoint
96       names between old and new records.  If a match is found, the old record
97       will be updated if the new record comes from a file with a later  time‐
98       stamp.   If  an  input  file is in GPX format and contains a file-level
99       timestamp, that will be used.  Otherwise, the last-modified time of the
100       file is used.
101

FILTERING OPTIONS

103       The  following  options  may be used to select waypoints for conversion
104       based on certain critera.  Most of the options only apply if  supported
105       site-specific  information  is in the GPX file being converted, and may
106       otherwise result in no waypoints being converted.
107
108       Filters that use an argument, except for radius  filters,  do  a  case-
109       insensitive search of the corresponding field for a match, to make them
110       forgiving of incorrect case and allow for partial search strings.   For
111       example,  a  cache  type  filter  of "event" will match the text "Event
112       Cache" from the GPX file.  Multiple search strings are  also  possible,
113       when  separated  by  colons  (:).  Specifying one of these options more
114       than once will add strings to that filter, instead of replacing it.
115
116       All filtering options, including waypoints  specified  on  the  command
117       line,  are  additive in their effects.  For example, a search combining
118       the "found" and "not found" filters on a  Geocaching.com  pocket  query
119       will result in no records being converted.
120
121       -a     Selects  only caches that are active, according to site-specific
122              information in the  GPX  files.   If  this  information  is  not
123              present  in  the  input  file  (as with LOC files), the cache is
124              assumed to be active.
125
126       -A     Selects only caches that are inactive, using the  same  criteria
127              as the -a filter option.
128
129       -b     Selects only caches that have travel bugs.
130
131       -f     Selects  only  caches  that have been found (symbol name = "Geo‐
132              cache Found").
133
134       -F     Selects only caches that have not  been  found  (symbol  name  =
135              "Geocache").
136
137       --cont=container_type
138              Filters caches based on container type (regular, micro, etc.).
139
140       --country=country
141              Filters caches based on the country where they are located.
142
143       --state=state
144              Filters  caches  based  on  the state or province where they are
145              located.
146
147       --owner=owner_name
148              Filters caches based on the owner's name.
149
150       --type=type_name
151              Filters caches based on cache type (traditional, event, virtual,
152              etc.).
153
154       --sym=symbol_name
155              Filters waypoints based on symbol name.
156
157       --radius=distance,lat,lon
158              Filters  waypoints based on distance from a certain set of coor‐
159              dinates.  Distance is a number of  kilometers  (n.nnK,  n.nnKM),
160              statute miles (n.nnMI) or nautical miles (n.nnM, n.nnNM).  If no
161              unit is specified, nautical miles are assumed by  default.   The
162              latitude and longitude are expressed as decimal degrees.
163
164       --radius=distance,waypoint
165              Filters waypoints based on distance from a given waypoint.  Dis‐
166              tance is expressed in the same way as the more  explicit  radius
167              filter.
168
169       --excl=waypoint_list
170              Allows an exclusion filter on waypoint names.
171
172       --filter=filter_file
173              Specifies  a  file  from  which to read name/value pairs, in the
174              format name=value, which correspond to any of the  string/radius
175              filter types.  The options in the filter file will be applied as
176              if they were expanded into  command-line  arguments  where  this
177              option is specified.
178

TERRACACHING.COM SUPPORT

180       Most  fields  in  GPX  files  from TerraCaching.com are mapped to their
181       equivalent CacheMate fields, which are based  on  those  used  by  Geo‐
182       caching.com.  Some that may not be so obvious are:
183
184           Mental challenge -> Difficulty
185           Physical challenge -> Terrain
186
187       The  "camo  challenge"  rating is prepended to the description text, if
188       present.
189

EXAMPLES

191       The following are various examples of cmconvert with different  filter‐
192       ing options.
193
194       To  list  all of the caches that you haven't found, that contain travel
195       bugs and are owned by bartacus or honeychile, you might do the  follow‐
196       ing:
197
198           cmconvert -lFb --owner=honeychile:bartacus caches.gpx
199
200       To  list  all caches located within 5 miles of the coordinates N36/W80,
201       you would enter:
202
203           cmconvert -l --radius=5M,36,-80 caches.gpx
204
205       A simpler example, this command would list all of the micro  caches  in
206       the input file:
207
208           cmconvert -l --cont=micro caches.gpx
209
210       This  command  converts  the  caches  listed  above  into  a  PDB  file
211       (caches.pdb) to import into CacheMate:
212
213           cmconvert --cont=micro caches.gpx
214
215       The following commands merges two GPX files into a single  import  file
216       (caches.pdb):
217
218           cmconvert caches.gpx,benchmarks.gpx
219

UNRESTRICTIONS

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

AUTHOR

226       Brian Smith <brian@smittyware.com>
227
228
229
230                                  12 May 2010                     CMCONVERT(1)
Impressum