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 PAA10807 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 <auto-faq-users@novia.net>; 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 <Your Name>
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