Mercurial > projects > relmon
changeset 4:f28486666a4f
Add manpages for relmon and relmon_watchlist
| author | Guido Berhoerster <guido+relmon@berhoerster.name> |
|---|---|
| date | Fri, 24 Oct 2014 22:44:39 +0200 |
| parents | 6d87242c537e |
| children | 86a0c5d11f05 |
| files | Makefile README docbook-update-source-data.xsl relmon.1.xml relmon_watchlist.4.xml |
| diffstat | 5 files changed, 683 insertions(+), 4 deletions(-) [+] |
line wrap: on
line diff
--- a/Makefile Mon Oct 20 19:31:20 2014 +0200 +++ b/Makefile Fri Oct 24 22:44:39 2014 +0200 @@ -31,32 +31,60 @@ PAX := pax GZIP := gzip SED := sed +XSLTPROC := xsltproc +DOCBOOK5_MANPAGES_STYLESHEET = http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl TCLSH_PATH := /usr/bin/tclsh +define generate-manpage-rule = +%.$(1): %.$(1).xml + $$(XSLTPROC) \ + --xinclude \ + --stringparam package $$(PACKAGE) \ + --stringparam version $$(VERSION)\ + docbook-update-source-data.xsl $$< | \ + $$(XSLTPROC) \ + --xinclude \ + $$(DOCBOOK5_MANPAGES_FLAGS) \ + --output $$@ \ + $$(DOCBOOK5_MANPAGES_STYLESHEET) \ + - +endef + DESTDIR ?= prefix ?= /usr/local bindir ?= $(prefix)/bin +datadir ?= $(prefix)/share +mandir ?= $(datadir)/man SCRIPTS = $(PACKAGE).tcl +MANPAGES = $(PACKAGE).1 $(PACKAGE)_watchlist.4 +DOCBOOK5_MANPAGES_FLAGS = --stringparam man.authors.section.enabled 0 \ + --stringparam man.copyright.section.enabled 0 .DEFAULT_TARGET = all .PHONY: all clean clobber dist install -all: $(PACKAGE) +all: $(PACKAGE) $(MANPAGES) $(PACKAGE): $(SCRIPTS) cp $< $@ +$(foreach section,1 2 3 4 5 6 7 8 9,$(eval $(call generate-manpage-rule,$(section)))) + %.tcl: %.tcl.in $(SED) -e '1s,#!.*,#!$(TCLSH_PATH),' -e 's,@VERSION@,$(VERSION),' $< \ > $@ install: $(INSTALL.exec) $(PACKAGE) "$(DESTDIR)$(bindir)/$(PACKAGE)" + for manpage in $(MANPAGES); do \ + $(INSTALL.data) $${manpage} \ + "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \ + done clean: - rm -f $(PACKAGE) $(SCRIPTS) + rm -f $(PACKAGE) $(SCRIPTS) $(MANPAGES) clobber: clean
--- a/README Mon Oct 20 19:31:20 2014 +0200 +++ b/README Fri Oct 24 22:44:39 2014 +0200 @@ -20,8 +20,9 @@ Requirements ------------ -relmon requires GNU make, GNU or BSD install, Tcl 8.5 or later, tcllib, tls, -and tdom. It has been tested on Linux distributions and FreeBSD. +relmon requires GNU make, GNU or BSD install, the xsltproc tool from libxml2, +Tcl 8.5 or later, tcllib, tls, and tdom. It has been tested on Linux +distributions and FreeBSD. License -------
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docbook-update-source-data.xsl Fri Oct 24 22:44:39 2014 +0200 @@ -0,0 +1,29 @@ +<?xml version="1.0"?> +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:db="http://docbook.org/ns/docbook" + xmlns="http://docbook.org/ns/docbook" + exclude-result-prefixes="xsl db"> + + <xsl:param name="package" select="''" /> + <xsl:param name="version" select="''" /> + + <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or + @class = 'version']"/> + + <xsl:template match="db:refmeta"> + <xsl:copy> + <xsl:apply-templates/> + <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo> + <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo> + </xsl:copy> + </xsl:template> + + <xsl:template match="@*|node()"> + <xsl:copy> + <xsl:apply-templates select="@*|node()"/> + </xsl:copy> + </xsl:template> + +</xsl:stylesheet>
--- /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>> 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>
--- /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>