| blob | 5aa25a8e842e77e879ac039cfd4621073951231d |
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 sted
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 .PP
344 avst
345 .RS 4
346 Distance to trackpoint in decimal degrees from a defined
347 \(lqhome\(rq
348 position\&. This is calculated in
349 PostgreSQL, so the field value is always
350 \FC\eN\F[]\&.
351 .RE
352 .RE
353 .PP
354 \fBpgwtab\fR
355 .RS 4
356 Output waypoints on a TAB\-separated format:
357 .PP
358 coor
359 .RS 4
360 Format:
361 \FC(\fIlat\fR,\fIlon\fR)\F[]
362 .RE
363 .PP
364 name
365 .RS 4
366 Title of waypoint\&.
367 .RE
368 .PP
369 ele
370 .RS 4
371 Elevation in metres above sea level\&.
372 .RE
373 .PP
374 type
375 .RS 4
376 Type of waypoint, same as the GPX
377 <type>
378 element\&.
379 .RE
380 .PP
381 time
382 .RS 4
383 Timestamp of waypoint\&.
384 .RE
385 .PP
386 cmt
387 .RS 4
388 Short waypoint description, used by the GPS as a comment\&. Same as the GPX
389 <cmt>
390 element\&.
391 .RE
392 .PP
393 descr
394 .RS 4
395 Long description, not used by the GPS\&. Same as the GPX
396 <desc>
397 element\&.
398 .RE
399 .PP
400 src
401 .RS 4
402 Source of data, same as the
403 <src>
404 GPX element\&.
405 .RE
406 .PP
407 sym
408 .RS 4
409 GPS symbol name\&. Same as the
410 <sym>
411 GPX element\&.
412 .RE
413 .RE
414 .PP
415 \fBpgwupd\fR
416 .RS 4
417 Output waypoints as SQL transactions which updates the
418 sted
419 and
420 dist
421 columns\&.
422 .RE
423 .PP
424 \fBposcount\fR
425 .RS 4
426 Creates a 3D plot where areas with many trackpoints are higher than areas with less track points\&.
427 .RE
428 .PP
429 \fBps\fR
430 .RS 4
431 Postscript\&. Unfinished\&.
432 .RE
433 .PP
434 \fBsvg\fR
435 .RS 4
436 Unfinished\&.
437 .RE
438 .PP
439 \fBxgraph\fR
440 .RS 4
441 Input format for
442 \fBxgraph\fR(1)\&.
443 .RE
444 .PP
445 \fBygraph\fR
446 .RS 4
447 Input format for
448 \fBygraph\fR(1)\&.
449 .RE
450 .RE
451 .PP
452 \fB\-\-outside\fR
453 .RS 4
454 Print only trackpoints outside a rectangle specified by
455 \fB\-\-pos1\fR
456 and
457 \fB\-\-pos2\fR\&.
458 .RE
459 .PP
460 \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
461 .RS 4
462 Specifies corners of an area rectangle used by the
463 \fB\-\-inside\fR
464 and
465 \fB\-\-outside\fR
466 options\&. The
467 \fIx\fR
468 and
469 \fIy\fR
470 values are specified as decimal degrees, negative for west or south\&.
471 .RE
472 .PP
473 \fB\-r\fR, \fB\-\-require \fR\fB\fIx\fR\fR
474 .RS 4
475 Specify requirements for trackpoints to be written\&.
476 \fIx\fR
477 is a string with the following flags:
478 .PP
479 \fBe\fR
480 .RS 4
481 Print only waypoints which have an elevation\&.
482 .RE
483 .PP
484 \fBp\fR
485 .RS 4
486 Print only waypoints which have a position\&.
487 .RE
488 .PP
489 \fBt\fR
490 .RS 4
491 Print only waypoints which have a timestamp\&.
492 .RE
493 .RE
494 .PP
495 \fB\-R\fR, \fB\-\-round \fR\fB\fIx\fR\fR\fB=\fR\fB\fIy\fR\fR\fB[,\fIx2\fR=\fIy2\fR[\&.\&.\&.]]\fR
496 .RS 4
497 Round trackpoint element
498 \fIx\fR
499 to
500 \fIy\fR
501 decimals\&.
502 .sp
503 Example:
504 \fB\-\-round lat=4,lon=5,ele=1\fR
505 .RE
506 .PP
507 \fB\-s\fR, \fB\-\-short\-date\fR
508 .RS 4
509 Use short date format\&.
510 .RE
511 .PP
512 \fB\-S\fR, \fB\-\-save\-to\-file \fR\fB\fIx\fR\fR
513 .RS 4
514 Save the unconverted data to a file with a filename starting with the timestamp of the first trackpoint\&. The parameter string
515 \fIx\fR
516 is added at the end of the filename\&. For the time being this option will ignore all other options\&.
517 .if n \{\
518 .sp
519 .\}
520 .RS 4
521 .BM yellow
522 .it 1 an-trap
523 .nr an-no-space-flag 1
524 .nr an-break-flag 1
525 .br
526 .ps +1
527 \fBNote\fR
528 .ps -1
529 .br
530 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\&.
531 .sp .5v
532 .EM yellow
533 .RE
534 .RE
535 .PP
536 \fB\-t\fR, \fB\-\-create\-breaks\fR
537 .RS 4
538 Create breaks in track between points with a difference more than the number of seconds specified by the
539 \fBPAUSE_LIMIT\fR
540 variable\&.
541 .RE
542 .PP
543 \fB\-T \fR\fB\fIx\fR\fR, \fB\-\-time\-shift \fR\fB\fIx\fR\fR
544 .RS 4
545 Move timestamps
546 \fIx\fR
547 seconds forwards or backwards in output\&.
548 \fIx\fR
549 can be a positive or negative integer\&.
550 .RE
551 .PP
552 \fB\-v\fR, \fB\-\-verbose\fR
553 .RS 4
554 Verbose output, can be repeated\&.
555 .RE
556 .PP
557 \fB\-\-version\fR
558 .RS 4
559 Print program version information\&.
560 .RE
561 .PP
562 \fB\-w\fR, \fB\-\-strip\-whitespace\fR
563 .RS 4
564 Strip all unnecessary whitespace\&.
565 .RE
566 .PP
567 \fB\-y\fR, \fB\-\-double\-y\-scale\fR
568 .RS 4
569 Double Y scale (latitude)\&.
570 .RE
571 .PP
572 \fB\-\-debug\fR
573 .RS 4
574 Print debugging messages\&.
575 .RE
576 .SH "Bugs and things that need to be done"
577 .sp
578 .RS 4
579 .ie n \{\
580 \h'-04'\(bu\h'+03'\c
581 .\}
582 .el \{\
583 .sp -1
584 .IP \(bu 2.3
585 .\}
586 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\&.
587 .RE
588 .sp
589 .RS 4
590 .ie n \{\
591 \h'-04'\(bu\h'+03'\c
592 .\}
593 .el \{\
594 .sp -1
595 .IP \(bu 2.3
596 .\}
597 Remove hardcodings, for example the
598 \(lqhome\(rq
599 position used to calculate the
600 avst
601 database column\&.
602 .RE
603 .sp
604 .RS 4
605 .ie n \{\
606 \h'-04'\(bu\h'+03'\c
607 .\}
608 .el \{\
609 .sp -1
610 .IP \(bu 2.3
611 .\}
612 Translate database column names to English\&.
613 .RE
614 .sp
615 .RS 4
616 .ie n \{\
617 \h'-04'\(bu\h'+03'\c
618 .\}
619 .el \{\
620 .sp -1
621 .IP \(bu 2.3
622 .\}
623 Add more tests to cover all command\-line options\&.
624 .RE
625 .SH "Author"
626 .PP
627 Made by
628 Øyvind A\&. Holm
629 \FCsunny@sunbase\&.org\F[]\&.
630 .SH "Copyright"
631 .PP
632 Copyleft \(co
633 Øyvind A\&. Holm
634 \FCsunny@sunbase\&.org\F[]\&. This is free software; see the file
635 \FCCOPYING\F[]
636 for legalese stuff\&.
637 .SH "License"
638 .PP
639 This program is free software; you can redistribute it and/or modify it under the terms of the
640 GNU General Public License
641 as published by the
642 Free Software Foundation; either version 2 of the License, or (at your option) any later version\&.
643 .PP
644 This program is distributed in the hope that it will be useful, but
645 \fIWITHOUT ANY WARRANTY\fR; without even the implied warranty of
646 \fIMERCHANTABILITY\fR
647 or
648 \fIFITNESS FOR A PARTICULAR PURPOSE\fR\&. See the GNU General Public License for more details\&.
649 .PP
650 You should have received a copy of the GNU General Public License along with this program; if not, write to
651 .sp
652 .if n \{\
653 .RS 4
654 .\}
655 .fam C
656 .ps -1
657 .nf
658 The Free Software Foundation, Inc\&.
659 59 Temple Place, Suite 330
660 Boston, MA 02111\-1307
661 USA
662 .fi
663 .fam
664 .ps +1
665 .if n \{\
666 .RE
667 .\}
668 .SH "See also"
669 .PP
670 \fBgpsbabel\fR(1)