Documentation update.

1 files changed, 31 insertions, 111 deletions

diff --git a/gpsdecode.xml b/gpsdecode.xml
index c3cbfde9..2d46989f 100644
--- a/gpsdecode.xml
+++ b/gpsdecode.xml
@@ -34,58 +34,51 @@ BSD terms apply: see the file COPYING in the distribution root for details.
 
 <refsect1 id='description'><title>DESCRIPTION</title>
 
-<para>This tool is a decoder/encoder for NMEA and various binary packet formats
-associated with GPS and differential-correction services.  It produces
-a text dump on standard output from binary on standard input, or
-binary packets on standard output from text on standard input, and
-aims to be 100% information-preserving in both directions.  As well as
-data, the decoder also prints decoder status messages to standard
-error as necessary.</para>
-
-<para>NMEA and GPS binary formats can be decoded to JSON (the same
-format used by
-<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
-but not encoded.</para>
-
-<para>Two of the supported formats are RTCM 2 and 3, a pair of obscure
+<para>This tool is a batch-mode decoder for NMEA and various binary
+packet formats associated with GPS, AIS, and differential-correction
+services.  It produces a JSON dump on standard output from binary on
+standard input. The JSON is the same format documented in
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>; 
+this tool uses the same decoding logic as gpsd, but with a simpler interface
+for batch processing of data files.
+</para>
+
+<para>NMEA, AIVDM (the NMEA-derived sentence format
+used by AIS, the marine Automatic Identification System), and all 
+GPS binary formats known to
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+can be decoded.</para>
+
+<para>Two more supported formats are RTCM 2 and 3, a pair of obscure
 and complicated serial protocol used for broadcasting pseudorange
 corrections from differential-GPS reference stations. You can use this
 mode of the tool with
 <citerefentry><refentrytitle>nc</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-to examine RTCM feeds from DGPSIP servers or Ntrip broadcasters. The
-decoder dump formats for RTCM2 are described in
-<citerefentry><refentrytitle>rtcm</refentrytitle><manvolnum>5</manvolnum></citerefentry>;
-these lines go to standard output. RTCM2 can be decoded and encoded; RTCM3 
-can only be decoded, and support is presently incomplete.</para>
-
-<para>Another supported format is AIVDM.  This is the sentence format
-used by the marine Automatic Identification System.  This can be
-decoded, but not yet encoded.</para>
+to examine RTCM feeds from DGPSIP servers or NTRIP broadcasters.</para>
 
 </refsect1>
 <refsect1 id='options'><title>OPTIONS</title>
 
 <para>The <option>-d</option> option tells the program to decode
-packets presented on standard input to a JSON dump on standard
-output. This is the default behavior.</para>
+packets presented on standard input to standard output. This is the
+default behavior.</para>
 
 <para>The <option>-e</option> option option tells the program to
-encode a text dump to binary on standard output. This option is a
-placeholder: support for RTCM2 encoding from the Sager format has been
-removed</para>
+encode JSON on standard input to JSON on standard output. This option
+is only useful for regression-testing of the JSON dumping and parsing
+code.</para>
 
-<para>The <option>-u</option> suppresses scaling of AIS data to float quantities
-and text expansion of numeric codes.  A dump with this option is
-lossless.</para>
+<para>The <option>-u</option> suppresses scaling of AIS data to float
+quantities and text expansion of numeric codes.  A dump with this
+option is lossless.</para>
 
-<para>The <option>-j</option> sets the dump format to JSON, with
-each each field preceded by a quoted label and colon and the
-entire dump line wrapped in curly braces.</para>
+<para>The <option>-j</option> explicitly sets the output dump format
+to JSON (the default behavior).</para>
 
 <para>The <option>-c</option> sets the AIS dump format to separate
 fields with an ASCII pipe symbol.  Fields are dumped in the order they
-occur in the AIS packet. Numerics are not scaled. Strings are unpacked
-from six-bit to full ASCII</para>
+occur in the AIS packet. Numerics are not scaled (-u is
+forced). Strings are unpacked from six-bit to full ASCII</para>
 
 <para>The <option>-V</option> option directs the program to emit its
 version number, then exit.</para>
@@ -94,9 +87,9 @@ version number, then exit.</para>
 mainly of interest to developers.</para>
 
 </refsect1>
-<refsect1 id='json_ais'><title>AIS DUMP FORMATS</title> 
+<refsect1 id='json_ais'><title>AIS DSV FORMAT</title> 
 
-<para>Without the <option>-j</option> option, dump lines are values of AIS
+<para>With the <option>-c</option> option, dump lines are values of AIS
 payload fields, pipe-separated, in the order that they occur in the
 payload. Spans of fields expressing a date are emitted as an ISO8601
 timestamp (look for colons and the trailing Z indicating Zulu/UTC
@@ -107,79 +100,6 @@ preceded by "0x"). Unused regional-authority fields are also dumped
 an integer bit length, followed by a colon, followed by a hex
 dump.</para>
 
-<para>By default, certain scaling and conversion operations are
-performed for the output.  Latitudes and longitudes are scaled to
-decimal degrees rather than the native AIS unit of 1/10000th of a
-minute of arc.  Ship (but not air) speeds are scaled to knots rather
-than tenth-of-knot units.  Navigation status and positioning-system
-type are dumped as text strings rather than IAS numeric codes. Rate of
-turn may appear as "nan" if is unavailable, or as one of the strings
-"fastright" or "fastleft" if it is out of the IAS encoding range;
-otherwise it is quadratically mapped back to the turn sensor number in
-degrees per minute. Vessel draughts are converted to decimal meters
-rather than native AIS decimeters.</para>
-
-<para>With the <option>-j</option> option, the AIS dump format changes
-to JSON.  Data fields are handled as described above in scaled and
-unscaled modes, but are values attached to JSON attributes as
-described in <citetitle><ulink
-url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO protocol
-decoding</ulink></citetitle>.</para>
-
-</refsect1>
-<refsect1 id='standard'><title>APPLICABLE STANDARDS</title>
-
-<para>The applicable standard for V2 is <citetitle>RTCM Recommended
-Standards for Differential NAVSTAR GPS Service</citetitle> RTCM Paper
-194-93/SC 104-STD.</para>
-
-<para>Note that <application>gpsdecode</application> presently
-recognizes only the 2.1 level of RTCM; the protocol was revised up to
-a version 2.3 including additional messages relating to GLONASS and
-real-time kinematics before being deprecated in favor of V3. It is
-now semi-obsolete.</para>
-
-<para>The applicable standard for V3 is <citetitle>RTCM Standard
-10403.1 for Differential GNSS Services - Version 3</citetitle> RTCM
-Paper 177-2006-SC104-STD.</para>
-
-<para>Ordering instructions for the RTCM standards are accessible from
-the website of the <ulink url='http://www.rtcm.org/'>Radio Technical
-Commission for Maritime Services</ulink> under "Publications".</para>
-
-<para>The applicable standard for AIVDM is <citetitle>ITU-R M.1371:
-ITU Recommendation on the Technical Characteristics for a Universal
-Shipborne Automatic Identification System (AIS) using Time Division
-Multiple Access in the Maritime Mobile Band</citetitle>, A more
-accessible description can be found at <citetitle><ulink
-url="http://gpsd.berlios.de/AIVDM.html">AIVDM/AIVDO protocol
-decoding</ulink></citetitle> on the references page of the
-GPSD project website.</para>
-
-</refsect1>
-<refsect1 id='bugs'><title>BUGS AND LIMITATIONS</title> 
-
-<para>AIDVM decoding of types 16-17, 22-23, and 25-26 is unverified.</para>
-
-<para>RTCM3 decoding is buggy and incomplete.</para>
-
-<para>RTCM2 represents floating-point quantities as an integer
-multiple of a fixed scale factor.  Editing an RTCM2 dump can produce
-numbers that are not an integer multiple of the scale factor for their
-field.  If you do this, the value actually packed into binary RTCM2
-will be rounded down to the nearest scale unit, and dumping will show
-slightly different numbers than those you entered.  This bug could be
-fixed by supporting the <option>-u</option> option to suppress
-scaling.</para>
-
-<para>The RTCM2 decoder logic is sufficiently convoluted to confuse some
-compiler optimizers, notably in GCC 3.x at -O2, into generating bad
-code.</para>
-
-<para>Older version of this utility used comma as a field separator with
-the <option>-c</option> option.  This was a mistake, as ship name and
-other string fields can contain commas.</para>
-
 </refsect1>
 <refsect1 id='see_also'><title>SEE ALSO</title>
 <para>