FAQ Wizard

----------

Author: Guido van Rossum <guido@python.org>

Version: 1.0

Date:  6 April 1998

This is a CGI program that maintains a user-editable FAQ.  It uses RCS

to keep track of changes to individual FAQ entries.  It is fully

configurable; everything you might want to change when using this

program to maintain some other FAQ than the Python FAQ is contained in

the configuration module, faqconf.py.

Note that the bulk of the code is not an executable script; it's an

importable module.  The actual script in cgi-bin is minimal.

Files:

faqw.py		executable script to be edited and installed in cgi-bin

faqwiz.py	main module, lives in same directory as FAQ entry files

faqconf.py	main configuration module

faqcust.py	additional local customization module (optional)

move-faqwiz.sh  Script to move faqwiz entries.

What's New?

-----------

Version 1.0 corrects some minor bugs and uses tab-agnostic

indentation; it is otherwise unchanged from version 0.9.0.

Version 0.9.0 uses the re module (Perl style regular expressions) for

all its regular expression needs, instead of the regex and regsub

modules (Emacs style).  This affects the syntax for regular

expressions entered by the user as search strings (with "regular

expression" checked), hence the version number jump.

Setup Information

-----------------

This assumes you are familiar with Python, with your http server, and

with running CGI scripts under your http server.  You need Python 1.5

or better.

Select a place where the Python modules that constitute the FAQ wizard

will live (the directory where you unpacked it is an obvious choice).

This will be called the SRCDIR.  This directory should not be writable

by other users of your system (since they would be able to execute

arbitrary code by invoking the FAQ wizard's CGI script).

Create a dedicated working directory, preferably one that's not

directly reachable from your http server.  This will be called the

FAQDIR.  Create a subdirectory named RCS.  Make both the working

directory and the RCS subdirectory wrld-writable.  (This is essential,

since the FAQ wizard runs as use nobody, and needs to create

additional files here!)

Edit faqconf.py to reflect your setup.  You only need to edit the top

part, up till the line of all dashes.  The comments should guide you

in your edits.  (Actually, you can also choose to add your changes to

faqcust.py and leave faqconf.py alone.  This is essential if you are

maintaining multiple FAQs; see below.)

Don't forget to edit the SECTION_TITLES variables to reflect the set

of section titles for your FAQ!

Next, edit faqw.py to reflect the pathname of your Python interpreter

and the values for SRCDIR and FAQDIR that you just chose.  Then

install faqw.py in your cgi-bin directory.  Make sure that it is

world-executable.  You should now be able to connect to the FAQ wizard

by entering the following URL in your web client (subsituting the

appropriate host and port for "your.web.server", and perhaps

specifying a different directory for "cgi-bin" if local conventions so

dictate):

	http://your.web.server/cgi-bin/faqw.py

If you are unable to get this working, check your server's error_log

file.  The documentation for Python's cgi module in the Python Library

Reference Manual gives plentyu additional information about installing

and debugging CGI scripts, including setup debugging.  This

documentation is repeated in the doc string in the cgi module; try

``import cgi; print cgi.__doc__''.

Assuming this works, you should now be able to add the first entry to

your FAQ using the FAQ wizard interface.  This creates a file

faq01.001.htp in your working directory and an RCS revision history

file faq01.001.htp,v in the RCS subdirectory.  You can now exercise

the other FAQ wizard features (search, index, whole FAQ, what's new,

roulette, and so on).

Maintaining Multiple FAQs

-------------------------

If you have multiple FAQs, you need a separate FAQDIR per FAQ, and a

different customization file per FAQ.  The easiest thing to do would

be to have the faqcust.py for each FAQ live in the FAQDIR for that

FAQ, but that creates some security concerns, since the FAQDIR must be

world writable: *if* someone who breaks into your system (or a

legitimate user) manages to edit the faqcust.py file they can get

arbitrary code to execute through the FAQ wizard.  Therefore, you will

need a more complex setup.

The best way is probably to have a directory that is only writable by

you for each FAQ, where you place the copy of faqcust.py for that FAQ,

and have a world-writable subdirectory DATA for the data.  You then

set FAQDIR to point to the DATA directory and change the faqw.py

bootstrap script to add FAQDIR/.. to sys.path (in front of SRCDIR, so

the dummy faqcust.py from SRCDIR is ignored).

--Guido van Rossum (home page: http://www.python.org/~guido/)