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