Description

# HG changeset patch # User Guido Berhoerster # Date 1414183479 -7200 # Node ID f28486666a4f209c5e6a48b62c803ff77f423d41 # Parent 6d87242c537e0803ab2297162fa249ca45e4eb41 Add manpages for relmon and relmon_watchlist diff -r 6d87242c537e -r f28486666a4f Makefile --- 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 diff -r 6d87242c537e -r f28486666a4f README --- 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 ------- diff -r 6d87242c537e -r f28486666a4f docbook-update-source-data.xsl --- /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 @@ + + + + + + + + + + + +

+ + + + + + + + + + diff -r 6d87242c537e -r f28486666a4f relmon.1.xml --- /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 @@ + + + + + + + Guido + Berhoerster + + guido+relmon@berhoerster.name + + + 24 October, 2014 + + + relmon + 1 + + + User Commands + + + relmon + monitor websites of software projects for releases + + + + relmon list + + + + + + + html + parseable + text + + + + + url + + + + number_items + + + statefile + + + + relmon list + + + atom + + + + url + + + + number_items + + + statefile + + + + relmon show + + statefile + + + name + + + + relmon update + + + + + + + + + + + + max_connections + + + + ca_dir + + + + delay + + + + max_host_connections + + + item + , + + + + logfile + + + + retries + + + + min_time + + + watchlist + + + statefile + + + + relmon help + + subcommand + + + + + Description + relmon 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. + 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 + relmon_watchlist + 4 for the exact format of + watchlist entries and further details on the operation of + relmon. 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. relmon + 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. + 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. + + + Subcommands + + relmon has the following subcommands: + + + list + + + 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 + + The following options are supported: + + + + format + + + Emit output in the specified format. Possible values for + format 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. + + + + + + + url + + + 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. + + + + + + + + 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. + + + + + + number_items + + + If used in combination with the + option or if the atom ouput format was selected, limit the + output to the specified number of recent history + entries. + + + + + + + + show + + + The show 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. + + + + + update + + + The update 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 ~ suffix added to it. + The following options are supported: + + + + + + + Trace and log all transfers and parsing. This option is + used for debugging purposes. + + + + + + + + Only update version information for projects from the + watchlist which were not successfully updated during the last + update due to errors. + + + + + + + + Increase logging verbosity and log information about each + transfer. + + + + + + max_connections + + + Limit the number of simultaneous connections to the + specified number. The default value is 16. + + + + + + ca_dir + + + Verify the validity of TLS certificates using the CA + certificates in the specified directory. + + + + + + delay + + + Wait at least the specified number of seconds before + making subsequent connections to the same host. The default + value is 0. + + + + + + max_host_connections + + + Limit the number of simultaneous connections to a single + host to the specified number. The default value is 4. + + + + + + items + + + Update only the specified items. Multiple items can be + specifed in the form of a comma-sperated list. + + + + + + logfile + + + Log to the specified logfile instead of stderr. + + + + + + retries + + + Limit the number of retries in case of connection + failures. The default value is 3. + + + + + + min_time + + + Only update version information for projects from the + watchlist which have not been updated for the specified + number of seconds. + + + + + + + + help + + + The help subcommand displays usage + information about the specified subcommand or all subcommands and + exits. + + + + + + Examples + + Updating version information + The following command retrieves the version information for the + entries in the watchlist foo.watchlist and stores + the results in the statefile foo.json using using + up to 100 simultaneous connections and logging all output to + relmon.log: + +$ relmon update -c 100 foo.watchlist foo.json + + + + Conditionally updating version information + The following command updates version information in the statefile + bar.json only for those entries in the watchlist + foo.watchlist 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: + +$ relmon update -v -t 172800 -e -l relmon.log watchlist relmon.json + + + + Displaying detailed information on a monitored project + The following command displays all recorded information for the + monitored project named foo from the statefile + foo.json: + +$ relmon show foo.json baz + + + + Creating a HTML document with the version information on each + of the monitored projects + 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 + http://example.net/releases.xml containing the 100 most + recently discovered releases from the statefile + foo.json: + +$ 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 + + + + + Exit Status + The following exit values are returned: + + + 0 + + Command successfully executed. + + + + > 0 + + An error has occured. + + + + + + See Also + relmon_format + 4 + + diff -r 6d87242c537e -r f28486666a4f relmon_watchlist.4.xml --- /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 @@ + + + + + + + Guido + Berhoerster + + guido+relmon@berhoerster.name + + + 24 October, 2014 + + + relmon_watchlist + 4 + + + File Formats + + + relmon_watchlist + watchlist for software projects monitored by + relmon1 + + + relmon_watchlist + + + Description + A relmon_watchlist consists of entries for + each monitored software projects which control how + relmon crawls websites and detects new + releases. + Each line is either an entry or a comment, lines containing only + whitespace are ignored. A comment starts with a leading + #. + 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 + re_syntax + n 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. + When updating the version information for a project + relmon 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. + + + Examples + + An entry for a project which publishes distribution + files on its homepage + The following example is an entry for a project named + foo which has a homepage at + http://example.org/foo/ with direct links to the distribution + files, e.g. at + http://example.org/foo/foo-1.0.tar.gz: + +foo http://example.org/foo/ /foo/foo-([\d.]+)\.tar\.gz + + + + An entry for a project which publishes distribution files of + new releases through an Atom feed + The following example is an entry for a project named + bar which publishes an + Atom feed at https://example.com/news.xml which contains + links to the distribution files on another host, e.g. at + http://archive.example.com/bar-1.0.tar.gz: + +bar https://example.com/news.xml /bar-([\d.]+)\.tar\.gz + + + + An entry for a project which publishes distribution files on a + file hosting website on multiple subpages + The following example is an entry for a project named + baz which links to the + actual the distribution files, e.g. at + http://example.net/projects/baz/1.0/baz-1.0.tar.gz, + from several versioned subpages, e.g. at + http://example.net/projects/baz/1.0/ and + http://example.net/projects/baz/1.1/, which are linked from + a common page under the URL + http://example.net/projects/baz/: + +baz http://example.net/projects/baz/ /baz/[\d.]+/ /baz-([\d.]+)\.tar\.gz + + + + + See Also + relmon + 1, + regex + 5, + re_syntax + n + +