Fix misleading PPS JSON documentation. Still needs work.

1 files changed, 15 insertions, 14 deletions

diff --git a/gpsd_json.xml b/gpsd_json.xml
index b72b9a54..a1a7bb39 100644
--- a/gpsd_json.xml
+++ b/gpsd_json.xml
@@ -1255,13 +1255,13 @@ Per Second) strobe from a device.</para>
 	<entry>real_sec</entry>
 	<entry>Yes</entry>
 	<entry>numeric</entry>
-        <entry>seconds from the realtime clock</entry>
+        <entry>seconds from the PPS source</entry>
 </row>
 <row>
 	<entry>real_nsec</entry>
 	<entry>Yes</entry>
 	<entry>numeric</entry>
-        <entry>nanoseconds from the realtime clock</entry>
+        <entry>nanoseconds from the PPS source</entry>
 </row>
 <row>
 	<entry>clock_sec</entry>
@@ -1286,29 +1286,30 @@ Per Second) strobe from a device.</para>
 </table>
 
 <para>This message is emitted once per second to watchers of a device
-emitting PPS, and is intended to report the offset between the start
-of the GPS second (when the 1PPS arrives) and seconds as reported by
-the system clock (which may be NTP-corrected).</para>
+emitting PPS, and reports the time of the start of the GPS second (when 
+the 1PPS arrives) and seconds as reported by the system clock (which 
+may be NTP-corrected) at that moment.</para>
 
-<para>The message contains second/microsecond pairs for two clocks;
-the realtime clock without NTP correction (the result of 
-clock_gettime(CLOCK_REALTIME), but only to microsecond precision) 
-and the ordinary system clock (which may be NTP corrected).</para>
+<para>The message contains two second/nanosecond pairs:
+real_sec and real_nsec contain the time the GPS thinks it was at the PPS edge;
+clock_sec and clock_nsec contain the time the system clock thinks it was at
+the PPS edge.   real_nsec is always to nanosecond precision.  clock_nsec
+is nanosecond precision on most systems.</para>
 
 <para>There are various sources of error in the reported clock times.
 For PPS delivered via a real serial-line strobe, serial-interrupt
 latency plus processing time to the timer call should be bounded above
-by about 10 microseconds; USB-to-serial control-line emulation is
-known to add jitter of about 50 microseconds.  (Both figures are for
-GPSD running in non-realtime mode on an x86 with a gigahertz clock and
-are estimates based on measured latency in other applications.)</para>
+by about 10 microseconds; that can be reduced to less than 1 microsecond if 
+your kernel supports RFC 2783.   USB1.1-to-serial control-line emulation is
+limited to about 1 millisecond. seconds.</para>
 
 <para>Here's an example:</para>
 
 <programlisting>
 {"class":"PPS","device":"/dev/ttyUSB0",
      "real_sec":1330212592, "real_nsec":343182,
-     "clock_sec":1330212592,"clock_nsec":343184}
+     "clock_sec":1330212592,"clock_nsec":343184,
+     "precision":-3}
 </programlisting>
 
 </listitem>