1FAQ Wizard 2---------- 3 4Author: Guido van Rossum <guido@python.org> 5Version: 1.0 6Date: 6 April 1998 7 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 15Note that the bulk of the code is not an executable script; it's an 16importable module. The actual script in cgi-bin is minimal. 17 18Files: 19 20faqw.py executable script to be edited and installed in cgi-bin 21faqwiz.py main module, lives in same directory as FAQ entry files 22faqconf.py main configuration module 23faqcust.py additional local customization module (optional) 24move-faqwiz.sh Script to move faqwiz entries. 25 26 27What's New? 28----------- 29 30Version 1.0 corrects some minor bugs and uses tab-agnostic 31indentation; it is otherwise unchanged from version 0.9.0. 32 33Version 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 40Setup Information 41----------------- 42 43This assumes you are familiar with Python, with your http server, and 44with running CGI scripts under your http server. You need Python 1.5 45or 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). 52 53Create a dedicated working directory, preferably one that's not 54directly 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!) 59 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 62in 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.) 65 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 70and 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): 77 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 87Assuming this works, you should now be able to add the first entry to 88your 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, 92roulette, and so on). 93 94 95Maintaining 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 114--Guido van Rossum (home page: http://www.python.org/~guido/) 115