INN commit: trunk (7 files)
INN Commit
Russ_Allbery at isc.org
Thu Aug 2 18:59:15 UTC 2007
Date: Thursday, August 2, 2007 @ 11:59:14
Author: iulius
Revision: 7627
Add new documentation for newsgroups(5).
Added:
trunk/doc/pod/newsgroups.pod
Modified:
trunk/MANIFEST
trunk/doc/man/ (properties)
trunk/doc/pod/Makefile
trunk/doc/pod/active.pod
trunk/doc/pod/active.times.pod
trunk/doc/pod/getlist.pod
--------------------------+
MANIFEST | 2
doc/pod/Makefile | 5 +
doc/pod/active.pod | 17 +++---
doc/pod/active.times.pod | 4 +
doc/pod/getlist.pod | 4 +
doc/pod/newsgroups.pod | 127 +++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 149 insertions(+), 10 deletions(-)
Modified: MANIFEST
===================================================================
--- MANIFEST 2007-08-02 15:01:21 UTC (rev 7626)
+++ MANIFEST 2007-08-02 18:59:14 UTC (rev 7627)
@@ -205,6 +205,7 @@
doc/man/news.daily.8 Manpage for news.daily
doc/man/news2mail.8 Manpage for news2mail
doc/man/newsfeeds.5 Manpage for newsfeeds config file
+doc/man/newsgroups.5 Manpage for newsgroups file
doc/man/newslog.5 Manpage for log files
doc/man/ninpaths.8 Manpage for ninpaths
doc/man/nnrpd.8 Manpage for nnrpd daemon
@@ -293,6 +294,7 @@
doc/pod/motd.news.pod Master file for motd.news.5
doc/pod/news.pod Master file for NEWS
doc/pod/newsfeeds.pod Master file for newsfeeds.5
+doc/pod/newsgroups.pod Master file for newsgroups.5
doc/pod/ninpaths.pod Master file for ninpaths.8
doc/pod/nnrpd.pod Master file for nnrpd.8
doc/pod/ovdb.pod Master file for ovdb.5
Property changes on: trunk/doc/man
___________________________________________________________________
Name: svn:ignore
- active.5
active.times.5
actsync.8
archive.8
auth_krb5.8
auth_smb.8
batcher.8
buffchan.8
buffindexed.conf.5
ckpasswd.8
control.ctl.5
convdate.1
ctlinnd.8
cycbuff.conf.5
distrib.pats.5
domain.8
expire.ctl.5
expireover.8
fastrm.1
getlist.1
grephistory.1
ident.8
inews.1
inn.conf.5
innbind.8
innconfval.1
innd.8
inndf.8
innmail.1
innupgrade.8
libauth.3
libinnhist.3
list.3
mailpost.8
makehistory.8
moderators.5
motd.news.5
newsfeeds.5
ninpaths.8
nnrpd.8
ovdb.5
ovdb_init.8
ovdb_monitor.8
ovdb_server.8
ovdb_stat.8
overchan.8
passwd.nntp.5
perl-nocem.8
pgpverify.1
pullnews.1
qio.3
radius.8
radius.conf.5
rc.news.8
readers.conf.5
rnews.1
sasl.conf.5
send-uucp.8
sendinpaths.8
simpleftp.1
sm.1
storage.conf.5
subscriptions.5
tdx-util.8
tinyleaf.8
tst.3
uwildmat.3
+ active.5
active.times.5
actsync.8
archive.8
auth_krb5.8
auth_smb.8
batcher.8
buffchan.8
buffindexed.conf.5
ckpasswd.8
control.ctl.5
convdate.1
ctlinnd.8
cycbuff.conf.5
distrib.pats.5
domain.8
expire.ctl.5
expireover.8
fastrm.1
getlist.1
grephistory.1
ident.8
inews.1
inn.conf.5
innbind.8
innconfval.1
innd.8
inndf.8
innmail.1
innupgrade.8
libauth.3
libinnhist.3
list.3
mailpost.8
makehistory.8
moderators.5
motd.news.5
newsfeeds.5
newsgroups.5
ninpaths.8
nnrpd.8
ovdb.5
ovdb_init.8
ovdb_monitor.8
ovdb_server.8
ovdb_stat.8
overchan.8
passwd.nntp.5
perl-nocem.8
pgpverify.1
pullnews.1
qio.3
radius.8
radius.conf.5
rc.news.8
readers.conf.5
rnews.1
sasl.conf.5
send-uucp.8
sendinpaths.8
simpleftp.1
sm.1
storage.conf.5
subscriptions.5
tdx-util.8
tinyleaf.8
tst.3
uwildmat.3
Modified: doc/pod/Makefile
===================================================================
--- doc/pod/Makefile 2007-08-02 15:01:21 UTC (rev 7626)
+++ doc/pod/Makefile 2007-08-02 18:59:14 UTC (rev 7627)
@@ -21,7 +21,7 @@
MAN5 = ../man/active.5 ../man/active.times.5 ../man/buffindexed.conf.5 \
../man/control.ctl.5 ../man/cycbuff.conf.5 ../man/distrib.pats.5 \
../man/expire.ctl.5 ../man/inn.conf.5 ../man/moderators.5 \
- ../man/motd.news.5 ../man/newsfeeds.5 ../man/ovdb.5 \
+ ../man/motd.news.5 ../man/newsfeeds.5 ../man/newsgroups.5 ../man/ovdb.5 \
../man/passwd.nntp.5 ../man/radius.conf.5 ../man/readers.conf.5 \
../man/storage.conf.5 ../man/subscriptions.5
@@ -84,11 +84,12 @@
../man/moderators.5: moderators.pod ; $(POD2MAN) -s 5 $? > $@
../man/motd.news.5: motd.news.pod ; $(POD2MAN) -s 5 $? > $@
../man/newsfeeds.5: newsfeeds.pod ; $(POD2MAN) -s 5 $? > $@
+../man/newsgroups.5: newsgroups.pod ; $(POD2MAN) -s 5 $? > $@
../man/ovdb.5: ovdb.pod ; $(POD2MAN) -s 5 $? > $@
../man/passwd.nntp.5: passwd.nntp.pod ; $(POD2MAN) -s 5 $? > $@
../man/radius.conf.5: radius.conf.pod ; $(POD2MAN) -s 5 $? > $@
../man/readers.conf.5: readers.conf.pod ; $(POD2MAN) -s 5 $? > $@
-../man/storage.conf.5: storage.conf.pod ; $(POD2MAN) -s 5 $? > $@
+../man/storage.conf.5: storage.conf.pod ; $(POD2MAN) -s 5 $? > $@
../man/subscriptions.5: subscriptions.pod ; $(POD2MAN) -s 5 $? > $@
../man/actsync.8: actsync.pod ; $(POD2MAN) -s 8 $? > $@
Modified: doc/pod/active.pod
===================================================================
--- doc/pod/active.pod 2007-08-02 15:01:21 UTC (rev 7626)
+++ doc/pod/active.pod 2007-08-02 18:59:14 UTC (rev 7627)
@@ -7,9 +7,12 @@
The file I<pathdb>/active lists the newsgroups carried by INN. This file
is generally maintained using ctlinnd(8) to create and remove groups, or
by letting controlchan(8) do so on the basis of received control messages;
-this file is then updated and a backup stored in I<pathdb>/active.old. The
-F<active> file should not be edited directly without throttling B<innd>, and
-must be reloaded using B<ctlinnd> before B<innd> is unthrottled. Editing
+this file is then updated and a backup stored in I<pathdb>/active.old. Note
+that the newsgroups(5) file normally contains the descriptions of the
+newsgroups carried by the news server.
+
+The F<active> file should not be edited directly without throttling B<innd>,
+and must be reloaded using B<ctlinnd> before B<innd> is unthrottled. Editing
it directly even with those precautions may make it inconsistent with the
overview database and won't update F<active.times>, so B<ctlinnd> should
be used to make modifications whenever possible.
@@ -105,7 +108,9 @@
To create additional groups after the server is running, you can use
C<ctlinnd newgroup>. You can also synchronize your newsgroup list to
-that of another server by using actsync(8).
+that of another server by using actsync(8) or get the F<active> file
+of another NNTP server with getlist(1). And do not forget to update
+your F<newsgroups> file.
=head1 HISTORY
@@ -116,7 +121,7 @@
=head1 SEE ALSO
-active.times(5), actsync(8), controlchan(8), ctlinnd(8), inn.conf(5),
-innd(8), news.daily(8), readers.conf(5).
+active.times(5), actsync(8), controlchan(8), ctlinnd(8), getlist(1),
+inn.conf(5), innd(8), news.daily(8), newsgroups(5), readers.conf(5).
=cut
Modified: doc/pod/active.times.pod
===================================================================
--- doc/pod/active.times.pod 2007-08-02 15:01:21 UTC (rev 7626)
+++ doc/pod/active.times.pod 2007-08-02 18:59:14 UTC (rev 7627)
@@ -21,6 +21,8 @@
the newsmaster specified at configure time if no creator argument was
given to B<ctlinnd> (by default, it is C<usenet>).
+You can get the F<active.times> file of another NNTP server with getlist(1).
+
=head1 EXAMPLE
The line:
@@ -45,6 +47,6 @@
=head1 SEE ALSO
-active(5), convdate(1), ctlinnd(8), inn.conf(5), innd(8), nnrpd(8).
+active(5), convdate(1), ctlinnd(8), getlist(1), inn.conf(5), innd(8), nnrpd(8).
=cut
Modified: doc/pod/getlist.pod
===================================================================
--- doc/pod/getlist.pod 2007-08-02 15:01:21 UTC (rev 7626)
+++ doc/pod/getlist.pod 2007-08-02 18:59:14 UTC (rev 7627)
@@ -77,8 +77,10 @@
Written by Landon Curt Noll <chongo at toad.com> for InterNetNews. Rewritten
in POD by Russ Allbery <rra at stanford.edu>.
+$Id$
+
=head1 SEE ALSO
-active(5), active.times(5), inn.conf(5), nnrpd(8), uwildmat(3)
+active(5), active.times(5), newsgroups(5), inn.conf(5), nnrpd(8), uwildmat(3).
=cut
Added: doc/pod/newsgroups.pod
===================================================================
--- doc/pod/newsgroups.pod (rev 0)
+++ doc/pod/newsgroups.pod 2007-08-02 18:59:14 UTC (rev 7627)
@@ -0,0 +1,127 @@
+=head1 NAME
+
+newsgroups - List of newsgroups and their short descriptions
+
+=head1 DESCRIPTION
+
+The file I<pathdb>/newsgroups contains a list of newsgroups for which
+a short description is available. This file is generally updated by
+controlchan(8) whenever a control message is received; it is used by
+B<nnrpd> in response to C<LIST NEWSGROUPS> and is only meant to provide
+information to users. News readers often show the list of carried
+newsgroups along with these descriptions.
+
+It is not necessary that all the groups carried by the news server
+(that is to say all the groups listed in the F<active> file) be listed
+in the F<newsgroups> file. And it is also not necessary that all the
+groups listed in the F<newsgroups> file be carried by the news server.
+Nonetheless, it is of course better if the F<active> and F<newsgroups>
+files have exactly the same newsgroups.
+
+If you use C<ctlinnd newgroup> to manually create a group, only the
+F<active> file is updated. You should then edit the F<newsgroups>
+file in order to add a short description for the created group. The
+same goes for manually removing or changing the status of a newsgroup.
+
+Each line of the F<newsgroups> file consists of two fields separated
+by at least one tabulation:
+
+ <name>\t<description>
+
+The first field is the name of the newsgroup. The second field is its
+description.
+
+You can get the F<newsgroups> file of another NNTP server with getlist(1).
+
+=head1 PREFERRED FORMAT FOR A ONE-LINE NEWSGROUP DESCRIPTION
+
+As far as the format of the F<newsgroups> file is concerned, there is a
+preferred format for each line. Since news administrators do not generally
+have the time to fix up the lines that are being automatically included
+from newgroup or checkgroups messages, this information is provided so
+that control message senders can craft better control messages. It will
+also be useful for news administrators to know how to format the
+description of their local newsgroups.
+
+There should be at least one hard tab (8 column tab stops) between the
+group name and the description. If the group name is at least 16 characters,
+it should be followed with one tab. If the group name is at least 8
+characters, it should be followed with two tabs. And in the unlikely event
+the group name is less than 8 characters, it should be followed with three
+tabs. For instance:
+
+ misc.transport.rail.europe Railroads & railways in all of Europe.
+ news.admin.nocem NoCeM protocol policy issues and information.
+ news.groups Discussions and lists of newsgroups.
+
+The total line length should be at most 79 columns. The description
+should start with a capital and not be more than 55 characters (79 - 24)
+long. If the group name is longer than 24 characters, the description
+should be correspondingly shorter. If the group is moderated, it should
+have C< (Moderated)> (note the space before the opening parenthesis)
+at the very end of the description, not counted as part of the length of
+the description. This text must be exactly that, with no variations,
+as it is used by news software to find moderated groups.
+
+Here is an example of moderated newsgroup:
+
+ news.lists.misc News-related statistics and lists. (Moderated)
+ news.admin.announce Announcements for news adminstrators. (Moderated)
+
+Traditionally, all newsgroup descriptions ended with a period, but this
+is not necessary and steals away one character that is occasionally
+useful for forming a better description.
+
+Some over-long descriptions could be made to easily fit the length by
+dropping useless wordings like C<Discussion of> which do not meaningfully
+contribute to the description. Others are usually pretty easy to get to
+no more than column eighty, except when the group names start getting
+really long. Hopefully then the group name itself contains quite a bit
+of description.
+
+In some cases, a longer description really will be necessary; they can
+of course be used within the F<newsgroups> file. However, they will
+probably be less readable and less useful for some Usenet users.
+
+Descriptions must not contain any control characters (octets between
+0x00 and 0x1F).
+
+=head1 ENCODING OF THE DESCRIPTIONS
+
+There is, at present, no good mechanism for managing the character set
+of the newsgroup descriptions. Many non-English hierarchies include
+newsgroup descriptions in their native languages, since this is more
+useful for their users, and those are included verbatim in the
+F<newsgroups> file. This unfortunately means that different lines of the
+file will require different character set settings to read properly, and
+those character sets are not documented in the file. Hopefully some
+future standard will provide a way to address this; in the meantime,
+using UTF-8 for non-ASCII characters is recommended.
+
+=head1 MINIMAL NEWSGROUPS FILE
+
+The minimal F<newsgroups> file shipped with INN is:
+
+ control Various control messages (no posting).
+ control.cancel Cancel messages (no posting).
+ control.checkgroups Hierarchy check control messages (no posting).
+ control.newgroup Newsgroup creation control messages (no posting).
+ control.rmgroup Newsgroup removal control messages (no posting).
+ junk Unfiled articles (no posting).
+
+=head1 HISTORY
+
+Written by Julien Elie <julien at trigofacile.com> for InterNetNews.
+The preferred format for a one-line newsgroup description is based on
+the policies by which the F<newsgroups> file in
+L<ftp://ftp.isc.org/pub/usenet/CONFIG/> is maintained; they were originally
+written by David Lawrence <tale at isc.org> and updated by Russ Allbery
+<rra at stanford.edu>.
+
+$Id$
+
+=head1 SEE ALSO
+
+active(5), controlchan(8), ctlinnd(8), getlist(1), nnrpd(8).
+
+=cut
Property changes on: trunk/doc/pod/newsgroups.pod
___________________________________________________________________
Name: svn:keywords
+ Author Date Id Revision
Name: svn:eol-style
+ native
More information about the inn-committers
mailing list