post_faq(1)						      General Commands Manual						       post_faq(1)

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 expres-
	      sion to always post the FAQ, since that will be interpreted as a numerical interval value.  Note that specifying an interval expres-
	      sion 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  con-
	      tents 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 "-- 
".  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 nec-
	      essary. 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 indi-
       cated 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)