1=head1 NAME
2
3docheckgroups - Process checkgroups and output a list of changes
4
5=head1 SYNOPSIS
6
7B<docheckgroups> [B<-u>] [I<include-pattern> [I<exclude-pattern>]]
8
9=head1 DESCRIPTION
10
11B<docheckgroups> is usually run by B<controlchan> in order to process
12checkgroups control messages.  It reads a list of newsgroups along
13with their descriptions on its standard input.  That list should
14be formatted like the newsgroups(5) file: each line contains the
15name of a newsgroup followed by one or more tabulations and its
16description.
17
18B<docheckgroups> will only check the presence of newsgroups
19which match I<include-pattern> (an B<egrep> expression like
20C<^comp\..*$> for newsgroups starting with C<comp.>) and which
21do not match I<exclude-pattern> (also an B<egrep> expression)
22except for newsgroups mentioned in the I<pathetc>/localgroups file.
23This file is also formatted like the newsgroups(5) file and
24should contain local newsgroups which would otherwise be mentioned
25for removal.  There is no need to put local newsgroups of hierarchies
26for which no checkgroups control messages are sent, unless
27you manually process checkgroups texts for them.  Lines beginning
28with a hash sign (C<#>) are not taken into account in this file.
29All the newsgroups and descriptions mentioned in I<pathetc>/localgroups
30are appended to the processed checkgroups.
31
32If I<exclude-pattern> is given, I<include-pattern> should also
33be given before (you can use an empty string ("") if you want
34to include all the newsgroups).  Be that as it may, B<docheckgroups>
35will only check newsgroups in the top-level hierarchies which are
36present in the checkgroups.
37
38Then, B<docheckgroups> checks the F<active> and F<newsgroups> files
39and displays on its standard output a list of changes, if any.  It
40does not change anything by default; it only points out what should
41be changed:
42
43=over 2
44
45=item *
46
47Newsgroups which should be removed (they are in the F<active> file
48but not in the checkgroups) and the relevant B<ctlinnd> commands
49to achieve that;
50
51=item *
52
53Newsgroups which should be added (they are not in the F<active> file
54but in the checkgroups) and the relevant B<ctlinnd> commands
55to achieve that;
56
57=item *
58
59Newsgroups which are incorrectly marked as moderated or unmoderated
60(they are both in the F<active> file and the checkgroups but their
61status differs) and the relevant B<ctlinnd> commands to fix that;
62
63=item *
64
65Descriptions which should be removed (they are in the F<newsgroups> file
66but not in the checkgroups);
67
68=item *
69
70Descriptions which should be added (they are not in the F<newsgroups> file
71but in the checkgroups).
72
73=back
74
75The output of B<docheckgroups> can be fed into B<mod-active> (it will
76pause the news server, update the F<active> file accordingly, reload it
77and resume the work of the news server) or into the shell (commands for
78B<ctlinnd> will be processed one by one).  In order to update the
79F<newsgroups> file, the B<-u> flag must be given to B<docheckgroups>.
80
81When processing a checkgroups manually, it is always advisable to first
82check the raw output of B<docheckgroups>.  Then, if everything looks
83fine, use B<mod-active> and the B<-u> flag.
84
85=head1 OPTIONS
86
87=over 4
88
89=item B<-u>
90
91If this flag is given, B<docheckgroups> will update the F<newsgroups> file:
92it removes obsolete descriptions and adds new ones.  It also sorts
93this file alphabetically and improves its general format (see newsgroups(5)
94for an explanation of the preferred number of tabulations).
95
96=back
97
98=head1 EXAMPLES
99
100So as to better understand how B<docheckgroups> works, here are examples
101with the following F<active> file:
102
103    a.first 0000000000 0000000001 y
104    a.second.announce 0000000000 0000000001 y
105    a.second.group 0000000000 0000000001 y
106    b.additional 0000000000 0000000001 y
107    b.third 0000000000 0000000001 y
108    c.fourth 0000000000 0000000001 y
109
110the following F<newsgroups> file (using tabulations):
111
112    a.first		First group.
113    a.second.announce	Announce group.
114    a.second.group	Second group.
115    b.third		Third group.
116    c.fourth		Fourth group.
117
118and the following F<localgroups> file (using tabulations):
119
120    b.additional	A local newsgroup I want to keep.
121
122The checkgroups we process is in the file F<test> which contains:
123
124    a.first		First group.
125    a.second.announce	Announce group. (Moderated)
126    a.second.group	Second group.
127    b.third		Third group.
128    c.fourth		Fourth group.
129
130If we run:
131
132    cat test | docheckgroups
133
134B<docheckgroups> will output that a.second.announce is incorrectly marked
135as unmoderated and that its description is obsolete.  Besides, two
136new descriptions will be mentioned for addition (the new one for
137a.second.announce and the missing description for b.additional S<-- it>
138should indeed be in the F<newsgroups> file and not only in F<localgroups>).
139Now that we have checked the output of B<docheckgroups> and that we agree
140with the changes, we run it with the B<-u> flag to update the F<newsgroups>
141file and we redirect the standard output to B<mod-active> to update the
142F<active> file:
143
144    cat test | docheckgroups -u | mod-active
145
146That's all!
147
148Now, suppose we run:
149
150    cat test | docheckgroups "^c\..*$"
151
152Nothing is output (indeed, everything is fine for the c.* hierarchy).
153It would have been similar if the F<test> file had only contained
154the checkgroups for the c.* hierarchy (B<docheckgroups> would not
155have checked a.* and b.*, even if they had been in I<include-pattern>).
156
157In order to check both a.* and c.*, you can run:
158
159    cat test | docheckgroups "^a\..*$|^c\..*$"
160
161And if you want to check a.* but not a.second.*, you can run:
162
163    cat test | docheckgroups "^a\..*$" "^a\.second\..*$"
164
165In our example, B<docheckgroups> will then mention a.second.announce and
166a.second.group for removal since they are in the F<active> file (the
167same goes for their descriptions).  Notwithstanding, if you do want to keep
168a.second.announce, just add this group to F<localgroups> and
169B<docheckgroups> will no longer mention it for removal.
170
171=head1 FILES
172
173=over 4
174
175=item I<pathbin>/docheckgroups
176
177The Shell script itself used to process checkgroups.
178
179=item I<pathetc>/localgroups
180
181The list of local newsgroups along with their descriptions.
182
183=back
184
185=head1 HISTORY
186
187Documentation written by Julien Elie for InterNetNews.
188
189=head1 SEE ALSO
190
191active(5), controlchan(8), ctlinnd(8), mod-active(8), newsgroups(5).
192
193=cut
194