gpsd-dev
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[gpsd-dev] [PATCH 1/5] Separate gpxlogger man page


From: Robert Norris
Subject: [gpsd-dev] [PATCH 1/5] Separate gpxlogger man page
Date: Wed, 8 Mar 2017 00:24:14 +0000

As a more stand-alone application, shift gpxlogger help into it's own
dedicated man page.

This also aids the separate distribution of a Windows version of gpxlogger,
where the .html version of help can be supplied.

TESTED:
'scons build-all www' generates current man pages and the new versions of
gpxlogger.1 and gpxlogger.html
---
 .gitignore    |   2 +
 SConstruct    |   3 +-
 gps.xml       |  74 +++--------------------------
 gpxlogger.xml | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 160 insertions(+), 68 deletions(-)
 create mode 100644 gpxlogger.xml

diff --git a/.gitignore b/.gitignore
index 4fa6cda8..e52adad5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,6 +48,7 @@ gpsmon.html
 gpspipe.html
 gpsprof.html
 gps2udp.html
+gpxlogger.html
 ntpmon.html
 libgps.html
 libgpsd.html
@@ -123,6 +124,7 @@ www/gpsmon.html
 www/gpspipe.html
 www/gpsprof.html
 www/gps_report.cgi
+www/gpxlogger.html
 www/hacking.html
 www/hardware-head.html
 www/hardware.html
