From gonix.com!owner-auto-faq-users@oasis.novia.net Sun May 19 15:23:17 1996 Received: (from majordom@localhost) by oasis.novia.net (8.7.5/Novia) id PAA1080 7 for auto-faq-users-outgoing; Sun, 19 May 1996 15:18:13 -0500 (CDT) Received: from gonix.gonix.com (gonix.gonix.com [199.171.32.3]) by oasis.novia. net (8.7.5/Novia) with SMTP id PAA10788 for ; Sun, 19 May 1996 15:18:07 -0500 (CDT) From: pschleck@gonix.gonix.com (Paul W Schleck KD3FU) Message-Id: <9605192017.AA16824@gonix.gonix.com> Subject: auto-faq User Tips #4 To: auto-faq-users@novia.net Date: Sun, 19 May 1996 15:17:16 -0500 (CDT) Cc: faq-maintainers@consensus.com Reply-To: auto-faq-maint@novia.net X-Mailer: ELM [version 2.4 PL20] Content-Type: text Sender: owner-auto-faq-users@oasis.novia.net Precedence: bulk Status: RO (As you've probably guessed by now, my problems reaching faq-maintainers@consensus.com have been solved. It required a bit of hacking with routing on the Gonix side to get my host to talk SMTP with the Consensus mail host. Thanks go to the Gonix administrators, including Jack Winslade, for getting the problem solved). This is the auto-faq User Tips bulletin #4. User Tips is an occasional, maybe once every few months, bulletin of subtle hints and tricks (as well as bug reports and version updates) for the auto-faq FAQ management and posting package. It is posted to auto-faq-users@novia.net and faq-maintainers@consensus.com. Back Issues ----------- Back issues of User Tips are available from the auto-faq WWW Page: http://www.novia.net/~pschleck/auto-faq/user-tips/ anonymous FTP site: ftp://ftp.novia.net/customers/pschleck/auto-faq/user-tips/ and ftpmail server: Send a mail message to ftpmail@ftp.novia.net with the following commands in the message body: open uuencode get /customers/pschleck/auto-faq/user-tips/INDEX get /customers/pschleck/auto-faq/user-tips/1 get /customers/pschleck/auto-faq/user-tips/2 get /customers/pschleck/auto-faq/user-tips/3 etc... Maintainer Hiatus ----------------- Yes, it really was back in November of 1995 when I sent the last User Tips bulletin. Work and school have kept me quite busy this spring (one more class until graduation, yeah!), but I have been working behind-the-scenes on several auto-faq-related issues, some of which are discussed in this bulletin. The auto-faq-users Mailing List is now Subscriber-Only ------------------------------------------------------ I regret that this was necessary, but an almost weekly barrage of spam articles (most notably the Magazine Subscription Spam from AOL users) has made it necessary to configure auto-faq-users as a private mailing list on the list server. All interested parties are still welcome to participate, they just now must subscribe to be able to send to the mailing list. To subscribe, send E-mail to auto-faq-users-request@novia.net with the following in the body of the message: subscribe auto-faq-users An automated acknowledgement and welcome message should follow shortly. What is the "news library" that Configure asks for during auto-faq setup? ------------------------------------------------------------------------- This has been a relatively frequent question at the auto-faq Help Desk (auto-faq-help@novia.net), so I feel it worthwhile to answer in this bulletin. Perhaps the install script should phrase the question a bit better (one of my goals for 3.3 before it goes final is to have Configure explain this in a bit more detail, possibly finding the right copy of inews). What it's asking for is the path to your inews script (usually it's found under /usr/lib/news with two data files called "active" and "newsgroups"; this is true whether or not your news spool is on another machine as these files and utilities are used by your newsreader client). Try typing the following command: find / -name inews -print It should find at least one suitable copy. Insert the directory path where it is found at the configure prompt above. If no copies of inews are returned from the find, this means that your host is probably not set up with any kind of news reading or posting software. Getting this problem solved is more the domain of your local news administrator (mail sent to "news" or "usenet" works in most cases). Perl 5-compatible auto-faq 3.3 still in beta test ------------------------------------------------- The Perl 5-compatible version of auto-faq, 3.3 beta, has gotten stable enough to use in an operational environment (I use it myself for the Amateur Radio Elmers Resource Directory). It has been trivially tested against Perl 4.036, 5.001, 5.001m, and 5.002. I would enthusiastically welcome any opportunity for expert users to try it out before I release it to the FAQ maintainer community as a final version (the impact of the RCS bug, discussed in User Tips #3, underscores the need for thorough testing in as wide a range of environments and interfaces as possible). Version 3.3 also incorporates all of the patches applied to 3.2. Users who may not necessarily be interested in extensive testing and evaluation, but wish to try a Perl 5-compatible version and are willing to accept the risks of using an experimental version, are also welcome. If you are interested, please send me E-mail and I will provide you with a copy of 3.3 beta in a standard release package. Using auto-faq to post HTML-based FAQ's --------------------------------------- A frequently-asked question on the faq-maintainers mailing list is how to write FAQ's for the World-Wide Web that can also be converted to straight ASCII to post to Usenet News. Since auto-faq uses article files that only contain the body, and then adds primary and auxilliary news headers for posting, this is actually quite easy. First, take your text-based document and convert it to HTML. Many strategies and HTML style guides exist. HTML authoring is beyond the scope of this bulletin, and the auto-faq-users and faq-maintainers mailing lists, so I'll refer you to the following references for more information: World-Wide Web FAQ (index of Web sites, pick the one closest to you): ftp://rtfm.mit.edu/pub/usenet/news.answers/www/faq/intro A Beginner's Guide to HTML: http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html To convert the HTML file to ASCII, invoke the Lynx text-based browser as follows: lynx -dump faq.html > faq.1 Where faq.html is your FAQ document converted to HTML. The .1 suffix is used by auto-faq to recognize it as an FAQ article body. If you have more than part of a given FAQ, you can use the auto-faq suffix and the HTML suffix together, e.g.: lynx -dump faq.1.html > faq.1 lynx -dump faq.2.html > faq.2 ... etc. I've found it useful to capture the above commands, with target testing, in a Unix "Makefile" as follows: all: faq.1 faq.2 faq.1: faq.1.html lynx -dump faq.1.html > faq.1 faq.2: faq.2.html lynx -dump faq.2.html > faq.2 Make sure that you have a single tab character in front of the lynx commands. Updates to your HTML files can be migrated to your ASCII article bodies by typing: make For more information about Unix make, consult your system's manual pages by typing the following command: man make Using auto-faq to post PGP-signed FAQ's --------------------------------------- FAQ articles cross-posted to the *.answers newsgroups may be PGP-signed, though the posting guidelines require that the PGP-signed part begin below the auxilliary headers. Like the HTML example above, this is also very easy with auto-faq. As with HTML authoring, the use of PGP is also beyond the scope of this bulletin and the mailing lists. There may also be local export and usage restrictions for software that uses strong encryption that you should be aware of. Refer to the following reference for more information about PGP: PGP Frequently-Asked Questions: ftp://rtfm.mit.edu/pub/usenet/news.answers/pgp-faq/ If you are maintaining your FAQ article body as ASCII text only, you should save it as a file other than the one used by auto-faq (the *.txt suffix is a good choice). To add a PGP signature to your FAQ, type: pgp -sat faq.txt cp faq.txt.asc faq.1 For multi-part FAQ's: pgp -sat faq.1.txt pgp -sat faq.2.txt cp faq.1.txt.asc faq.1 cp faq.2.txt.asc faq.2 If you are combining both HTML conversion and PGP signatures, add the following commands before the pgp commands above: lynx -dump faq.1.html > faq.1.txt lynx -dump faq.2 html > faq.2.txt This may be represented in the following Makefile rules. I recommend a separate "pgp" target so that you can convert (and check) your article multiple times before signing your article once before posting. The Unix make rules for just signing your articles with PGP are: pgp: faq.1 faq.2 faq.1: pgp -sat faq.1.txt cp faq.1.txt.asc faq.1 faq.2: pgp -sat faq.2.txt cp faq.2.txt.asc faq.2 Add the following rules to convert your HTML-based FAQ documents to ASCII before PGP-signing them: all: faq.1.txt faq.2.txt faq.1.txt: lynx -dump faq.1.html > faq.1.txt faq.2.txt lynx -dump faq.2.html > faq.2.txt To convert your documents, type: make To sign your documents, type: make pgp (I realize that the above rules and suffix conventions are a bit complicated. Personal experience setting them up has demonstrated that they are probably the simplest way to represent the dependencies without confusing auto-faq, lynx, pgp, or Unix make). Still looking for a Help Desk volunteer --------------------------------------- It's still just Ian Kluft and myself. Correspondence to the auto-faq-help@novia.net Help Desk mailbox has been relatively light (maybe one or two messages a month that have usually required only brief responses). We would welcome anyone, even someone who is a little too busy or underqualified to actually reply to correspondence right now, but who can read the mail for a while and get up to speed for the near future. One of the reasons that auto-faq is a viable and maintained utility to this day is that I was able to almost seamlessly take over from Ian because I had worked closely with him on enhancements, bug-fixes, and handling user correspondence. I'd like to make sure that auto-faq remains viable for the future by having at least one or two qualified people who can cover for me either temporarily or permanently. (I'm not going anywhere anytime soon, but it's always a good idea to have a contingency plan. Certainly no one should feel obligated to have to take over either, but getting involved has a way of making one feel like part of a team, and be somewhat protective of their creations and contributions :-). If you'd like to volunteer, or simply discuss what volunteering would involve, drop me a line. auto-faq 4.0 ------------ I'm still contemplating a 4.0. Though it will probably be backwards-compatible with 3.x configuration files, it will use enhanced features of Perl 5 such as object-orientation (and hence won't be compatible with Perl 4.036 or earlier). Other ideas I've been considering include: - Allowing static and dynamic header customization through object-oriented inheritance; auto-faq 3.x allows this through a quite well-conceived, but still somewhat complex and kludgy (sorry, Ian! :-) extension mechanism that takes advantage of the interchangability of variables and functions in Perl 4. (To be more fully described in a future issue of User Tips). - Capture the HTML and PGP tool integration rules and target dependencies described above as a seamless user option (possibly incorporating an interface to the Unix "make" utility) - Providing either a compatibility mode or conversion utility to allow FAQ maintainers who are currently using Jon Kamens' post_faq.pl utility to easily migrate to auto-faq (I consider both auto-faq and post_faq.pl to be excellent utilities, though clearly they have slightly different features and meet slightly different needs). I initially planned to begin work on this sometime this summer. However, a dearth of feedback, combined with delays in fully beta-testing 3.3., may push this back somewhat. If you want to see this happen, please help me out with good feedback and suggestions. Coming up in a future auto-faq User Tips: ----------------------------------------- - Further updates on auto-faq 3.3 beta - Even further header customization of auto-faq using user-supplied extension functions written in Perl that can be evaluated by auto-faq without modifying the script itself (another powerful capability of auto-faq 3.x). - More updates on auto-faq 4.0 -- Paul W. Schleck auto-faq-maint@novia.net auto-faq Maintainer