blob: a1e4d44047825285885244bc28cdf412fdd1cbcc [file] [log] [blame]
Guido van Rossum132e1891997-05-26 20:15:09 +00001FAQ Wizard
2----------
3
4Author: Guido van Rossum <guido@python.org>
Guido van Rossum36dfbcf1998-04-06 14:25:36 +00005Version: 1.0
6Date: 6 April 1998
Guido van Rossum132e1891997-05-26 20:15:09 +00007
8
9This is a CGI program that maintains a user-editable FAQ. It uses RCS
10to keep track of changes to individual FAQ entries. It is fully
11configurable; everything you might want to change when using this
12program to maintain some other FAQ than the Python FAQ is contained in
13the configuration module, faqconf.py.
14
Guido van Rossumdafce6d1997-06-02 23:10:06 +000015Note that the bulk of the code is not an executable script; it's an
16importable module. The actual script in cgi-bin is minimal.
Guido van Rossum132e1891997-05-26 20:15:09 +000017
18Files:
19
20faqw.py executable script to be edited and installed in cgi-bin
Guido van Rossumb1823ad1997-12-09 16:04:46 +000021faqwiz.py main module, lives in same directory as FAQ entry files
Guido van Rossum132e1891997-05-26 20:15:09 +000022faqconf.py main configuration module
23faqcust.py additional local customization module (optional)
Martin v. Löwis73e61872002-03-18 08:56:23 +000024move-faqwiz.sh Script to move faqwiz entries.
Guido van Rossum132e1891997-05-26 20:15:09 +000025
Guido van Rossum80e57fb1997-12-21 07:05:32 +000026
27What's New?
28-----------
29
Guido van Rossum36dfbcf1998-04-06 14:25:36 +000030Version 1.0 corrects some minor bugs and uses tab-agnostic
31indentation; it is otherwise unchanged from version 0.9.0.
32
Guido van Rossum80e57fb1997-12-21 07:05:32 +000033Version 0.9.0 uses the re module (Perl style regular expressions) for
34all its regular expression needs, instead of the regex and regsub
35modules (Emacs style). This affects the syntax for regular
36expressions entered by the user as search strings (with "regular
37expression" checked), hence the version number jump.
38
39
Guido van Rossumdafce6d1997-06-02 23:10:06 +000040Setup Information
41-----------------
42
43This assumes you are familiar with Python, with your http server, and
Guido van Rossum685fe831998-04-08 21:37:13 +000044with running CGI scripts under your http server. You need Python 1.5
Guido van Rossumf1ead1a1997-08-28 02:38:01 +000045or better.
46
47Select a place where the Python modules that constitute the FAQ wizard
48will live (the directory where you unpacked it is an obvious choice).
49This will be called the SRCDIR. This directory should not be writable
50by other users of your system (since they would be able to execute
51arbitrary code by invoking the FAQ wizard's CGI script).
Guido van Rossumdafce6d1997-06-02 23:10:06 +000052
53Create a dedicated working directory, preferably one that's not
Guido van Rossumf1ead1a1997-08-28 02:38:01 +000054directly reachable from your http server. This will be called the
55FAQDIR. Create a subdirectory named RCS. Make both the working
56directory and the RCS subdirectory wrld-writable. (This is essential,
57since the FAQ wizard runs as use nobody, and needs to create
58additional files here!)
Guido van Rossumdafce6d1997-06-02 23:10:06 +000059
60Edit faqconf.py to reflect your setup. You only need to edit the top
61part, up till the line of all dashes. The comments should guide you
Guido van Rossum8c5fa911997-08-28 02:38:54 +000062in your edits. (Actually, you can also choose to add your changes to
63faqcust.py and leave faqconf.py alone. This is essential if you are
64maintaining multiple FAQs; see below.)
Guido van Rossumdafce6d1997-06-02 23:10:06 +000065
66Don't forget to edit the SECTION_TITLES variables to reflect the set
67of section titles for your FAQ!
68
69Next, edit faqw.py to reflect the pathname of your Python interpreter
Guido van Rossumf1ead1a1997-08-28 02:38:01 +000070and the values for SRCDIR and FAQDIR that you just chose. Then
71install faqw.py in your cgi-bin directory. Make sure that it is
72world-executable. You should now be able to connect to the FAQ wizard
73by entering the following URL in your web client (subsituting the
74appropriate host and port for "your.web.server", and perhaps
75specifying a different directory for "cgi-bin" if local conventions so
76dictate):
Guido van Rossumdafce6d1997-06-02 23:10:06 +000077
78 http://your.web.server/cgi-bin/faqw.py
79
80If you are unable to get this working, check your server's error_log
81file. The documentation for Python's cgi module in the Python Library
82Reference Manual gives plentyu additional information about installing
83and debugging CGI scripts, including setup debugging. This
84documentation is repeated in the doc string in the cgi module; try
85``import cgi; print cgi.__doc__''.
86
Guido van Rossumf1ead1a1997-08-28 02:38:01 +000087Assuming this works, you should now be able to add the first entry to
Guido van Rossumdafce6d1997-06-02 23:10:06 +000088your FAQ using the FAQ wizard interface. This creates a file
89faq01.001.htp in your working directory and an RCS revision history
90file faq01.001.htp,v in the RCS subdirectory. You can now exercise
91the other FAQ wizard features (search, index, whole FAQ, what's new,
Guido van Rossumf1ead1a1997-08-28 02:38:01 +000092roulette, and so on).
Guido van Rossumd7918fb1997-05-30 12:01:24 +000093
Guido van Rossum80e57fb1997-12-21 07:05:32 +000094
Guido van Rossum8c5fa911997-08-28 02:38:54 +000095Maintaining Multiple FAQs
96-------------------------
97
98If you have multiple FAQs, you need a separate FAQDIR per FAQ, and a
99different customization file per FAQ. The easiest thing to do would
100be to have the faqcust.py for each FAQ live in the FAQDIR for that
101FAQ, but that creates some security concerns, since the FAQDIR must be
102world writable: *if* someone who breaks into your system (or a
103legitimate user) manages to edit the faqcust.py file they can get
104arbitrary code to execute through the FAQ wizard. Therefore, you will
105need a more complex setup.
106
107The best way is probably to have a directory that is only writable by
108you for each FAQ, where you place the copy of faqcust.py for that FAQ,
109and have a world-writable subdirectory DATA for the data. You then
110set FAQDIR to point to the DATA directory and change the faqw.py
111bootstrap script to add FAQDIR/.. to sys.path (in front of SRCDIR, so
112the dummy faqcust.py from SRCDIR is ignored).
113
Guido van Rossum132e1891997-05-26 20:15:09 +0000114--Guido van Rossum (home page: http://www.python.org/~guido/)