Add "Program" to .yapfaqrc.
[usenet/yapfaq.git] / yapfaq.pl
CommitLineData
dc88d139
TH
1#! /usr/bin/perl -W
2#
ace701c4 3# yapfaq Version 0.7 by Thomas Hochstein
7aaba0e0 4# (Original author: Marc Brockschmidt)
dc88d139 5#
7aaba0e0 6# This script posts any project described in its config-file. Most people
dc88d139
TH
7# will use it in combination with cron(8).
8#
9# Copyright (C) 2003 Marc Brockschmidt <marc@marcbrockschmidt.de>
7aaba0e0 10# Copyright (c) 2010 Thomas Hochstein <thh@inter.net>
dc88d139
TH
11#
12# It can be redistributed and/or modified under the same terms under
13# which Perl itself is published.
14
647af2ea 15my $Version = "0.8-prelease";
dc88d139 16
605916ef
TH
17# Please do not change this setting!
18# You may override the default .rc file (.yapfaqrc) by using "-c .rc file"
d60c2d5f 19my $RCFile = '.yapfaqrc';
605916ef 20# Valid configuration variables for use in a .rc file
39cb5672 21my @ValidConfVars = ('NNTPServer','NNTPUser','NNTPPass','Sender','ConfigFile','Program');
d60c2d5f 22
605916ef
TH
23################################### Defaults ###################################
24# Please do not change anything in here!
25# Use a runtime configuration file (.yapfaqrc by default) to override defaults.
7ef63844 26my %Config = (NNTPServer => "",
2507947f
TH
27 NNTPUser => "",
28 NNTPPass => "",
29 Sender => "",
39cb5672
TH
30 ConfigFile => "yapfaq.cfg",
31 Program => "");
dc88d139 32
605916ef 33################################# Main program #################################
dc88d139
TH
34
35use strict;
36use Net::NNTP;
40847f71 37use Net::Domain qw(hostfqdn);
dc88d139
TH
38use Date::Calc qw(Add_Delta_YM Add_Delta_Days Delta_Days Today);
39use Fcntl ':flock'; # import LOCK_* constants
4251e545 40use Getopt::Std;
dc88d139
TH
41my ($TDY, $TDM, $TDD) = Today(); #TD: Today's date
42
b9550622 43# read commandline options
4251e545 44my %Options;
86c0a100 45getopts('Vhvpdt:f:c:s:', \%Options);
b9550622 46# -V: print version / copyright information
a052296f
TH
47if ($Options{'V'}) {
48 print "$0 v $Version\nCopyright (c) 2003 Marc Brockschmidt <marc\@marcbrockschmidt.de>\nCopyright (c) 2010 Thomas Hochstein <thh\@inter.net>\n";
49 print "This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.\n";
50 exit(0);
51}
b9550622 52# -h: feed myself to perldoc
4251e545 53if ($Options{'h'}) {
ae3b1b79 54 exec ('perldoc', $0);
4251e545
TH
55 exit(0);
56};
b9550622 57# -f: set $Faq
4251e545
TH
58my ($Faq) = $Options{'f'} if ($Options{'f'});
59
d60c2d5f 60# read runtime configuration (configuration variables)
86c0a100
TH
61$RCFile = $Options{'c'} if ($Options{'c'});
62if (-f $RCFile) {
63 readrc (\$RCFile,\%Config);
64} else {
65 warn "$0: W: .rc file $RCFile does not exist!\n";
66}
d60c2d5f 67
39cb5672
TH
68$Options{'s'} = $Config{'Program'} if (!defined($Options{'s'}));
69
b9550622 70# read configuration (configured FAQs)
dc88d139 71my @Config;
2507947f 72readconfig (\$Config{'ConfigFile'}, \@Config, \$Faq);
dc88d139 73
b9550622
TH
74# for each FAQ:
75# - parse configuration
76# - read status data
77# - if FAQ is due: call postfaq()
dc88d139
TH
78foreach (@Config) {
79 my ($LPD,$LPM,$LPY) = (01, 01, 0001); #LP: Last posting-date
80 my ($NPY,$NPM,$NPD); #NP: Next posting-date
81 my $SupersedeMID;
82
0c6ebe78 83 my ($ActName,$File,$PFreq,$Expire) =($$_{'name'},$$_{'file'},$$_{'posting-frequency'},$$_{'expires'});
dc88d139
TH
84 my ($From,$Subject,$NG,$Fup2)=($$_{'from'},$$_{'subject'},$$_{'ngs'},$$_{'fup2'});
85 my ($MIDF,$ReplyTo,$ExtHea)=($$_{'mid-format'},$$_{'reply-to'},$$_{'extraheader'});
86 my ($Supersede) =($$_{'supersede'});
4251e545 87
b9550622 88 # -f: loop if not FAQ to post
4251e545
TH
89 next if (defined($Faq) && $ActName ne $Faq);
90
b9550622 91 # read status data
dc88d139
TH
92 if (open (FH, "<$File.cfg")) {
93 while(<FH>){
94 if (/##;; Lastpost:\s*(\d{1,2})\.(\d{1,2})\.(\d{2}(\d{2})?)/){
95 ($LPD, $LPM, $LPY) = ($1, $2, $3);
96 } elsif (/^##;;\s*LastMID:\s*(<\S+@\S+>)\s*$/) {
97 $SupersedeMID = $1;
98 }
99 }
100 close FH;
101 } else {
74407146 102 warn "$0: W: Couldn't open $File.cfg: $!\n";
dc88d139
TH
103 }
104
105 $SupersedeMID = "" unless $Supersede;
106
0c6ebe78
TH
107 ($NPY,$NPM,$NPD) = calcdelta ($LPY,$LPM,$LPD,$PFreq);
108
b9550622 109 # if FAQ is due: get it out
4251e545
TH
110 if (Delta_Days($NPY,$NPM,$NPD,$TDY,$TDM,$TDD) >= 0 or ($Options{'p'})) {
111 if($Options{'d'}) {
112 print "$ActName: Would be posted now (but running in simulation mode [$0 -d]).\n" if $Options{'v'};
113 } else {
2507947f 114 postfaq(\$ActName,\$File,\$From,\$Subject,\$NG,\$Fup2,\$MIDF,\$ExtHea,\$Config{'Sender'},\$TDY,\$TDM,\$TDD,\$ReplyTo,\$SupersedeMID,\$Expire);
4251e545
TH
115 }
116 } elsif($Options{'v'}) {
117 print "$ActName: Nothing to do.\n";
dc88d139
TH
118 }
119}
120
121exit;
122
d60c2d5f
TH
123#################################### readrc ####################################
124# Takes a filename and the reference to an array which contains the valid options
125
126sub readrc{
127 my ($File, $Config) = @_;
128
129 print "Reading $$File.\n" if($Options{'v'});
130
131 open FH, "<$$File" or die "$0: Can't open $$File: $!";
132 while (<FH>) {
133 if (/^\s*(\S+)\s*=\s*'?(.*?)'?\s*(#.*$|$)/) {
134 if (grep(/$1/,@ValidConfVars)) {
135 $$Config{$1} = $2 if $2 ne '';
136 } else {
137 warn "$0: W: $1 is not a valid configuration variable (reading from $$File)\n";
138 }
139 }
140 }
141}
142
dc88d139 143################################## readconfig ##################################
4251e545
TH
144# Takes a filename, a reference to an array, which will hold hashes with
145# the data from $File, and - optionally - the name of the (single) FAQ to post
dc88d139
TH
146
147sub readconfig{
4251e545 148 my ($File, $Config, $Faq) = @_;
dc88d139
TH
149 my ($LastEntry, $Error, $i) = ('','',0);
150
b802358a 151 print "Reading configuration from $$File.\n" if($Options{'v'});
4251e545 152
74407146 153 open FH, "<$$File" or die "$0: E: Can't open $$File: $!";
dc88d139 154 while (<FH>) {
4251e545 155 next if (defined($$Faq) && !/^\s*=====\s*$/ && defined($$Config[$i]{'name'}) && $$Config[$i]{'name'} ne $$Faq );
dc88d139
TH
156 if (/^(\s*(\S+)\s*=\s*'?(.*?)'?\s*(#.*$|$)|^(.*?)'?\s*(#.*$|$))/ && not /^\s*$/) {
157 $LastEntry = lc($2) if $2;
158 $$Config[$i]{$LastEntry} .= $3 if $3;
159 $$Config[$i]{$LastEntry} .= "\n$5" if $5 && $5;
160 }
161 if (/^\s*=====\s*$/) {
162 $i++;
163 }
164 }
165 close FH;
166
167 #Check saved values:
168 for $i (0..$i){
4251e545 169 next if (defined($$Faq) && defined($$Config[$i]{'name'}) && $$Config[$i]{'name'} ne $$Faq );
dbca4ad8
TH
170 unless(defined($$Config[$i]{'name'}) && $$Config[$i]{'name'} =~ /^\S+$/) {
171 $Error .= "E: The name of your project \"$$Config[$i]{'name'}\" is not defined or contains whitespaces.\n"
dc88d139 172 }
dbca4ad8
TH
173 unless(defined($$Config[$i]{'file'}) && -f $$Config[$i]{'file'}) {
174 $Error .= "E: The file to post for your project \"$$Config[$i]{'name'}\" is not defined or does not exist.\n"
175 }
176 unless(defined($$Config[$i]{'from'}) && $$Config[$i]{'from'} =~ /\S+\@(\S+\.)?\S{2,}\.\S{2,}/) {
177 $Error .= "E: The From header for your project \"$$Config[$i]{'name'}\" seems to be incorrect.\n"
178 }
179 unless(defined($$Config[$i]{'ngs'}) && $$Config[$i]{'ngs'} =~ /^\S+$/) {
180 $Error .= "E: The Newsgroups header for your project \"$$Config[$i]{'name'}\" is not defined or contains whitespaces.\n"
181 }
182 unless(defined($$Config[$i]{'subject'})) {
183 $Error .= "E: The Subject header for your project \"$$Config[$i]{'name'}\" is not defined.\n"
dc88d139
TH
184 }
185 unless(!$$Config[$i]{'fup2'} || $$Config[$i]{'fup2'} =~ /^\S+$/) {
dbca4ad8 186 $Error .= "E: The Followup-To header for your project \"$$Config[$i]{'name'}\" contains whitespaces.\n"
dc88d139 187 }
dbca4ad8 188 unless(defined($$Config[$i]{'posting-frequency'}) && $$Config[$i]{'posting-frequency'} =~ /^\s*\d+\s*[dwmy]\s*$/) {
74407146 189 $Error .= "E: The Posting-frequency for your project \"$$Config[$i]{'name'}\" is invalid.\n"
dc88d139 190 }
5ddba442 191 unless(!$$Config[$i]{'expires'} || $$Config[$i]{'expires'} =~ /^\s*\d+\s*[dwmy]\s*$/) {
ac69c3ee
TH
192 warn "$0: W: The Expires for your project \"$$Config[$i]{'name'}\" is invalid - set to 3 month.\n";
193 $$Config[$i]{'expires'} = '3m'; # set default (3 month) if expires is unset or invalid
0c6ebe78 194 }
8f067a2f 195 unless(!$$Config[$i]{'mid-format'} || $$Config[$i]{'mid-format'} =~ /^<\S+\@(\S+\.)?\S{2,}\.\S{2,}>/) {
ac69c3ee
TH
196 warn "$0: W: The Message-ID format for your project \"$$Config[$i]{'name'}\" seems to be invalid - set to default.\n";
197 $$Config[$i]{'mid-format'} = '<%n-%d.%m.%y@'.hostfqdn.'>'; # set default if mid-format is invalid
40847f71 198 }
dc88d139 199 }
dbca4ad8 200 $Error .= "-" x 25 . 'program terminated' . "-" x 25 . "\n" if $Error;
dc88d139
TH
201 die $Error if $Error;
202}
203
0c6ebe78
TH
204################################# calcdelta #################################
205# Takes a date (year, month and day) and a time period (1d, 1w, 1m, 1y, ...)
206# and adds the latter to the former
207
208sub calcdelta {
209 my ($Year, $Month, $Day, $Period) = @_;
210 my ($NYear, $NMonth, $NDay);
211
212 if ($Period =~ /(\d+)\s*([dw])/) { # Is counted in days or weeks: Use Add_Delta_Days.
213 ($NYear, $NMonth, $NDay) = Add_Delta_Days($Year, $Month, $Day, (($2 eq "w")?$1 * 7: $1 * 1));
214 } elsif ($Period =~ /(\d+)\s*([my])/) { #Is counted in months or years: Use Add_Delta_YM
215 ($NYear, $NMonth, $NDay) = Add_Delta_YM($Year, $Month, $Day, (($2 eq "m")?(0,$1):($1,0)));
216 }
217 return ($NYear, $NMonth, $NDay);
218}
5a6670c7
TH
219
220################################ updatestatus ###############################
221# Takes a MID and a status file name
222# and writes status information to disk
223
224sub updatestatus {
225 my ($ActName, $File, $date, $MID) = @_;
226
227 print "$$ActName: Save status information.\n" if($Options{'v'});
228
229 open (FH, ">$$File.cfg") or die "$0: E: Can't open $$File.cfg: $!";
230 print FH "##;; Lastpost: $date\n";
231 print FH "##;; LastMID: $MID\n";
232 close FH;
233}
0c6ebe78 234
dc88d139
TH
235################################## postfaq ##################################
236# Takes a filename and many other vars.
237#
238# It reads the data-file $File and then posts the article.
239
240sub postfaq {
0c6ebe78 241 my ($ActName,$File,$From,$Subject,$NG,$Fup2,$MIDF,$ExtraHeaders,$Sender,$TDY,$TDM,$TDD,$ReplyTo,$Supersedes,$Expire) = @_;
dc88d139
TH
242 my (@Header,@Body,$MID,$InRealBody,$LastModified);
243
366322b2 244 print "$$ActName: Preparing to post.\n" if($Options{'v'});
4251e545 245
dc88d139
TH
246 #Prepare MID:
247 $$TDM = ($$TDM < 10 && $$TDM !~ /^0/) ? "0" . $$TDM : $$TDM;
248 $$TDD = ($$TDD < 10 && $$TDD !~ /^0/) ? "0" . $$TDD : $$TDD;
13ce8c26 249 my $Timestamp = time;
dc88d139
TH
250
251 $MID = $$MIDF;
ac69c3ee 252 $MID = '<%n-%d.%m.%y@'.hostfqdn.'>' if !defined($MID); # set to default if unset
dc88d139
TH
253 $MID =~ s/\%n/$$ActName/g;
254 $MID =~ s/\%d/$$TDD/g;
255 $MID =~ s/\%m/$$TDM/g;
256 $MID =~ s/\%y/$$TDY/g;
13ce8c26 257 $MID =~ s/\%t/$Timestamp/g;
dc88d139 258
dc88d139
TH
259 #Now get the body:
260 open (FH, "<$$File");
261 while (<FH>){
262 s/\r//;
263 push (@Body, $_), next if $InRealBody;
264 $InRealBody++ if /^$/;
8e1cb154 265 $LastModified = $1 if /^Last-modified: (\S+)$/i;
dc88d139
TH
266 push @Body, $_;
267 }
268 close FH;
269 push @Body, "\n" if ($Body[-1] ne "\n");
270
271 #Create Date- and Expires-Header:
272 my @time = localtime;
273 my $ss = ($time[0]<10) ? "0" . $time[0] : $time[0];
274 my $mm = ($time[1]<10) ? "0" . $time[1] : $time[1];
275 my $hh = ($time[2]<10) ? "0" . $time[2] : $time[2];
276 my $day = $time[3];
277 my $month = ($time[4]+1<10) ? "0" . ($time[4]+1) : $time[4]+1;
278 my $monthN = ("Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec")[$time[4]];
279 my $wday = ("Sun","Mon","Tue","Wed","Thu","Fri","Sat")[$time[6]];
280 my $year = (1900 + $time[5]);
281 my $tz = $time[8] ? " +0200" : " +0100";
7823ece9
TH
282
283 $$Expire = '3m' if !$$Expire; # set default if unset: 3 month
284
0c6ebe78 285 my ($expY,$expM,$expD) = calcdelta ($year,$month,$day,$$Expire);
dc88d139
TH
286 my $expmonthN = ("Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec")[$expM-1];
287
288 my $date = "$day $monthN $year " . $hh . ":" . $mm . ":" . $ss . $tz;
289 my $expdate = "$expD $expmonthN $expY $hh:$mm:$ss$tz";
0c6ebe78 290
dc88d139
TH
291 #Replace %LM by the content of the news.answer-pseudo-header Last-modified:
292 if ($LastModified) {
293 $$Subject =~ s/\%LM/$LastModified/;
294 }
295
4251e545
TH
296 # Test mode?
297 if($Options{'t'} and $Options{'t'} !~ /console/i) {
298 $$NG = $Options{'t'};
299 }
300
dc88d139
TH
301 #Now create the complete Header:
302 push @Header, "From: $$From\n";
303 push @Header, "Newsgroups: $$NG\n";
304 push @Header, "Followup-To: $$Fup2\n" if $$Fup2;
305 push @Header, "Subject: $$Subject\n";
306 push @Header, "Message-ID: $MID\n";
307 push @Header, "Supersedes: $$Supersedes\n" if $$Supersedes;
308 push @Header, "Date: $date\n";
309 push @Header, "Expires: $expdate\n";
310 push @Header, "Sender: $$Sender\n" if $$Sender;
311 push @Header, "Mime-Version: 1.0\n";
312 push @Header, "Reply-To: $$ReplyTo\n" if $$ReplyTo;
313 push @Header, "Content-Type: text/plain; charset=ISO-8859-15\n";
314 push @Header, "Content-Transfer-Encoding: 8bit\n";
315 push @Header, "User-Agent: yapfaq/$Version\n";
316 if ($$ExtraHeaders) {
317 push @Header, "$_\n" for (split /\n/, $$ExtraHeaders);
318 }
319
0e741504
TH
320 my @Article = (@Header, "\n", @Body);
321
b9550622 322 # post article
366322b2 323 print "$$ActName: Posting article ...\n" if($Options{'v'});
5a6670c7
TH
324 my $failure = post(\@Article);
325
326 if ($failure) {
327 print "$$ActName: Posting failed, ERROR.dat may have more information.\n" if($Options{'v'} && (!defined($Options{'t'}) || $Options{'t'} !~ /console/i));
328 } else {
329 updatestatus($ActName, $File, "$day.$month.$year", $MID) if !defined($Options{'t'});
330 }
dc88d139
TH
331}
332
333################################## post ##################################
334# Takes a complete article (Header and Body).
335#
336# It opens a connection to $NNTPServer and posts the message.
337
338sub post {
339 my ($ArticleR) = @_;
5a6670c7 340 my ($failure) = -1;
dc88d139 341
5a6670c7 342 # test mode - print article to console
4251e545 343 if(defined($Options{'t'}) and $Options{'t'} =~ /console/i) {
55bfbd3c 344 print "-----BEGIN--------------------------------------------------\n";
5a6670c7 345 print @$ArticleR;
55bfbd3c 346 print "------END---------------------------------------------------\n";
5a6670c7
TH
347 # pipe article to script
348 } elsif(defined($Options{'s'})) {
b855559e
TH
349 open (POST, "| $Options{'s'}") or die "$0: E: Cannot fork $Options{'s'}: $!\n";
350 print POST @$ArticleR;
351 close POST;
5a6670c7
TH
352 if ($? == 0) {
353 $failure = 0;
354 } else {
355 warn "$0: W: $Options{'s'} exited with status ", ($? >> 8), "\n";
356 $failure = $?;
357 }
358 # post article
359 } else {
360 my $NewsConnection = Net::NNTP->new($Config{'NNTPServer'}, Reader => 1) or die "$0: E: Can't connect to news server '$Config{'NNTPServer'}'!\n";
361 $NewsConnection->authinfo ($Config{'NNTPUser'}, $Config{'NNTPPass'}) if (defined($Config{'NNTPUser'}));
362 $NewsConnection->post();
363 $NewsConnection->datasend (@$ArticleR);
364 $NewsConnection->dataend();
365
366 if ($NewsConnection->ok()) {
367 $failure = 0;
368 # Posting failed? Save to ERROR.dat
369 } else {
370 warn "$0: W: Posting failed!\n";
371 open FH, ">>ERROR.dat";
372 print FH "\nPosting failed! Saving to ERROR.dat. Response from news server:\n";
373 print FH $NewsConnection->code();
374 print FH $NewsConnection->message();
375 print FH "\n";
376 print FH @$ArticleR;
377 print FH "-" x 80, "\n";
378 close FH;
379 }
380 $NewsConnection->quit();
dc88d139 381 }
5a6670c7 382 return $failure;
dc88d139
TH
383}
384
272b0243
TH
385__END__
386
387################################ Documentation #################################
388
389=head1 NAME
390
391yapfaq - Post Usenet FAQs I<(yet another postfaq)>
392
393=head1 SYNOPSIS
394
9817f98a 395B<yapfaq> [B<-Vhvpd>] [B<-t> I<newsgroups> | CONSOLE] [B<-f> I<project name>] [B<-s> I<program>] [B<-c> I<.rc file>]
272b0243
TH
396
397=head1 REQUIREMENTS
398
399=over 2
400
401=item -
402
403Perl 5.8 or later
404
405=item -
406
407Net::NNTP
408
409=item -
410
411Date::Calc
412
413=item -
414
415Getopt::Std
416
417=back
418
419Furthermore you need access to a news server to actually post FAQs.
420
421=head1 DESCRIPTION
422
423B<yapfaq> posts (one or more) FAQs to Usenet with a certain posting
424frequency (every n days, weeks, months or years), adding all necessary
425headers as defined in its config file (by default F<yapfaq.cfg>).
426
427=head2 Configuration
428
429F<yapfaq.cfg> consists of one or more blocks, separated by C<=====> on
430a single line, each containing the configuration for one FAQ as a set
227afd47
TH
431of definitions in the form of I<param = value>. Everything after a "#"
432sign is ignored so you may comment your configuration file.
272b0243
TH
433
434=over 4
435
436=item B<Name> = I<project name>
437
438A name referring to your FAQ, also used for generation of a Message-ID.
439
440This value must be set.
441
442=item B<File> = I<file name>
443
444A file containing the message body of your FAQ and all pseudo headers
445(subheaders in the news.answers style).
446
447This value must be set.
448
449=item B<Posting-frequency> = I<time period>
450
451The posting frequency defines how often your FAQ will be posted.
452B<yapfaq> will only post your FAQ if this period of time has passed
453since the last posting.
454
455You can declare that time period either in I<B<d>ays> or I<B<w>weeks>
456or I<B<m>onths> or I<B<y>ears>.
457
458This value must be set.
459
ac69c3ee 460=item B<Expires> = I<time period> (optional)
272b0243
TH
461
462The period of time after which your message will expire. An Expires
463header will be calculated adding this time period to today's date.
464
465You can declare this time period either in I<B<d>ays> or I<B<w>weeks>
466or I<B<m>onths> or I<B<y>ears>.
467
ac69c3ee 468This setting is optional; the default is 3 months.
272b0243
TH
469
470=item B<From> = I<author>
471
472The author of your FAQ as it will appear in the From header of the
473message.
474
475This value must be set.
476
477=item B<Subject> = I<subject>
478
479The title of your FAQ as it will appear in the Subject header of the
480message.
481
482You may use the special string C<%LM> which will be replaced with
483the contents of the Last-Modified subheader in your I<File>.
484
485This value must be set.
486
487=item B<NGs> = I<newsgroups>
488
489A comma-separated list of newsgroup(s) to post your FAQ to as it will
490appear in the Newsgroups header of the message.
491
492This value must be set.
493
ac69c3ee 494=item B<Fup2> = I<newsgroup | poster> (optional)
272b0243
TH
495
496A comma-separated list of newsgroup(s) or the special string I<poster>
497as it will appear in the Followup-To header of the message.
498
499This setting is optional.
500
ac69c3ee 501=item B<MID-Format> = I<pattern> (optional)
272b0243
TH
502
503A pattern from which the message ID is generated as it will appear in
504the Message-ID header of the message.
505
506You may use the special strings C<%n> for the I<Name> of your project,
13ce8c26
TH
507C<%d> for the date the message is posted, C<%m> for the month, C<%y>
508for the year and C<%t> for a time stamp (number of seconds since the
509epoch), respectively.
272b0243 510
ac69c3ee
TH
511This setting is optional; the default is '<%n-%d.%m.%y@I<YOURHOST>>'
512where I<YOURHOST> is the fully qualified domain name (FQDN) of the
513host B<yapfaq> is running on. Obviously that will only work if you
514have defined a reasonable hostname that the hostfqdn() function of
515Net::Domain can return.
272b0243 516
ac69c3ee 517=item B<Supersede> = I<yes> (optional)
272b0243
TH
518
519Add Supersedes header to the message containing the Message-ID header
520of the last posting.
521
522This setting is optional; you should set it to yes or leave it out.
523
ac69c3ee 524=item B<ExtraHeader> = I<additional headers> (optional)
272b0243
TH
525
526The contents of I<ExtraHeader> is added verbatim to the headers of
527your message so you can add custom headers like Approved.
528
529This setting is optional.
530
531=back
532
227afd47 533=head3 Example configuration file
272b0243
TH
534
535 # name of your project
536 Name = 'testpost'
537
538 # file to post (complete body and pseudo-headers)
539 # ($File.cfg contains data on last posting and last MID)
540 File = 'test.txt'
541
542 # how often your project should be posted
543 # use (d)ay OR (w)eek OR (m)onth OR (y)ear
544 Posting-frequency = '1d'
545
546 # time period after which the posting should expire
547 # use (d)ay OR (w)eek OR (m)onth OR (y)ear
ac69c3ee 548 # Expires = '3m'
272b0243
TH
549
550 # header "From:"
551 From = 'test@domain.invalid'
552
553 # header "Subject:"
554 # (may contain "%LM" which will be replaced by the contents of the
555 # Last-Modified pseudo header).
556 Subject = 'test noreply ignore'
557
558 # comma-separated list of newsgroup(s) to post to
559 # (header "Newsgroups:")
560 NGs = 'de.test'
561
562 # header "Followup-To:"
ac69c3ee 563 # Fup2 = 'poster'
272b0243
TH
564
565 # Message-ID ("%n" is $Name)
ac69c3ee 566 # MID-Format = '<%n-%d.%m.%y@domain.invalid>'
272b0243
TH
567
568 # Supersede last posting?
569 Supersede = yes
570
571 # extra headers (appended verbatim)
572 # use this for custom headers like "Approved:"
573 ExtraHeader = 'Approved: moderator@domain.invalid
574 X-Header: Some text'
575
576 # other projects may follow separated with "====="
577 =====
578
579 Name = 'othertest'
580 File = 'test.txt'
581 Posting-frequency = '2m'
582 From = 'My Name <my.name@domain.invalid>'
583 Subject = 'Test of yapfag <%LM>'
584 NGs = 'de.test,de.alt.test'
585 Fup2 = 'de.test'
586 MID-Format = '<%n-%m.%y@domain.invalid>'
587 Supersede = yes
588
227afd47
TH
589=head3 Status Information
590
272b0243
TH
591Information about the last post and about how to form message IDs for
592posts is stored in a file named F<I<project name>.cfg> which will be
593generated if it does not exist. Each of those status files will
594contain two lines, the first being the date of the last time the FAQ
595was posted and the second being the message ID of that incarnation.
596
227afd47
TH
597=head2 Runtime Configuration
598
599Apart from configuring which FAQ(s) to post you may (re)set some
600runtime configuration variables via the .rcfile (by default
601F<.yapfaqrc>). F<.yapfaqrc> must contain one definition in the form of
602I<param = value> on each line; everything after a "#" sign is ignored.
603
604If you omit some settings they will be set to default values hardcoded
605in F<yapfaq.pl>.
606
607B<Please note that all parameter names are case-sensitive!>
608
609=over 4
610
611=item B<NNTPServer> = I<NNTP server> (mandatory)
612
613Host name of the NNTP server to post to. Must be set (or omitted; the
614default is "localhost"); if set to en empty string, B<yapfaq> falls
615back to Perl's build-in defaults (contents of environment variables
616NNTPSERVER and NEWSHOST; if not set, default from Net::Config; if not
617set, "news" is used).
618
619=item B<NNTPUser> = I<user name> (optional)
620
621User name used for authentication with the NNTP server (I<AUTHINFO
622USER>).
623
624This setting is optional; if it is not set, I<NNTPPass> is ignored and
625no authentication is tried.
626
627=item B<NNTPPass> = I<password> (optional)
628
629Password used for authentication with the NNTP server (I<AUTHINFO
630PASS>).
631
632This setting is optional; it must be set if I<NNTPUser> is present.
633
634=item B<Sender> = I<Sender header> (optional)
635
636The Sender header that will be added to every posted message.
637
638This setting is optional.
639
640=item B<ConfigFile> = I<configuration file> (mandatory)
641
642The configuration file defining the FAQ(s) to post. Must be set (or
643omitted; the default is "yapfaq.cfg").
644
39cb5672
TH
645=item B<Program> = I<file name> (optional)
646
647A program the article is piped to instead of posting it to Usenet.
648See option "-f" below (which takes preference).
649
650This setting is optional.
651
227afd47
TH
652=back
653
654=head3 Example runtime configuration file
655
656 NNTPServer = 'localhost'
657 NNTPUser = ''
658 NNTPPass = ''
659 Sender = ''
660 ConfigFile = 'yapfaq.cfg'
39cb5672 661 Program = ''
227afd47
TH
662
663=head3 Using more than one runtime configuration
664
665You may use more than one runtime configuration file with the B<-c>
666option (see below).
667
272b0243
TH
668=head1 OPTIONS
669
670=over 3
671
a052296f
TH
672=item B<-V> (version)
673
674Print out version and copyright information on B<yapfaq> and exit.
675
272b0243
TH
676=item B<-h> (help)
677
ae3b1b79 678Print this man page and exit.
272b0243
TH
679
680=item B<-v> (verbose)
681
682Print out status information while running to STDOUT.
683
684=item B<-p> (post unconditionally)
685
686Post (all) FAQs unconditionally ignoring the posting frequency setting.
687
688You may want to use this with the B<-f> option (see below).
689
690=item B<-d> (dry run)
691
692Start B<yapfaq> in simulation mode, i.e. don't post anything and don't
693update any status information.
694
695=item B<-t> I<newsgroup(s) | CONSOLE> (test)
696
697Don't post to the newsgroups defined in F<yqpfaq.cfg>, but to the
698newsgroups given after B<-t> as a comma-separated list or print the
699FAQs to STDOUT separated by lines of dashes if the special string
700C<CONSOLE> is given. This can be used to preview what B<yapfaq> would
701do without embarassing yourself on Usenet. The status files are not
702updated when this option is given.
703
704You may want to use this with the B<-f> option (see below).
705
706=item B<-f> I<project name>
707
708Just deal with one FAQ only.
709
710By default B<yapfaq> will work on all FAQs that are defined in
711F<yapfaq.cfg>, check whether they are due for posting and - if they
712are - post them. Consequently when the B<-p> option is set all FAQs
713will be posted unconditionally. That may not be what you want to
714achieve, so you can limit the operation of B<yapfaq> to the named FAQ
715only.
716
b855559e
TH
717=item B<-s> I<program> (pipe to script)
718
719Instead of posting the article(s) to Usenet pipe them to the external
720I<program> on STDIN (which may post the article(s) then). A return
721value of 0 will be considered success.
722
0e741504
TH
723For example, you may want to use the I<inews> utility from the INN package
724or the much more powerful replacement I<tinews.pl> from
725I<ftp://ftp.tin.org/tin/tools/tinews.pl> which is able to sign postings.
726
39cb5672
TH
727If I<Program> is also defined in the runtime configuration file (by default
728F<.yapfaqrc>), B<-s> takes preference.
729
227afd47
TH
730=item B<-c> I<.rc file>
731
732Load another runtime configuration file (.rc file) than F<.yaofaq.rc>.
733
734You may for example define another usenet server to post your FAQ(s)
735to or load another configuration file defining (an)other FAQ(s).
736
272b0243
TH
737=back
738
739=head1 EXAMPLES
740
741Post all FAQs that are due for posting:
742
743 yapfaq
744
745Do a dry run, showing which FAQs would be posted:
746
747 yapfaq -dv
748
749Do a test run and print on STDOUT what the FAQ I<myfaq> would look
750like when posted, regardless whether it is due for posting or not:
751
752 yapfaq -pt CONSOLE -f myfaq
753
754Do a "real" test run and post the FAQ I<myfaq> to I<de.test>, but only
755if it is due:
756
757 yapfaq -t de.test -f myfaq
758
9817f98a
TH
759Post all FAQs (that are due for posting) using inews from INN:
760
761 yapfaq -s inews
762
763Do a dry run using a runtime configuration from .alternaterc, showing
764which FAQs would be posted:
765
766 yapfaq -dvc .alternaterc
767
272b0243
TH
768=head1 ENVIRONMENT
769
9817f98a
TH
770=over 4
771
772=item NNTPSERVER
773
774The default NNTP server to post to, used by the Net::NNTP module. You
775can also specify the server using the runtime configuration file (by
776default F<.yapfaqrc>).
777
778=back
272b0243
TH
779
780=head1 FILES
781
782=over 4
783
784=item F<yapfaq.pl>
785
786The script itself.
787
227afd47
TH
788=item F<.yapfaqrc>
789
790Runtime configuration file for B<yapfaq>.
791
272b0243
TH
792=item F<yapfaq.cfg>
793
794Configuration file for B<yapfaq>.
795
796=item F<*.cfg>
797
798Status data on FAQs.
799
800The status files will be created on successful posting if they don't
801already exist. The first line of the file will be the date of the last
802time the FAQ was posted and the second line will be the message ID of
803the last post of that FAQ.
804
805=back
806
807=head1 BUGS
808
809Many, I'm sure.
810
811=head1 SEE ALSO
812
813L<http://th-h.de/download/scripts.php> will have the current
814version of this program.
815
816=head1 AUTHOR
817
818Thomas Hochstein <thh@inter.net>
819
227afd47 820Original author (up to version 0.5b, dating from 2003):
272b0243
TH
821Marc Brockschmidt <marc@marcbrockschmidt.de>
822
272b0243
TH
823=head1 COPYRIGHT AND LICENSE
824
825Copyright (c) 2003 Marc Brockschmidt <marc@marcbrockschmidt.de>
826
827Copyright (c) 2010 Thomas Hochstein <thh@inter.net>
828
829This program is free software; you may redistribute it and/or modify it
830under the same terms as Perl itself.
831
832=cut
This page took 0.068158 seconds and 4 git commands to generate.