File: post_faq.man.base

package info (click to toggle)
post-faq 0.10-13
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 172 kB
  • ctags: 26
  • sloc: perl: 313; makefile: 43; sh: 26; awk: 7
file content (317 lines) | stat: -rw-r--r-- 11,024 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
.\" $Id: post_faq.man.base,v 1.19 1994/02/23 21:43:03 jik Exp $
.\" 
.\" Copyright (c) 1991 Jonathan I. Kamens.  See the GNU Public License
.\" (any version) for terms of distribution.
.\"
.TH post_faq.pl 1
.SH NAME
post_faq.pl \- post a USENET periodic posting
.SH SYNOPSIS
post_faq.pl
.BI \-config " filename"
[
.B \-interval 
.I days
|
.I expression
] [
.BI \-inewscmd " command"
] [
.BI \-server " server"
] [
.BI \-idhost " hostname"
] [
.BI \-sigfile " filename"
] [
.BI \-only " list"
|
.BI \-omit " list"
] [
.BI \-quiet " level"
] [
.B \-force
] [
.B \-expire_search
] [
.B \-debug
]
.SH DESCRIPTION
The
.I post_faq.pl
.IR perl (1)
script reads USENET periodic postings (a.k.a. "FAQs") and posts them
with appropriate
.BR Message-ID ,
.BR Expires ,
.BR Supersedes ,
and
.B References
headers added.

If, when reading an FAQ in order to post it, the script sees a string
in the format "@message-id idname@", then it will substitute in place
of it the Message ID that it thinks would be used to post the posting
with ID name "idname" during the current run of posting.  I realize
that the previous sentence is extremely confusing; if you don't
understand it, and you want to use Message ID substitution, then you
can read the script to see exactly what it does :-).

Similarly, if the script sees a string in the format "@old-id
idname@", it will look for a posting with the specified ID name
earlier in the configuration file, and substitute the Message ID used
the last time that posting was posted.  A warning is printed if the
specified posting was not encountered earlier in the configuration
file, in which case the string "<unknown>" is substituted.

These "@...@" escapes are meant to be used in the body of a posting;
don't use them to put the Message-ID and Supersedes fields into a
posting header, since the script will do that automatically.

The following command-line options are supported, and may be specified
in any order:
.TP
.BI \-config " filename"
Specifies the configuration file from which to read information about
the FAQs that should be posted.  See the section entitled
"CONFIGURATION FILE" below for a description of the format of the file.

This option must be specified, since a configuration file must be
provided.
.TP
.BI \-interval " days \fR|\fI expression"
If a number is specified, it is the default periodicity (in days) with
which FAQs should be posted.  If the script is run and the interval
for an FAQ has not expired, a message to that effect is printed and
the FAQ is not posted.

This is useful if you want to (for example) run the script once a day
from
.IR cron (8),
and have it automatically figure out when to post.

The default interval is #interval#\c
.ie #interval#=0 , which
.el \&.  An interval of 0
means that posting always occurs (and
that no
.B Expires
header is added to the posting).

If a non-numerical expression is specified, then it is evaluated to
determine whether or not the FAQ should be posted.  When the
expression is evaluated, the following variables are set: $minute (the
current minute in the hour), $hour (the current hour), $mday (the
current day of the month), $month (the current month, 0 through 11),
$year (the current year), $wday (the current day of the week, 0
through 6, 0 is Sunday), $yday (the current day in the year), and
$interval (the number of days since the last posting, or undef if
there is no previous posting timestamp).  For example, to post every
monday, use `$wday==1'.  To post on the seventh of every month, use
`$mday==7'.  To post on the second Monday in every month, use
`$wday==1 && $mday>7'.  You will probably want to use single quotes to
protect the interval expression you specify from the shell.  Also,
beware of using something like `1' as an expression to always post the
FAQ, since that will be interpreted as a numerical interval value.
Note that specifying an interval expression of `$interval>x', where
`x' is some integer, is equivalent to just specifying `x' as the
interval expression.

If an FAQ is posted with forcing enabled (see the
.B \-force
option below), then the interval is ignored.  Also, note that
intervals specified in the configuration file override both the
default and the interval specified on the command line.
.TP
.BI \-inewscmd " command"
Specifies the command to pipe into to post the message.  Defaults to
"#inews#".

