Mercurial > projects > relmon

comparison relmon_watchlist.4.xml @ 4:f28486666a4f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add manpages for relmon and relmon_watchlist
author Guido Berhoerster <guido+relmon@berhoerster.name>
date Fri, 24 Oct 2014 22:44:39 +0200
parents
children
comparison
equal deleted inserted replaced
3:6d87242c537e 4:f28486666a4f
1 <?xml version="1.0"?>
2 <!--
3
4 Copyright (C) 2014 Guido Berhoerster <guido+relmon@berhoerster.name>
5
6 Permission is hereby granted, free of charge, to any person obtaining
7 a copy of this software and associated documentation files (the
8 "Software"), to deal in the Software without restriction, including
9 without limitation the rights to use, copy, modify, merge, publish,
10 distribute, sublicense, and/or sell copies of the Software, and to
11 permit persons to whom the Software is furnished to do so, subject to
12 the following conditions:
13
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24
25 -->
26 <refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
27 <info>
28 <author>
29 <personname>
30 <firstname>Guido</firstname>
31 <surname>Berhoerster</surname>
32 </personname>
33 <email>guido+relmon@berhoerster.name</email>
34 <personblurb/>
35 </author>
36 <date>24 October, 2014</date>
37 </info>
38 <refmeta>
39 <refentrytitle>relmon_watchlist</refentrytitle>
40 <manvolnum>4</manvolnum>
41 <refmiscinfo class="source"/>
42 <refmiscinfo class="version"/>
43 <refmiscinfo class="manual">File Formats</refmiscinfo>
44 </refmeta>
45 <refnamediv>
46 <refname>relmon_watchlist</refname>
47 <refpurpose>watchlist for software projects monitored by
48 <citerefentry><refentrytitle>relmon</refentrytitle><manvolnum>1</manvolnum></citerefentry></refpurpose>
49 </refnamediv>
50 <refsynopsisdiv>
51 <para><replaceable>relmon_watchlist</replaceable></para>
52 </refsynopsisdiv>
53 <refsect1>
54 <title>Description</title>
55 <para>A <replaceable>relmon_watchlist</replaceable> consists of entries for
56 each monitored software projects which control how
57 <command>relmon</command> crawls websites and detects new
58 releases.</para>
59 <para>Each line is either an entry or a comment, lines containing only
60 whitespace are ignored. A comment starts with a leading
61 <literal>#</literal>.</para>
62 <para>An entry consists of three or more fields which are seperated by
63 whitespace. The first field contains the name of the project which must
64 be unique within the watchlist. The second field contains the base URL
65 which is used as the starting point for crawling and must be a valid URL.
66 Any fields between the second and the last but one field contain advanced
67 regular expressions as described in
68 <citerefentry><refentrytitle>re_syntax</refentrytitle>
69 <manvolnum>n</manvolnum></citerefentry> for matching the URLs of links
70 to follow. All patterns are implicitly anchored to the end of the
71 complete URL. The last field is the version-matching regular expression
72 which matches URLs of links to distribution files and must contain
73 exactly one reporting subexpression for extracting the version
74 number.</para>
75 <para>When updating the version information for a project
76 <command>relmon</command> starts with retrieving the document or feed
77 associated with the base URL. In case there are one or more fields before
78 the last version-matching field, relmon will retrieve all linked
79 documents or feeds whose URLs are matched by the regular expression
80 specified in the first field after the base URL. This process is then
81 repeated, that is documents or feeds linked from the documents or feeds
82 retrieved in the previous step are retrieved if the associated URLs match
83 the regular expression in the subsequent field and so on, until the last
84 version-matching field is reached. Finally, the version-matching regular
85 expression specified in the last field is used to match any URLs of
86 distribution files linked from the documents or feeds retrieved in the
87 previous step and the version numbers are extracted.</para>
88 </refsect1>
89 <refsect1>
90 <title>Examples</title>
91 <example>
92 <title>An entry for a project which publishes distribution
93 files on its homepage</title>
94 <para>The following example is an entry for a project named
95 <application class="software">foo</application> which has a homepage at
96 <uri>http://example.org/foo/</uri> with direct links to the distribution
97 files, e.g. at
98 <uri>http://example.org/foo/foo-1.0.tar.gz</uri>:</para>
99 <programlisting>
100 foo http://example.org/foo/ /foo/foo-([\d.]+)\.tar\.gz
101 </programlisting>
102 </example>
103 <example>
104 <title>An entry for a project which publishes distribution files of
105 new releases through an Atom feed</title>
106 <para>The following example is an entry for a project named
107 <application class="software">bar</application> which publishes an
108 Atom feed at <uri>https://example.com/news.xml</uri> which contains
109 links to the distribution files on another host, e.g. at
110 <uri>http://archive.example.com/bar-1.0.tar.gz</uri>:</para>
111 <programlisting>
112 bar https://example.com/news.xml /bar-([\d.]+)\.tar\.gz
113 </programlisting>
114 </example>
115 <example>
116 <title>An entry for a project which publishes distribution files on a
117 file hosting website on multiple subpages</title>
118 <para>The following example is an entry for a project named
119 <application class="software">baz</application> which links to the
120 actual the distribution files, e.g. at
121 <uri>http://example.net/projects/baz/1.0/baz-1.0.tar.gz</uri>,
122 from several versioned subpages, e.g. at
123 <uri>http://example.net/projects/baz/1.0/</uri> and
124 <uri>http://example.net/projects/baz/1.1/</uri>, which are linked from
125 a common page under the URL
126 <uri>http://example.net/projects/baz/</uri>:</para>
127 <programlisting>
128 baz http://example.net/projects/baz/ /baz/[\d.]+/ /baz-([\d.]+)\.tar\.gz
129 </programlisting>
130 </example>
131 </refsect1>
132 <refsect1>
133 <title>See Also</title>
134 <para><citerefentry><refentrytitle>relmon</refentrytitle>
135 <manvolnum>1</manvolnum></citerefentry>,
136 <citerefentry><refentrytitle>regex</refentrytitle>
137 <manvolnum>5</manvolnum></citerefentry>,
138 <citerefentry><refentrytitle>re_syntax</refentrytitle>
139 <manvolnum>n</manvolnum></citerefentry></para>
140 </refsect1>
141 </refentry>