diff --git a/SConstruct b/SConstruct
index 7c417c86..0d3ff63c 100644
--- a/SConstruct
+++ b/SConstruct
@@ -1526,7 +1526,7 @@ base_manpages = {
     "cgps.1": "gps.xml",
     "gpsinit.8": "gpsinit.xml",
     "lcdgps.1": "gps.xml",
-    "gpxlogger.1": "gps.xml",
+    "gpxlogger.1": "gpxlogger.xml",
     "libgps.3": "libgps.xml",
     "libgpsmm.3": "libgpsmm.xml",
     "libQgpsmm.3": "libgpsmm.xml",
@@ -2069,6 +2069,7 @@ htmlpages = Split('''
     www/gpsmon.html
     www/gpspipe.html
     www/gpsprof.html
+    www/gpxlogger.html
     www/hardware.html
     www/internals.html
     www/libgps.html
diff --git a/gps.xml b/gps.xml
index f7747a02..e9cd9fd1 100644
--- a/gps.xml
+++ b/gps.xml
@@ -20,7 +20,6 @@ BSD terms apply: see the file COPYING in the distribution 
root for details.
 <refname>xgpsspeed</refname>
 <refname>cgps</refname>
 <refname>lcdgps</refname>
-<refname>gpxlogger</refname>
 <refname>gegps</refname>
 <refpurpose>test clients for gpsd</refpurpose>
 </refnamediv>
@@ -93,25 +92,6 @@ BSD terms apply: see the file COPYING in the distribution 
root for details.
       </group>
 </cmdsynopsis>
 <cmdsynopsis>
-  <command>gpxlogger</command>
-      <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
-      <arg choice='opt'>-d </arg>
-      <arg choice='opt'>-e <replaceable>export-method</replaceable></arg>
-      <arg choice='opt'>-f <replaceable>filename</replaceable></arg>
-      <arg choice='opt'>-l </arg>
-      <arg choice='opt'>-m <replaceable>minmove</replaceable></arg>
-      <arg choice='opt'>-h </arg>
-      <arg choice='opt'>-V </arg>
-      <arg choice='opt'>-i <replaceable>track timeout</replaceable></arg>
-      <group>
-       <replaceable>server</replaceable>
-         <group>
-           <replaceable>:port</replaceable>
-             <group><replaceable>:device</replaceable></group>
-         </group>
-      </group>
-</cmdsynopsis>
-<cmdsynopsis>
   <command>gegps</command>
       <arg choice='opt'>-d <replaceable>directory</replaceable></arg>
       <arg choice='opt'>-i </arg>
@@ -208,7 +188,10 @@ address, collecting data from attached serial device 
5.</para></listitem>
 the separate manual pages for
 
<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 and
-<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+and
+<citerefentry><refentrytitle>gpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+.</para>
 
 <refsect2><title>xgps</title>
 
@@ -278,48 +261,7 @@ assumes a 4x40 LCD and writes data formatted to fit that 
size screen.
 Also displays 4- or 6-character Maidenhead grid square output.</para>
 
 </refsect2>
-<refsect2><title>gpxlogger</title>
-
-<para>This program collects fixes from <application>gpsd</application>
-and logs them to standard output in GPX, an XML profile for track
-logging.</para>
-
-<para>The output may be composed of multiple tracks. A new track is
-created if there's no fix written for an interval specified by the
-<option>-i</option> and defaulting to 5 seconds.</para>
-
-<para>The <option>-d</option> option tells
-<application>gpxlogger</application> to run as a daemon in background.
-It requires the <option>-f</option> option, which directs output to a
-specified logfile.</para>
-
-<para>The <option>-m</option> option sets a minimum move distance in
-meters (it may include a fractional decimal part).  Motions shorter
-than this will not be logged.</para>
-
-<para>The <option>-r</option> option tells
-<application>gpxlogger</application> to retry when GPSd loses the fix.
-Without <option>-r</option>, <application>gpxlogger</application>
-would quit in this case.</para>
-
-<para><application>gpxlogger</application> can use any of the
-export methods that <application>gpsd</application> supports.
-For a list of these methods, use the <option>-l</option>.
-To force the method, give the <option>-e</option> one of
-the colon-terminated method names from the <option>-l</option>
-table.</para>
-<!-- ipcrm -M 0x47505344 will remove a stuck segment -->
-
-<para>If D-Bus support is available on the host, GPSD is configured to
-use it, and <command>-e dbus</command> is specified, this program
-listens to DBUS broadcasts from
-<application>gpsd</application> via org.gpsd.fix.</para>
-
-<para>With <command>-e sockets</command>, or if sockets is the method
-defaulted to, you may give a server-port-device specification as
-arguments.</para>
 
-</refsect2>
 <refsect2><title>gegps</title>
 
 <para>This program collects fixes from <application>gpsd</application>
@@ -350,6 +292,7 @@ after that.</para>
 
<citerefentry><refentrytitle>gpsprof</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 
<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 
<citerefentry><refentrytitle>gpsmon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+<citerefentry><refentrytitle>gpxlogger</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 </para>
 </refsect1>
 
@@ -357,11 +300,8 @@ after that.</para>
 
 <para>
 Remco Treffcorn, Derrick Brashear, Russ Nelson &amp; Eric S. Raymond,
-Jeff Francis (cgps). Amaury Jacquot <email>address@hidden</email>
-&amp; Petter Reinholdtsen <email>address@hidden</email> (gpxlogger).
-Chris Kuethe <email>address@hidden</email> (gpxlogger), Chen
-Wei <email>address@hidden</email> (gegps &amp; xgpsspeed), Robin Wittler
-<email>address@hidden</email> (xgpsspeed).
+Jeff Francis (cgps), Chen Wei <email>address@hidden</email> (gegps &amp; 
xgpsspeed),
+Robin Wittler <email>address@hidden</email> (xgpsspeed).
 </para>
 
 <para>This manual page by Eric S. Raymond <email>address@hidden</email></para>
diff --git a/gpxlogger.xml b/gpxlogger.xml
new file mode 100644
index 00000000..41c20c24
--- /dev/null
+++ b/gpxlogger.xml
@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+This file is Copyright (c) 2017 by the GPSD project
+BSD terms apply: see the file COPYING in the distribution root for details.
+-->
+<!DOCTYPE refentry PUBLIC
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";>
+<refentry id='gpxlogger.1'>
+<refentryinfo><date>05 Mar 2017</date></refentryinfo>
+<refmeta>
+<refentrytitle>gpxlogger</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="source">The GPSD Project</refmiscinfo>
+<refmiscinfo class="manual">GPSD Documentation</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>gpxlogger</refname>
+<refpurpose>Tool to connect to gpsd and generate a GPX file</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+  <command>gpxlogger</command>
+      <arg choice='opt'>-D <replaceable>debug-level</replaceable></arg>
+      <arg choice='opt'>-d </arg>
+      <arg choice='opt'>-e <replaceable>export-method</replaceable></arg>
+      <arg choice='opt'>-f <replaceable>filename</replaceable></arg>
+      <arg choice='opt'>-l </arg>
+      <arg choice='opt'>-m <replaceable>minmove</replaceable></arg>
+      <arg choice='opt'>-h </arg>
+      <arg choice='opt'>-V </arg>
+      <arg choice='opt'>-i <replaceable>track timeout</replaceable></arg>
+      <group>
+       <replaceable>server</replaceable>
+         <group>
+           <replaceable>:port</replaceable>
+             <group><replaceable>:device</replaceable></group>
+         </group>
+      </group>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>This program collects fixes from <application>gpsd</application>
+and logs them to standard output in GPX, an XML profile for track
+logging.</para>
+
+<para>The output may be composed of multiple tracks. A new track is
+created if there's no fix written for an interval specified by the
+<option>-i</option> and defaulting to 5 seconds.</para>
+
+<para><application>gpxlogger</application> can use any of the
+export methods that <application>gpsd</application> supports.
+For a list of these methods, use the <option>-l</option>.
+To force the method, give the <option>-e</option> one of
+the colon-terminated method names from the <option>-l</option>
+table.</para>
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+
+<para>The <option>-h</option> option causes 
<application>gpxlogger</application>
+to emit a summary of its options and then exit.</para>
+
+<para>The <option>-V</option> option causes 
<application>gpxlogger</application>
+to dump the package version and exit.</para>
+
+<para> The <option>-D</option> option sets a debug level;
+it is primarily for use by GPSD developers.
+It enables various progress messages to standard error.</para>
+
+<para>The <option>-d</option> option tells
+<application>gpxlogger</application> to run as a daemon in background.
+It requires the <option>-f</option> option, which directs output to a
+specified logfile.</para>
+
+<para>The <option>-m</option> option sets a minimum move distance in
+meters (it may include a fractional decimal part).  Motions shorter
+than this will not be logged.</para>
+
+<para>The <option>-r</option> option tells
+<application>gpxlogger</application> to retry when GPSd loses the fix.
+Without <option>-r</option>, <application>gpxlogger</application>
+would quit in this case.</para>
+
+<para>If D-Bus support is available on the host, GPSD is configured to
+use it, and <command>-e dbus</command> is specified, this program
+listens to DBUS broadcasts from
+<application>gpsd</application> via org.gpsd.fix.</para>
+
+<para>With <command>-e sockets</command>, or if sockets is the method
+defaulted to, you may give a server-port-device specification as
+arguments.</para>
+
+<para>The sockets default is to all devices on the localhost,
+using the default GPSD port 2947. An optional argument to any
+client may specify a server to get data from. A colon-separated suffix
+is taken as a port number. If there is a second colon-separated
+suffix, that is taken as a specific device name to be
+watched. However, if the server specification contains square
+brackets, the part inside them is taken as an IPv6 address and
+port/device suffixes are only parsed after the trailing bracket.
+Possible cases look like this:</para>
+
+<variablelist>
+<varlistentry>
+<term>localhost:/dev/ttyS1</term>
+<listitem><para>Look at the default port of localhost, trying both
+IPv4 and IPv6 and watching output from serial device 1.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>example.com:2317</term>
+<listitem><para>Look at port 2317 on example.com, trying both
+IPv4 and IPv6.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>71.162.241.5:2317:/dev/ttyS3</term>
+<listitem><para>Look at port 2317 at the specified IPv4
+address, collecting data from attached serial device 3.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:2317:/dev/ttyS5</term>
+<listitem><para>Look at port 2317 at the specified IPv6
+address, collecting data from attached serial device 5.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>
+<citerefentry><refentrytitle>gpsd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>gps</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+<citerefentry><refentrytitle>gpspipe</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+</para>
+</refsect1>
+
+<refsect1 id='maintainer'><title>AUTHORS</title>
+
+<para>
+  Amaury Jacquot <email>address@hidden</email> &amp;
+  Petter Reinholdtsen <email>address@hidden</email> &amp;
+  Chris Kuethe <email>address@hidden</email>
+</para>
+
+</refsect1>
+
+</refentry>
-- 
2.11.0




reply via email to

[Prev in Thread] Current Thread [Next in Thread]