We have a new man page.

1 files changed, 154 insertions, 0 deletions

diff --git a/gpsprof.xml b/gpsprof.xml
new file mode 100644
index 00000000..db229cd6
--- /dev/null
+++ b/gpsprof.xml
@@ -0,0 +1,154 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC 
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "docbook/docbookx.dtd">
+<refentry id='gpsprof.1'>
+<refmeta>
+<refentrytitle>gpsprof</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='date'>10 Feb 2005</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>gpsprof</refname>
+<refpurpose>profile a GPS and gpsd, plotting latency information</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+  <command>gpsprof</command>  
+      <arg choice='opt'>-f <replaceable>plot_type</replaceable></arg>
+      <arg choice='opt'>-n <replaceable>packetcount</replaceable></arg>
+      <arg choice='opt'>-o <replaceable>outfile</replaceable></arg>
+      <arg choice='opt'>-r </arg>
+      <arg choice='opt'>-t <replaceable>title</replaceable></arg>
+      <arg choice='opt'>-T <replaceable>terminal type</replaceable></arg>
+      <arg choice='opt'>-h</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+
+<para><application>gpsprof</application> measures the various
+latencies between a GPS and its client. It draws an illustrative
+graph. It can be told to save the raw profile data.</para>  
+
+<para><application>gpsprof</application> uses instrumentation built
+into <application>gpsd</application> that will only be present if
+it was configiured to support profiling.</para>
+
+<para>Graphs are generated using
+<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+
+</refsect1>
+<refsect1 id='options'><title>OPTIONS</title>
+
+<para>The -f option sets the plot type. The X axis is samples
+(sentences with timestamps).  The Y axis is latency in seconds.
+Currently the following plot types are defined:</para>
+
+<variablelist>
+<varlistentry>
+<term>raw</term>
+<listitem>
+<para>Plot raw data.  This is not likely to be very useful, as 
+buffering effects in the USB or RS232 layer tend to produce absurdly
+large latencies at the beginning of a session.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>strip</term>
+<listitem>
+<para>Plot filtered data.  Sentences with an apparent latency larger
+than 1 second are discarded.  This is the default.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>Each plot conveys the following information:</para>
+
+<variablelist>
+<varlistentry>
+<term>RS232 time</term>
+<listitem>
+<para>Minimum time required to send the sentence from the GPS to
+<application>gpsd</application>. This is computed, not measured, 
+and may be an underestimate.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Other line latency</term>
+<listitem>
+<para>The transmission latency between the GPS and 
+<application>gpsd</application> not accounted for by RS232 time.
+Total line latency (the sum of this bar and RS232 time)
+is measured; it begins with the GPS sentence's timestamp and ends with 
+a timestamp that <application>gpsd</application> generates at 
+sentence-reading time, before it is decoded.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Decode time</term>
+<listitem>
+<para>Elapsed time between sentence reception and the moment that
+<application>gpsd</application> ships the resulting update to
+the profiling client.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>TCP/IP latency</term>
+<listitem>
+<para>Elapsed time between the moment that
+<application>gpsd</application> ships the update to
+the profiling client and the moment it is decoded and timestamped.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>The -n option sets the number of packets to sample.  The default
+is 100.</para>
+
+<para>The -o option specifies the name of a file in which to dump the
+profiling data;
+<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+will read ot from there.  If this option is not specified, the data
+will be written to a tempfile and discarded after the plot id made</para>
+
+<para>The -t option sets a text string to be included in the plot
+title.  Specifying the GPS make and model is a good use for it.</para>
+
+<para>The -T option sets a terminal type for
+<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+.  It will normally default to "x11" at produce a display immediately,
+but (for example) specifying "-T png" will instead cause a PNG image
+of the graphic to be shipped to standard output.</para>
+
+<para>The -h option makes <application>gpsprof</application> print 
+a usage message and exit.</para>
+
+</refsect1>
+<refsect1 id='bugs'><title>BUGS AND LIMITAIONS</title>
+
+<para>Probably overestimates TCP/IP latency somewhat, as that includes the
+Python interpreter's decode time. A C client would be faster.</para>
+
+</refsect1>
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+<citerefentry><refentrytitle>libgps</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+<citerefentry><refentrytitle>libgpsd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+<citerefentry><refentrytitle>gpsprobe</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+<citerefentry><refentrytitle>gnuplot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+</para>
+</refsect1>
+
+<refsect1 id='maintainer'><title>AUTHOR</title> 
+
+<para>Eric S. Raymond <email>esr@thyrsus.com</email>.  There is a
+project page <ulink
+url="http://gpsd.berlios.de/">here</ulink>.</para>
+
+</refsect1>
+
+</refentry>
+