| blob | cc39c4746d395598dfdce601cbe686890aedc239 |
1 .\" Title: gpst
2 .\" Author: [see the "Author" section]
3 .\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
4 .\" Date: $Id$
5 .\" Manual: [FIXME: manual]
6 .\" Source: [FIXME: source]
7 .\" Language: English
8 .\"
9 .TH "GPST" "1" "$Id$" "[FIXME: source]" "[FIXME: manual]"
10 .\" -----------------------------------------------------------------
11 .\" * (re)Define some macros
12 .\" -----------------------------------------------------------------
13 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14 .\" toupper - uppercase a string (locale-aware)
15 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16 .de toupper
17 .tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
18 \\$*
19 .tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
20 ..
21 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 .\" SH-xref - format a cross-reference to an SH section
23 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
24 .de SH-xref
25 .ie n \{\
26 .\}
27 .toupper \\$*
28 .el \{\
29 \\$*
30 .\}
31 ..
32 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33 .\" SH - level-one heading that works better for non-TTY output
34 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35 .de1 SH
36 .\" put an extra blank line of space above the head in non-TTY output
37 .if t \{\
38 .sp 1
39 .\}
40 .sp \\n[PD]u
41 .nr an-level 1
42 .set-an-margin
43 .nr an-prevailing-indent \\n[IN]
44 .fi
45 .in \\n[an-margin]u
46 .ti 0
47 .HTML-TAG ".NH \\n[an-level]"
48 .it 1 an-trap
49 .nr an-no-space-flag 1
50 .nr an-break-flag 1
51 \." make the size of the head bigger
52 .ps +3
53 .ft B
54 .ne (2v + 1u)
55 .ie n \{\
56 .\" if n (TTY output), use uppercase
57 .toupper \\$*
58 .\}
59 .el \{\
60 .nr an-break-flag 0
61 .\" if not n (not TTY), use normal case (not uppercase)
62 \\$1
63 .in \\n[an-margin]u
64 .ti 0
65 .\" if not n (not TTY), put a border/line under subheading
66 .sp -.6
67 \l'\n(.lu'
68 .\}
69 ..
70 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71 .\" SS - level-two heading that works better for non-TTY output
72 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73 .de1 SS
74 .sp \\n[PD]u
75 .nr an-level 1
76 .set-an-margin
77 .nr an-prevailing-indent \\n[IN]
78 .fi
79 .in \\n[IN]u
80 .ti \\n[SN]u
81 .it 1 an-trap
82 .nr an-no-space-flag 1
83 .nr an-break-flag 1
84 .ps \\n[PS-SS]u
85 \." make the size of the head bigger
86 .ps +2
87 .ft B
88 .ne (2v + 1u)
89 .if \\n[.$] \&\\$*
90 ..
91 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92 .\" BB/BE - put background/screen (filled box) around block of text
93 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94 .de BB
95 .if t \{\
96 .sp -.5
97 .br
98 .in +2n
99 .ll -2n
100 .gcolor red
101 .di BX
102 .\}
103 ..
104 .de EB
105 .if t \{\
106 .if "\\$2"adjust-for-leading-newline" \{\
107 .sp -1
108 .\}
109 .br
110 .di
111 .in
112 .ll
113 .gcolor
114 .nr BW \\n(.lu-\\n(.i
115 .nr BH \\n(dn+.5v
116 .ne \\n(BHu+.5v
117 .ie "\\$2"adjust-for-leading-newline" \{\
118 \M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
119 .\}
120 .el \{\
121 \M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
122 .\}
123 .in 0
124 .sp -.5v
125 .nf
126 .BX
127 .in
128 .sp .5v
129 .fi
130 .\}
131 ..
132 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 .\" BM/EM - put colored marker in margin next to block of text
134 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135 .de BM
136 .if t \{\
137 .br
138 .ll -2n
139 .gcolor red
140 .di BX
141 .\}
142 ..
143 .de EM
144 .if t \{\
145 .br
146 .di
147 .ll
148 .gcolor
149 .nr BH \\n(dn
150 .ne \\n(BHu
151 \M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
152 .in 0
153 .nf
154 .BX
155 .in
156 .fi
157 .\}
158 ..
159 .\" -----------------------------------------------------------------
160 .\" * set default formatting
161 .\" -----------------------------------------------------------------
162 .\" disable hyphenation
163 .nh
164 .\" disable justification (adjust text to left margin only)
165 .ad l
166 .\" -----------------------------------------------------------------
167 .\" * MAIN CONTENT STARTS HERE *
168 .\" -----------------------------------------------------------------
169 .SH "Name"
170 gpst \- Converts between various GPS formats\&.
171 .SH "Synopsis"
172 .fam C
173 .HP \w'\fBgpst\fR\ 'u
174 \fBgpst\fR [\fIoptions\fR] [\fIfile\fR...]
175 .fam
176 .fam C
177 .HP \w'\fBgpst\fR\ 'u
178 \fBgpst\fR {\-S} [\fIoptions\fR] [\fIfile\fR...]
179 .fam
180 .SH "Description"
181 .PP
182 \fB\-\-chronology\fR
183 .RS 4
184 Check for broken chronology, warn about entries with an old timestamp\&.
185 .RE
186 .PP
187 \fB\-d\fR, \fB\-\-skip\-dups\fR
188 .RS 4
189 If succeeding identical coordinates are found, print only the first one and ignore the rest\&.
190 .RE
191 .PP
192 \fB\-e\fR, \fB\-\-epoch\fR
193 .RS 4
194 Use seconds since 1970\-01\-01 00:00:00 GMT as date format\&.
195 .RE
196 .PP
197 \fB\-\-fix\fR
198 .RS 4
199 Comment out entries which is obviously wrong\&. Use together with
200 \fB\-\-chronology\fR
201 to fix those kind of errors\&. Does not work with GPX output yet\&.
202 .RE
203 .PP
204 \fB\-\-from\-date \fR\fB\fIx\fR\fR
205 .RS 4
206 Used by the
207 \FCpgwupd\F[]
208 format\&. Specifies from which date waypoints should be updated\&. No checks for valid date format here, let
209 PostgreSQL
210 take care of that\&. All variants it understands can be used here\&.
211 .RE
212 .PP
213 \fB\-h\fR, \fB\-\-help\fR
214 .RS 4
215 Send a brief help summary to stdout\&.
216 .RE
217 .PP
218 \fB\-\-inside\fR
219 .RS 4
220 Print only trackpoints inside a rectangle specified by
221 \fB\-\-pos1\fR
222 and
223 \fB\-\-pos2\fR\&.
224 .RE
225 .PP
226 \fB\-n\fR, \fB\-\-undefined \fR\fB\fIx\fR\fR
227 .RS 4
228 Use
229 \fIx\fR
230 as undefined value\&.
231 .RE
232 .PP
233 \fB\-\-near\fR
234 .RS 4
235 Add names of the three closest waypoints to the trackpoint\&. Unfinished and experimental, needs
236 \fBgpsbabel\fR(1), which is called from the program as
237 \fB/usr/local/bin/gpsbabel\fR\&.
238 .RE
239 .PP
240 \fB\-o\fR, \fB\-\-output\-format \fR\fB\fIx\fR\fR
241 .RS 4
242 Use output format
243 \fIx\fR:
244 .PP
245 \fBclean\fR
246 .RS 4
247 TAB\-separated format with longitude, latitude and altitude\&.
248 .RE
249 .PP
250 \fBcsv\fR
251 .RS 4
252 TAB\-separated format:
253 .PP
254 date
255 .RS 4
256 Date of trackpoint\&. Format:
257 \FC\fIyyyy\fR\-\fImm\fR\-\fIdd\fRT\fIhh\fR:\fImm\fR:\fIss\fRZ\F[]
258 unless the
259 \fB\-\-epoch\fR
260 option is specified\&. If so, it\(cqs represented as number of seconds since 1970\-01\-01 00:00:00 UTC\&.
261 .RE
262 .PP
263 longitude
264 .RS 4
265 Longitude, decimal degrees\&.
266 .RE
267 .PP
268 latitude
269 .RS 4
270 Latitude, decimal degrees\&.
271 .RE
272 .PP
273 altitude
274 .RS 4
275 Altitude in metres above sea level\&. Optional\&. If not present, the corresponding TAB is also printed, to keep the number of columns intact\&.
276 .RE
277 .RE
278 .PP
279 \fBgpsml\fR (Default)
280 .RS 4
281 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
282 de facto
283 and widely used, so storing GPS data in anything else is sheer waste of work\&. Probably not finished yet\&.
284 .RE
285 .PP
286 \fBgpstrans\fR
287 .RS 4
288 The format generated by
289 \fBgpstrans\fR(1)\&.
290 .RE
291 .PP
292 \fBgpx\fR
293 .RS 4
294 Not complete yet, but good enough in most cases\&.
295 .RE
296 .PP
297 \fBpgtab\fR
298 .RS 4
299 TAB\-separated format for import into
300 PostgreSQL\&. Undefined values are written as
301 \FC\eN\F[]
302 if the
303 \fB\-\-undefined\fR
304 option is not specified\&.
305 .PP
306 date
307 .RS 4
308 Format:
309 \FC\fIyyyy\fR\-\fImm\fR\-\fIdd\fRT\fIhh\fR:\fImm\fR:\fIss\fRZ\F[]
310 .RE
311 .PP
312 coor
313 .RS 4
314 Format:
315 \FC(\fIlat\fR,\fIlon\fR)\F[]
316 .RE
317 .PP
318 ele
319 .RS 4
320 Altitude in metres above sea level\&.
321 .RE
322 .PP
323 name
324 .RS 4
325 Short name of closest waypoint\&. Calculated in
326 PostgreSQL, so this value is always
327 \FC\eN\F[]\&.
328 .RE
329 .PP
330 dist
331 .RS 4
332 Distance in decimal degrees to closest waypoint\&. Calculated in
333 PostgreSQL, so this value is always
334 \FC\eN\F[]\&.
335 .RE
336 .PP
337 description
338 .RS 4
339 Description of waypoint\&. Calculated in
340 PostgreSQL, so this value is always
341 \FC\eN\F[]\&.
342 .RE
343 .RE
344 .PP
345 \fBpgwtab\fR
346 .RS 4
347 Output waypoints on a TAB\-separated format:
348 .PP
349 coor
350 .RS 4
351 Format:
352 \FC(\fIlat\fR,\fIlon\fR)\F[]
353 .RE
354 .PP
355 name
356 .RS 4
357 Title of waypoint\&.
358 .RE
359 .PP
360 ele
361 .RS 4
362 Elevation in metres above sea level\&.
363 .RE
364 .PP
365 type
366 .RS 4
367 Type of waypoint, same as the GPX
368 <type>
369 element\&.
370 .RE
371 .PP
372 time
373 .RS 4
374 Timestamp of waypoint\&.
375 .RE
376 .PP
377 cmt
378 .RS 4
379 Short waypoint description, used by the GPS as a comment\&. Same as the GPX
380 <cmt>
381 element\&.
382 .RE
383 .PP
384 descr
385 .RS 4
386 Long description, not used by the GPS\&. Same as the GPX
387 <desc>
388 element\&.
389 .RE
390 .PP
391 src
392 .RS 4
393 Source of data, same as the
394 <src>
395 GPX element\&.
396 .RE
397 .PP
398 sym
399 .RS 4
400 GPS symbol name\&. Same as the
401 <sym>
402 GPX element\&.
403 .RE
404 .RE
405 .PP
406 \fBpgwupd\fR
407 .RS 4
408 Output waypoints as SQL transactions which updates the
409 name
410 and
411 dist
412 columns\&.
413 .RE
414 .PP
415 \fBposcount\fR
416 .RS 4
417 Creates a 3D plot where areas with many trackpoints are higher than areas with less track points\&.
418 .RE
419 .PP
420 \fBps\fR
421 .RS 4
422 Postscript\&. Unfinished\&.
423 .RE
424 .PP
425 \fBsvg\fR
426 .RS 4
427 Unfinished\&.
428 .RE
429 .PP
430 \fBxgraph\fR
431 .RS 4
432 Input format for
433 \fBxgraph\fR(1)\&.
434 .RE
435 .PP
436 \fBygraph\fR
437 .RS 4
438 Input format for
439 \fBygraph\fR(1)\&.
440 .RE
441 .RE
442 .PP
443 \fB\-\-outside\fR
444 .RS 4
445 Print only trackpoints outside a rectangle specified by
446 \fB\-\-pos1\fR
447 and
448 \fB\-\-pos2\fR\&.
449 .RE
450 .PP
451 \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
452 .RS 4
453 Specifies corners of an area rectangle used by the
454 \fB\-\-inside\fR
455 and
456 \fB\-\-outside\fR
457 options\&. The
458 \fIx\fR
459 and
460 \fIy\fR
461 values are specified as decimal degrees, negative for west or south\&.
462 .RE
463 .PP
464 \fB\-r\fR, \fB\-\-require \fR\fB\fIx\fR\fR
465 .RS 4
466 Specify requirements for trackpoints to be written\&.
467 \fIx\fR
468 is a string with the following flags:
469 .PP
470 \fBe\fR
471 .RS 4
472 Print only waypoints which have an elevation\&.
473 .RE
474 .PP
475 \fBp\fR
476 .RS 4
477 Print only waypoints which have a position\&.
478 .RE
479 .PP
480 \fBt\fR
481 .RS 4
482 Print only waypoints which have a timestamp\&.
483 .RE
484 .RE
485 .PP
486 \fB\-R\fR, \fB\-\-round \fR\fB\fIx\fR\fR\fB=\fR\fB\fIy\fR\fR\fB[,\fIx2\fR=\fIy2\fR[\&.\&.\&.]]\fR
487 .RS 4
488 Round trackpoint element
489 \fIx\fR
490 to
491 \fIy\fR
492 decimals\&.
493 .sp
494 Example:
495 \fB\-\-round lat=4,lon=5,ele=1\fR
496 .RE
497 .PP
498 \fB\-s\fR, \fB\-\-short\-date\fR
499 .RS 4
500 Use short date format\&.
501 .RE
502 .PP
503 \fB\-S\fR, \fB\-\-save\-to\-file \fR\fB\fIx\fR\fR
504 .RS 4
505 Save the unconverted data to a file with a filename starting with the timestamp of the first trackpoint\&. The parameter string
506 \fIx\fR
507 is added at the end of the filename\&. For the time being this option will ignore all other options\&.
508 .if n \{\
509 .sp
510 .\}
511 .RS 4
512 .BM yellow
513 .it 1 an-trap
514 .nr an-no-space-flag 1
515 .nr an-break-flag 1
516 .br
517 .ps +1
518 \fBNote\fR
519 .ps -1
520 .br
521 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\&.
522 .sp .5v
523 .EM yellow
524 .RE
525 .RE
526 .PP
527 \fB\-t\fR, \fB\-\-create\-breaks\fR
528 .RS 4
529 Create breaks in track between points with a difference more than the number of seconds specified by the
530 \fBPAUSE_LIMIT\fR
531 variable\&.
532 .RE
533 .PP
534 \fB\-T \fR\fB\fIx\fR\fR, \fB\-\-time\-shift \fR\fB\fIx\fR\fR
535 .RS 4
536 Move timestamps
537 \fIx\fR
538 seconds forwards or backwards in output\&.
539 \fIx\fR
540 can be a positive or negative integer\&.
541 .RE
542 .PP
543 \fB\-v\fR, \fB\-\-verbose\fR
544 .RS 4
545 Verbose output, can be repeated\&.
546 .RE
547 .PP
548 \fB\-\-version\fR
549 .RS 4
550 Print program version information\&.
551 .RE
552 .PP
553 \fB\-w\fR, \fB\-\-strip\-whitespace\fR
554 .RS 4
555 Strip all unnecessary whitespace\&.
556 .RE
557 .PP
558 \fB\-y\fR, \fB\-\-double\-y\-scale\fR
559 .RS 4
560 Double Y scale (latitude)\&.
561 .RE
562 .PP
563 \fB\-\-debug\fR
564 .RS 4
565 Print debugging messages\&.
566 .RE
567 .SH "Bugs and things that need to be done"
568 .sp
569 .RS 4
570 .ie n \{\
571 \h'-04'\(bu\h'+03'\c
572 .\}
573 .el \{\
574 .sp -1
575 .IP \(bu 2.3
576 .\}
577 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\&.
578 .RE
579 .sp
580 .RS 4
581 .ie n \{\
582 \h'-04'\(bu\h'+03'\c
583 .\}
584 .el \{\
585 .sp -1
586 .IP \(bu 2.3
587 .\}
588 Remove hardcodings\&.
589 .RE
590 .sp
591 .RS 4
592 .ie n \{\
593 \h'-04'\(bu\h'+03'\c
594 .\}
595 .el \{\
596 .sp -1
597 .IP \(bu 2.3
598 .\}
599 Translate database column names to English\&.
600 .RE
601 .sp
602 .RS 4
603 .ie n \{\
604 \h'-04'\(bu\h'+03'\c
605 .\}
606 .el \{\
607 .sp -1
608 .IP \(bu 2.3
609 .\}
610 Add more tests to cover all command\-line options\&.
611 .RE
612 .SH "Author"
613 .PP
614 Made by
615 Øyvind A\&. Holm
616 \FCsunny@sunbase\&.org\F[]\&.
617 .SH "Copyright"
618 .PP
619 Copyleft \(co
620 Øyvind A\&. Holm
621 \FCsunny@sunbase\&.org\F[]\&. This is free software; see the file
622 \FCCOPYING\F[]
623 for legalese stuff\&.
624 .SH "License"
625 .PP
626 This program is free software; you can redistribute it and/or modify it under the terms of the
627 GNU General Public License
628 as published by the
629 Free Software Foundation; either version 2 of the License, or (at your option) any later version\&.
630 .PP
631 This program is distributed in the hope that it will be useful, but
632 \fIWITHOUT ANY WARRANTY\fR; without even the implied warranty of
633 \fIMERCHANTABILITY\fR
634 or
635 \fIFITNESS FOR A PARTICULAR PURPOSE\fR\&. See the GNU General Public License for more details\&.
636 .PP
637 You should have received a copy of the GNU General Public License along with this program; if not, write to
638 .sp
639 .if n \{\
640 .RS 4
641 .\}
642 .fam C
643 .ps -1
644 .nf
645 The Free Software Foundation, Inc\&.
646 59 Temple Place, Suite 330
647 Boston, MA 02111\-1307
648 USA
649 .fi
650 .fam
651 .ps +1
652 .if n \{\
653 .RE
654 .\}
655 .SH "See also"
656 .PP
657 \fBgpsbabel\fR(1)