AUTO-FAQ - automation for UseNet FAQ postings Copyright (c) 1992, 1993, 1994 by Ian Kluft Copyright (c) 1995, 1999 by Paul W. Schleck This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. Questions or feedback regarding this program may be directed to: Paul W. Schleck auto-faq-maint@novia.net http://www.novia.net/~pschleck/auto-faq/ P.O. Box 155 Mount Rainier, MD 20712-0155 USA RCS ID: $Id: README,v 3.7 1997/07/26 14:53:23 pschleck Exp pschleck $ About AUTO-FAQ -------------- The AUTO-FAQ script was made to help posting Frequently-Asked Questions (FAQ) articles to UseNet newsgroups. It also helps with cross-posting FAQs to the news.answers newsgroup, if the FAQ author chooses to do so, by complying with all the formatting requirements automatically. It has test modes so the FAQ author can see how the posted article will look without actually posting it, or by posting it to a local test newsgroup. (Between the two test modes, the FAQ author can get a good indication that everything will operate smoothly when the time comes for that first automated FAQ posting.) See Part 2.1 "Environment Variables" for information on how to activate the test modes. AUTO-FAQ is built around the concept that there may be multiple FAQ's main- tained from one site, often by people who are experts on their topic but not at UseNet news. Each article in AUTO-FAQ's configuration file can have differ- ent authors but will be posted by one "news guru" user, the user that actually runs AUTO-FAQ. Or the news guru and the FAQ author can be the same person. For this arrangement to work, the FAQ text files must be readable by the news guru user. If any error occurs in obtaining the text, AUTO-FAQ will send mail to the FAQ author and the news guru informing them of the failure and asking them to post the FAQ manually. In order to get full automation of FAQ postings, the news guru user must have access to the system crontab and make it activate AUTO-FAQ at the desired intervals, whether they be weekly, biweekly, monthly, etc. How to Use this Documentation ----------------------------- AUTO-FAQ automates much of the process of posting FAQs. But AUTO-FAQ has no way to know certain things like the location of the FAQ text, the title of the FAQ (or, if you want, the different titles for each part of the FAQ), which newsgroup(s) it will be posted in, how many days an FAQ article should go before it is expired, etc. Only you can answer these questions. Often the answers will be different for each FAQ you maintain. Plan to spend a little time doing the configuration and testing it. AUTO-FAQ contains many features, some necessary for every FAQ, some optional, and still others which are quite advanced so that many users might not want to deal with them immediately. This documentation separates each of those categories so that you can go as far as you need and leave the most complicated parts aside. Wherever you see an "optional" or "advanced" feature, you may safely skip it during your initial familiarization with AUTO-FAQ. Though you should return to them later when you are more comfortable with the base features. Table of Contents ----------------- Part 1 - Instructions for All FAQs 1.1 Installation 1.2 Site-specific Modifications 1.3 Invocation of AUTO-FAQ 1.4 The FAQ Text Files 1.5 The Configuration File Part 2 - Getting Ready to Post 2.1 Environment Variables 2.2 Testing Techniques 2.3 Getting Approval for Cross-posting to News.Answers 2.3.1.1 The faq-maintainers Mail List 2.3.1.2 Posting to Multiple Moderated Newsgroups 2.4 Learning from Others' Mistakes (Pitfalls/Workarounds) Part 3 - Keeping up-to-date about AUTO-FAQ 3.1 The Auto-faq-users Mailing List 3.2 Where to Go for Help 3.3 Techniques for Helping Other AUTO-FAQ Users 3.4 Obtaining the Latest Version 3.5 User Tips Bulletins 3.6 World-Wide Web Home Page Part 4 - Advanced Features 4.1 Using Status Files 4.1.1 Customizing your Status Files 4.1.2 Upgrading from Sequence Files 4.2 Change Control for Your FAQ 4.3 Customization with @-macros 4.4 User-loadable Header Functions Part 5 - Utility Programs 5.1 txt2dig: creating RFC1153 digests Appendix A - Related Readings Appendix B - Acknowledgments Part 1 - Instructions for All FAQs ---------------------------------- 1.1 Installation ---------------- AUTO-FAQ is a PERL script. If PERL is installed at your site, then do the following: * Make a "faq" directory wherever you want to do your FAQ maintenance. * Unpack the shar file by running it as a /bin/sh shell script. * Run "Configure". It will determine what kind of system you're running on and where to find certain programs. It will also ask you questions about some of your preferences. It will create a config.sh file, then it will run "auto-faq.SH" which will create the AUTO-FAQ program based on your configuration, as determined by the Configure script. * Copy the config.sample file to a configuration file named "faq-config." Edit this file as appropriate to reflect desired headers for your FAQ articles to be posted by AUTO-FAQ. config.sample file. 1.2 Site-specific Modifications ------------------------------- As of Version 3.0, you should not need to make any modifications to run AUTO-FAQ on a Unix-like system. However, systems vary so much that this goal may not always be achievable. Please send mail to auto-faq-help@novia.net if you determine that some site-specific modifications were necessary. 1.3 Invocation of AUTO-FAQ -------------------------- From the shell command line, AUTO-FAQ can be run as follows: auto-faq rec.radio.amateur.misc Or, if more than one FAQ article is to be posted at once, they can all be listed on the command line. Example: auto-faq rec.radio.amateur.misc rec.radio.cb amdahl.aviation Note that these "names" for the FAQs do not have to match the name of the newsgroup they will be posted to. If different kinds of postings will be placed in the same newsgroup, any recognizable title is acceptable, These can be set up from the configuration file, which will be covered in detail later. Example: auto-faq ham-radio-faq ham-radio-archives The AUTO-FAQ configuration file "faq-config" must be in the current directory when AUTO-FAQ is started. To start AUTO-FAQ from a crontab, add an entry similar to the following one into your crontab file: # post rec.radio.cb FAQ (3:08 AM, 7th & 22nd of each month) 8 3 7,22 * * cd /usr/home/ikluft/txt/faq; ./auto-faq rec.radio.cb More than one FAQ can be "auto-posted" at one time, as illustrated with the command-line invocations above. 1.4 The FAQ Text Files ---------------------- The names of the FAQ text files are obtained from the configuration file. The text files should contain only text - no news headers, shell commands, or other machine-readable formats (except for the standard "digest" format, if the FAQ author chooses to use it.) All the news headers will be added by the AUTO-FAQ program from information in the configuration file. Multi-part FAQs are supported by AUTO-FAQ. Regardless of the filenames chosen in the configuration file, the first FAQ text file must end in ".1" - even one-part FAQs must do this. For example, you may choose to name the files with a base name of "cb-faq" (this was used for the CB radio newsgroup.) Then the FAQ files will be called cb-faq.1, cb-faq.2, and cb-faq.3, making it a 3-part FAQ. When a 4th part is added, just make a file cb-faq.4. AUTO-FAQ will find it and post them all as a 4-part FAQ during the next automatic posting. In summary, the FAQ text files contain only human-readable text so that the FAQ author does not have to be a news guru. The number of parts to the FAQ depends only on how many files that AUTO-FAQ can find which have the base name and sequentially-numbered suffixes. 1.5 The Configuration File -------------------------- Almost everything that AUTO-FAQ knows, it gets from the configuration file. We'll start with an example which will be followed by some discussion. This sample is taken from a running installation so be sure to change the site- specific information to match your site. --example AUTO-FAQ configuration---------------------------------------------- #!/bin/false # # Configuration for auto-faq # # Current newsgroups covered by this file: # rec.radio.amateur.misc (cross-posted to news.answers) # rec.radio.cb (cross-posted to news.answers) # # global parameters articledir="/home/ikluft/txt/faq" # default directory for FAQ chgctrl-type="rcs" # set reasonable defaults for RCS chgctrl-format="x" # revision info: version/date/time (not used when in RCS mode) newstech="ikluft" # technical lead for FAQ postings from="newstech" # From: field default is news-tech user techname="Ian Kluft" # full name of technical lead testgroup="sbay.test" # newsgroup for tests testdistrib="local" # distribution for tests organization="sbay.org - Silicon Valley/South Bay UseNet Network" localdomain="thunder.sbay.org" # local internet domain name timezone="PST8PDT" # local timezone approval="" # news.answers approval (optional) === hamradio-faq articledir="/home/ikluft/txt/faq/ham-radio" # directory for FAQ articlebase="faq" # basename for FAQ statusbase="ham.status" # sequence file for Supersedes: headers owner="hamradio-faq@kluft.com" # owner of FAQ text file ownername="Ham Radio FAQ Coordinators" # full name of owner organization="Kluft Consulting" localdomain="kluft.com" # local internet domain name newsgroup="rec.radio.amateur.misc" # primary newsgroup for FAQ postings extragroups="rec.radio.info,rec.answers,news.answers" # secondary newsgroup(s) for cross-posting # extragroups may be left empty faqid="ham-radio-faq" # identifier for message ID & archive name archive="radio/ham-radio/faq" # override archive name distribution="world" # normal FAQ posting distribution approval="" # moderated newsgroup approval interval="35" # how many days before the message expires Keywords: FAQ RADIO AMATEUR HAM Posting-Frequency:: posted on the 7th of each month\ A how-to-find-the-FAQ article is posted on the 14th, 21st, and 28th X-Content-Currency: This FAQ changes regularly. When a saved or printed copy\ is over 6 months old, please obtain a new one. Instructions in Part 2\ indicate where to find them via NetNews, FTP, and e-mail. === ham-faq-ptr articledir="/home/ikluft/txt/faq/ham-radio" # directory for FAQ articlebase="ham-faq-ptr" # basename for FAQ statusbase="ham-ptr.status" # sequence file for Supersedes: headers title="How to find the answers to frequently-asked questions about Ham Radio" owner="hamradio-faq@kluft.com" # owner of FAQ text file ownername="Ham Radio FAQ Coordinators" # full name of owner organization="Kluft Consulting" localdomain="kluft.com" # local internet domain name newsgroup="rec.radio.amateur.misc" # primary newsgroup for FAQ postings extragroups="rec.radio.info" # secondary newsgroup(s) for cross-posting # extragroups may be left empty faqid="ham-faq-ptr" # identifier for message ID & archive name distribution="world" # normal FAQ posting distribution approval="" # moderated newsgroup approval interval="20" # how many days before the message expires Keywords: FAQ RADIO AMATEUR HAM Posting-Frequency:: this is posted on the 14th, 21st, and 28th of each month\ The FAQ articles described here are posted on the 7th of each month === cb-faq articledir="/home/ikluft/txt/faq/cb" # directory for FAQ articlebase="faq" # basename for FAQ statusbase="cb.status" # sequence file for Supersedes: headers owner="cb-faq@kluft.com" # owner of FAQ text file ownername="CB FAQ Coordinators" # full name of owner organization="Kluft Consulting" localdomain="kluft.com" # local internet domain name newsgroup="rec.radio.cb" # primary newsgroup for FAQ postings extragroups="rec.radio.info,rec.answers,news.answers" # secondary newsgroup(s) for cross-posting # extragroups may be left empty faqid="cb-radio-faq" # identifier for message ID & archive name archive="radio/cb-faq" # override archive name distribution="world" # normal FAQ posting distribution approval="" # moderated newsgroup approval interval="18" # how many days before the message expires Keywords: FAQ RADIO CB Posting-Frequency:: posted on the 7th and 22nd of each month X-Content-Currency: This FAQ changes regularly. When your saved or printed copy\ is over 9 months old, please obtain a new one from rec.radio.cb or\ news.answers on NetNews, from rtfm.mit.edu or ftp.amdahl.com via FTP, or\ from listserv@rtfm.mit.edu via e-mail. === test articlebase="test" # basename for FAQ statusbase="test.stat" # basename for per-part status files title="Test Posting from the FAQ-generator script" owner="ikluft" # owner of FAQ text file ownername="Ian Kluft" # full name of owner newsgroup="sbay.test" # primary newsgroup for FAQ postings distribution="local" # normal FAQ posting distribution interval="1" # how many days before the message expires faqid="test-faq" # identifier for message ID & archive name refseqnum="./lastid.test" # file to find reference sequence number archive="test" # you know where you can put it! :-) Summary: This is only used to test the FAQ-generator \ You may ignore it or, if you have time to waste, you may read it. --end of example-------------------------------------------------------------- In the configuration file, any line beginning with a "#" is a comment. Blank lines are ignored so they may be used for readability. Lines beginning with "===" (followed by a space) define the name of an FAQ. This keyword must match the name used on the command line to post the FAQ. It is used nowhere else so any descriptive name is acceptable. If only one FAQ is being posted (even if it has multiple parts), it is recommended that the keyword for the newsgroup be the name of the newsgroup. Each "===" line marks the beginning of the attributes for an FAQ. The rest of the lines are either news headers which will be copied verbatim into the FAQ news headers (see "Summary", "Keywords", "X-Content-Currency' or "Posting-Frequency" in the example above) or configuration attributes which describe the FAQs. For example: attribute="value" # comment, more on attribute formatting later News-Header: Text to the end of the line \ Headers may continue to another line if they end in a backslash.\ The backslash will not be copied into the final output\ Everything else is copied verbatim\ Don't forget to put some whitespace at the beginning of the following\ lines in order to comply with RFC822. Aux-Header:: This is an auxiliary header as commonly used in news.answers\ It is formatted just like a primary header except for the double ::\ It will be printed with only one colon in the FAQ\ but it will be in the auxiliary header section after a blank line Any attributes or headers before the first "===" line are global and will apply to all FAQs. Attributes may be overridden by redefining the attribute local to the specific FAQ. Local attributes follow each "=== keyword" line. Headers cannot be overridden. They just keep getting appended to a list. The same header name should not be used more than once unless permitted by RFC822. All attributes use the following format: attribute-name="attribute-value" where attribute-name and attribute-value are substituted with the appropriate names and values. The attribute-value may be empty but this is treated the same as an omitted attribute. The equals sign and the quotes are required. Any extra text after the closing quote is ignored. However, for readability, it is recommended that pound signs "#" be used to make it clear that any following text is a comment. (See the example above.) An optional feature which applies to configuration attributes is @-macros. See Part 4.3 "Advanced Features" for more information on this feature for advanced users. All of auto-faq's configuration attributes are described below. Any required attributes which will have the same value for all the FAQs should be placed in the global attributes area at the beginning of the configuration file. (Required attributes are noted in all-caps in order to stand out better.) * approval: This fills in the "Approved" news header. If you want to cross- post your FAQs to news.answers (and you should), you can obtain the contents of this field from the newsgroup moderator after you've sent in a sample posting of your FAQ. If you are cross-posting to any other moderated newsgroups, you may add more comma-delimited approvals to this entry but you *must* have each moderator's approval before doing so. (See Part 2.3 "Getting Approval for Cross-posting to News.Answers" for information on news.answers and posting to multiple moderated newsgroups.) [optional in AUTO-FAQ, required for news.answers] * archive: This may be used to override the default archive name (which would be taken from the faqid attribute) or to force an "Archive-Name" auxiliary header to be generated even if the "faqid" attribute is not defined. This is only of interest if you are cross-posting to news.answers. [optional in AUTO-FAQ, required for news.answers unless the faqid attribute is used] * articlebase: the basename of the FAQ files. As discussed in the text about FAQ text files (above), AUTO-FAQ will append a ".1" to the name for the first (or only) text file in the FAQ. If there are more files with sequentially numbered suffixes, AUTO-FAQ will consider them part of the same FAQ and post them all. [REQUIRED] * articledir: the full-path directory where the FAQ text files are located. If change control (SCCS, RCS, etc) is intended to be used with the FAQ text files, the SCCS/RCS files may be kept in this directory or others defined by the chgctrl-path attribute. [REQUIRED] * change-format: [this is an optional feature intended for advanced users] this is functionally a duplicate of the chgctrl-format attribute, except that it is used to produce a "Changes:" auxiliary header. If omitted, the "Changes:" auxiliary header will not be included in the FAQ. For that reason, even if RCS is used (so this field is not used) it must be non-empty for the Changes: header to be included in the posted article. See Part 4 "Advanced Features" for more information on using change control. [optional] * chgctrl-cmd: [this is an optional feature intended for advanced users] the shell command line used to extract information for the "Revision:" and "Changes:" auxiliary headers. If chgctrl-cmd is omitted, the default is to use SCCS. A sprintf-like "%s" may be inserted anywhere in the string to add the path of the change control file to the command. The following examples all show the chgctrl-format attribute, which is the default for the "Revision:" auxiliary header. For the "Changes:" auxiliary header, substitute in the change-format attribute in its place. For BSD-style SCCS: (chgctrl-type is empty, "bsd", or "bsd-sccs") sccs prs -d'@chgctrl-format@' %s For USL-style SCCS: (chgctrl-type is "sccs", "usl-sccs", or "att-sccs") prs -d"@chgctrl-format@" %s For RCS: (chgctrl-type is "rcs") rlog -b %s | awk '/^revision / {ver=$2; getline; tstamp=substr($0,6,20); print ver tstamp; exit}' [See Part 4 "Advanced Features" for more information on @-macros.] Use of RCS is possible with this method but no RCS examples have been developed by or provided to the author yet. See Part 4 "Advanced Features" for more information on using change control. [optional] * chgctrl-format: [this is an optional feature intended for advanced users] the change control (SCCS, RCS, or similar system) data for the "Revision:" auxiliary header. If omitted, the "Revision" header will not appear in the posted FAQ and AUTO-FAQ will not look for any SCCS/RCS files. For that reason, even if RCS is used (so this field is not used) it must be non-empty for the Revision: header to be included in the posted article. For BSD-style SCCS: (chgctrl-type is empty, "bsd", or "bsd-sccs") :I: :Dm:/:Dd:/:Dy: :T: For USL-style SCCS: (chgctrl-type is "sccs", "usl-sccs", or "att-sccs") (same as BSD) For RCS: (chgctrl-type is "rcs") (not used in formatting, defaults to "-" because it must be non-empty to enable the Revision: header) See Part 4 "Advanced Features" for more information on using change control. [optional] * chgctrl-path: [this is an optional feature intended for advanced users] a list of one or more directories where the change control (SCCS, RCS, etc) file may be found. The list is delimited by two colons "::" since that combination is extremely unlikely to appear in a directory name. A sprintf- like "%s" may be included in each path name to insert the basename of the FAQ file (the articlebase attribute with .1, .2, ... appended.) If the path starts with a "/" it will be used as an absolute path from the system root, otherwise it will be relative to the directory from the articledir attribute. The defaults are controlled by the chgctrl-type attribute. For BSD-style SCCS: (chgctrl-type is empty, "bsd", or "bsd-sccs") SCCS/s.%s For USL-style SCCS: (chgctrl-type is "sccs", "usl-sccs", or "att-sccs") s.%s::SCCS/s.%s For RCS: (chgctrl-type is "rcs") %s,v::RCS/%s,v In each case above, the change control file will be found in either the same directory as the FAQ file or in the SCCS/RCS directory beneath it. See Part 4 "Advanced Features" for more information on using change control. [optional] * chgctrl-type: [this is an optional feature intended for advanced users] This attribute can be used to select the default values for the other change control attributes: chgctrl-cmd, chgctrl-format, and chgctrl-path. See the descriptions of each of those attributes for their default values. There are 3 sets of defaults to choose from. If you store your FAQ with a BSD-style SCCS (included with BSD, SunOS, Ultrix, and other BSD-derivatives), set this attribute to "bsd-sccs". Synonyms for bsd-sccs include "bsd" or an empty string. If you use an AT&T- or USL-style SCCS (included with any AT&T- or USL-derived Unix, which means it can call itself by the trademark "Unix"), use the value "usl-sccs", or synonyms "att-sccs" or just "sccs". If you use RCS, use the value "rcs". See Part 4 "Advanced Features" for more information on using change control. [optional] * distribution: used to fill in the "Distribution" news header, except in test postings. Use the widest distribution appropriate for the newsgroup. [REQUIRED] * expires-format: this field is used to specify a different format than the default for the "Expires" header. The default format is @date(D) date(T)@ which generates a date like 12/7/96 16:29:51. One possible reason to specify a different format would be if your news-posting software has formatting restrictions of the "Expires" header. A possible alternative would be: @date(a)@ @date(d)@ @date(b)@ @date(T)@ @date(Z)@ which generates a date like Sat 07 Dec 96 02:48:27 PDT. See Part 4 "Advanced Features" for more information about @ macros. [optional] * extragroups: if the FAQ should be posted to more newsgroups than the primary one, they should be listed here, separated by commas. (No spaces.) This is used to fill in the "Newsgroups" news header, except in test postings. The primary newsgroup should not be listed on this line - see the newsgroup attribute. [optional] * faqid: a string used in the "Message-ID" header and the "Archive-Name" auxiliary header. Also used in the "Supersedes" header if a previous FAQ is being superseded. [optional in AUTO-FAQ, recommended for news.answers] * followup: used to fill in the Followup-To header. The default value, which is recommended for most uses, is the primary newsgroup name. [optional] * from: used to fill in the From header. If set to "newstech" the value is the contents of the newstech attribute, else if set to "owner" the value is set to the contents of the owner attribute, else set to its literal value. [optional] * interval: the number of days the article should be retained at all news sites which carry the newsgroups where this FAQ goes. It is used to calculate the expiration date. Recommended value: add 3-4 days to the actual posting interval (which is controlled from the crontab) so that there is time for the FAQ to propagate around the net. In order to be a good net.citizen, don't use more than that because this value affects disk resources on other peoples' machines. [REQUIRED] * localdomain: the local sites' Internet mail domain name. This is used with the newstech and owner attributes the generate return mail addresses. Also, if a faqid attribute is specified, this attribute will be used to make a custom message-ID. (To avoid the custom IDs, omit the faqid attribute, not localdomain.) [REQUIRED] * local-func-src: [this is an optional feature intended for advanced users] This is the name of a file which contains PERL functions which are to be merged into AUTO-FAQ. This currently only supports functions for news headers. See Part 4 "Advanced Features." [optional] * newsgroup: this is the primary newsgroup that the FAQ is intended for. It is used to fill in the "Newsgroups" news header, except in test postings. If no title attribute is specified, it will be used to make a generic title. (See the title attribute.) [REQUIRED] * newscmd: the news posting command. The default is the value given to the Configure script during initial setup (See Part 1.1 "Installation" for more information) followed by an "-h" switch [optional, required if the default is not correct for your site] * newstech: the user-id of the news guru who posts the FAQ articles. This may contain a fully-qualified domain mail address if the news guru prefers to receive mail in another location (i.e. ikluft@kluft.com.) If the address does not contain an "@", "%", or "!", (i.e. ikluft) then the local domain will be appended to the address when it is placed in the "From" news header. [REQUIRED] * organization: The name of the Organization which the FAQ originated from. It fills in the "Organization" header. [optional] * owner: the user ID of the FAQ author - the owner of the FAQ text files. This is used to create the "Reply-To" news header. As with the newstech attribute, this may contain a full e-mail path if the owner is a mail list or if the owner prefers to receive mail at another site. It will also be used for any e-mail generated by AUTO-FAQ in case of failure to access the FAQ text files. [REQUIRED] * ownername: this is the first and last name of the FAQ author. It is used in the "Reply-To" news header. It can be the name of an editors mail list or a local user. [REQUIRED] * post-pri-hdrs: [this is an optional feature intended for advanced users] This attribute contains a colon-delimited list of headers in the order they will appear in the primary header during news posting mode. Other related attributes include post-2nd-hdrs for the auxiliary/secondary headers. See test-pri-hdrs for the headers used in test mode. Examples can be found in Part 4 "Advanced Features." [optional] * refid: this contains the "faqid" of a different FAQ. It is used with the refseqfile attribute to add a reference to another FAQ in the "References" news header. This is only of interest if you are posting 2 closely-related FAQs that have different titles or need to be linked for some reason. The pointed-to FAQ must be posted before the one that references it. [optional, obsoleted by status files - see "statusbase"] * refseqfile: this is similar to the seqfile attribute. It points to the sequence file of another FAQ. When used along with the refid attribute, this will add an entry to the "References" news header with the Message ID of the pointer-to FAQ. This should be used for related FAQs which do not have the same title or other attributes. [optional, obsoleted by status files - see "statusbase"] * seqfile: specifies the name of the sequence file for this FAQ. If used, the sequence file stores the Message ID of the previous time this FAQ was posted. If the seqfile and faqid attributes are defined, AUTO-FAQ will generate a "Supersedes" news header so that the arrival of this FAQ at each news site will cause the previous copy to be expired, thereby saving disk resources at thousands of news sites. [optional in AUTO-FAQ, recommended for news.answers, obsoleted by status files - see "statusbase"] * statusbase: defines the base of the name of a per-part status file. The full path of the file will be determined by the "articledir", "statusbase", and the same .1, .2, .3, etc suffixes as articles use. After each part is posted, any information desired for the next run can be saved in the status file. By default, the message ID and date are saved, but these can be customized with the "savestatus" attribute. For * techname: the first & last name of the news guru [REQUIRED] * testdistrib: the distribution area for test postings. Use a local-system distribution. It fills in the "Distribution" header on test postings. [REQUIRED] * testgroup: the newsgroup where test news postings will be sent. Use a local test newsgroup. It fills in the "Newsgroups" header on test postings. [REQUIRED] * test-pri-hdrs: [this is an optional feature intended for advanced users] This attribute contains a colon-delimited list of headers in the order they will appear in the primary header during test mode. Other related attributes include test-2nd-hdrs for the auxiliary/secondary headers and test-3rd-hdrs for the tertiary headers. (Tertiary headers are only used in test mode so headers which are not appropriate for the primary headers may still be displayed and, therefore, tested.) See post-pri-hdrs for the headers used in regular news-posting mode. Examples can be found in Part 4 "Advanced Features." [optional] * timezone: this is used to set the TZ environment variable within auto-faq. The default is GMT. This should be a global attribute unless, for some reason, you want one or more FAQs to have different time zones. [optional] * title: the title for the FAQ articles, used to fill in the "Subject" news header. For example: title="Frequently Asked Questions about Ham Radio" If omitted, a generic title will be used " Frequently Asked Questions." Individual parts may be given different titles by appending the part number to the attribute name as shown in the following example: title-1="Ham Radio Frequently-Asked Questions: Introduction" title-2="Ham Radio Frequently-Asked Questions: Information Sources" title-3="Ham Radio Frequently-Asked Questions: Technical Questions" On multi-part FAQs, except those with part-specific titles, AUTO-FAQ will append "(Part X of Y)" with X being the part number and Y being the total number of parts. If your FAQ will be cross-posted to news.answers, it is a good idea to put the newsgroup name or topic at the beginning of the title. News.answers contains articles from so many different topics that this will help yours stand out a little better for the people looking for your subject area. [optional] Part 2 - Getting Ready to Post ------------------------------ Now that you've completed your faq-config file, you're ready to start looking at the output and making adjustments until you're satisfied with it. 2.1 Environment Variables ------------------------- All environment variables are optional (because AUTO-FAQ is made to run from cron as well as the command line.) If they are defined, they will have the following effects: FAQ_TEST if set and not empty, posts to the test newsgroup instead of the entire news broadcast distribution. FAQ_NOSEND if set and not empty, AUTO-FAQ does not send mail or post news. Instead, all mail and news output are routed into the file "faq.out" in the current directory. Also, the sequence file will not be updated with this article's Message ID since upcoming postings need to supersede the last article that was actually posted. FAQ_DEBUG used only for debugging AUTO-FAQ. (That's obvious, right?) NNTPSERVER since AUTO-FAQ invokes inews, this can be used by inews to post to a non-default NNTP server (set to the hostname of the desired NNTP server, which must allow posting) PERL_OPTS since AUTO-FAQ is actually a PERL script, this can be used to invoke any desired PERL command line options. This is mainly used for debugging. The author uses "-w" to get PERL to do more detailed error reporting. The environment variables HOME, PATH, TZ, or DOTDIR have no affect on AUTO-FAQ since it overrides them. Examples: (Bourne-compatible-shell, e.g., sh, ksh, or bash) FAQ_NOSEND=1; FAQ_TEST=1; export FAQ_NOSEND FAQ_TEST (csh) setenv FAQ_NOSEND 1; setenv FAQ_TEST 1 2.2 Testing Techniques ---------------------- There are some techniques which can make a smoother ride out of setting up the AUTO-FAQ software. If you take the following precautions, you can be quite confident that you won't have any major problems. However, plan to put in enough time to look over the sample news outputs and test articles to look for errors in your configuration. Step 1: Create the faq-config file. Make sure the FAQ text files are in the directory specified by the configuration (and that they are consecutively numbered with suffixes ".1", ".2", etc.) Step 2: Set the FAQ_NOSEND environment variable. In the Korn Shell, use "export FAQ_NOSEND=1" and in C Shell use "setenv FAQ_NOSEND 1" With this variable set, AUTO-FAQ will send its output to the "faq.out" file rather than posting news. Step 3: Do a test run "auto-faq faq-keyword", substituting faq-keyword for the name of your FAQ from the faq-config file. Check the output in the faq.out file. Correct any errors and repeat this process until the output in "faq.out" looks acceptable for posting as news. Don't post it to news yet. Step 4: Set the FAQ_TEST environment variable. In the Korn Shell, use "export FAQ_TEST=1" and in C Shell use "setenv FAQ_TEST 1" With this variable set, AUTO-FAQ will use the test newsgroup instead of the FAQ's primary newsgroup. Since FAQ_NOSEND is still set in the environment (repeat Step 2 if you've logged out since then) you will still send output to "faq.out." Step 5: Do another test run as in Step 3. Again, check the output in faq.out, correct any errors, and try again. Do not proceed to Step 6 until you are happy with the results both with and without FAQ_TEST set. Step 6: Unset the FAQ_NOSEND environment variable but leave the FAQ_TEST variable set. This will, in the next step, make AUTO-FAQ post to the test newsgroup and verify proper operation with a real news posting and check for any site-specific problems. Step 7: Do another test run. This time it will post an article to the test newsgroup. Look there and correct any errors in the configuration. (Go back to step 2, if necessary, after making any changes.) Step 8: When everything looks good with the test posting and no-send tests, put AUTO-FAQ in your crontab and monitor the scheduled posting for any problems. By this point, unless there is a problem with cron (i.e. if the system is not up at the time you scheduled the posting) you shouldn't have any problems. 2.3 Getting Approval for Cross-posting to News.Answers ------------------------------------------------------ News.answers is a moderated newsgroup where FAQs for any newsgroups can be cross-posted. It provides a single place where people can browse for informa- tion to see if it is available somewhere on the net. There are some formatting requirements, all of which can be complied with via AUTO-FAQ. However, you should be aware of what they are. Articles in that newsgroup that you should read are listed in Appendix A - "Related Readings." The requirements may seem odd if you're new to FAQs but they are very reasonable for what news.answers is trying to accomplish. Besides, using AUTO-FAQ, it won't be much work to comply with the standards. When you understand the requirements, finish up the AUTO-FAQ configuration for your FAQ and use the FAQ_NOSEND to generate a sample of the FAQ as it would be posted. (Leave out the approval field until instructed what to put in it by the moderator.) Then mail the sample to the moderator - the address is news-answers-request@mit.edu. Wait for either the approval or some comments to return. It's normal to go for a few rounds of revisions before the FAQ is completely ready. (If you read the directions completely, you might get it approved on the first request! That is one of the purposes of AUTO-FAQ.) 2.3.1.1 The faq-maintainers Mail List ------------------------------------- There is also a faq-maintainers mail list. Once your FAQ is ready for posting, you should consider joining it. There are actually 2 lists: faq-maintainers - for discussion and announcements, traffic is "bursty" faq-maintainers-announce - announcements only, low traffic If you join faq-maintainers, you get faq-maintainers-announce too. Send a message to faq-maintainers-request@consensus.com or faq-maintainers-announce-request@mit.edu, depending on which list you want to subscribe to, with "subscribe" in the message body (don't forget the -request when joining or leaving any UseNet mail list!) See the articles in news.answers from Appendix A "Related Readings." 2.3.1.2 Posting to Multiple Moderated Newsgroups ------------------------------------------------ The Internet RFCs ("requests for comments," the defining articles for Internet protocols) do not specify what to do when more than one approval is needed to post an article. Until such a definition is made, it will be sufficient to make a comma-delimited list of approvals with the "approval" attribute, which becomes the Approved: header. For example, the rec.radio.amateur.misc FAQ is cross-posted to news.answers and rec.radio.info, so both moderators' approvals (acquired via e-mail ahead of time) are placed in a single Approved: header. approval="moo-cow-request@Moo.Edu,mars-info-request@mars.base.mil" However, there is one major point of netiquette that you absolutely must follow: YOU MUST HAVE EACH MODERATOR'S APPROVAL TO POST TO THEIR NEWSGROUP BEFORE ANY POSTING WITH AN "APPROVED:" HEADER WILL BE ALLOWED If you fail to do that, you will almost certainly make yourself look like a troublemaker and will find it difficult to get people's cooperation for some time to come. Most moderators will cancel articles that they did not approve. And it's their right to do so. That's just how UseNet works. 2.4 Learning from Others' Mistakes (Pitfalls/Workarounds) --------------------------------------------------------- If we don't learn from each other's mistakes, we will repeat them. Pay atten- tion to the following errors that have been made in the past and try to avoid them. This is not intended to embarrass anyone - no names will be mentioned. Some of these result from ambiguities in the behavior of the auto-faq program as well as classic interoperability problems of network software written according to ambiguous standards (i.e., they may be fixed sometime in the distant future). If you have a learning experience or workaround for a potential pitfall you'd like to share, send e-mail to the author. * Don't accidentally post your FAQ at an unscheduled time. Forgetting to set FAQ_NOSEND and/or FAQ_TEST in the environment will accomplish exactly that. The author did that once... * If you have blank fields in your faq.out file, verify that you aren't missing any required configuration attributes. * AUTO-FAQ by design generates all the primary and secondary news headers that will appear in any posted FAQ. Other FAQ-posting software available on the net may operate differently. One user, after evaluating AUTO-FAQ and another package, decided to use AUTO-FAQ but left the secondary news headers in the FAQ text files. This resulted in redundant secondary headers appearing in the article. On the first attempt, the news.answers moderator sent the FAQ back for editing. The problem went away when the extra headers were removed from the FAQ text. * After one FAQ maintainer obtained approval from the moderator to cross-post his FAQ to news.answers, he decided to post it just to news.answers because he had posted it to his newsgroup just a few days prior. He made a one-time modification to the newsgroup attribute for the FAQ and posted it. Unfortu- nately, the newsgroup attribute is also used for the "Subject:" header so it was posted as "news.answers Frequently Asked Questions" even though it was not on that subject. There are two lessons in this: 1) temporary changes to the newsgroup attribute are not recommended because they can change the subject of the articles and 2) the news.answers moderator does not approve of postings to news.answers which are not cross-posted because they are in conflict with news.answers' effort to conserve network bandwidth. * The InterNetwork News (INN) server does not seem to like the Expires date format that auto-faq generates, even though it is supposedly RFC 1036 standard (see Appendix A - "Related Readings" below). A practical workaround to this is to use an faq-config configuration option combined with some auto-faq "macros" as follows: expires-format="@date(d)@ @date(b)@ @date(Y)@ @date(T)@ -0000" # needed for INN Of course, this header assumes UTC (Coordinated Universal Time), but is both RFC 1036 standard and INN compatible. Part 3 - Keeping up-to-date about AUTO-FAQ ------------------------------------------ This part will tell you how to keep in touch with other AUTO-FAQ users and how to obtain updates. 3.1 The Auto-faq-users Mailing List ----------------------------------- Once you're up and running, or maybe slightly before that, you'll definitely want to subscribe to the auto-faq-users mail list. It is intended for discussion about AUTO-FAQ and notices about new updates. To subscribe, send an e-mail message to the "majordomo" mail list server at majordomo@novia.net The subject of the message does not matter because the majordomo program which will receive your mail will ignore it. (So you may even omit the subject.) The message should contain one line only: subscribe auto-faq-users Majordomo will obtain your e-mail address from your mail headers. It will send you a reply welcoming you to the mail list. From that point on, you will receive copies of all messages sent to the list. You may send mail to the list (i.e. to reply to a message, to ask other users a question, etc.) at the following address: auto-faq-users@novia.net As a final note, if at any time in the future you need to unsubscribe from auto-faq-users (i.e. so you can resubscribe at another site you're moving to) just send mail to the same majordomo@novia.net you used to subscribe. The command to send will look like this unsubscribe auto-faq-users IMPORTANT: as with all mailing lists - send your request to join or leave a list to the control/request address, not the list itself. On any mail list, if you send such a request to everyone on the list, you will annoy a lot of people and make yourself look bad. This is an important item of netiquette to remember. 3.2 Where to Go for Help ------------------------ If you have an urgent need for help in your configuration and you've tried everything you can think of, you aren't out of options. You can send mail to auto-faq-users, as shown above, or to a smaller group of advanced users at the following mail list: auto-faq-help@novia.net The auto-faq-help list consists of the author and a few volunteers. They have real jobs to do so some discretion is requested. However, in a case where you can't get your copy of auto-faq working on your system and you've read this documentation, they are willing to help because they'd like to see another new site run auto-faq and expand its user base. When reporting suspected bugs with AUTO-FAQ, the following advice applies: * Be reasonably sure that it is a bug. Things that are bugs include either AUTO-FAQ or its Configure script crashing, emitting unusual error output, or behaving contrary to how the documentation says it should. * Provide enough information to allow for a proper diagnosis. This usually includes the contents of your faq-config file, the contents of faq.out after setting the FAQ_NOSEND environmental variable to 1 (asssuming AUTO-FAQ will execute successfully), the version of AUTO-FAQ, the name and version of your computer's operating system (the output of "uname -a" is sufficient for Unix and Unix-like operating systems), any unusual error output from either Configure or AUTO-FAQ, and a description of the *exact* steps that led up to encountered bug. It is quite likely that the maintainers will need all or most of the above information anyway, and providing it first saves them from having to ask for it and speeds up getting the problem fixed. * Please be patient. All bug reports are read with interest and are acknowledged, even if they turn out not to be bugs. Do understand that even if it turns out to be a bug, it will require a nontrivial amount of time to diagnose and be properly fixed in the baseline version of AUTO-FAQ (and released as either a patch or a new version). Allow at least 7-10 days after reporting a bug before asking about it again to either auto-faq-help or auto-faq-users. 3.3 Techniques for Helping Other AUTO-FAQ Users ----------------------------------------------- Once you get started with AUTO-FAQ, you may be surprised how quickly you become accustomed to it. Before you know it, you'll be answering other users' questions and helping solve their problems. Here are a few tips. The main thing to remember when helping another AUTO-FAQ user is to duplicate the problem they describe. The author has found that it is useful to create a separate subdirectory for this purpose. Ask the other user for anything you'll need to duplicate their environment - their faq-config file is a must. If they have made any changes to auto-faq or are running a different version than you are, ask for a copy of it. Once the files are ready in the duplicate environment, make a sample FAQ text file. You don't need their full FAQ text - a one-liner with "this is a test" will usually do the trick. Of course, even on single-part FAQs, don't forget the .1 suffix on the file name. Then edit their sample faq-config so the "articledir" attribute points to your test directory. If they use a "newscmd" attribute, you may need to change it but you probably won't use it unless you're testing the news-posting inter- face. Make sure to export FAQ_NOSEND=1 into your environment. From here you mainly want to do test runs and look at the results in faq.out. When you can get it to behave the same as the other user describes, you're mostly done. At that point, it may be obvious or it may not. Look for deviations from the recommended configuration. If necessary, look through the AUTO-FAQ script to determine why the behavior you observed is occurring. If you still can't duplicate the problem after all this, maybe it's something specific to the user's system. In that case, ask more questions and send a problem report to the author. 3.4 Obtaining the Latest Version -------------------------------- The AUTO-FAQ package has been quite stable for the last few years, so there isn't an absolute need to upgrade to the very latest version. In fact, the maintainer has noticed that many users are using versions as far back as 2.4. There is certainly no need to upgrade if the version you have meets your needs, but new versions usually fix significant bugs or add valuable enhancements requested by many users, so you should at least be aware of the changes for each version and how to upgrade. Announcements regarding new versions are made to the auto-faq-users@novia.net mailing list. The latest versions are archived at the AUTO-FAQ FTP site: ftp://ftp.novia.net/customers/pschleck/auto-faq/ 3.5 User Tips Bulletins ----------------------- As an addendum to the manual, the maintainer has chosen to publish occasional "tip sheets" containing condensed, easy-to-use instructions to get the most out of auto-faq. They are sent approximately monthly or bimonthly to the auto-faq-users mailing list. Back issues are available at the AUTO-FAQ anonymous FTP site under the "user-tips" subdirectory (see the file "user-tips/INDEX" for a list of back issues and their abstracts). 3.6 World-Wide Web Home Page ---------------------------- There is now a World-Wide Web Home Page for auto-faq at: http://www.novia.net/~pschleck/auto-faq/ It encompasses all of the above information resources for auto-faq in an easily-browsable hypertext format. Part 4 - Advanced Features -------------------------- This part is entirely optional. If if it looks like too much start-up work, you can save this for later reference. However, you can take advantage of these features later on to customize your FAQ in almost any way you like. 4.1 Using Status Files ---------------------- Introduced in Version 3.0, status files are used to save information between postings. When AUTO-FAQ begins the process of posting a FAQ, it checks for a status file for each part using this expression to generate the path @articledir@/@statusbase@.@part@ where articledir and statusbase are defined in the config file and part is set by AUTO-FAQ to match the part being posted. 4.1.1 Customizing your Status Files ----------------------------------- By default, the message ID and date are saved. But you can customize that with the "savestatus" attribute. The default would look like this savestatus="message-id=@posted_header(Message-ID)@:: date=@date(a)@ @date(d)@ @date(b)@ @date(T)@ @date(Z)@" (That should be one line. It is broken here for formatting reasons.) Using more delimeters "::" you can add more fields that will be available at the next posting. The status attributes will be saved in the same format as the faq-config file. (AUTO-FAQ will add double-quotes around the value before writing it to the status file.) When read back in, each of these fields will have the string "Saved-" prefixed to it. So they are accessed as Saved-message-id and Saved-date. This is already done automatically with the built-in code for the Supersedes: header. So, if you set up the status files, AUTO-FAQ will use them. If/when you find other convenient information to include in your status files, try it out and then send a suggestion to the author. That way it can be included in future versions of AUTO-FAQ and will benefit other users too. 4.1.2 Upgrading from Sequence Files ----------------------------------- If your FAQ uses pre-Version 3.0 sequence files, you can upgrade to status files with a transition period of one posting. Use the following steps: 1. Add the statusbase attribute. Make sure the resulting pathname, including numbered suffixes (.1, .2, .3, etc. like the article texts), will not overwrite any articles or other data. 2. Post the FAQ (or wait for the time that cron will post it.) This will create the status files for each part of your periodic posting. 3. Comment out or remove the seqfile attributes. 4.2 Change Control for Your FAQ ------------------------------- It sometimes is useful for readers to know when their newsgroup's FAQ has changed. Change control programs such as SCCS and RCS can be used to track changes and assign version numbers. AUTO-FAQ supports the use of SCCS, RCS, or any other change control system via the chgctrl-cmd, chgctrl-format, and chgctrl-path attributes. To set up change control using USL-style SCCS: (any AT&T- or USL-derived Unix) In version 3.0 or later: * set chgctrl-type to "usl-sccs" Prior to version 3.0: * set chgctrl-format to ":I: :Dm:/:Dd:/:Dy: :T:" or any other format usable by the prs(1) command (this example will print the version number and date) * leave chgctrl-cmd unset because the defaults support this configuration * check if the default chgctrl-path is acceptable. If you keep your SCCS files in the same directory as the text files or in an "SCCS" directory beneath the same directory, no change is necessary. Otherwise, add the location of your SCCS files to the default path, which is shown below: chgctrl-path="s.%s::SCCS/s.%s" To set up change control using BSD-style SCCS: (BSD, SunOS, DEC Ultrix, etc) In version 3.0 or later: * set chgctrl-type to "bsd-sccs" Prior to version 3.0: * set chgctrl-format to ":I: :Dm:/:Dd:/:Dy: :T:" or any other format usable by the sccs(1) command * set chgctrl-cmd to "sccs prs -d'@chgctrl-format@' %s" * check your chgctrl-path as shown above for the AT&T Unix-style SCCS To set up change control using RCS: In version 3.0 or later: * set chgctrl-type to "rcs" Prior to version 3.0: (RCS support was not available in earlier versions.) To disable the change control features of AUTO-FAQ: * make sure no change control file can be found by the same name as the FAQ files using the chgctrl-path attribute. This is a slight difference as of Version 3.0 - previously, it was possible to leave chgctrl-format unset in order to turn off change control. In order to simplify change control to just setting the "chgctrl-type" attribute, it was necessary to assign default values to chgctrl-format. It is probably not a significant change since, if change control was not in use for AUTO-FAQ, the change control files probably don't exist. 4.3 Customization with @-macros ------------------------------- "@-macros" get their name from the delimeter character that surrounds them. They may be in the value of any attribute in the faq-config file. To use an @-macro, a configuration attribute value may contain a substring enclosed in at-signs "@" which can consist of the name of another attribute or a special function. For example, chgctrl-cmd="prs -d'@chgctrl-format@' %s" expires-format="@date(A)@, @date(d)@ @date(b)@ @date(Y)@ @date(T)@ @date(Z)@" title="@newsgroup@ Answers to Frequently-Asked Questions" In the first line, the attribute called "chgctrl-format" is inserted in the string in place of the name and @'s. In the second example, the date function is called several times with different arguments. The third line is just an additional example of how a macro might be used. The ability to include other configuration attributes is a very powerful feature! You have the ability to create any arbitrarily-named attribute (as long as that name is not used elsewhere by AUTO-FAQ) and then include it in one or more other attributes or headers simply by inserting a macro with its name. The date() function's arguments are the same as the System V "date" command's format letters, except that only the letter is allowed. The following is edited from the System V date man page: a abbreviated weekday name A full weekday name b abbreviated month name B full month name d day of month - 01 to 31 D date as mm/dd/yy e day of month - 1 to 31 (single digits are preceded by a blank) h abbreviated month name (same as b) H hour - 00 to 23 I hour - 01 to 12 j day of year - 001 to 366 m month of year - 01 to 12 M minute - 00 to 59 p string containing AM or PM r time as hh:mm:ss pp, where pp is AM or PM R time as hh:mm S second - 00 to 59 T time as hh:mm:ss w day of week - Sunday = 0 y year within century - 00 to 99 Y year as ccyy (4 digits) Z timezone name The n, t, U, W, x, and X letters from System V are not supported by auto-faq's date function. The posted_header() function is available after each part has been posted and, therefore, is only useful for status files. The parameter is simply the name of a header and the value will be the contents of that header as it was posted. 4.4 User-loadable Header Functions ---------------------------------- The news headers are the biggest concern in automating an FAQ. So it should be no surprise that they used to be the most common area that users made local patches to. This feature practically eliminates the user's need to modify AUTO-FAQ itself for local enhancements. If you need to modify the way AUTO-FAQ handles a particular news header, you can write a PERL function for it and leave it in a separate file that AUTO-FAQ loads "on-the-fly". For example, if your local function sources are in a file called "my.fncs", you can add the following attribute to any FAQ or to your global attributes area: local-func-src="my.fncs" The contents of the "my.fncs" file could include the following trivial example: --sample local functions file------------------------------------------------- sub local_hdr_organization { &pr_header ( "Organization", "some place that hard-codes everything" ); } 1; --end of sample--------------------------------------------------------------- Some rules for local function files: 1. All functions names in the file must be prefixed with "local_hdr_". 2. If you don't follow Rule #1, you could inadvertently (or on purpose) replace an existing function in AUTO-FAQ. Any such replacement is not supported by AUTO-FAQ's architecture. You may do so at your own risk. 3. The remainder of the function name must be the header name in all lower case. Dashes must be replaced with underscores as well. So a function to handle the "Reply-To:" header would be called &local_hdr_reply_to(). 4. any variables and functions within AUTO-FAQ may be used but must be treated as read-only. Modifications of any variables are not supported by AUTO-FAQ's architecture. You may do so at your own risk. 5. use the &pr_header() function to print your header. That will allow your headers to take advantage of @-macros. 6. End your file with a single line "1;" so, if the interpreter gets that far, PERL will claim the evaluation to be a success and you can continue without any warning messages from AUTO-FAQ. Note: Changes have been made in Version 3.0. To support an internal reorgan- ization, pr_header takes separate parameters for the header name and value. The value should not contain a newline (unlike pre-3.0 local functions.) Additional control of the headers can be achieved by modifying the list of built-in headers. This allows you to change the order they appear in. It also allows you to add or remove headers to/from an FAQ's output. Any added headers must be accompanied by a user-loadable local function to handle it. Under most circumstances, these changes are not necessary. They is available for flexibility. Modifications to the header lists are done via the following attributes, shown with their default values: # regular posting mode primary headers post-pri-hdrs="From:Newsgroups:Subject:Message-ID:References:Reply-To:Followup-To:Distribution:Organization:Approved:Expires:Supersedes" # regular posting mode auxiliary/secondary headers post-2nd-hdrs="Posted-By:Archive-Name:Revision:Changes" # test mode primary headers test-pri-hdrs="From:Newsgroups:Subject:Message-ID:References:Reply-To:Followup-To:Distribution:Organization" # test mode mode auxiliary/secondary headers test-2nd-hdrs="Posted-By:Archive-Name:Revision:Changes" # test mode mode tertiary headers (ones that cannot be primaries in a test) test-3rd-hdrs="Approved:Expires:Supersedes" Part 5 - Utility Programs ------------------------- 5.1 txt2dig: creating RFC1153 digests ------------------------------------- There has been plenty of talk on the faq-maintainers mail list about using message digests as a standard FAQ format. Many FAQ maintainers are reluctant to switch because their FAQs are already established and it will take a lot of work to convert them. For a volunteer, that is a completely valid reason not to spend the time to make the change. But, if you're just getting started, maybe you'll want to consider using message digests. The idea is simple but, as usual, "the Devil is in the details." A message digest is a collection of mail-like messages. On mail lists, they may used as be a collection of messages that were sent to the list during an hour or day. In a FAQ, they can be used to logically separate different subjects in a familiar format. An additional advantage comes from some smart newsreading software, like "nn", that can break the FAQ down into its component messages for convenient separate reading. This may be the strongest reason to choose the message digest format. There is still another, though it is a weak reason right now. It may soon be possible to use another script to convert your digest-format FAQ into an HTML (hypertext markup language) document suitable for viewing on the Internet's World-Wide Web (WWW). However, until such a script is completed, it is simply vaporware. The idea was conceived just in time to be mentioned with version 3.2 and will hopefully be included with a future version of AUTO-FAQ. The details of message digests are kept in RFC 1153. (See Appendix A "Related Readings".) However, you don't need to know all the details to use txt2dig because it was made with those details in mind. (For example, txt2dig inserts a table of contents and lines of 30 or 70 hyphens "-" where required.) --example file: preamble------------------------------------------------------ This is a test of the digestify script. It makes RFC1153-compatible output from a series of RFC 822 message files. An advantage to digest news articles is that they are transmitted as one message but some newsreaders, like nn, will "undigestify" them upon arrival. This beginning section is called the preamble. The digestify script will append a table of contents to the preamble before printing the messages. --end of preamble------------------------------------------------------------- --example file: msg01--------------------------------------------------------- From: ikluft@thunder.sbay.org (Ian Kluft) Date: Fri Jan 14 11:49:17 1994 Subject: digestify test This should appear as a message in the digest. --end of msg01---------------------------------------------------------------- --example file: msg02--------------------------------------------------------- From: ikluft@thunder.sbay.org (Ian Kluft) Date: Fri Jan 14 11:50:19 1994 This should also appear as a message in the digest. It doesn't have a subject. ------------------------------ The preceding line of 30 hyphens should have a space prepended to it by digestify so that undigestifiers won't get confused. --end of msg02---------------------------------------------------------------- --example file: msg03--------------------------------------------------------- Subject: [FAQ A3] What should a digest message look like in a FAQ article? Date: Fri Jan 14 11:51:20 1994 Summary: simulation of an actual FAQ message This is a test of how digest messages will commonly look in a FAQ article. There is a Date and a Subject only. This is because the entire digest itself is from you. Each message only needs to have a Subject. A Date header shows how recent the answer is, so it is highly recommended. --end of msg03---------------------------------------------------------------- Cut and paste those into separate files. (You aren't re-typing them, are you? as a FAQ maintainer, you should always remember to automate tasks!) Then run the txt2dig command: txt2dig preamble msg0[123] The output should serve as an example of what digests look like. And now you have a tool to make them! If you choose to use the message digest format in your FAQ, you should have a copy of RFC1153 handy for reference. Appendix A - Related Readings ----------------------------- "Introduction to the *.answers newsgroups" "*.answers submission guidelines" both regularly posted to the *.answers newsgroups (including news.answers), or available via anonymous FTP from: ftp://rtfm.mit.edu/pub/usenet/news.answers/news-answers/ ftp://ftp.uu.net/usenet/news.answers/news-answers/ or via E-mail server: mail-server@rtfm.mit.edu send usenet/news.answers/news-answers/introduction send usenet/news.answers/news-answers/guidelines RFC822 "Standard for the Format of ARPA Internet Text Messages" RFC1036 "Standard for Interchange of Usenet Messages" RFC1153 "Digest Message Format" (optional, this is a style preferred by some FAQ maintainers but not by others - make your own choice) The Internet RFCs can be obtained from ftp://ftp.internic.net/ among other sites. Appendix B - Acknowledgments ----------------------------- Thanks to the users who have provided input based on their installation of the software: Jamie Andrews (jamie@cs.sfu.ca, Burnaby, British Columbia, Canada) Karl Berry (karl@cs.umb.edu, Boston, Massachusetts, USA) Tony Chen (adchen@umaxc.weeg.uiowa.edu, Iowa City, Iowa, USA) Steve Schallehn (steve@matt.ksu.ksu.edu, Manhattan, Kansas, USA) Steve Watt (steve@watt.com, San Jose, California, USA) Anne Bennett (anne@alcor.concordia.ca, Montreal, Quebec, Canada) Thanks to the *.answers moderation team (news-answers-request@mit.edu) for listing AUTO-FAQ in their submission guidelines. Current Maintainer: Paul W. Schleck (auto-faq-maint@novia.net, Omaha, Nebraska, USA) Original Author: Ian Kluft (ikluft@thunder.sbay.org, Santa Clara, California, USA)