mirror of
https://github.com/python/cpython.git
synced 2025-10-31 05:31:20 +00:00
113 lines
4.7 KiB
Text
113 lines
4.7 KiB
Text
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)
|
|
|
|
|
|
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/)
|