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/) |