branches/gpst.xml-option/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     <cmdsynopsis>
  17       <command>gpst</command>
  18       <arg choice="opt">
  19         <replaceable>options</replaceable>
  20       </arg>
  21       <arg choice="opt" rep="repeat">
  22         <replaceable>file</replaceable>
  23       </arg>
  24     </cmdsynopsis>
  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     <cmdsynopsis>
  36       <command>gpst</command>
  37       <arg choice="req">-u</arg>
  38       <arg choice="opt">
  39         <replaceable>options</replaceable>
  40       </arg>
  41       <arg choice="opt" rep="repeat">
  42         <replaceable>file</replaceable>
  43       </arg>
  44     </cmdsynopsis>
  45   </refsynopsisdiv>
  46   <refsect1 id="gpst.description">
  47     <title>Description</title>
  48
  49     <variablelist>
  50
  51       <varlistentry>
  52         <term><option>--chronology</option></term>
  53         <listitem>
  54           <para>Check for broken chronology, warn about entries with an
  55           old timestamp.
  56           If the <option>--xml</option> option is specified, the result
  57           of the scan is written to stdout as usual, and all other
  58           output is suppressed.
  59           If the <option>--xml</option> option is
  60           <emphasis>not</emphasis> used, it is reported as warnings to
  61           stderr.</para>
  62         </listitem>
  63       </varlistentry>
  64
  65       <varlistentry>
  66         <term><option>-d</option>, <option>--skip-dups</option></term>
  67         <listitem>
  68           <para>If succeeding identical coordinates are found, print
  69           only the first one and ignore the rest.</para>
  70         </listitem>
  71       </varlistentry>
  72
  73       <varlistentry>
  74         <term><option>-e</option>, <option>--epoch</option></term>
  75         <listitem>
  76           <para>Use seconds since 1970-01-01 00:00:00 GMT as date
  77           format.</para>
  78         </listitem>
  79       </varlistentry>
  80
  81       <varlistentry>
  82         <term><option>--fix</option></term>
  83         <listitem>
  84           <para>Comment out entries which is obviously wrong.
  85           Use together with <option>--chronology</option> to fix those
  86           kind of errors.
  87           Does not work with GPX output yet.</para>
  88         </listitem>
  89       </varlistentry>
  90
  91       <varlistentry>
  92         <term><option>-h</option>, <option>--help</option></term>
  93         <listitem>
  94           <para>Send a brief help summary to stdout.</para>
  95         </listitem>
  96       </varlistentry>
  97
  98       <varlistentry>
  99         <term><option>--inside</option></term>
 100         <listitem>
 101           <para>Print only trackpoints inside a rectangle specified by
 102           <option>--pos1</option> and <option>--pos2</option>.</para>
 103         </listitem>
 104       </varlistentry>
 105
 106       <varlistentry>
 107         <term><option>--near</option></term>
 108         <listitem>
 109           <para>Add names of the three closest waypoints to the
 110           trackpoint.
 111           Unfinished and experimental, needs <citerefentry>
 112           <refentrytitle>gpsbabel</refentrytitle>
 113           <manvolnum>1</manvolnum> </citerefentry>.</para>
 114         </listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><option>-n</option>, <option>--undefined
 119         <replaceable>x</replaceable></option></term>
 120         <listitem>
 121           <para>Use <replaceable>x</replaceable> as undefined
 122           value.</para>
 123         </listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>-o</option>, <option>--output-format
 128         <replaceable>x</replaceable></option></term>
 129         <listitem>
 130           <para>Use output format <replaceable>x</replaceable>:</para>
 131           <variablelist>
 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>poscount</option></term>
 224               <listitem>
 225                 <para>Creates a 3D plot where areas with many
 226                 trackpoints are higher than areas with less track
 227                 points.</para>
 228               </listitem>
 229             </varlistentry>
 230
 231             <varlistentry>
 232               <term><option>ps</option></term>
 233               <listitem>
 234                 <para>Postscript. Unfinished.</para>
 235               </listitem>
 236             </varlistentry>
 237
 238             <varlistentry>
 239               <term><option>svg</option></term>
 240               <listitem>
 241                 <para>Unfinished.</para>
 242               </listitem>
 243             </varlistentry>
 244
 245             <varlistentry>
 246               <term><option>xgraph</option></term>
 247               <listitem>
 248                 <para>Input format for <citerefentry>
 249                 <refentrytitle>xgraph</refentrytitle>
 250                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 251               </listitem>
 252             </varlistentry>
 253
 254             <varlistentry>
 255               <term><option>ygraph</option></term>
 256               <listitem>
 257                 <para>Input format for <citerefentry>
 258                 <refentrytitle>ygraph</refentrytitle>
 259                 <manvolnum>1</manvolnum> </citerefentry>.</para>
 260               </listitem>
 261             </varlistentry>
 262           </variablelist>
 263         </listitem>
 264
 265       </varlistentry>
 266
 267       <varlistentry>
 268         <term><option>--outside</option></term>
 269         <listitem>
 270           <para>Print only trackpoints outside a rectangle specified by
 271           <option>--pos1</option> and <option>--pos2</option>.</para>
 272         </listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><option>--pos1
 277         <replaceable>x</replaceable></option></term>
 278         <term><option>--pos2
 279         <replaceable>x</replaceable></option></term>
 280
 281         <listitem>
 282           <para>Specifies corners of an area rectangle used by the
 283           <option>--inside</option> and <option>--outside</option>
 284           options.
 285           The <replaceable>x</replaceable> value is in
 286           <literal><replaceable>lat</replaceable>,<replaceable>lon</replaceable></literal>
 287           format (decimal degrees, negative for west or south).</para>
 288         </listitem>
 289       </varlistentry>
 290
 291       <varlistentry>
 292         <term><option>-r</option>, <option>--require
 293         <replaceable>x</replaceable></option></term>
 294         <listitem>
 295           <para>Specify requirements for trackpoints to be written.
 296           <replaceable>x</replaceable> is a string with the following
 297           flags:</para>
 298           <variablelist>
 299             <varlistentry>
 300               <term><option>e</option></term>
 301               <listitem>
 302                 <para>Print only waypoints which have an
 303                 elevation.</para>
 304               </listitem>
 305             </varlistentry>
 306             <varlistentry>
 307               <term><option>p</option></term>
 308               <listitem>
 309                 <para>Print only waypoints which have a position.</para>
 310               </listitem>
 311             </varlistentry>
 312             <varlistentry>
 313               <term><option>t</option></term>
 314               <listitem>
 315                 <para>Print only waypoints which have a
 316                 timestamp.</para>
 317               </listitem>
 318             </varlistentry>
 319           </variablelist>
 320         </listitem>
 321       </varlistentry>
 322
 323       <varlistentry>
 324         <term><option>-R</option>, <option>--round
 325         <replaceable>x</replaceable>=<replaceable>y</replaceable><optional>,<replaceable>x2</replaceable>=<replaceable>y2</replaceable><optional>...</optional></optional></option></term>
 326         <listitem>
 327           <para>Round trackpoint element <replaceable>x</replaceable> to
 328           <replaceable>y</replaceable> decimals.</para>
 329           <para>Example:</para>
 330           <blockquote>
 331             <para><option>--round lat=4,lon=5,ele=1</option></para>
 332           </blockquote>
 333         </listitem>
 334       </varlistentry>
 335
 336       <varlistentry>
 337         <term><option>-s</option>, <option>--short-date</option></term>
 338         <listitem>
 339           <para>Use short date format.</para>
 340         </listitem>
 341       </varlistentry>
 342
 343       <varlistentry>
 344         <term><option>-S</option>, <option>--save-to-file
 345         <replaceable>x</replaceable></option></term>
 346
 347         <listitem>
 348           <para>Save the unconverted data to a file with a filename
 349           starting with the timestamp of the first trackpoint.
 350           The parameter string <replaceable>x</replaceable> is added at
 351           the end of the filename.
 352           For the time being this option will ignore all other
 353           options.</para>
 354           <note>
 355             <para>If several files are specified on the command line,
 356             all data will be saved into only one file.
 357             This behaviour may change in the future.</para>
 358           </note>
 359         </listitem>
 360       </varlistentry>
 361
 362       <varlistentry>
 363         <term><option>-t</option>,
 364         <option>--create-breaks</option></term>
 365         <listitem>
 366           <para>Create breaks in track between points with a difference
 367           more than the number of seconds specified by the
 368           <varname>$PAUSE_LIMIT</varname> variable.</para>
 369         </listitem>
 370       </varlistentry>
 371
 372       <varlistentry>
 373         <term><option>-u</option>,
 374         <option>--comment-out-dups</option></term>
 375         <listitem>
 376           <para>Comment out following data with identical position
 377           values, only print first entry.</para>
 378         </listitem>
 379       </varlistentry>
 380
 381       <varlistentry>
 382         <term><option>-v</option>, <option>--verbose</option></term>
 383         <listitem>
 384           <para>Verbose output, can be repeated.</para>
 385         </listitem>
 386       </varlistentry>
 387
 388       <varlistentry>
 389         <term><option>-w</option>,
 390         <option>--strip-whitespace</option></term>
 391         <listitem>
 392           <para>Strip all unnecessary whitespace.</para>
 393         </listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><option>-x</option>,
 398         <option>--xml</option></term>
 399         <listitem>
 400           <para>Create XML output.</para>
 401           <para></para>
 402         </listitem>
 403       </varlistentry>
 404
 405       <varlistentry>
 406         <term><option>-y</option>,
 407         <option>--double-y-scale</option></term>
 408         <listitem>
 409           <para>Double Y scale (latitude) to get it right in
 410           gnuplot.</para>
 411         </listitem>
 412       </varlistentry>
 413
 414       <varlistentry>
 415         <term><option>--version</option></term>
 416         <listitem>
 417           <para>Print version information.</para>
 418         </listitem>
 419       </varlistentry>
 420
 421       <varlistentry>
 422         <term><option>--debug</option></term>
 423         <listitem>
 424           <para>Print debugging messages.</para>
 425         </listitem>
 426       </varlistentry>
 427
 428     </variablelist>
 429
 430   </refsect1>
 431   <refsect1 id="gpst.bugs">
 432     <title>Bugs</title>
 433
 434     <para>Pretty incomplete in some areas.
 435     Some of the source formats are undocumented and thus incomplete.
 436     Some functionality is not working properly, for example the
 437     Postscript output.</para>
 438
 439   </refsect1>
 440   <refsect1 id="gpst.author">
 441     <title>Author</title>
 442
 443     <para>Made by <personname><firstname>Øyvind</firstname>
 444     <othername>A.</othername> <surname>Holm</surname></personname>
 445     <email>sunny@sunbase.org</email>.</para>
 446
 447   </refsect1>
 448   <refsect1 id="gpst.copyright">
 449     <title>Copyright</title>
 450
 451     <para>Copyleft © <personname><firstname>Øyvind</firstname>
 452     <othername>A.</othername> <surname>Holm</surname></personname>
 453     <email>sunny@sunbase.org</email>.
 454     This is free software; see the file <filename>COPYING</filename> for
 455     legalese stuff.</para>
 456
 457   </refsect1>
 458   <refsect1 id="gpst.license">
 459     <title>License</title>
 460
 461     <para>This program is free software; you can redistribute it and/or
 462     modify it under the terms of the <citetitle>GNU General Public
 463     License</citetitle> as published by the <orgname
 464     class="nonprofit">Free Software Foundation</orgname>; either version
 465     2 of the License, or (at your option) any later version.</para>
 466
 467     <para>This program is distributed in the hope that it will be
 468     useful, but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even
 469     the implied warranty of <emphasis>MERCHANTABILITY</emphasis> or
 470     <emphasis>FITNESS FOR A PARTICULAR PURPOSE</emphasis>.
 471     See the GNU General Public License for more details.</para>
 472
 473     <para>You should have received a copy of the GNU General Public
 474     License along with this program; if not, write to
 475 <address>The Free Software Foundation, Inc.
 476 <street>59 Temple Place</street>, <otheraddr>Suite 330</otheraddr>
 477 <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
 478 <country>USA</country></address></para>
 479
 480   </refsect1>
 481   <refsect1 id="gpst.seealso">
 482     <title>See also</title>
 483
 484     <para><citerefentry>
 485       <refentrytitle>gpsbabel</refentrytitle>
 486       <manvolnum>1</manvolnum>
 487     </citerefentry></para>
 488
 489   </refsect1>
 490   <!-- vim: set tw=72 ts=2 sts=2 sw=2 et fo=tcqw fenc=UTF-8 : -->
 491 </refentry>