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