--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/relmon_watchlist.4.xml	Fri Oct 24 22:44:39 2014 +0200
@@ -0,0 +1,141 @@
+<?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_watchlist</refentrytitle>
+    <manvolnum>4</manvolnum>
+    <refmiscinfo class="source"/>
+    <refmiscinfo class="version"/>
+    <refmiscinfo class="manual">File Formats</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>relmon_watchlist</refname>
+    <refpurpose>watchlist for software projects monitored by
+    <citerefentry><refentrytitle>relmon</refentrytitle><manvolnum>1</manvolnum></citerefentry></refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <para><replaceable>relmon_watchlist</replaceable></para>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <para>A <replaceable>relmon_watchlist</replaceable> consists of entries for
+      each monitored software projects which control how
+      <command>relmon</command> crawls websites and detects new
+      releases.</para>
+    <para>Each line is either an entry or a comment, lines containing only
+      whitespace are ignored. A comment starts with a leading
+    <literal>#</literal>.</para>
+    <para>An entry consists of three or more fields which are seperated by
+      whitespace. The first field contains the name of the project which must
+      be unique within the watchlist. The second field contains the base URL
+      which is used as the starting point for crawling and must be a valid URL.
+      Any fields between the second and the last but one field contain advanced
+      regular expressions as described in
+      <citerefentry><refentrytitle>re_syntax</refentrytitle>
+      <manvolnum>n</manvolnum></citerefentry> for matching the URLs of links
+      to follow. All patterns are implicitly anchored to the end of the
+      complete URL. The last field is the version-matching regular expression
+      which matches URLs of links to distribution files and must contain
+      exactly one reporting subexpression for extracting the version
+      number.</para>
+    <para>When updating the version information for a project
+      <command>relmon</command> starts with retrieving the document or feed
+      associated with the base URL. In case there are one or more fields before
+      the last version-matching field, relmon will retrieve all linked
+      documents or feeds whose URLs are matched by the regular expression
+      specified in the first field after the base URL. This process is then
+      repeated, that is documents or feeds linked from the documents or feeds
+      retrieved in the previous step are retrieved if the associated URLs match
+      the regular expression in the subsequent field and so on,  until the last
+      version-matching field is reached. Finally, the version-matching regular
+      expression specified in the last field is used to match any URLs of
+      distribution files linked from the documents or feeds retrieved in the
+      previous step and the version numbers are extracted.</para>
+  </refsect1>
+  <refsect1>
+    <title>Examples</title>
+    <example>
+      <title>An entry for a project which publishes distribution
+      files on its homepage</title>
+      <para>The following example is an entry for a project named
+        <application class="software">foo</application> which has a homepage at
+        <uri>http://example.org/foo/</uri> with direct links to the distribution
+        files, e.g. at
+        <uri>http://example.org/foo/foo-1.0.tar.gz</uri>:</para>
+      <programlisting>
+foo http://example.org/foo/ /foo/foo-([\d.]+)\.tar\.gz
+      </programlisting>
+    </example>
+    <example>
+      <title>An entry for a project which publishes distribution files of
+      new releases through an Atom feed</title>
+      <para>The following example is an entry for a project named
+        <application class="software">bar</application> which publishes an
+        Atom feed at <uri>https://example.com/news.xml</uri> which contains
+        links to the distribution files on another host, e.g. at
+        <uri>http://archive.example.com/bar-1.0.tar.gz</uri>:</para>
+      <programlisting>
+bar https://example.com/news.xml /bar-([\d.]+)\.tar\.gz
+      </programlisting>
+    </example>
+    <example>
+      <title>An entry for a project which publishes distribution files on a
+      file hosting website on multiple subpages</title>
+      <para>The following example is an entry for a project named
+        <application class="software">baz</application> which links to the
+        actual the distribution files, e.g. at
+        <uri>http://example.net/projects/baz/1.0/baz-1.0.tar.gz</uri>,
+        from several versioned subpages, e.g. at
+        <uri>http://example.net/projects/baz/1.0/</uri> and
+        <uri>http://example.net/projects/baz/1.1/</uri>, which are linked from
+        a common page under the URL
+        <uri>http://example.net/projects/baz/</uri>:</para>
+      <programlisting>
+baz http://example.net/projects/baz/ /baz/[\d.]+/ /baz-([\d.]+)\.tar\.gz
+      </programlisting>
+    </example>
+  </refsect1>
+  <refsect1>
+    <title>See Also</title>
+    <para><citerefentry><refentrytitle>relmon</refentrytitle>
+      <manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>regex</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>re_syntax</refentrytitle>
+      <manvolnum>n</manvolnum></citerefentry></para>
+  </refsect1>
+</refentry>