projects/relmon

changeset 4:f28486666a4f

Add manpages for relmon and relmon_watchlist
author Guido Berhoerster <guido+relmon@berhoerster.name>
date Fri Oct 24 22:44:39 2014 +0200 (2014-10-24)
parents 6d87242c537e
children 86a0c5d11f05
files Makefile README docbook-update-source-data.xsl relmon.1.xml relmon_watchlist.4.xml
line diff
     1.1 --- a/Makefile	Mon Oct 20 19:31:20 2014 +0200
     1.2 +++ b/Makefile	Fri Oct 24 22:44:39 2014 +0200
     1.3 @@ -31,32 +31,60 @@
     1.4  PAX :=		pax
     1.5  GZIP :=		gzip
     1.6  SED :=		sed
     1.7 +XSLTPROC :=	xsltproc
     1.8 +DOCBOOK5_MANPAGES_STYLESHEET =	http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
     1.9  TCLSH_PATH :=	/usr/bin/tclsh
    1.10  
    1.11 +define generate-manpage-rule =
    1.12 +%.$(1): %.$(1).xml
    1.13 +	$$(XSLTPROC) \
    1.14 +	    --xinclude \
    1.15 +	    --stringparam package $$(PACKAGE) \
    1.16 +	    --stringparam version $$(VERSION)\
    1.17 +	    docbook-update-source-data.xsl $$< | \
    1.18 +	    $$(XSLTPROC) \
    1.19 +	    --xinclude \
    1.20 +	    $$(DOCBOOK5_MANPAGES_FLAGS) \
    1.21 +	    --output $$@ \
    1.22 +	    $$(DOCBOOK5_MANPAGES_STYLESHEET) \
    1.23 +	    -
    1.24 +endef
    1.25 +
    1.26  DESTDIR ?=
    1.27  prefix ?=	/usr/local
    1.28  bindir ?=	$(prefix)/bin
    1.29 +datadir ?=	$(prefix)/share
    1.30 +mandir ?=	$(datadir)/man
    1.31  
    1.32  SCRIPTS =	$(PACKAGE).tcl
    1.33 +MANPAGES =	$(PACKAGE).1 $(PACKAGE)_watchlist.4
    1.34 +DOCBOOK5_MANPAGES_FLAGS =	--stringparam man.authors.section.enabled 0 \
    1.35 +				--stringparam man.copyright.section.enabled 0
    1.36  
    1.37  .DEFAULT_TARGET = all
    1.38  
    1.39  .PHONY: all clean clobber dist install
    1.40  
    1.41 -all: $(PACKAGE)
    1.42 +all: $(PACKAGE) $(MANPAGES)
    1.43  
    1.44  $(PACKAGE): $(SCRIPTS)
    1.45  	cp $< $@
    1.46  
    1.47 +$(foreach section,1 2 3 4 5 6 7 8 9,$(eval $(call generate-manpage-rule,$(section))))
    1.48 +
    1.49  %.tcl: %.tcl.in
    1.50  	$(SED) -e '1s,#!.*,#!$(TCLSH_PATH),' -e 's,@VERSION@,$(VERSION),' $< \
    1.51  	    > $@
    1.52  
    1.53  install:
    1.54  	$(INSTALL.exec) $(PACKAGE) "$(DESTDIR)$(bindir)/$(PACKAGE)"
    1.55 +	for manpage in $(MANPAGES); do \
    1.56 +	    $(INSTALL.data) $${manpage} \
    1.57 +	        "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
    1.58 +	done
    1.59  
    1.60  clean:
    1.61 -	rm -f $(PACKAGE) $(SCRIPTS)
    1.62 +	rm -f $(PACKAGE) $(SCRIPTS) $(MANPAGES)
    1.63  
    1.64  clobber: clean
    1.65  
     2.1 --- a/README	Mon Oct 20 19:31:20 2014 +0200
     2.2 +++ b/README	Fri Oct 24 22:44:39 2014 +0200
     2.3 @@ -20,8 +20,9 @@
     2.4  Requirements
     2.5  ------------
     2.6  
     2.7 -relmon requires GNU make, GNU or BSD install, Tcl 8.5 or later, tcllib, tls,
     2.8 -and tdom. It has been tested on Linux distributions and FreeBSD.
     2.9 +relmon requires GNU make, GNU or BSD install, the xsltproc tool from libxml2,
    2.10 +Tcl 8.5 or later, tcllib, tls, and tdom. It has been tested on Linux
    2.11 +distributions and FreeBSD.
    2.12  
    2.13  License
    2.14  -------
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/docbook-update-source-data.xsl	Fri Oct 24 22:44:39 2014 +0200
     3.3 @@ -0,0 +1,29 @@
     3.4 +<?xml version="1.0"?>
     3.5 +<xsl:stylesheet
     3.6 +  version="1.0"
     3.7 +  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     3.8 +  xmlns:db="http://docbook.org/ns/docbook"
     3.9 +  xmlns="http://docbook.org/ns/docbook"
    3.10 +  exclude-result-prefixes="xsl db">
    3.11 +
    3.12 +  <xsl:param name="package" select="''" />
    3.13 +  <xsl:param name="version" select="''" />
    3.14 +
    3.15 +  <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or
    3.16 +    @class = 'version']"/>
    3.17 +
    3.18 +  <xsl:template match="db:refmeta">
    3.19 +    <xsl:copy>
    3.20 +      <xsl:apply-templates/>
    3.21 +      <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo>
    3.22 +      <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
    3.23 +    </xsl:copy>
    3.24 +  </xsl:template>
    3.25 +
    3.26 +  <xsl:template match="@*|node()">
    3.27 +    <xsl:copy>
    3.28 +      <xsl:apply-templates select="@*|node()"/>
    3.29 +    </xsl:copy>
    3.30 +  </xsl:template>
    3.31 +
    3.32 +</xsl:stylesheet>
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/relmon.1.xml	Fri Oct 24 22:44:39 2014 +0200
     4.3 @@ -0,0 +1,480 @@
     4.4 +<?xml version="1.0"?>
     4.5 +<!--
     4.6 +
     4.7 +Copyright (C) 2014 Guido Berhoerster <guido+relmon@berhoerster.name>
     4.8 +
     4.9 +Permission is hereby granted, free of charge, to any person obtaining
    4.10 +a copy of this software and associated documentation files (the
    4.11 +"Software"), to deal in the Software without restriction, including
    4.12 +without limitation the rights to use, copy, modify, merge, publish,
    4.13 +distribute, sublicense, and/or sell copies of the Software, and to
    4.14 +permit persons to whom the Software is furnished to do so, subject to
    4.15 +the following conditions:
    4.16 +
    4.17 +The above copyright notice and this permission notice shall be included
    4.18 +in all copies or substantial portions of the Software.
    4.19 +
    4.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    4.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    4.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    4.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    4.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    4.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    4.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    4.27 +
    4.28 +-->
    4.29 +<refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
    4.30 +  <info>
    4.31 +    <author>
    4.32 +      <personname>
    4.33 +        <firstname>Guido</firstname>
    4.34 +        <surname>Berhoerster</surname>
    4.35 +      </personname>
    4.36 +      <email>guido+relmon@berhoerster.name</email>
    4.37 +      <personblurb/>
    4.38 +    </author>
    4.39 +    <date>24 October, 2014</date>
    4.40 +  </info>
    4.41 +  <refmeta>
    4.42 +    <refentrytitle>relmon</refentrytitle>
    4.43 +    <manvolnum>1</manvolnum>
    4.44 +    <refmiscinfo class="source"/>
    4.45 +    <refmiscinfo class="version"/>
    4.46 +    <refmiscinfo class="manual">User Commands</refmiscinfo>
    4.47 +  </refmeta>
    4.48 +  <refnamediv>
    4.49 +    <refname>relmon</refname>
    4.50 +    <refpurpose>monitor websites of software projects for releases</refpurpose>
    4.51 +  </refnamediv>
    4.52 +  <refsynopsisdiv>
    4.53 +    <cmdsynopsis>
    4.54 +      <command>relmon list</command>
    4.55 +      <arg choice="opt">
    4.56 +        <option>-H</option>
    4.57 +      </arg>
    4.58 +      <arg choice="opt">
    4.59 +        <option>-f</option>
    4.60 +        <group choice="plain">
    4.61 +          <arg choice="plain">html</arg>
    4.62 +          <arg choice="plain">parseable</arg>
    4.63 +          <arg choice="plain">text</arg>
    4.64 +        </group>
    4.65 +      </arg>
    4.66 +      <arg choice="opt">
    4.67 +        <option>-F</option>
    4.68 +        <replaceable>url</replaceable>
    4.69 +      </arg>
    4.70 +      <arg choice="opt">
    4.71 +        <option>-n</option>
    4.72 +        <replaceable>number_items</replaceable>
    4.73 +      </arg>
    4.74 +      <arg choice="plain">
    4.75 +        <replaceable>statefile</replaceable>
    4.76 +      </arg>
    4.77 +    </cmdsynopsis>
    4.78 +    <cmdsynopsis>
    4.79 +      <command>relmon list</command>
    4.80 +      <arg choice="plain">
    4.81 +        <option>-f</option>
    4.82 +        <arg choice="plain">atom</arg>
    4.83 +      </arg>
    4.84 +      <arg choice="plain">
    4.85 +        <option>-F</option>
    4.86 +        <arg choice="plain">url</arg>
    4.87 +      </arg>
    4.88 +      <arg choice="opt">
    4.89 +        <option>-n</option>
    4.90 +        <replaceable>number_items</replaceable>
    4.91 +      </arg>
    4.92 +      <arg choice="plain">
    4.93 +        <replaceable>statefile</replaceable>
    4.94 +      </arg>
    4.95 +    </cmdsynopsis>
    4.96 +    <cmdsynopsis>
    4.97 +      <command>relmon show</command>
    4.98 +      <arg choice="plain">
    4.99 +        <replaceable>statefile</replaceable>
   4.100 +      </arg>
   4.101 +      <arg choice="plain" rep="repeat">
   4.102 +        <replaceable>name</replaceable>
   4.103 +      </arg>
   4.104 +    </cmdsynopsis>
   4.105 +    <cmdsynopsis>
   4.106 +      <command>relmon update</command>
   4.107 +      <arg choice="opt">
   4.108 +        <option>-d</option>
   4.109 +      </arg>
   4.110 +      <arg choice="opt">
   4.111 +        <option>-e</option>
   4.112 +      </arg>
   4.113 +      <arg choice="opt">
   4.114 +        <option>-v</option>
   4.115 +      </arg>
   4.116 +      <arg choice="opt">
   4.117 +        <option>-c</option>
   4.118 +        <replaceable>max_connections</replaceable>
   4.119 +      </arg>
   4.120 +      <arg choice="opt">
   4.121 +        <option>-C</option>
   4.122 +        <replaceable>ca_dir</replaceable>
   4.123 +      </arg>
   4.124 +      <arg choice="opt">
   4.125 +        <option>-D</option>
   4.126 +        <replaceable>delay</replaceable>
   4.127 +      </arg>
   4.128 +      <arg choice="opt">
   4.129 +        <option>-H</option>
   4.130 +        <replaceable>max_host_connections</replaceable>
   4.131 +      </arg>
   4.132 +      <arg choice="opt"><option>-i</option>
   4.133 +        <arg choice="plain"><replaceable>item</replaceable></arg>
   4.134 +        <arg choice="opt" rep="repeat"><replaceable>,</replaceable></arg>
   4.135 +      </arg>
   4.136 +      <arg choice="opt">
   4.137 +        <option>-l</option>
   4.138 +        <replaceable>logfile</replaceable>
   4.139 +      </arg>
   4.140 +      <arg choice="opt">
   4.141 +        <option>-r</option>
   4.142 +        <replaceable>retries</replaceable>
   4.143 +      </arg>
   4.144 +      <arg choice="opt">
   4.145 +        <option>-t</option>
   4.146 +        <replaceable>min_time</replaceable>
   4.147 +      </arg>
   4.148 +      <arg choice="plain">
   4.149 +        <replaceable>watchlist</replaceable>
   4.150 +      </arg>
   4.151 +      <arg choice="plain">
   4.152 +        <replaceable>statefile</replaceable>
   4.153 +      </arg>
   4.154 +    </cmdsynopsis>
   4.155 +    <cmdsynopsis>
   4.156 +      <command>relmon help</command>
   4.157 +      <arg choice="opt">
   4.158 +        <replaceable>subcommand</replaceable>
   4.159 +      </arg>
   4.160 +    </cmdsynopsis>
   4.161 +  </refsynopsisdiv>
   4.162 +  <refsect1>
   4.163 +    <title>Description</title>
   4.164 +    <para><command>relmon</command> is a utility for monitoring websites of
   4.165 +      software projects for new releases. It can crawl websites via HTTP or
   4.166 +      HTTPS using a configurable number of simultaneous connections and parse
   4.167 +      HTML and XHTML documents as well as RSS 2.0 and Atom feeds. Software
   4.168 +      releases are detected by extracting the version numbers from links to
   4.169 +      distribution files from the parsed documents or feeds and comparing them
   4.170 +      to previously extracted version numbers.</para>
   4.171 +    <para>The crawling of the website of a software projects and the extraction
   4.172 +      of version numbers are controlled by an entry with directions in a
   4.173 +      watchlist file, see
   4.174 +      <citerefentry><refentrytitle>relmon_watchlist</refentrytitle>
   4.175 +      <manvolnum>4</manvolnum></citerefentry> for the exact format of
   4.176 +      watchlist entries and further details on the operation of
   4.177 +      <command>relmon</command>.  In addition to the version numbers, the
   4.178 +      history of releases consisting of the times new release were initially
   4.179 +      discovered, any encountered errors and the time the version information
   4.180 +      was last updated are recorded in a statefile. <command>relmon</command>
   4.181 +      can selectively update explicitly specified items or on the basis of the
   4.182 +      time an item was last updated or whether any errors were encountered
   4.183 +      during the previous update of an item.</para>
   4.184 +    <para>The recorded information on each software project can be output in
   4.185 +      several different formats, including formatted text, machine-parseable
   4.186 +      text, and HTML, optionally with the history of releases in Atom feed
   4.187 +      format.</para>
   4.188 +  </refsect1>
   4.189 +  <refsect1>
   4.190 +    <title>Subcommands</title>
   4.191 +    <variablelist>
   4.192 +      <para><command>relmon</command> has the following subcommands:</para>
   4.193 +      <varlistentry>
   4.194 +        <term>
   4.195 +          <command>list</command>
   4.196 +        </term>
   4.197 +        <listitem>
   4.198 +          <para>List version information for each software project in the
   4.199 +          statefile in a tabular form and/or the history of releases in the
   4.200 +          specified output format</para>
   4.201 +          <variablelist>
   4.202 +            <para>The following options are supported:</para>
   4.203 +            <varlistentry>
   4.204 +              <term>
   4.205 +                <option>-f</option>
   4.206 +                <replaceable>format</replaceable>
   4.207 +              </term>
   4.208 +              <listitem>
   4.209 +                <para>Emit output in the specified format. Possible values for
   4.210 +                  <replaceable>format</replaceable> are html, atom, parseable
   4.211 +                  and text, the default output format is text. The parseable
   4.212 +                  format consist of one line per software project with four
   4.213 +                  fields seperated by a single tab containing the name,
   4.214 +                  version, timestamp and status. If the atom format is
   4.215 +                  selected, an Atom feed which only contains the history of
   4.216 +                  releases is emitted.  Otherwise version information for each
   4.217 +                  software project in the statefile is emitted in a tabular
   4.218 +                  form.
   4.219 +                </para>
   4.220 +              </listitem>
   4.221 +            </varlistentry>
   4.222 +            <varlistentry>
   4.223 +              <term>
   4.224 +                <option>-F</option>
   4.225 +                <replaceable>url</replaceable>
   4.226 +              </term>
   4.227 +              <listitem>
   4.228 +                <para>If the output format is set to html, add a link to an
   4.229 +                  Atom feed with the specified URL. If the output format is
   4.230 +                  atom, use the specified URL as the URL where the Atom feed is
   4.231 +                  published. This option is mandatory if the atom ouput format
   4.232 +                  is selected.</para>
   4.233 +              </listitem>
   4.234 +            </varlistentry>
   4.235 +            <varlistentry>
   4.236 +              <term>
   4.237 +                <option>-H</option>
   4.238 +              </term>
   4.239 +              <listitem>
   4.240 +                <para>Include the history of released versions in the output.
   4.241 +                  If the parseable ouput format was selected, the history is
   4.242 +                  separated with a single blank line from the version
   4.243 +                  information and consists of one line per history entry with
   4.244 +                  three fields seperated by a single tab containing the times,
   4.245 +                  name and version.</para>
   4.246 +              </listitem>
   4.247 +            </varlistentry>
   4.248 +            <varlistentry>
   4.249 +              <term>
   4.250 +                <option>-n</option>
   4.251 +                <replaceable>number_items</replaceable>
   4.252 +              </term>
   4.253 +              <listitem>
   4.254 +                <para>If used in combination with the <option>-H</option>
   4.255 +                  option or if the atom ouput format was selected, limit the
   4.256 +                  output to the specified number of recent history
   4.257 +                  entries.</para>
   4.258 +              </listitem>
   4.259 +            </varlistentry>
   4.260 +          </variablelist>
   4.261 +        </listitem>
   4.262 +      </varlistentry>
   4.263 +      <varlistentry>
   4.264 +        <term>
   4.265 +          <command>show</command>
   4.266 +        </term>
   4.267 +        <listitem>
   4.268 +          <para>The <command>show</command> subcommand shows the name, latest
   4.269 +            version, time of the last update, all known version nubers and
   4.270 +            links to the corresponding distribution files, any errors
   4.271 +            encountered during the last update operation, as well as the
   4.272 +            release history for each specified software project from the
   4.273 +            specified statefile.</para>
   4.274 +        </listitem>
   4.275 +      </varlistentry>
   4.276 +      <varlistentry>
   4.277 +        <term>
   4.278 +          <command>update</command>
   4.279 +        </term>
   4.280 +        <listitem>
   4.281 +          <para>The <command>update</command> subcommand gathers information
   4.282 +            on all or a specified subset of the software projects specified in
   4.283 +            the watchlist and updates or creates a new statefile. Before
   4.284 +            updating the statefile a backup copy is created using the current
   4.285 +            filename with a <literal>~</literal> suffix added to it.</para>
   4.286 +          <para>The following options are supported:</para>
   4.287 +          <variablelist>
   4.288 +            <varlistentry>
   4.289 +              <term>
   4.290 +                <option>-d</option>
   4.291 +              </term>
   4.292 +              <listitem>
   4.293 +                <para>Trace and log all transfers and parsing. This option is
   4.294 +                  used for debugging purposes.</para>
   4.295 +              </listitem>
   4.296 +            </varlistentry>
   4.297 +            <varlistentry>
   4.298 +              <term>
   4.299 +                <option>-e</option>
   4.300 +              </term>
   4.301 +              <listitem>
   4.302 +                <para>Only update version information for projects from the
   4.303 +                  watchlist which were not successfully updated during the last
   4.304 +                  update due to errors.</para>
   4.305 +              </listitem>
   4.306 +            </varlistentry>
   4.307 +            <varlistentry>
   4.308 +              <term>
   4.309 +                <option>-v</option>
   4.310 +              </term>
   4.311 +              <listitem>
   4.312 +                <para>Increase logging verbosity and log information about each
   4.313 +                  transfer.</para>
   4.314 +              </listitem>
   4.315 +            </varlistentry>
   4.316 +            <varlistentry>
   4.317 +              <term>
   4.318 +                <option>-c</option>
   4.319 +                <replaceable>max_connections</replaceable>
   4.320 +              </term>
   4.321 +              <listitem>
   4.322 +                <para>Limit the number of simultaneous connections to the
   4.323 +                  specified number. The default value is 16.</para>
   4.324 +              </listitem>
   4.325 +            </varlistentry>
   4.326 +            <varlistentry>
   4.327 +              <term>
   4.328 +                <option>-C</option>
   4.329 +                <replaceable>ca_dir</replaceable>
   4.330 +              </term>
   4.331 +              <listitem>
   4.332 +                <para>Verify the validity of TLS certificates using the CA
   4.333 +                  certificates in the specified directory.</para>
   4.334 +              </listitem>
   4.335 +            </varlistentry>
   4.336 +            <varlistentry>
   4.337 +              <term>
   4.338 +                <option>-D</option>
   4.339 +                <replaceable>delay</replaceable>
   4.340 +              </term>
   4.341 +              <listitem>
   4.342 +                <para>Wait at least the specified number of seconds before
   4.343 +                  making subsequent connections to the same host. The default
   4.344 +                  value is 0.</para>
   4.345 +              </listitem>
   4.346 +            </varlistentry>
   4.347 +            <varlistentry>
   4.348 +              <term>
   4.349 +                <option>-H</option>
   4.350 +                <replaceable>max_host_connections</replaceable>
   4.351 +              </term>
   4.352 +              <listitem>
   4.353 +                <para>Limit the number of simultaneous connections to a single
   4.354 +                  host to the specified number. The default value is 4.</para>
   4.355 +              </listitem>
   4.356 +            </varlistentry>
   4.357 +            <varlistentry>
   4.358 +              <term>
   4.359 +                <option>-i</option>
   4.360 +                <replaceable>items</replaceable>
   4.361 +              </term>
   4.362 +              <listitem>
   4.363 +                <para>Update only the specified items. Multiple items can be
   4.364 +                  specifed in the form of a comma-sperated list.</para>
   4.365 +              </listitem>
   4.366 +            </varlistentry>
   4.367 +            <varlistentry>
   4.368 +              <term>
   4.369 +                <option>-l</option>
   4.370 +                <replaceable>logfile</replaceable>
   4.371 +              </term>
   4.372 +              <listitem>
   4.373 +                <para>Log to the specified logfile instead of stderr.</para>
   4.374 +              </listitem>
   4.375 +            </varlistentry>
   4.376 +            <varlistentry>
   4.377 +              <term>
   4.378 +                <option>-r</option>
   4.379 +                <replaceable>retries</replaceable>
   4.380 +              </term>
   4.381 +              <listitem>
   4.382 +                <para>Limit the number of retries in case of connection
   4.383 +                  failures. The default value is 3.</para>
   4.384 +              </listitem>
   4.385 +            </varlistentry>
   4.386 +            <varlistentry>
   4.387 +              <term>
   4.388 +                <option>-t</option>
   4.389 +                <replaceable>min_time</replaceable>
   4.390 +              </term>
   4.391 +              <listitem>
   4.392 +                <para>Only update version information for projects from the
   4.393 +                  watchlist which have not been updated for the specified
   4.394 +                  number of seconds.</para>
   4.395 +              </listitem>
   4.396 +            </varlistentry>
   4.397 +          </variablelist>
   4.398 +        </listitem>
   4.399 +      </varlistentry>
   4.400 +      <varlistentry>
   4.401 +        <term>
   4.402 +          <command>help</command>
   4.403 +        </term>
   4.404 +        <listitem>
   4.405 +          <para>The <command>help</command> subcommand displays usage
   4.406 +            information about the specified subcommand or all subcommands and
   4.407 +            exits.</para>
   4.408 +        </listitem>
   4.409 +      </varlistentry>
   4.410 +    </variablelist>
   4.411 +  </refsect1>
   4.412 +  <refsect1>
   4.413 +    <title>Examples</title>
   4.414 +    <example>
   4.415 +      <title>Updating version information</title>
   4.416 +      <para>The following command retrieves the version information for the
   4.417 +        entries in the watchlist <filename>foo.watchlist</filename> and stores
   4.418 +        the results in the statefile <filename>foo.json</filename> using using
   4.419 +        up to 100 simultaneous connections and logging all output to
   4.420 +        <filename>relmon.log</filename>:</para>
   4.421 +      <screen>
   4.422 +$ relmon update -c 100 foo.watchlist foo.json
   4.423 +      </screen>
   4.424 +    </example>
   4.425 +    <example>
   4.426 +      <title>Conditionally updating version information</title>
   4.427 +      <para>The following command updates version information in the statefile
   4.428 +        <filename>bar.json</filename> only for those entries in the watchlist
   4.429 +        <filename>foo.watchlist</filename> which either have not been updated
   4.430 +        for at least 48 hours or which could not be sucessfully updated during
   4.431 +        the last update operation due to errors:</para>
   4.432 +      <screen>
   4.433 +$ relmon update -v -t 172800 -e -l relmon.log watchlist relmon.json
   4.434 +      </screen>
   4.435 +    </example>
   4.436 +    <example>
   4.437 +      <title>Displaying detailed information on a monitored project</title>
   4.438 +      <para>The following command displays all recorded information for the
   4.439 +        monitored project named foo from the statefile
   4.440 +        <filename>foo.json</filename>:</para>
   4.441 +      <screen>
   4.442 +$ relmon show foo.json baz
   4.443 +      </screen>
   4.444 +    </example>
   4.445 +    <example>
   4.446 +      <title>Creating a HTML document with the version information on each
   4.447 +        of the monitored projects</title>
   4.448 +      <para>The following command sequence creates a HTML document containing a
   4.449 +        table with the version information of each monitored project as well as
   4.450 +        an associated Atom feed with the URL
   4.451 +        <uri>http://example.net/releases.xml</uri> containing the 100 most
   4.452 +        recently discovered releases from the statefile
   4.453 +        <filename>foo.json</filename>:</para>
   4.454 +      <screen>
   4.455 +$ relmon list -f html -F 'http://example.net/releases.xml' foo.json > releases.html
   4.456 +$ relmon list -f atom -F 'http://example.net/releases.xml' -n 100 foo.json
   4.457 +      </screen>
   4.458 +    </example>
   4.459 +  </refsect1>
   4.460 +  <refsect1>
   4.461 +    <title>Exit Status</title>
   4.462 +    <para>The following exit values are returned:</para>
   4.463 +    <variablelist>
   4.464 +      <varlistentry>
   4.465 +        <term>0</term>
   4.466 +        <listitem>
   4.467 +          <para>Command successfully executed.</para>
   4.468 +        </listitem>
   4.469 +      </varlistentry>
   4.470 +      <varlistentry>
   4.471 +        <term>&gt; 0</term>
   4.472 +        <listitem>
   4.473 +          <para>An error has occured.</para>
   4.474 +        </listitem>
   4.475 +      </varlistentry>
   4.476 +    </variablelist>
   4.477 +  </refsect1>
   4.478 +  <refsect1>
   4.479 +    <title>See Also</title>
   4.480 +    <para><citerefentry><refentrytitle>relmon_format</refentrytitle>
   4.481 +      <manvolnum>4</manvolnum></citerefentry></para>
   4.482 +  </refsect1>
   4.483 +</refentry>
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/relmon_watchlist.4.xml	Fri Oct 24 22:44:39 2014 +0200
     5.3 @@ -0,0 +1,141 @@
     5.4 +<?xml version="1.0"?>
     5.5 +<!--
     5.6 +
     5.7 +Copyright (C) 2014 Guido Berhoerster <guido+relmon@berhoerster.name>
     5.8 +
     5.9 +Permission is hereby granted, free of charge, to any person obtaining
    5.10 +a copy of this software and associated documentation files (the
    5.11 +"Software"), to deal in the Software without restriction, including
    5.12 +without limitation the rights to use, copy, modify, merge, publish,
    5.13 +distribute, sublicense, and/or sell copies of the Software, and to
    5.14 +permit persons to whom the Software is furnished to do so, subject to
    5.15 +the following conditions:
    5.16 +
    5.17 +The above copyright notice and this permission notice shall be included
    5.18 +in all copies or substantial portions of the Software.
    5.19 +
    5.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    5.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    5.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    5.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    5.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    5.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    5.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    5.27 +
    5.28 +-->
    5.29 +<refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
    5.30 +  <info>
    5.31 +    <author>
    5.32 +      <personname>
    5.33 +        <firstname>Guido</firstname>
    5.34 +        <surname>Berhoerster</surname>
    5.35 +      </personname>
    5.36 +      <email>guido+relmon@berhoerster.name</email>
    5.37 +      <personblurb/>
    5.38 +    </author>
    5.39 +    <date>24 October, 2014</date>
    5.40 +  </info>
    5.41 +  <refmeta>
    5.42 +    <refentrytitle>relmon_watchlist</refentrytitle>
    5.43 +    <manvolnum>4</manvolnum>
    5.44 +    <refmiscinfo class="source"/>
    5.45 +    <refmiscinfo class="version"/>
    5.46 +    <refmiscinfo class="manual">File Formats</refmiscinfo>
    5.47 +  </refmeta>
    5.48 +  <refnamediv>
    5.49 +    <refname>relmon_watchlist</refname>
    5.50 +    <refpurpose>watchlist for software projects monitored by
    5.51 +    <citerefentry><refentrytitle>relmon</refentrytitle><manvolnum>1</manvolnum></citerefentry></refpurpose>
    5.52 +  </refnamediv>
    5.53 +  <refsynopsisdiv>
    5.54 +    <para><replaceable>relmon_watchlist</replaceable></para>
    5.55 +  </refsynopsisdiv>
    5.56 +  <refsect1>
    5.57 +    <title>Description</title>
    5.58 +    <para>A <replaceable>relmon_watchlist</replaceable> consists of entries for
    5.59 +      each monitored software projects which control how
    5.60 +      <command>relmon</command> crawls websites and detects new
    5.61 +      releases.</para>
    5.62 +    <para>Each line is either an entry or a comment, lines containing only
    5.63 +      whitespace are ignored. A comment starts with a leading
    5.64 +    <literal>#</literal>.</para>
    5.65 +    <para>An entry consists of three or more fields which are seperated by
    5.66 +      whitespace. The first field contains the name of the project which must
    5.67 +      be unique within the watchlist. The second field contains the base URL
    5.68 +      which is used as the starting point for crawling and must be a valid URL.
    5.69 +      Any fields between the second and the last but one field contain advanced
    5.70 +      regular expressions as described in
    5.71 +      <citerefentry><refentrytitle>re_syntax</refentrytitle>
    5.72 +      <manvolnum>n</manvolnum></citerefentry> for matching the URLs of links
    5.73 +      to follow. All patterns are implicitly anchored to the end of the
    5.74 +      complete URL. The last field is the version-matching regular expression
    5.75 +      which matches URLs of links to distribution files and must contain
    5.76 +      exactly one reporting subexpression for extracting the version
    5.77 +      number.</para>
    5.78 +    <para>When updating the version information for a project
    5.79 +      <command>relmon</command> starts with retrieving the document or feed
    5.80 +      associated with the base URL. In case there are one or more fields before
    5.81 +      the last version-matching field, relmon will retrieve all linked
    5.82 +      documents or feeds whose URLs are matched by the regular expression
    5.83 +      specified in the first field after the base URL. This process is then
    5.84 +      repeated, that is documents or feeds linked from the documents or feeds
    5.85 +      retrieved in the previous step are retrieved if the associated URLs match
    5.86 +      the regular expression in the subsequent field and so on,  until the last
    5.87 +      version-matching field is reached. Finally, the version-matching regular
    5.88 +      expression specified in the last field is used to match any URLs of
    5.89 +      distribution files linked from the documents or feeds retrieved in the
    5.90 +      previous step and the version numbers are extracted.</para>
    5.91 +  </refsect1>
    5.92 +  <refsect1>
    5.93 +    <title>Examples</title>
    5.94 +    <example>
    5.95 +      <title>An entry for a project which publishes distribution
    5.96 +      files on its homepage</title>
    5.97 +      <para>The following example is an entry for a project named
    5.98 +        <application class="software">foo</application> which has a homepage at
    5.99 +        <uri>http://example.org/foo/</uri> with direct links to the distribution
   5.100 +        files, e.g. at
   5.101 +        <uri>http://example.org/foo/foo-1.0.tar.gz</uri>:</para>
   5.102 +      <programlisting>
   5.103 +foo http://example.org/foo/ /foo/foo-([\d.]+)\.tar\.gz
   5.104 +      </programlisting>
   5.105 +    </example>
   5.106 +    <example>
   5.107 +      <title>An entry for a project which publishes distribution files of
   5.108 +      new releases through an Atom feed</title>
   5.109 +      <para>The following example is an entry for a project named
   5.110 +        <application class="software">bar</application> which publishes an
   5.111 +        Atom feed at <uri>https://example.com/news.xml</uri> which contains
   5.112 +        links to the distribution files on another host, e.g. at
   5.113 +        <uri>http://archive.example.com/bar-1.0.tar.gz</uri>:</para>
   5.114 +      <programlisting>
   5.115 +bar https://example.com/news.xml /bar-([\d.]+)\.tar\.gz
   5.116 +      </programlisting>
   5.117 +    </example>
   5.118 +    <example>
   5.119 +      <title>An entry for a project which publishes distribution files on a
   5.120 +      file hosting website on multiple subpages</title>
   5.121 +      <para>The following example is an entry for a project named
   5.122 +        <application class="software">baz</application> which links to the
   5.123 +        actual the distribution files, e.g. at
   5.124 +        <uri>http://example.net/projects/baz/1.0/baz-1.0.tar.gz</uri>,
   5.125 +        from several versioned subpages, e.g. at
   5.126 +        <uri>http://example.net/projects/baz/1.0/</uri> and
   5.127 +        <uri>http://example.net/projects/baz/1.1/</uri>, which are linked from
   5.128 +        a common page under the URL
   5.129 +        <uri>http://example.net/projects/baz/</uri>:</para>
   5.130 +      <programlisting>
   5.131 +baz http://example.net/projects/baz/ /baz/[\d.]+/ /baz-([\d.]+)\.tar\.gz
   5.132 +      </programlisting>
   5.133 +    </example>
   5.134 +  </refsect1>
   5.135 +  <refsect1>
   5.136 +    <title>See Also</title>
   5.137 +    <para><citerefentry><refentrytitle>relmon</refentrytitle>
   5.138 +      <manvolnum>1</manvolnum></citerefentry>,
   5.139 +      <citerefentry><refentrytitle>regex</refentrytitle>
   5.140 +      <manvolnum>5</manvolnum></citerefentry>,
   5.141 +      <citerefentry><refentrytitle>re_syntax</refentrytitle>
   5.142 +      <manvolnum>n</manvolnum></citerefentry></para>
   5.143 +  </refsect1>
   5.144 +</refentry>