Note that if you specify the
.B \-debug
option (see below) and also specify a posting command with this
option, the command you specify 
.B will
be used, even though debugging is enabled.
.TP
.BI \-server " server"
Specifies an NNTP server to put into the NNTPSERVER environment
variable before running the posting command.  Defaults to the contents 
of #serverfile#.  If you don't use NNTP, you don't have to do anything
with this.
.TP
.BI \-idhost " hostname"
Specifies the host name to put after the `@' in the Message ID.
Defaults to the contents of #idhostfile#.
.TP
.BI \-sigfile " filename"
Specifies the default signature file, which should contain a signature
to be appended to the bottom of the posted message, preceded by "--
\en".
.ie "#sigfile#"none" The default is no signature.
.el \{\
Defaults to "#sigfile#".  If "none" is specified, then no signature
will be appended.

Signature file specifications in the configuration file override the
default and the command-line specification.
.\}
.TP
.BI \-only " list"
A comma-separated list of the ID names (see the "CONFIGURATION FILE"
section) of the FAQs that should be examined and posted if
necessary. The other FAQs in the configuration file will be ignored.
This option takes precedence over the
.B \-omit
option (see below).
.TP
.BI \-omit " list"
A comma-separated list of the ID names of FAQS that should be ignored.
If
.B \-only
is specified, then this option is ignored.
.TP
.BI \-quiet " level"
Specifies how quiet
.I post_faq.pl
should be when performing its work.  The default is 0.  If 1 is
specified, then progress messages will not be printed, but reports of
successful posting will.  If 2 is specified, then reports of
successful posting will also be omitted, and only errors will be
printed.
.TP
.B \-expire_search
When an evaluated Perl expression, rather than a number, is specified
for an interval (as described above),
.I post_faq.pl
normally will not insert an
.B Expires
header in the posted FAQ.  However, if
.B \-expire_search
is specified, or if it is enabled by default when
.I post_faq.pl
is installed, then the script will attempt to search forward for the
next posting date for the FAQ, and use that as the basis for an
.B Expires
header.  It does this by counting forward one day at a time and
checking if the FAQ should be posted at each subsequent time.

Note that if the interval expression is worded in such a way that this
forward counting will never land on a timestamp when the FAQ would be
posted, the script will loop forever trying to determine when the
posting should expire.  Therefore, the script prints a warning for
every 100 days it goes into the future, to draw the user's attention
to a possible infinite loop.
.TP
.B \-force
Forces FAQs to be posted even if they should not be when judging by
their timestamps and posting intervals.  Force specifications in the
configuration file override this flag (i.e., if the configuration file
says not to force an FAQ, it will not be forced even when this flag is
specified, and if the configuration file says to force, it will be
forced even if this flag is omitted).
.TP
.B \-debug
Turns on debugging.  The message is sent to stdout instead of posted,
and timestamp files are not changed in any way.
.SH CONFIGURATION FILE
Each line in the configuration file (excluding lines containing
whitespace only and lines starting with '#', which are ignored)
represents one FAQ for the program to deal with.  Each line contains
seven whitespace-separated fields: idname, file, timestamp, interval,
sigfile, force, and parent.  Empty fields (for the timestamp,
interval, sigfile, force and parent fields, which are allowed to be
empty) are indicated with a single period.  A field can be enclosed in
single or double quotes to protect whitespace inside it, and a backslash
can be used to quote any character in a field (including quotes and
whitespace).  The meaning of each field
is as follows:
.TP
.B idname
The ID name of the FAQ.  Each FAQ in the
configuration file must have a unique ID name.  The name is used
by 
.I post_faq.pl
when printing messages about the FAQ and when creating
its Message-ID.  Also, it is used to specify FAQs with the
.B \-only
and
.B \-omit
options (see above).
.TP
.B file
The file in which the text of the FAQ is located.  It should be in the
correct format for a USENET posting, including a posting header
(excluding the header fields that will be added by
.IR post_faq.pl ).
.TP
.B timestamp
The timestamp of when the FAQ was last posted.  If adding an FAQ to
the configuration file for the first time, this should contain a
period.
.I post_faq.pl
will update this field in the configuration file when it posts the
FAQ.
.TP
.B interval
The posting interval, as described above.  If unspecified, the
default or command-line-specified interval is used.  Be careful to
quote the interval if you are using an expression with spaces or tabs
in it.
.TP
.B sigfile
The signature file, as described above.  If unspecified, the default
or command-line-specified signature file is used.
.TP
.B force
Whether or not to force the posting of the FAQ, ignoring the interval.
If unspecified, the default or command-line-specified value is used.
If specified, it should be one of the following numbers:
.RS
.IP 0
Don't force -- post the FAQ if its interval says that it should be
posted.
.IP 1
Force the FAQ to be posted the next time
.I post_faq.pl
is run, and then
switch the force field back to the default value.
.IP 2
Always force the FAQ to be posted, without changing the force field
when done.
.IP 3
Force the FAQ to be posted the next time
.I post_faq.pl
is run, and then set
the force field to \-2.
.IP "\-1 or \-2"
Never post the FAQ.
.PP
Any other values are illegal.
.RE
.TP
.B parent
The ID name of the parent article of this one.  The parent must appear
earlier in the configuration file.  If specified, then the current FAQ
will not be posted unless the parent FAQ was posted successfully.
However, note that if the interval for the current FAQ has not
expired, it will not be posted even if the parent was posted, unless
"force" is true as well.
.SH FILES
The files used by
.I post_faq.pl
are the configuration file specified on the command line and the
files, specified in the configuration file, containing the text of
each FAQ.  Furthermore, note that a backup of the configuration file
with a ".old" extension is saved when the script is run without the
.B \-debug
option.
.SH AUTHOR
Jonathan I. Kamens <jik@Athena.MIT.EDU>.
.if !"#maintainer#"" \{\
.SH LOCAL MAINTAINER
#maintainer#
.\}
.SH SEE ALSO
perl(1), inews(1), cron(8)
.SH DIAGNOSTICS
Should be self-explanatory.