<?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>