.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DOCHECKGROUPS 8"
.TH DOCHECKGROUPS 8 "2022-07-10" "INN 2.7.2" "InterNetNews Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
docheckgroups \- Process checkgroups and output a list of changes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdocheckgroups\fR [\fB\-u\fR] [\fIinclude-pattern\fR [\fIexclude-pattern\fR]]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdocheckgroups\fR is usually run by \fBcontrolchan\fR in order to process
checkgroups control messages.  It reads a list of newsgroups along
with their descriptions on its standard input.  That list should
be formatted like the \fBnewsgroups\fR\|(5) file: each line contains the
name of a newsgroup followed by one or more tabulations and its
description.
.PP
\&\fBdocheckgroups\fR will only check the presence of newsgroups
which match \fIinclude-pattern\fR (an \fBegrep\fR expression like
\&\f(CW\*(C`^comp\e..*$\*(C'\fR for newsgroups starting with \f(CW\*(C`comp.\*(C'\fR) and which
do not match \fIexclude-pattern\fR (also an \fBegrep\fR expression)
except for newsgroups mentioned in the \fIpathetc\fR/localgroups file.
This file is also formatted like the \fBnewsgroups\fR\|(5) file and
should contain local newsgroups which would otherwise be mentioned
for removal.  There is no need to put local newsgroups of hierarchies
for which no checkgroups control messages are sent, unless
you manually process checkgroups texts for them.  Lines beginning
with a hash sign (\f(CW\*(C`#\*(C'\fR) are not taken into account in this file.
All the newsgroups and descriptions mentioned in \fIpathetc\fR/localgroups
are appended to the processed checkgroups.
.PP
If \fIexclude-pattern\fR is given, \fIinclude-pattern\fR should also
be given before (you can use an empty string ("") if you want
to include all the newsgroups).  Be that as it may, \fBdocheckgroups\fR
will only check newsgroups in the top-level hierarchies which are
present in the checkgroups.
.PP
Then, \fBdocheckgroups\fR checks the \fIactive\fR and \fInewsgroups\fR files
and displays on its standard output a list of changes, if any.  It
does not change anything by default; it only points out what should
be changed:
.IP "\(bu" 2
Newsgroups which should be removed (they are in the \fIactive\fR file
but not in the checkgroups) and the relevant \fBctlinnd\fR commands
to achieve that;
.IP "\(bu" 2
Newsgroups which should be added (they are not in the \fIactive\fR file
but in the checkgroups) and the relevant \fBctlinnd\fR commands
to achieve that;
.IP "\(bu" 2
Newsgroups which are incorrectly marked as moderated or unmoderated
(they are both in the \fIactive\fR file and the checkgroups but their
status differs) and the relevant \fBctlinnd\fR commands to fix that;
.IP "\(bu" 2
Descriptions which should be removed (they are in the \fInewsgroups\fR file
but not in the checkgroups);
.IP "\(bu" 2
Descriptions which should be added (they are not in the \fInewsgroups\fR file
but in the checkgroups).
.PP
The output of \fBdocheckgroups\fR can be fed into \fBmod-active\fR (it will
pause the news server, update the \fIactive\fR file accordingly, reload it
and resume the work of the news server) or into the shell (commands for
\&\fBctlinnd\fR will be processed one by one).  In order to update the
\&\fInewsgroups\fR file, the \fB\-u\fR flag must be given to \fBdocheckgroups\fR.
.PP
When processing a checkgroups manually, it is always advisable to first
check the raw output of \fBdocheckgroups\fR.  Then, if everything looks
fine, use \fBmod-active\fR and the \fB\-u\fR flag.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-u\fR" 4
.IX Item "-u"
If this flag is given, \fBdocheckgroups\fR will update the \fInewsgroups\fR file:
it removes obsolete descriptions and adds new ones.  It also sorts
this file alphabetically and improves its general format (see \fBnewsgroups\fR\|(5)
for an explanation of the preferred number of tabulations).
.SH "EXAMPLES"
.IX Header "EXAMPLES"
So as to better understand how \fBdocheckgroups\fR works, here are examples
with the following \fIactive\fR file:
.PP
.Vb 6
\&    a.first 0000000000 0000000001 y
\&    a.second.announce 0000000000 0000000001 y
\&    a.second.group 0000000000 0000000001 y
\&    b.additional 0000000000 0000000001 y
\&    b.third 0000000000 0000000001 y
\&    c.fourth 0000000000 0000000001 y
.Ve
.PP
the following \fInewsgroups\fR file (using tabulations):
.PP
.Vb 5
\&    a.first             First group.
\&    a.second.announce   Announce group.
\&    a.second.group      Second group.
\&    b.third             Third group.
\&    c.fourth            Fourth group.
.Ve
.PP
and the following \fIlocalgroups\fR file (using tabulations):
.PP
.Vb 1
\&    b.additional        A local newsgroup I want to keep.
.Ve
.PP
The checkgroups we process is in the file \fItest\fR which contains:
.PP
.Vb 5
\&    a.first             First group.
\&    a.second.announce   Announce group. (Moderated)
\&    a.second.group      Second group.
\&    b.third             Third group.
\&    c.fourth            Fourth group.
.Ve
.PP
If we run:
.PP
.Vb 1
\&    cat test | docheckgroups
.Ve
.PP
\&\fBdocheckgroups\fR will output that a.second.announce is incorrectly marked
as unmoderated and that its description is obsolete.  Besides, two
new descriptions will be mentioned for addition (the new one for
a.second.announce and the missing description for b.additional \-\-\ it
should indeed be in the \fInewsgroups\fR file and not only in \fIlocalgroups\fR).
Now that we have checked the output of \fBdocheckgroups\fR and that we agree
with the changes, we run it with the \fB\-u\fR flag to update the \fInewsgroups\fR
file and we redirect the standard output to \fBmod-active\fR to update the
\&\fIactive\fR file:
.PP
.Vb 1
\&    cat test | docheckgroups \-u | mod\-active
.Ve
.PP
That's all!
.PP
Now, suppose we run:
.PP
.Vb 1
\&    cat test | docheckgroups "^c\e..*$"
.Ve
.PP
Nothing is output (indeed, everything is fine for the c.* hierarchy).
It would have been similar if the \fItest\fR file had only contained
the checkgroups for the c.* hierarchy (\fBdocheckgroups\fR would not
have checked a.* and b.*, even if they had been in \fIinclude-pattern\fR).
.PP
In order to check both a.* and c.*, you can run:
.PP
.Vb 1
\&    cat test | docheckgroups "^a\e..*$|^c\e..*$"
.Ve
.PP
And if you want to check a.* but not a.second.*, you can run:
.PP
.Vb 1
\&    cat test | docheckgroups "^a\e..*$" "^a\e.second\e..*$"
.Ve
.PP
In our example, \fBdocheckgroups\fR will then mention a.second.announce and
a.second.group for removal since they are in the \fIactive\fR file (the
same goes for their descriptions).  Notwithstanding, if you do want to keep
a.second.announce, just add this group to \fIlocalgroups\fR and
\&\fBdocheckgroups\fR will no longer mention it for removal.
.SH "FILES"
.IX Header "FILES"
.IP "\fIpathbin\fR/docheckgroups" 4
.IX Item "pathbin/docheckgroups"
The Shell script itself used to process checkgroups.
.IP "\fIpathetc\fR/localgroups" 4
.IX Item "pathetc/localgroups"
The list of local newsgroups along with their descriptions.
.SH "HISTORY"
.IX Header "HISTORY"
Documentation written by Julien Elie for InterNetNews.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBactive\fR\|(5), \fBcontrolchan\fR\|(8), \fBctlinnd\fR\|(8), \fBmod\-active\fR\|(8), \fBnewsgroups\fR\|(5).