branches/gpst.xml-option/doc/gpst.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>gpst</title><meta name="generator" content="DocBook XSL Stylesheets V1.71.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="gpst"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>gpst — Converts between various GPS formats.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">gpst</code>  [
   4         <em class="replaceable"><code>options</code></em>
   5       ] [
   6         <em class="replaceable"><code>file</code></em>
   7       ...]</p></div><div class="cmdsynopsis"><p><code class="command">gpst</code>  {-S} [
   8         <em class="replaceable"><code>options</code></em>
   9       ] [
  10         <em class="replaceable"><code>file</code></em>
  11       ...]</p></div><div class="cmdsynopsis"><p><code class="command">gpst</code>  {-u} [
  12         <em class="replaceable"><code>options</code></em>
  13       ] [
  14         <em class="replaceable"><code>file</code></em>
  15       ...]</p></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="gpst.description"></a><h2>Description</h2><div class="variablelist"><dl><dt><span class="term"><code class="option">--chronology</code></span></dt><dd><p>Check for broken chronology, warn about entries with an
  16           old timestamp.
  17           If the <code class="option">--xml</code> option is specified, the result
  18           of the scan is written to stdout as usual, and all other
  19           output is suppressed.
  20           If the <code class="option">--xml</code> option is
  21           <span class="emphasis"><em>not</em></span> used, it is reported as warnings to
  22           stderr.</p></dd><dt><span class="term"><code class="option">-d</code>, <code class="option">--skip-dups</code></span></dt><dd><p>If succeeding identical coordinates are found, print
  23           only the first one and ignore the rest.</p></dd><dt><span class="term"><code class="option">-e</code>, <code class="option">--epoch</code></span></dt><dd><p>Use seconds since 1970-01-01 00:00:00 GMT as date
  24           format.</p></dd><dt><span class="term"><code class="option">--fix</code></span></dt><dd><p>Comment out entries which is obviously wrong.
  25           Use together with <code class="option">--chronology</code> to fix those
  26           kind of errors.
  27           Does not work with GPX output yet.</p></dd><dt><span class="term"><code class="option">-h</code>, <code class="option">--help</code></span></dt><dd><p>Send a brief help summary to stdout.</p></dd><dt><span class="term"><code class="option">--inside</code></span></dt><dd><p>Print only trackpoints inside a rectangle specified by
  28           <code class="option">--pos1</code> and <code class="option">--pos2</code>.</p></dd><dt><span class="term"><code class="option">--near</code></span></dt><dd><p>Add names of the three closest waypoints to the
  29           trackpoint.
  30           Unfinished and experimental, needs <span class="citerefentry"><span class="refentrytitle">gpsbabel</span>(1)</span>.</p></dd><dt><span class="term"><code class="option">-n</code>, <code class="option">--undefined
  31         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Use <em class="replaceable"><code>x</code></em> as undefined
  32           value.</p></dd><dt><span class="term"><code class="option">-o</code>, <code class="option">--output-format
  33         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Use output format <em class="replaceable"><code>x</code></em>:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">clean</code></span></dt><dd><p>TAB-separated format with longitude, latitude and
  34                 altitude.</p></dd><dt><span class="term"><code class="option">csv</code></span></dt><dd><p>TAB-separated format:
  35                 </p><div class="variablelist"><dl><dt><span class="term">date</span></dt><dd><p>Date of trackpoint.
  36                       Format:
  37                       <code class="literal"><em class="replaceable"><code>yyyy</code></em>-<em class="replaceable"><code>mm</code></em>-<em class="replaceable"><code>dd</code></em>T<em class="replaceable"><code>hh</code></em>:<em class="replaceable"><code>mm</code></em>:<em class="replaceable"><code>ss</code></em>Z</code>
  38                       unless the <code class="option">--epoch</code> option is
  39                       specified.
  40                       If so, it’s represented as number of seconds since
  41                       1970-01-01 00:00:00 UTC.</p></dd><dt><span class="term">longitude</span></dt><dd><p>Longitude, decimal degrees.</p></dd><dt><span class="term">latitude</span></dt><dd><p>Latitude, decimal degrees.</p></dd><dt><span class="term">altitude</span></dt><dd><p>Altitude in metres above sea level.
  42                       Optional.
  43                       If not present, the corresponding TAB is also
  44                       printed, to keep the number of columns
  45                       intact.</p></dd></dl></div></dd><dt><span class="term"><code class="option">gpsml</code> (Default)</span></dt><dd><p>Line-based XML which makes it easy to edit and
  46                 grep.
  47                 In the past, there was this big plan about making this
  48                 the default storage format, so it was declared as The
  49                 Honourable Default Output Format.
  50                 But using GPX is the way to go, so this will probably
  51                 change in the future.
  52                 It’s way too <span class="foreignphrase"><em class="foreignphrase">de facto</em></span> and
  53                 widely used, so storing GPS data in anything else is
  54                 sheer waste of work.
  55                 Probably not finished yet.</p></dd><dt><span class="term"><code class="option">gpstrans</code></span></dt><dd><p>The format generated by <span class="citerefentry"><span class="refentrytitle">gpstrans</span>(1)</span>.</p></dd><dt><span class="term"><code class="option">gpx</code></span></dt><dd><p>Not complete yet, but good enough in most
  56                 cases.</p></dd><dt><span class="term"><code class="option">poscount</code></span></dt><dd><p>Creates a 3D plot where areas with many
  57                 trackpoints are higher than areas with less track
  58                 points.</p></dd><dt><span class="term"><code class="option">ps</code></span></dt><dd><p>Postscript. Unfinished.</p></dd><dt><span class="term"><code class="option">svg</code></span></dt><dd><p>Unfinished.</p></dd><dt><span class="term"><code class="option">xgraph</code></span></dt><dd><p>Input format for <span class="citerefentry"><span class="refentrytitle">xgraph</span>(1)</span>.</p></dd><dt><span class="term"><code class="option">ygraph</code></span></dt><dd><p>Input format for <span class="citerefentry"><span class="refentrytitle">ygraph</span>(1)</span>.</p></dd></dl></div></dd><dt><span class="term"><code class="option">--outside</code></span></dt><dd><p>Print only trackpoints outside a rectangle specified by
  59           <code class="option">--pos1</code> and <code class="option">--pos2</code>.</p></dd><dt><span class="term"><code class="option">--pos1
  60         <em class="replaceable"><code>x</code></em></code>, </span><span class="term"><code class="option">--pos2
  61         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Specifies corners of an area rectangle used by the
  62           <code class="option">--inside</code> and <code class="option">--outside</code>
  63           options.
  64           The <em class="replaceable"><code>x</code></em> value is in
  65           <code class="literal"><em class="replaceable"><code>lat</code></em>,<em class="replaceable"><code>lon</code></em></code>
  66           format (decimal degrees, negative for west or south).</p></dd><dt><span class="term"><code class="option">-r</code>, <code class="option">--require
  67         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Specify requirements for trackpoints to be written.
  68           <em class="replaceable"><code>x</code></em> is a string with the following
  69           flags:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">e</code></span></dt><dd><p>Print only waypoints which have an
  70                 elevation.</p></dd><dt><span class="term"><code class="option">p</code></span></dt><dd><p>Print only waypoints which have a position.</p></dd><dt><span class="term"><code class="option">t</code></span></dt><dd><p>Print only waypoints which have a
  71                 timestamp.</p></dd></dl></div></dd><dt><span class="term"><code class="option">-R</code>, <code class="option">--round
  72         <em class="replaceable"><code>x</code></em>=<em class="replaceable"><code>y</code></em>[<span class="optional">,<em class="replaceable"><code>x2</code></em>=<em class="replaceable"><code>y2</code></em>[<span class="optional">...</span>]</span>]</code></span></dt><dd><p>Round trackpoint element <em class="replaceable"><code>x</code></em> to
  73           <em class="replaceable"><code>y</code></em> decimals.</p><p>Example:</p><div class="blockquote"><blockquote class="blockquote"><p><code class="option">--round lat=4,lon=5,ele=1</code></p></blockquote></div></dd><dt><span class="term"><code class="option">-s</code>, <code class="option">--short-date</code></span></dt><dd><p>Use short date format.</p></dd><dt><span class="term"><code class="option">-S</code>, <code class="option">--save-to-file
  74         <em class="replaceable"><code>x</code></em></code></span></dt><dd><p>Save the unconverted data to a file with a filename
  75           starting with the timestamp of the first trackpoint.
  76           The parameter string <em class="replaceable"><code>x</code></em> is added at
  77           the end of the filename.
  78           For the time being this option will ignore all other
  79           options.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If several files are specified on the command line,
  80             all data will be saved into only one file.
  81             This behaviour may change in the future.</p></div></dd><dt><span class="term"><code class="option">-t</code>,
  82         <code class="option">--create-breaks</code></span></dt><dd><p>Create breaks in track between points with a difference
  83           more than the number of seconds specified by the
  84           <code class="varname">$PAUSE_LIMIT</code> variable.</p></dd><dt><span class="term"><code class="option">-u</code>,
  85         <code class="option">--comment-out-dups</code></span></dt><dd><p>Comment out following data with identical position
  86           values, only print first entry.</p></dd><dt><span class="term"><code class="option">-v</code>, <code class="option">--verbose</code></span></dt><dd><p>Verbose output, can be repeated.</p></dd><dt><span class="term"><code class="option">-w</code>,
  87         <code class="option">--strip-whitespace</code></span></dt><dd><p>Strip all unnecessary whitespace.</p></dd><dt><span class="term"><code class="option">-x</code>,
  88         <code class="option">--xml</code></span></dt><dd><p>Create XML output.</p><p></p></dd><dt><span class="term"><code class="option">-y</code>,
  89         <code class="option">--double-y-scale</code></span></dt><dd><p>Double Y scale (latitude) to get it right in
  90           gnuplot.</p></dd><dt><span class="term"><code class="option">--version</code></span></dt><dd><p>Print version information.</p></dd><dt><span class="term"><code class="option">--debug</code></span></dt><dd><p>Print debugging messages.</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="gpst.bugs"></a><h2>Bugs</h2><p>Pretty incomplete in some areas.
  91     Some of the source formats are undocumented and thus incomplete.
  92     Some functionality is not working properly, for example the
  93     Postscript output.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="gpst.author"></a><h2>Author</h2><p>Made by <span class="personname"><span class="firstname">Øyvind</span> <span class="othername">A.</span> <span class="surname">Holm</span></span>
  94     <code class="email">&lt;<a href="mailto:sunny@sunbase.org">sunny@sunbase.org</a>&gt;</code>.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="gpst.copyright"></a><h2>Copyright</h2><p>Copyleft © <span class="personname"><span class="firstname">Øyvind</span> <span class="othername">A.</span> <span class="surname">Holm</span></span>
  95     <code class="email">&lt;<a href="mailto:sunny@sunbase.org">sunny@sunbase.org</a>&gt;</code>.
  96     This is free software; see the file <code class="filename">COPYING</code> for
  97     legalese stuff.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="gpst.license"></a><h2>License</h2><p>This program is free software; you can redistribute it and/or
  98     modify it under the terms of the <em class="citetitle">GNU General Public
  99     License</em> as published by the <span class="orgname">Free Software Foundation</span>; either version
 100     2 of the License, or (at your option) any later version.</p><p>This program is distributed in the hope that it will be
 101     useful, but <span class="emphasis"><em>WITHOUT ANY WARRANTY</em></span>; without even
 102     the implied warranty of <span class="emphasis"><em>MERCHANTABILITY</em></span> or
 103     <span class="emphasis"><em>FITNESS FOR A PARTICULAR PURPOSE</em></span>.
 104     See the GNU General Public License for more details.</p><p>You should have received a copy of the GNU General Public
 105     License along with this program; if not, write to
 106 </p><div class="address"><p>The Free Software Foundation, Inc.<br />
 107 <span class="street">59 Temple Place</span>, <span class="otheraddr">Suite 330</span><br />
 108 <span class="city">Boston</span>, <span class="state">MA</span> <span class="postcode">02111-1307</span><br />
 109 <span class="country">USA</span></p></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="gpst.seealso"></a><h2>See also</h2><p><span class="citerefentry"><span class="refentrytitle">gpsbabel</span>(1)</span></p></div></div></body></html>