Ugh. Manual pages have to be in the repo in order for xmlto not to be required.

1 files changed, 124 insertions, 0 deletions

diff --git a/gpsprof.1 b/gpsprof.1
new file mode 100644
index 00000000..8f22a895
--- /dev/null
+++ b/gpsprof.1
@@ -0,0 +1,124 @@
+.\"Generated by db2man.xsl. Don't modify this, modify the source.
+.de Sh \" Subsection
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.TH "GPSPROF" 1 "" "" ""
+.SH NAME
+gpsprof \- profile a GPS and gpsd, plotting latency information
+.SH "SYNOPSIS"
+.ad l
+.hy 0
+.HP 8
+\fBgpsprof\fR [\-f\ \fIplot_type\fR] [\-m\ \fIthreshold\fR] [\-n\ \fIpacketcount\fR] [\-s\ \fIspeed\fR] [\-t\ \fItitle\fR] [\-h]
+.ad
+.hy
+
+.SH "DESCRIPTION"
+
+.PP
+gpsprof measures the various latencies between a GPS and its client\&. It emits to standard output a GNUPLOT program that draws an illustrative graph\&. It can also be told to emit the raw profile data\&. The information it provides can be useful for establishing an upper bound on latency, and thus on position accuracy of a GPS in motion\&.
+
+.PP
+gpsprof uses instrumentation built into gpsd\&.
+
+.PP
+To display the graph, use \fBgnuplot\fR(1)\&. Thus, for example, to display the default spatial scatter plot, do this: 
+
+.nf
+
+gpsprof | gnuplot \-persist
+
+.fi
+ 
+
+.SH "OPTIONS"
+
+.PP
+The \-f option sets the plot type\&. The X axis is samples (sentences with timestamps)\&. The Y axis is normally latency in seconds\&. Currently the following plot types are defined:
+
+.TP
+space
+Generate a scattergram of fixes and plot a probable\-error circle\&. This data is only meaningful if the GPS is held stationary while gpsprof is running\&. This is the default\&.
+
+
+
+.TP
+uninstrumented
+Plot total latency without instrumentation\&. Useful mainly as a check that the instrumentation is not producing significant distortion\&. It only plots times for sentences that contain fixes; staircase\-like artifacts in the plot are created when elapsed time from sentences without fixes is lumped in\&.
+
+.TP
+raw
+Plot raw data\&.
+
+.TP
+split
+Each sentence has its RS232 latency time colored differently\&.
+
+.TP
+cycle
+Report on the set of sentences or packets emitted by the GPS, their send intervals, and the basic cycle time\&. (This report is plain text rather than a gnuplot script\&.)
+
+.PP
+The instrumented time plots conveys the following information:
+
+.TP
+RS232 time
+Minimum time required to send the sentence from the GPS to gpsd\&. This is computed, not measured, and may be an underestimate\&.
+
+.TP
+Other line latency
+The transmission latency between the GPS and gpsd 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 gpsd generates at sentence\-reading time, before it is decoded\&.
+
+.TP
+Decode time
+Elapsed time between sentence reception and the moment that gpsd ships the resulting update to the profiling client\&.
+
+.TP
+TCP/IP latency
+Elapsed time between the moment that gpsd ships the update to the profiling client and the moment it is decoded and timestamped\&.
+
+.PP
+Because of RS232 buffering effects, the profiler sometimes generates reports of ridiculously high latencies right at the beginning of a session\&. The \-m option lets you set a latency threshold, in multiples of the cycle time, above which reports are discarded\&.
+
+.PP
+The \-n option sets the number of packets to sample\&. The default is 100\&.
+
+.PP
+The \-s option sets the baud rate\&. Note, this will only work if the chipset accepts a speed\-change command (SiRF\-II supports this feature)\&.
+
+.PP
+The \-t option sets a text string to be included in the plot title\&.
+
+.PP
+The \-h option makes gpsprof print a usage message and exit\&.
+
+.SH "BUGS AND LIMITAIONS"
+
+.PP
+Probably overestimates TCP/IP latency somewhat, as that includes the Python interpreter's decode time\&. A C client would be faster\&.
+
+.SH "SEE ALSO"
+
+.PP
+ \fBgpsd\fR(8), \fBxgps\fR(1), \fBlibgps\fR(3), \fBlibgpsd\fR(3), \fBgnuplot\fR(1)\&.
+
+.SH "AUTHOR"
+
+.PP
+Eric S\&. Raymond <esr@thyrsus\&.com>\&. There is a project page for gpsd  here: \fIhttp://gpsd.berlios.de/\fR\&.
+