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.