--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/relmon.1.xml	Fri Oct 24 22:44:39 2014 +0200
@@ -0,0 +1,480 @@
+<?xml version="1.0"?>
+<!--
+
+Copyright (C) 2014 Guido Berhoerster <guido+relmon@berhoerster.name>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
+  <info>
+    <author>
+      <personname>
+        <firstname>Guido</firstname>
+        <surname>Berhoerster</surname>
+      </personname>
+      <email>guido+relmon@berhoerster.name</email>
+      <personblurb/>
+    </author>
+    <date>24 October, 2014</date>
+  </info>
+  <refmeta>
+    <refentrytitle>relmon</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="source"/>
+    <refmiscinfo class="version"/>
+    <refmiscinfo class="manual">User Commands</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>relmon</refname>
+    <refpurpose>monitor websites of software projects for releases</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>relmon list</command>
+      <arg choice="opt">
+        <option>-H</option>
+      </arg>
+      <arg choice="opt">
+        <option>-f</option>
+        <group choice="plain">
+          <arg choice="plain">html</arg>
+          <arg choice="plain">parseable</arg>
+          <arg choice="plain">text</arg>
+        </group>
+      </arg>
+      <arg choice="opt">
+        <option>-F</option>
+        <replaceable>url</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-n</option>
+        <replaceable>number_items</replaceable>
+      </arg>
+      <arg choice="plain">
+        <replaceable>statefile</replaceable>
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>relmon list</command>
+      <arg choice="plain">
+        <option>-f</option>
+        <arg choice="plain">atom</arg>
+      </arg>
+      <arg choice="plain">
+        <option>-F</option>
+        <arg choice="plain">url</arg>
+      </arg>
+      <arg choice="opt">
+        <option>-n</option>
+        <replaceable>number_items</replaceable>
+      </arg>
+      <arg choice="plain">
+        <replaceable>statefile</replaceable>
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>relmon show</command>
+      <arg choice="plain">
+        <replaceable>statefile</replaceable>
+      </arg>
+      <arg choice="plain" rep="repeat">
+        <replaceable>name</replaceable>
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>relmon update</command>
+      <arg choice="opt">
+        <option>-d</option>
+      </arg>
+      <arg choice="opt">
+        <option>-e</option>
+      </arg>
+      <arg choice="opt">
+        <option>-v</option>
+      </arg>
+      <arg choice="opt">
+        <option>-c</option>
+        <replaceable>max_connections</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-C</option>
+        <replaceable>ca_dir</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-D</option>
+        <replaceable>delay</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-H</option>
+        <replaceable>max_host_connections</replaceable>
+      </arg>
+      <arg choice="opt"><option>-i</option>
+        <arg choice="plain"><replaceable>item</replaceable></arg>
+        <arg choice="opt" rep="repeat"><replaceable>,</replaceable></arg>
+      </arg>
+      <arg choice="opt">
+        <option>-l</option>
+        <replaceable>logfile</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-r</option>
+        <replaceable>retries</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-t</option>
+        <replaceable>min_time</replaceable>
+      </arg>
+      <arg choice="plain">
+        <replaceable>watchlist</replaceable>
+      </arg>
+      <arg choice="plain">
+        <replaceable>statefile</replaceable>
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>relmon help</command>
+      <arg choice="opt">
+        <replaceable>subcommand</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <para><command>relmon</command> is a utility for monitoring websites of
+      software projects for new releases. It can crawl websites via HTTP or
+      HTTPS using a configurable number of simultaneous connections and parse
+      HTML and XHTML documents as well as RSS 2.0 and Atom feeds. Software
+      releases are detected by extracting the version numbers from links to
+      distribution files from the parsed documents or feeds and comparing them
+      to previously extracted version numbers.</para>
+    <para>The crawling of the website of a software projects and the extraction
+      of version numbers are controlled by an entry with directions in a
+      watchlist file, see
+      <citerefentry><refentrytitle>relmon_watchlist</refentrytitle>
+      <manvolnum>4</manvolnum></citerefentry> for the exact format of
+      watchlist entries and further details on the operation of
+      <command>relmon</command>.  In addition to the version numbers, the
+      history of releases consisting of the times new release were initially
+      discovered, any encountered errors and the time the version information
+      was last updated are recorded in a statefile. <command>relmon</command>
+      can selectively update explicitly specified items or on the basis of the
+      time an item was last updated or whether any errors were encountered
+      during the previous update of an item.</para>
+    <para>The recorded information on each software project can be output in
+      several different formats, including formatted text, machine-parseable
+      text, and HTML, optionally with the history of releases in Atom feed
+      format.</para>
+  </refsect1>
+  <refsect1>
+    <title>Subcommands</title>
+    <variablelist>
+      <para><command>relmon</command> has the following subcommands:</para>
+      <varlistentry>
+        <term>
+          <command>list</command>
+        </term>
+        <listitem>
+          <para>List version information for each software project in the
+          statefile in a tabular form and/or the history of releases in the
+          specified output format</para>
+          <variablelist>
+            <para>The following options are supported:</para>
+            <varlistentry>
+              <term>
+                <option>-f</option>
+                <replaceable>format</replaceable>
+              </term>
+              <listitem>
+                <para>Emit output in the specified format. Possible values for
+                  <replaceable>format</replaceable> are html, atom, parseable
+                  and text, the default output format is text. The parseable
+                  format consist of one line per software project with four
+                  fields seperated by a single tab containing the name,
+                  version, timestamp and status. If the atom format is
+                  selected, an Atom feed which only contains the history of
+                  releases is emitted.  Otherwise version information for each
+                  software project in the statefile is emitted in a tabular
+                  form.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-F</option>
+                <replaceable>url</replaceable>
+              </term>
+              <listitem>
+                <para>If the output format is set to html, add a link to an
+                  Atom feed with the specified URL. If the output format is
+                  atom, use the specified URL as the URL where the Atom feed is
+                  published. This option is mandatory if the atom ouput format
+                  is selected.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-H</option>
+              </term>
+              <listitem>
+                <para>Include the history of released versions in the output.
+                  If the parseable ouput format was selected, the history is
+                  separated with a single blank line from the version
+                  information and consists of one line per history entry with
+                  three fields seperated by a single tab containing the times,
+                  name and version.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-n</option>
+                <replaceable>number_items</replaceable>
+              </term>
+              <listitem>
+                <para>If used in combination with the <option>-H</option>
+                  option or if the atom ouput format was selected, limit the
+                  output to the specified number of recent history
+                  entries.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <command>show</command>
+        </term>
+        <listitem>
+          <para>The <command>show</command> subcommand shows the name, latest
+            version, time of the last update, all known version nubers and
+            links to the corresponding distribution files, any errors
+            encountered during the last update operation, as well as the
+            release history for each specified software project from the
+            specified statefile.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <command>update</command>
+        </term>
+        <listitem>
+          <para>The <command>update</command> subcommand gathers information
+            on all or a specified subset of the software projects specified in
+            the watchlist and updates or creates a new statefile. Before
+            updating the statefile a backup copy is created using the current
+            filename with a <literal>~</literal> suffix added to it.</para>
+          <para>The following options are supported:</para>
+          <variablelist>
+            <varlistentry>
+              <term>
+                <option>-d</option>
+              </term>
+              <listitem>
+                <para>Trace and log all transfers and parsing. This option is
+                  used for debugging purposes.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-e</option>
+              </term>
+              <listitem>
+                <para>Only update version information for projects from the
+                  watchlist which were not successfully updated during the last
+                  update due to errors.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-v</option>
+              </term>
+              <listitem>
+                <para>Increase logging verbosity and log information about each
+                  transfer.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-c</option>
+                <replaceable>max_connections</replaceable>
+              </term>
+              <listitem>
+                <para>Limit the number of simultaneous connections to the
+                  specified number. The default value is 16.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-C</option>
+                <replaceable>ca_dir</replaceable>
+              </term>
+              <listitem>
+                <para>Verify the validity of TLS certificates using the CA
+                  certificates in the specified directory.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-D</option>
+                <replaceable>delay</replaceable>
+              </term>
+              <listitem>
+                <para>Wait at least the specified number of seconds before
+                  making subsequent connections to the same host. The default
+                  value is 0.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-H</option>
+                <replaceable>max_host_connections</replaceable>
+              </term>
+              <listitem>
+                <para>Limit the number of simultaneous connections to a single
+                  host to the specified number. The default value is 4.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-i</option>
+                <replaceable>items</replaceable>
+              </term>
+              <listitem>
+                <para>Update only the specified items. Multiple items can be
+                  specifed in the form of a comma-sperated list.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-l</option>
+                <replaceable>logfile</replaceable>
+              </term>
+              <listitem>
+                <para>Log to the specified logfile instead of stderr.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-r</option>
+                <replaceable>retries</replaceable>
+              </term>
+              <listitem>
+                <para>Limit the number of retries in case of connection
+                  failures. The default value is 3.</para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>
+                <option>-t</option>
+                <replaceable>min_time</replaceable>
+              </term>
+              <listitem>
+                <para>Only update version information for projects from the
+                  watchlist which have not been updated for the specified
+                  number of seconds.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <command>help</command>
+        </term>
+        <listitem>
+          <para>The <command>help</command> subcommand displays usage
+            information about the specified subcommand or all subcommands and
+            exits.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Examples</title>
+    <example>
+      <title>Updating version information</title>
+      <para>The following command retrieves the version information for the
+        entries in the watchlist <filename>foo.watchlist</filename> and stores
+        the results in the statefile <filename>foo.json</filename> using using
+        up to 100 simultaneous connections and logging all output to
+        <filename>relmon.log</filename>:</para>
+      <screen>
+$ relmon update -c 100 foo.watchlist foo.json
+      </screen>
+    </example>
+    <example>
+      <title>Conditionally updating version information</title>
+      <para>The following command updates version information in the statefile
+        <filename>bar.json</filename> only for those entries in the watchlist
+        <filename>foo.watchlist</filename> which either have not been updated
+        for at least 48 hours or which could not be sucessfully updated during
+        the last update operation due to errors:</para>
+      <screen>
+$ relmon update -v -t 172800 -e -l relmon.log watchlist relmon.json
+      </screen>
+    </example>
+    <example>
+      <title>Displaying detailed information on a monitored project</title>
+      <para>The following command displays all recorded information for the
+        monitored project named foo from the statefile
+        <filename>foo.json</filename>:</para>
+      <screen>
+$ relmon show foo.json baz
+      </screen>
+    </example>
+    <example>
+      <title>Creating a HTML document with the version information on each
+        of the monitored projects</title>
+      <para>The following command sequence creates a HTML document containing a
+        table with the version information of each monitored project as well as
+        an associated Atom feed with the URL
+        <uri>http://example.net/releases.xml</uri> containing the 100 most
+        recently discovered releases from the statefile
+        <filename>foo.json</filename>:</para>
+      <screen>
+$ relmon list -f html -F 'http://example.net/releases.xml' foo.json > releases.html
+$ relmon list -f atom -F 'http://example.net/releases.xml' -n 100 foo.json
+      </screen>
+    </example>
+  </refsect1>
+  <refsect1>
+    <title>Exit Status</title>
+    <para>The following exit values are returned:</para>
+    <variablelist>
+      <varlistentry>
+        <term>0</term>
+        <listitem>
+          <para>Command successfully executed.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>&gt; 0</term>
+        <listitem>
+          <para>An error has occured.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>See Also</title>
+    <para><citerefentry><refentrytitle>relmon_format</refentrytitle>
+      <manvolnum>4</manvolnum></citerefentry></para>
+  </refsect1>
+</refentry>