doc/gpst.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4//EN" "../../../Tools/dtd/docbook-4.4/docbookx.dtd">
   3 <refentry id="gpst" lang="en">
   4   <!-- File ID: 84662624-f924-11dd-9043-0001805bf4b1 -->
   5   <refmeta>
   6     <refentrytitle>gpst</refentrytitle>
   7     <manvolnum>1</manvolnum>
   8   </refmeta>
   9   <refnamediv>
  10     <refname>gpst</refname>
  11     <refpurpose>Converts between various GPS formats.</refpurpose>
  12   </refnamediv>
  13   <refsynopsisdiv>
  14
  15     <cmdsynopsis>
  16       <command>gpst</command>
  17       <arg choice="opt">
  18         <replaceable>options</replaceable>
  19       </arg>
  20       <arg choice="opt" rep="repeat">
  21         <replaceable>file</replaceable>
  22       </arg>
  23     </cmdsynopsis>
  24
  25     <cmdsynopsis>
  26       <command>gpst</command>
  27       <arg choice="req">-S</arg>
  28       <arg choice="opt">
  29         <replaceable>options</replaceable>
  30       </arg>
  31       <arg choice="opt" rep="repeat">
  32         <replaceable>file</replaceable>
  33       </arg>
  34     </cmdsynopsis>
  35
  36   </refsynopsisdiv>
  37   <refsect1 id="gpst.description">
  38     <title>Description</title>
  39
  40     <variablelist>
  41
  42       <varlistentry>
  43         <term><option>--chronology</option></term>
  44         <listitem>
  45           <para>Check for broken chronology, warn about entries with an
  46           old timestamp.</para>
  47         </listitem>
  48       </varlistentry>
  49
  50       <varlistentry>
  51         <term><option>-d</option>, <option>--skip-dups</option></term>
  52         <listitem>
  53           <para>If succeeding identical coordinates are found, print
  54           only the first one and ignore the rest.</para>
  55         </listitem>
  56       </varlistentry>
  57
  58       <varlistentry>
  59         <term><option>-e</option>, <option>--epoch</option></term>
  60         <listitem>
  61           <para>Use seconds since 1970-01-01 00:00:00 GMT as date
  62           format.</para>
  63         </listitem>
  64       </varlistentry>
  65
  66       <varlistentry>
  67         <term><option>--fix</option></term>
  68         <listitem>
  69           <para>Comment out entries which is obviously wrong.
  70           Use together with <option>--chronology</option> to fix those
  71           kind of errors.
  72           Does not work with GPX output yet.</para>
  73         </listitem>
  74       </varlistentry>
  75
  76       <varlistentry>
  77         <term><option>--from-date
  78         <replaceable>x</replaceable></option></term>
  79         <listitem>
  80           <para>Used by the <literal>pgwupd</literal> format.
  81           Specifies from which date waypoints should be updated.
  82           No checks for valid date format here, let
  83           <application>PostgreSQL</application> take care of that.
  84           All variants it understands can be used here.</para>
  85         </listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><option>-h</option>, <option>--help</option></term>
  90         <listitem>
  91           <para>Send a brief help summary to stdout.</para>
  92         </listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term><option>--inside</option></term>
  97         <listitem>
  98           <para>Print only trackpoints inside a rectangle specified by
  99           <option>--pos1</option> and <option>--pos2</option>.</para>
 100         </listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term><option>-n</option>, <option>--undefined
 105         <replaceable>x</replaceable></option></term>
 106         <listitem>
 107           <para>Use <replaceable>x</replaceable> as undefined
 108           value.</para>
 109         </listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><option>--near</option></term>
 114         <listitem>
 115           <para>Add names of the three closest waypoints to the
 116           trackpoint.
 117           Unfinished and experimental, needs <citerefentry>
 118           <refentrytitle>gpsbabel</refentrytitle>
 119           <manvolnum>1</manvolnum> </citerefentry>, which is called from
 120           the program as
 121           <command>/usr/local/bin/gpsbabel</command>.</para>
 122         </listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>-o</option>, <option>--output-format
 127         <replaceable>x</replaceable></option></term>
 128         <listitem>
 129           <para>Use output format <replaceable>x</replaceable>:</para>
 130           <variablelist>
 131
 132             <varlistentry>
 133               <term><option>clean</option></term>
 134               <listitem>
 135                 <para>TAB-separated format with longitude, latitude and
 136                 altitude.</para>
 137               </listitem>
 138             </varlistentry>
 139
 140             <varlistentry>
 141               <term><option>csv</option></term>
 142               <listitem>
 143                 <para>TAB-separated format:
 144                 <variablelist>
 145
 146                   <varlistentry>
 147                     <term>date</term>
 148                     <listitem>
 149                       <para>Date of trackpoint.
 150                       Format:
 151                       <literal><replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>T<replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>ss</replaceable>Z</literal>
 152                       unless the <option>--epoch</option> option is
 153                       specified.
 154                       If so, it’s represented as number of seconds since
 155                       1970-01-01 00:00:00 UTC.</para>
 156                     </listitem>
 157                   </varlistentry>
 158
 159                   <varlistentry>
 160                     <term>longitude</term>
 161                     <listitem>
 162                       <para>Longitude, decimal degrees.</para>
 163                     </listitem>
 164                   </varlistentry>
 165
 166                   <varlistentry>
 167                     <term>latitude</term>
 168                     <listitem>
 169                       <para>Latitude, decimal degrees.</para>
 170                     </listitem>
 171                   </varlistentry>
 172
 173                   <varlistentry>
 174                     <term>altitude</term>
 175                     <listitem>
 176                       <para>Altitude in metres above sea level.
 177                       Optional.
 178                       If not present, the corresponding TAB is also
 179                       printed, to keep the number of columns
 180                       intact.</para>
 181                     </listitem>
 182                   </varlistentry>
 183
 184                 </variablelist></para>
 185               </listitem>
 186             </varlistentry>
 187
 188             <varlistentry>
 189               <term><option>gpsml</option> (Default)</term>
 190               <listitem>
 191                 <para>Line-based XML which makes it easy to edit and
 192                 grep.
 193                 In the past, there was this big plan about making this
 194                 the default storage format, so it was declared as The
 195                 Honourable Default Output Format.
 196                 But using GPX is the way to go, so this will probably
 197                 change in the future.
 198                 It’s way too <foreignphrase>de facto</foreignphrase> and
 199                 widely used, so storing GPS data in anything else is
 200                 sheer waste of work.
 201                 Probably not finished yet.</para>
 202               </listitem>
 203             </varlistentry>
 204
 205             <varlistentry>
 206               <term><option>gpstrans</option></term>
 207               <listitem>
 208                 <para>The format generated by <citerefentry>
 209                 <refentrytitle>gpstrans</refentrytitle>
 210                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 211               </listitem>
 212             </varlistentry>
 213
 214             <varlistentry>
 215               <term><option>gpx</option></term>
 216               <listitem>
 217                 <para>Not complete yet, but good enough in most
 218                 cases.</para>
 219               </listitem>
 220             </varlistentry>
 221
 222             <varlistentry>
 223               <term><option>pgtab</option></term>
 224               <listitem>
 225                 <para>TAB-separated format for import into
 226                 <application>PostgreSQL</application>.
 227                 Undefined values are written as <literal>\N</literal> if
 228                 the <option>--undefined</option> option is not
 229                 specified.</para>
 230                 <variablelist>
 231
 232                   <varlistentry>
 233                     <term><database class="field">date</database></term>
 234                     <listitem>
 235                       <para>Format:
 236                       <literal><replaceable>yyyy</replaceable>-<replaceable>mm</replaceable>-<replaceable>dd</replaceable>T<replaceable>hh</replaceable>:<replaceable>mm</replaceable>:<replaceable>ss</replaceable>Z</literal></para>
 237                     </listitem>
 238                   </varlistentry>
 239
 240                   <varlistentry>
 241                     <term><database class="field">coor</database></term>
 242                     <listitem>
 243                       <para>Format:
 244                       <literal>(<replaceable>lat</replaceable>,<replaceable>lon</replaceable>)</literal></para>
 245                     </listitem>
 246                   </varlistentry>
 247
 248                   <varlistentry>
 249                     <term><database class="field">ele</database></term>
 250                     <listitem>
 251                       <para>Altitude in metres above sea level.</para>
 252                     </listitem>
 253                   </varlistentry>
 254
 255                   <varlistentry>
 256                     <term><database class="field">name</database></term>
 257                     <listitem>
 258                       <para>Short name of closest waypoint.
 259                       Calculated in
 260                       <application>PostgreSQL</application>, so this
 261                       value is always <literal>\N</literal>.</para>
 262                     </listitem>
 263                   </varlistentry>
 264
 265                   <varlistentry>
 266                     <term><database class="field">dist</database></term>
 267                     <listitem>
 268                       <para>Distance in decimal degrees to closest
 269                       waypoint.
 270                       Calculated in
 271                       <application>PostgreSQL</application>, so this
 272                       value is always <literal>\N</literal>.</para>
 273                     </listitem>
 274                   </varlistentry>
 275
 276                   <varlistentry>
 277                     <term><database
 278                     class="field">description</database></term>
 279                     <listitem>
 280                       <para>Description of waypoint.
 281                       Calculated in
 282                       <application>PostgreSQL</application>, so this
 283                       value is always <literal>\N</literal>.</para>
 284                     </listitem>
 285                   </varlistentry>
 286
 287                 </variablelist>
 288               </listitem>
 289             </varlistentry>
 290
 291             <varlistentry>
 292               <term><option>pgwtab</option></term>
 293               <listitem>
 294                 <para>Output waypoints on a TAB-separated format:</para>
 295                 <variablelist>
 296
 297                   <varlistentry>
 298                     <term><database class="field">coor</database></term>
 299                     <listitem>
 300                       <para>Format:
 301                       <literal>(<replaceable>lat</replaceable>,<replaceable>lon</replaceable>)</literal></para>
 302                     </listitem>
 303                   </varlistentry>
 304
 305                   <varlistentry>
 306                     <term><database class="field">name</database></term>
 307                     <listitem>
 308                       <para>Title of waypoint.</para>
 309                     </listitem>
 310                   </varlistentry>
 311
 312                   <varlistentry>
 313                     <term><database class="field">ele</database></term>
 314                     <listitem>
 315                       <para>Elevation in metres above sea level.</para>
 316                     </listitem>
 317                   </varlistentry>
 318
 319                   <varlistentry>
 320                     <term><database class="field">type</database></term>
 321                     <listitem>
 322                       <para>Type of waypoint, same as the GPX <sgmltag
 323                       class="starttag">type</sgmltag> element.</para>
 324                     </listitem>
 325                   </varlistentry>
 326
 327                   <varlistentry>
 328                     <term><database class="field">time</database></term>
 329                     <listitem>
 330                       <para>Timestamp of waypoint.</para>
 331                     </listitem>
 332                   </varlistentry>
 333
 334                   <varlistentry>
 335                     <term><database class="field">cmt</database></term>
 336                     <listitem>
 337                       <para>Short waypoint description, used by the GPS
 338                       as a comment.
 339                       Same as the GPX <sgmltag
 340                       class="starttag">cmt</sgmltag> element.</para>
 341                     </listitem>
 342                   </varlistentry>
 343
 344                   <varlistentry>
 345                     <term><database
 346                     class="field">descr</database></term>
 347                     <listitem>
 348                       <para>Long description, not used by the GPS.
 349                       Same as the GPX <sgmltag
 350                       class="starttag">desc</sgmltag> element.</para>
 351                     </listitem>
 352                   </varlistentry>
 353
 354                   <varlistentry>
 355                     <term><database class="field">src</database></term>
 356                     <listitem>
 357                       <para>Source of data, same as the <sgmltag
 358                       class="starttag">src</sgmltag> GPX element.</para>
 359                     </listitem>
 360                   </varlistentry>
 361
 362                   <varlistentry>
 363                     <term><database class="field">sym</database></term>
 364                     <listitem>
 365                       <para>GPS symbol name.
 366                       Same as the <sgmltag
 367                       class="starttag">sym</sgmltag> GPX element.</para>
 368                     </listitem>
 369                   </varlistentry>
 370
 371                 </variablelist>
 372               </listitem>
 373             </varlistentry>
 374
 375             <varlistentry>
 376               <term><option>pgwupd</option></term>
 377               <listitem>
 378                 <para>Output waypoints as SQL transactions which updates
 379                 the <database class="field">name</database> and
 380                 <database class="field">dist</database> columns.</para>
 381               </listitem>
 382             </varlistentry>
 383
 384             <varlistentry>
 385               <term><option>poscount</option></term>
 386               <listitem>
 387                 <para>Creates a 3D plot where areas with many
 388                 trackpoints are higher than areas with less track
 389                 points.</para>
 390               </listitem>
 391             </varlistentry>
 392
 393             <varlistentry>
 394               <term><option>ps</option></term>
 395               <listitem>
 396                 <para>Postscript. Unfinished.</para>
 397               </listitem>
 398             </varlistentry>
 399
 400             <varlistentry>
 401               <term><option>svg</option></term>
 402               <listitem>
 403                 <para>Unfinished.</para>
 404               </listitem>
 405             </varlistentry>
 406
 407             <varlistentry>
 408               <term><option>xgraph</option></term>
 409               <listitem>
 410                 <para>Input format for <citerefentry>
 411                 <refentrytitle>xgraph</refentrytitle>
 412                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 413               </listitem>
 414             </varlistentry>
 415
 416             <varlistentry>
 417               <term><option>ygraph</option></term>
 418               <listitem>
 419                 <para>Input format for <citerefentry>
 420                 <refentrytitle>ygraph</refentrytitle>
 421                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 422               </listitem>
 423             </varlistentry>
 424
 425           </variablelist>
 426         </listitem>
 427       </varlistentry>
 428
 429       <varlistentry>
 430         <term><option>--outside</option></term>
 431         <listitem>
 432           <para>Print only trackpoints outside a rectangle specified by
 433           <option>--pos1</option> and <option>--pos2</option>.</para>
 434         </listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term><option>--pos1
 439         <replaceable>x1</replaceable>,<replaceable>y1</replaceable></option></term>
 440         <term><option>--pos2
 441         <replaceable>x2</replaceable>,<replaceable>y2</replaceable></option></term>
 442         <listitem>
 443           <para>Specifies corners of an area rectangle used by the
 444           <option>--inside</option> and <option>--outside</option>
 445           options.
 446           The <replaceable>x</replaceable> and
 447           <replaceable>y</replaceable> values are specified as decimal
 448           degrees, negative for west or south.</para>
 449         </listitem>
 450       </varlistentry>
 451
 452       <varlistentry>
 453         <term><option>-r</option>, <option>--require
 454         <replaceable>x</replaceable></option></term>
 455         <listitem>
 456           <para>Specify requirements for trackpoints to be written.
 457           <replaceable>x</replaceable> is a string with the following
 458           flags:</para>
 459           <variablelist>
 460
 461             <varlistentry>
 462               <term><option>e</option></term>
 463               <listitem>
 464                 <para>Print only waypoints which have an
 465                 elevation.</para>
 466               </listitem>
 467             </varlistentry>
 468
 469             <varlistentry>
 470               <term><option>p</option></term>
 471               <listitem>
 472                 <para>Print only waypoints which have a position.</para>
 473               </listitem>
 474             </varlistentry>
 475
 476             <varlistentry>
 477               <term><option>t</option></term>
 478               <listitem>
 479                 <para>Print only waypoints which have a
 480                 timestamp.</para>
 481               </listitem>
 482             </varlistentry>
 483
 484           </variablelist>
 485         </listitem>
 486       </varlistentry>
 487
 488       <varlistentry>
 489         <term><option>-R</option>, <option>--round
 490         <replaceable>x</replaceable>=<replaceable>y</replaceable><optional>,<replaceable>x2</replaceable>=<replaceable>y2</replaceable><optional>...</optional></optional></option></term>
 491         <listitem>
 492           <para>Round trackpoint element <replaceable>x</replaceable> to
 493           <replaceable>y</replaceable> decimals.</para>
 494           <para>Example:</para>
 495           <blockquote>
 496             <para><option>--round lat=4,lon=5,ele=1</option></para>
 497           </blockquote>
 498         </listitem>
 499       </varlistentry>
 500
 501       <varlistentry>
 502         <term><option>-s</option>, <option>--short-date</option></term>
 503         <listitem>
 504           <para>Use short date format.</para>
 505         </listitem>
 506       </varlistentry>
 507
 508       <varlistentry>
 509         <term><option>-S</option>, <option>--save-to-file
 510         <replaceable>x</replaceable></option></term>
 511         <listitem>
 512           <para>Save the unconverted data to a file with a filename
 513           starting with the timestamp of the first trackpoint.
 514           The parameter string <replaceable>x</replaceable> is added at
 515           the end of the filename.
 516           For the time being this option will ignore all other
 517           options.</para>
 518           <note>
 519             <para>If several files are specified on the command line,
 520             all data will be saved into only one file.
 521             This behaviour may change in the future.</para>
 522           </note>
 523         </listitem>
 524       </varlistentry>
 525
 526       <varlistentry>
 527         <term><option>-t</option>,
 528         <option>--create-breaks</option></term>
 529         <listitem>
 530           <para>Create breaks in track between points with a difference
 531           more than the number of seconds specified by the
 532           <envar>PAUSE_LIMIT</envar> variable.</para>
 533         </listitem>
 534       </varlistentry>
 535
 536       <varlistentry>
 537         <term><option>-T <replaceable>x</replaceable></option>,
 538         <option>--time-shift
 539         <replaceable>x</replaceable></option></term>
 540         <listitem>
 541           <para>Move timestamps <replaceable>x</replaceable> seconds
 542           forwards or backwards in output.
 543           <replaceable>x</replaceable> can be a positive or negative
 544           integer.</para>
 545         </listitem>
 546       </varlistentry>
 547
 548       <varlistentry>
 549         <term><option>-v</option>, <option>--verbose</option></term>
 550         <listitem>
 551           <para>Verbose output, can be repeated.</para>
 552         </listitem>
 553       </varlistentry>
 554
 555       <varlistentry>
 556         <term><option>--version</option></term>
 557         <listitem>
 558           <para>Print program version information.</para>
 559         </listitem>
 560       </varlistentry>
 561
 562       <varlistentry>
 563         <term><option>-w</option>,
 564         <option>--strip-whitespace</option></term>
 565         <listitem>
 566           <para>Strip all unnecessary whitespace.</para>
 567         </listitem>
 568       </varlistentry>
 569
 570       <varlistentry>
 571         <term><option>-y</option>,
 572         <option>--double-y-scale</option></term>
 573         <listitem>
 574           <para>Double Y scale (latitude).</para>
 575         </listitem>
 576       </varlistentry>
 577
 578       <varlistentry>
 579         <term><option>--debug</option></term>
 580         <listitem>
 581           <para>Print debugging messages.</para>
 582         </listitem>
 583       </varlistentry>
 584
 585     </variablelist>
 586
 587   </refsect1>
 588   <refsect1 id="gpst.bugs">
 589     <title>Bugs and things that need to be done</title>
 590
 591     <itemizedlist>
 592
 593       <listitem>
 594         <para>Pretty incomplete in some areas.
 595         Some of the source formats are undocumented and thus incomplete.
 596         Some functionality is not working properly, for example the
 597         Postscript output.</para>
 598       </listitem>
 599
 600       <listitem>
 601         <para>Remove hardcodings.</para>
 602       </listitem>
 603
 604       <listitem>
 605         <para>Translate database column names to English.</para>
 606       </listitem>
 607
 608       <listitem>
 609         <para>Add more tests to cover all command-line options.</para>
 610       </listitem>
 611
 612     </itemizedlist>
 613
 614   </refsect1>
 615   <refsect1 id="gpst.author">
 616     <title>Author</title>
 617
 618     <para>Made by <personname><firstname>Øyvind</firstname>
 619     <othername>A.</othername> <surname>Holm</surname></personname>
 620     <email>sunny@sunbase.org</email>.</para>
 621
 622   </refsect1>
 623   <refsect1 id="gpst.copyright">
 624     <title>Copyright</title>
 625
 626     <para>Copyleft © <personname><firstname>Øyvind</firstname>
 627     <othername>A.</othername> <surname>Holm</surname></personname>
 628     <email>sunny@sunbase.org</email>.
 629     This is free software; see the file <filename>COPYING</filename> for
 630     legalese stuff.</para>
 631
 632   </refsect1>
 633   <refsect1 id="gpst.license">
 634     <title>License</title>
 635
 636     <para>This program is free software: you can redistribute it and/or
 637     modify it under the terms of the <citetitle>GNU General Public
 638     License</citetitle> as published by the <orgname
 639     class="nonprofit">Free Software Foundation</orgname>, either version
 640     3 of the License, or (at your option) any later version.</para>
 641
 642     <para>This program is distributed in the hope that it will be
 643     useful, but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even
 644     the implied warranty of <emphasis>MERCHANTABILITY</emphasis> or
 645     <emphasis>FITNESS FOR A PARTICULAR PURPOSE</emphasis>.
 646     See the GNU General Public License for more details.</para>
 647
 648     <para>You should have received a copy of the GNU General Public
 649     License along with this program.
 650     If not, see <ulink url="http://www.gnu.org/licenses/" />.</para>
 651
 652   </refsect1>
 653   <refsect1 id="gpst.seealso">
 654     <title>See also</title>
 655
 656     <para><citerefentry>
 657       <refentrytitle>gpsbabel</refentrytitle>
 658       <manvolnum>1</manvolnum>
 659     </citerefentry></para>
 660
 661   </refsect1>
 662   <!-- vim: set tw=72 ts=2 sts=2 sw=2 et fo=tcqw fenc=UTF-8 : -->
 663 </refentry>