NAME
post_faq - post a USENET periodic posting
SYNOPSIS
post_faq -config filename [ -interval days | expression ] [ -inewscmd
command ] [ -server server ] [ -idhost hostname ] [ -sigfile filename ]
[ -only list | -omit list ] [ -quiet level ] [ -force ] [
-expire_search ] [ -debug ]
DESCRIPTION
The post_faq perl(1) script reads USENET periodic postings (a.k.a.
"FAQs") and posts them with appropriate Message-ID, Expires,
Supersedes, and 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:
-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.
-interval days | 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 cron(8), and have it automatically figure out when to
post.
The default interval is 0, which means that posting always
occurs (and that no 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 -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.
-inewscmd command
Specifies the command to pipe into to post the message.
Defaults to "/usr/bin/inews".
Note that if you specify the -debug option (see below) and also
specify a posting command with this option, the command you
specify will be used, even though debugging is enabled.
-server server
Specifies an NNTP server to put into the NNTPSERVER environment
variable before running the posting command. Defaults to the
contents of /etc/news/server. If you don’t use NNTP, you don’t
have to do anything with this.
-idhost hostname
Specifies the host name to put after the ‘@’ in the Message ID.
Defaults to the contents of /etc/mailname.
-sigfile filename
Specifies the default signature file, which should contain a
signature to be appended to the bottom of the posted message,
preceded by "-- \n". The default is no signature.
-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 -omit option
(see below).
-omit list
A comma-separated list of the ID names of FAQS that should be
ignored. If -only is specified, then this option is ignored.
-quiet level
Specifies how quiet post_faq 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.
-expire_search
When an evaluated Perl expression, rather than a number, is
specified for an interval (as described above), post_faq
normally will not insert an Expires header in the posted FAQ.
However, if -expire_search is specified, or if it is enabled by
default when post_faq 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 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.
-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).
-debug Turns on debugging. The message is sent to stdout instead of
posted, and timestamp files are not changed in any way.
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:
idname The ID name of the FAQ. Each FAQ in the configuration file must
have a unique ID name. The name is used by post_faq when
printing messages about the FAQ and when creating its Message-
ID. Also, it is used to specify FAQs with the -only and -omit
options (see above).
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
post_faq).
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. post_faq will update this field in the
configuration file when it posts the FAQ.
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.
sigfile
The signature file, as described above. If unspecified, the
default or command-line-specified signature file is used.
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:
0 Don’t force -- post the FAQ if its interval says that it
should be posted.
1 Force the FAQ to be posted the next time post_faq is run,
and then switch the force field back to the default
value.
2 Always force the FAQ to be posted, without changing the
force field when done.
3 Force the FAQ to be posted the next time post_faq is run,
and then set the force field to -2.
-1 or -2
Never post the FAQ.
Any other values are illegal.
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.
FILES
The files used by post_faq 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 -debug option.
AUTHOR
Jonathan I. Kamens <jik@Athena.MIT.EDU>.
SEE ALSO
perl(1), inews(1), cron(8)
DIAGNOSTICS
Should be self-explanatory.
post_faq(1)