Home | History | Annotate | only in /external/python/cpython2/Tools/faqwiz
Up to higher level directory
NameDateSize
faqconf.py22-Oct-202014.8K
faqcust.py22-Oct-202075
faqw.py22-Oct-20201.1K
faqwiz.py22-Oct-202024.2K
move-faqwiz.sh22-Oct-20201.2K
README22-Oct-20204.7K

README

      1 FAQ Wizard
      2 ----------
      3 
      4 Author: Guido van Rossum <guido (a] 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/)
    115