Documentation.

diff --git a/Makefile b/Makefile
new file mode 100644 (file)
index 0000000..1d5d681
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,10 @@
+# The xmlto formatter is required to format XML intto display documentation.
+
+coverity-submit.html: coverity-submit.xml
+       xmlto xhtml-nochunks coverity-submit.xml
+
+coverity-submit.1: coverity-submit.xml
+       xmlto man coverity-submit.xml
+
+clean:
+       rm -f coverity-submit.html coverity-submit.1

diff --git a/coverity-submit.xml b/coverity-submit.xml
new file mode 100644 (file)
index 0000000..b46428a
--- /dev/null
+++ b/coverity-submit.xml
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY gpsdsock       "/var/run/gpsd.sock">
+]>
+<refentry id='gpsd.8'>
+<refentryinfo><date>9 Aug 2004</date></refentryinfo>
+<refmeta>
+<refentrytitle>gpsd</refentrytitle>
+<manvolnum>8</manvolnum>
+<refmiscinfo class="source">Coverity</refmiscinfo>
+<refmiscinfo class="manual">Coverity Documentation</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>coverity-submit</refname>
+<refpurpose>interface daemon for GPS receivers</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+  <command>coverity-submit</command>
+      <arg choice='opt'>-n </arg>
+      <arg choice='opt'>
+          <group><replaceable>project-name</replaceable></group>
+      </arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>DESCRIPTION</title>
+
+<para>This tool aims to make submitting projects for code auditing on
+the demonstration Coverity server into a one-step operation.  It
+automates the sequence of (a) running cov-build locally, (b) bundling
+the results into a tarball with a properly formatted README, (c)
+uploading the result to a public drop area of your choice, a(d)
+submitting an analysis request to the server, and (e) retrieving the 
+request status.</para>
+
+</refsect1>
+<refsect1><title>CONFIGURATION</title>
+
+<para>To use this tool, you need to set up a configuration file named
+<filename>.coverity-submit</filename> in your home directory.  This
+configuration file is best explained by example.</para>
+
+<programlisting>
+[DEFAULT]
+       name=Eric S. Raymond
+       userid=esr
+       email=esr@thyrsus.com
+       tools=/usr/local/coverity/bin
+       upload=scp %s esr@login.ibiblio.org:/public/html/catb/esr
+       advertise=http://catb.org/~esr/%s
+[gpsd]
+       password=XXXXXX
+       prebuild=scons -c
+       build=scons
+       postbuild=
+[giflib]
+       password=YYYYYYY
+       prebuild=autogen.sh &amp;&amp; make clean
+       build=make -k
+       postbuild=
+</programlisting>
+
+<para>Begin with a [DEFAULT] section giving your name and userid on the
+Coverity server. You may specify the email address to which success
+or failure notifications should be mailed for all other projects here, 
+or specify different addresses per-project.</para>
+
+<para>If cov-build is not in your execution path, you may use the
+'tools' option to tell <application>coverity-submit</application>
+where to find it.</para>
+
+<para>The 'upload' and 'advertise' option are required.  They tell
+<application>coverity-submit</application> how to ship your tarball to
+a public drop area where the Coverity server can see it, and the URL
+the Coverity server can use to fetch it.  Each of these options must
+contain the string '%s' indicating where the generated name of the
+tarball should be spliced in. Note that, like 'email', there can also
+be specified in a per-project entry in case you want to have separate
+per-project drop areas.</para>
+
+<para>This configuration describes two different (real) projects, one
+with an scons-based build and one with an autotools-based build. For
+each project you must specifty the Coverity build password and the
+local build command to pass to cov-build. You may optionally specify
+local prebuild and postbuild commands.</para>
+
+</refsect1>
+<refsect1><title>OPERATION</title>
+
+<para>The first thing <application>coverity-submit</application> does when 
+invoked is figure out which project profile to use.  If no argument is 
+specified but the basename of the current directory matches a project,
+it is selected. Otherwise, a command-line argument can specify the project 
+name (it is a fatal error for it not to match one of the configured 
+project profiles).</para>
+
+<para>There is just one option; <option>-n</option>, which says to display
+all the commands that would be run without actually executing them.</para>
+
+<para>Once <application>coverity-submit</application> has determined
+which project profile to use, it then performs the following steps:</para>
+
+<procedure>
+<step><para>The project's local prebuild command, if specified.</para></step>
+<step><para>The project's local build command.</para></step>
+<step><para>The project's local prebuild command, if specified.</para></step>
+<step><para>Generating a README and bundling it into a tarball with the scan results.</para></step>
+<step><para>Copying the tarball to the upload location.</para></step>
+<step><para>Sending an analysis job request to the Coverity server.</para></step>
+</procedure>
+
+<para>The script will report the result of the job request by dumping the
+server's HTML response.</para>
+
+</refsect1>
+<refsect1><title>PREREQUISITES</title>
+
+<para>Requires Python 3, curl, and cov-build.</para>
+
+</refsect1>
+<refsect1 id='maintainer'><title>AUTHOR</title>
+
+<para>Eric S. Raymond</para>
+</refsect1>
+
+</refentry>