Ubuntu Manpage: post_faq - post a USENET periodic posting

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>.

DIAGNOSTICS

       Should be self-explanatory.

                                                                                      post_faq(1)