doc/gpst.1

   1 '\" t
   2 .\"     Title: gpst
   3 .\"    Author: [see the "Author" section]
   4 .\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
   5 .\"      Date: 2010-05-01
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "GPST" "1" "2010-05-01" "[FIXME: source]" "[FIXME: manual]"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 gpst \- Converts between various GPS formats\&.
  23 .SH "SYNOPSIS"
  24 .HP \w'\fBgpst\fR\ 'u
  25 \fBgpst\fR [\fIoptions\fR] [\fIfile\fR...]
  26 .HP \w'\fBgpst\fR\ 'u
  27 \fBgpst\fR {\-S} [\fIoptions\fR] [\fIfile\fR...]
  28 .SH "DESCRIPTION"
  29 .PP
  30 \fB\-\-chronology\fR
  31 .RS 4
  32 Check for broken chronology, warn about entries with an old timestamp\&.
  33 .RE
  34 .PP
  35 \fB\-d\fR, \fB\-\-skip\-dups\fR
  36 .RS 4
  37 If succeeding identical coordinates are found, print only the first one and ignore the rest\&.
  38 .RE
  39 .PP
  40 \fB\-e\fR, \fB\-\-epoch\fR
  41 .RS 4
  42 Use seconds since 1970\-01\-01 00:00:00 GMT as date format\&.
  43 .RE
  44 .PP
  45 \fB\-\-fix\fR
  46 .RS 4
  47 Comment out entries which is obviously wrong\&. Use together with
  48 \fB\-\-chronology\fR
  49 to fix those kind of errors\&. Does not work with GPX output yet\&.
  50 .RE
  51 .PP
  52 \fB\-\-from\-date \fR\fB\fIx\fR\fR
  53 .RS 4
  54 Used by the
  55 pgwupd
  56 format\&. Specifies from which date waypoints should be updated\&. No checks for valid date format here, let
  57 PostgreSQL
  58 take care of that\&. All variants it understands can be used here\&.
  59 .RE
  60 .PP
  61 \fB\-h\fR, \fB\-\-help\fR
  62 .RS 4
  63 Send a brief help summary to stdout\&.
  64 .RE
  65 .PP
  66 \fB\-\-inside\fR
  67 .RS 4
  68 Print only trackpoints inside a rectangle specified by
  69 \fB\-\-pos1\fR
  70 and
  71 \fB\-\-pos2\fR\&.
  72 .RE
  73 .PP
  74 \fB\-n\fR, \fB\-\-undefined \fR\fB\fIx\fR\fR
  75 .RS 4
  76 Use
  77 \fIx\fR
  78 as undefined value\&.
  79 .RE
  80 .PP
  81 \fB\-\-near\fR
  82 .RS 4
  83 Add names of the three closest waypoints to the trackpoint\&. Unfinished and experimental, needs
  84 \fBgpsbabel\fR(1), which is called from the program as
  85 \fB/usr/local/bin/gpsbabel\fR\&.
  86 .RE
  87 .PP
  88 \fB\-o\fR, \fB\-\-output\-format \fR\fB\fIx\fR\fR
  89 .RS 4
  90 Use output format
  91 \fIx\fR:
  92 .PP
  93 \fBclean\fR
  94 .RS 4
  95 TAB\-separated format with longitude, latitude and altitude\&.
  96 .RE
  97 .PP
  98 \fBcsv\fR
  99 .RS 4
 100 TAB\-separated format:
 101 .PP
 102 date
 103 .RS 4
 104 Date of trackpoint\&. Format:
 105 \fIyyyy\fR\-\fImm\fR\-\fIdd\fRT\fIhh\fR:\fImm\fR:\fIss\fRZ
 106 unless the
 107 \fB\-\-epoch\fR
 108 option is specified\&. If so, it\(cqs represented as number of seconds since 1970\-01\-01 00:00:00 UTC\&.
 109 .RE
 110 .PP
 111 longitude
 112 .RS 4
 113 Longitude, decimal degrees\&.
 114 .RE
 115 .PP
 116 latitude
 117 .RS 4
 118 Latitude, decimal degrees\&.
 119 .RE
 120 .PP
 121 altitude
 122 .RS 4
 123 Altitude in metres above sea level\&. Optional\&. If not present, the corresponding TAB is also printed, to keep the number of columns intact\&.
 124 .RE
 125 .RE
 126 .PP
 127 \fBgpsml\fR (Default)
 128 .RS 4
 129 Line\-based XML which makes it easy to edit and grep\&. In the past, there was this big plan about making this the default storage format, so it was declared as The Honourable Default Output Format\&. But using GPX is the way to go, so this will probably change in the future\&. It\(cqs way too
 130 de facto
 131 and widely used, so storing GPS data in anything else is sheer waste of work\&. Probably not finished yet\&.
 132 .RE
 133 .PP
 134 \fBgpstrans\fR
 135 .RS 4
 136 The format generated by
 137 \fBgpstrans\fR(1)\&.
 138 .RE
 139 .PP
 140 \fBgpx\fR
 141 .RS 4
 142 Not complete yet, but good enough in most cases\&.
 143 .RE
 144 .PP
 145 \fBpgtab\fR
 146 .RS 4
 147 TAB\-separated format for import into
 148 PostgreSQL\&. Undefined values are written as
 149 \eN
 150 if the
 151 \fB\-\-undefined\fR
 152 option is not specified\&.
 153 .PP
 154 date
 155 .RS 4
 156 Format:
 157 \fIyyyy\fR\-\fImm\fR\-\fIdd\fRT\fIhh\fR:\fImm\fR:\fIss\fRZ
 158 .RE
 159 .PP
 160 coor
 161 .RS 4
 162 Format:
 163 (\fIlat\fR,\fIlon\fR)
 164 .RE
 165 .PP
 166 ele
 167 .RS 4
 168 Altitude in metres above sea level\&.
 169 .RE
 170 .PP
 171 name
 172 .RS 4
 173 Short name of closest waypoint\&. Calculated in
 174 PostgreSQL, so this value is always
 175 \eN\&.
 176 .RE
 177 .PP
 178 dist
 179 .RS 4
 180 Distance in decimal degrees to closest waypoint\&. Calculated in
 181 PostgreSQL, so this value is always
 182 \eN\&.
 183 .RE
 184 .PP
 185 description
 186 .RS 4
 187 Description of waypoint\&. Calculated in
 188 PostgreSQL, so this value is always
 189 \eN\&.
 190 .RE
 191 .RE
 192 .PP
 193 \fBpgwtab\fR
 194 .RS 4
 195 Output waypoints on a TAB\-separated format:
 196 .PP
 197 coor
 198 .RS 4
 199 Format:
 200 (\fIlat\fR,\fIlon\fR)
 201 .RE
 202 .PP
 203 name
 204 .RS 4
 205 Title of waypoint\&.
 206 .RE
 207 .PP
 208 ele
 209 .RS 4
 210 Elevation in metres above sea level\&.
 211 .RE
 212 .PP
 213 type
 214 .RS 4
 215 Type of waypoint, same as the GPX
 216 <type>
 217 element\&.
 218 .RE
 219 .PP
 220 time
 221 .RS 4
 222 Timestamp of waypoint\&.
 223 .RE
 224 .PP
 225 cmt
 226 .RS 4
 227 Short waypoint description, used by the GPS as a comment\&. Same as the GPX
 228 <cmt>
 229 element\&.
 230 .RE
 231 .PP
 232 descr
 233 .RS 4
 234 Long description, not used by the GPS\&. Same as the GPX
 235 <desc>
 236 element\&.
 237 .RE
 238 .PP
 239 src
 240 .RS 4
 241 Source of data, same as the
 242 <src>
 243 GPX element\&.
 244 .RE
 245 .PP
 246 sym
 247 .RS 4
 248 GPS symbol name\&. Same as the
 249 <sym>
 250 GPX element\&.
 251 .RE
 252 .RE
 253 .PP
 254 \fBpgwupd\fR
 255 .RS 4
 256 Output waypoints as SQL transactions which updates the
 257 name
 258 and
 259 dist
 260 columns\&.
 261 .RE
 262 .PP
 263 \fBposcount\fR
 264 .RS 4
 265 Creates a 3D plot where areas with many trackpoints are higher than areas with less track points\&.
 266 .RE
 267 .PP
 268 \fBps\fR
 269 .RS 4
 270 Postscript\&. Unfinished\&.
 271 .RE
 272 .PP
 273 \fBsvg\fR
 274 .RS 4
 275 Unfinished\&.
 276 .RE
 277 .PP
 278 \fBxgraph\fR
 279 .RS 4
 280 Input format for
 281 \fBxgraph\fR(1)\&.
 282 .RE
 283 .PP
 284 \fBygraph\fR
 285 .RS 4
 286 Input format for
 287 \fBygraph\fR(1)\&.
 288 .RE
 289 .RE
 290 .PP
 291 \fB\-\-outside\fR
 292 .RS 4
 293 Print only trackpoints outside a rectangle specified by
 294 \fB\-\-pos1\fR
 295 and
 296 \fB\-\-pos2\fR\&.
 297 .RE
 298 .PP
 299 \fB\-\-pos1 \fR\fB\fIx1\fR\fR\fB,\fR\fB\fIy1\fR\fR, \fB\-\-pos2 \fR\fB\fIx2\fR\fR\fB,\fR\fB\fIy2\fR\fR
 300 .RS 4
 301 Specifies corners of an area rectangle used by the
 302 \fB\-\-inside\fR
 303 and
 304 \fB\-\-outside\fR
 305 options\&. The
 306 \fIx\fR
 307 and
 308 \fIy\fR
 309 values are specified as decimal degrees, negative for west or south\&.
 310 .RE
 311 .PP
 312 \fB\-r\fR, \fB\-\-require \fR\fB\fIx\fR\fR
 313 .RS 4
 314 Specify requirements for trackpoints to be written\&.
 315 \fIx\fR
 316 is a string with the following flags:
 317 .PP
 318 \fBe\fR
 319 .RS 4
 320 Print only waypoints which have an elevation\&.
 321 .RE
 322 .PP
 323 \fBp\fR
 324 .RS 4
 325 Print only waypoints which have a position\&.
 326 .RE
 327 .PP
 328 \fBt\fR
 329 .RS 4
 330 Print only waypoints which have a timestamp\&.
 331 .RE
 332 .RE
 333 .PP
 334 \fB\-R\fR, \fB\-\-round \fR\fB\fIx\fR\fR\fB=\fR\fB\fIy\fR\fR\fB[,\fIx2\fR=\fIy2\fR[\&.\&.\&.]]\fR
 335 .RS 4
 336 Round trackpoint element
 337 \fIx\fR
 338 to
 339 \fIy\fR
 340 decimals\&.
 341 .sp
 342 Example:
 343 \fB\-\-round lat=4,lon=5,ele=1\fR
 344 .RE
 345 .PP
 346 \fB\-s\fR, \fB\-\-short\-date\fR
 347 .RS 4
 348 Use short date format\&.
 349 .RE
 350 .PP
 351 \fB\-S\fR, \fB\-\-save\-to\-file \fR\fB\fIx\fR\fR
 352 .RS 4
 353 Save the unconverted data to a file with a filename starting with the timestamp of the first trackpoint\&. The parameter string
 354 \fIx\fR
 355 is added at the end of the filename\&. For the time being this option will ignore all other options\&.
 356 .if n \{\
 357 .sp
 358 .\}
 359 .RS 4
 360 .it 1 an-trap
 361 .nr an-no-space-flag 1
 362 .nr an-break-flag 1
 363 .br
 364 .ps +1
 365 \fBNote\fR
 366 .ps -1
 367 .br
 368 If several files are specified on the command line, all data will be saved into only one file\&. This behaviour may change in the future\&.
 369 .sp .5v
 370 .RE
 371 .RE
 372 .PP
 373 \fB\-t\fR, \fB\-\-create\-breaks\fR
 374 .RS 4
 375 Create breaks in track between points with a difference more than the number of seconds specified by the
 376 \fBPAUSE_LIMIT\fR
 377 variable\&.
 378 .RE
 379 .PP
 380 \fB\-T \fR\fB\fIx\fR\fR, \fB\-\-time\-shift \fR\fB\fIx\fR\fR
 381 .RS 4
 382 Move timestamps
 383 \fIx\fR
 384 seconds forwards or backwards in output\&.
 385 \fIx\fR
 386 can be a positive or negative integer\&.
 387 .RE
 388 .PP
 389 \fB\-v\fR, \fB\-\-verbose\fR
 390 .RS 4
 391 Verbose output, can be repeated\&.
 392 .RE
 393 .PP
 394 \fB\-\-version\fR
 395 .RS 4
 396 Print program version information\&.
 397 .RE
 398 .PP
 399 \fB\-w\fR, \fB\-\-strip\-whitespace\fR
 400 .RS 4
 401 Strip all unnecessary whitespace\&.
 402 .RE
 403 .PP
 404 \fB\-y\fR, \fB\-\-double\-y\-scale\fR
 405 .RS 4
 406 Double Y scale (latitude)\&.
 407 .RE
 408 .PP
 409 \fB\-\-debug\fR
 410 .RS 4
 411 Print debugging messages\&.
 412 .RE
 413 .SH "BUGS AND THINGS THAT NEED TO BE DONE"
 414 .sp
 415 .RS 4
 416 .ie n \{\
 417 \h'-04'\(bu\h'+03'\c
 418 .\}
 419 .el \{\
 420 .sp -1
 421 .IP \(bu 2.3
 422 .\}
 423 Pretty incomplete in some areas\&. Some of the source formats are undocumented and thus incomplete\&. Some functionality is not working properly, for example the Postscript output\&.
 424 .RE
 425 .sp
 426 .RS 4
 427 .ie n \{\
 428 \h'-04'\(bu\h'+03'\c
 429 .\}
 430 .el \{\
 431 .sp -1
 432 .IP \(bu 2.3
 433 .\}
 434 Remove hardcodings\&.
 435 .RE
 436 .sp
 437 .RS 4
 438 .ie n \{\
 439 \h'-04'\(bu\h'+03'\c
 440 .\}
 441 .el \{\
 442 .sp -1
 443 .IP \(bu 2.3
 444 .\}
 445 Translate database column names to English\&.
 446 .RE
 447 .sp
 448 .RS 4
 449 .ie n \{\
 450 \h'-04'\(bu\h'+03'\c
 451 .\}
 452 .el \{\
 453 .sp -1
 454 .IP \(bu 2.3
 455 .\}
 456 Add more tests to cover all command\-line options\&.
 457 .RE
 458 .SH "AUTHOR"
 459 .PP
 460 Made by
 461 Øyvind A\&. Holm
 462 sunny@sunbase\&.org\&.
 463 .SH "COPYRIGHT"
 464 .PP
 465 Copyleft \(co
 466 Øyvind A\&. Holm
 467 sunny@sunbase\&.org\&. This is free software; see the file
 468 COPYING
 469 for legalese stuff\&.
 470 .SH "LICENSE"
 471 .PP
 472 This program is free software: you can redistribute it and/or modify it under the terms of the
 473 GNU General Public License
 474 as published by the
 475 Free Software Foundation, either version 3 of the License, or (at your option) any later version\&.
 476 .PP
 477 This program is distributed in the hope that it will be useful, but
 478 \fIWITHOUT ANY WARRANTY\fR; without even the implied warranty of
 479 \fIMERCHANTABILITY\fR
 480 or
 481 \fIFITNESS FOR A PARTICULAR PURPOSE\fR\&. See the GNU General Public License for more details\&.
 482 .PP
 483 You should have received a copy of the GNU General Public License along with this program\&. If not, see
 484 \m[blue]\fB\%http://www.gnu.org/licenses/\fR\m[]\&.
 485 .SH "SEE ALSO"
 486 .PP
 487 \fBgpsbabel\fR(1)