← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Tools/faqwiz/README

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Tools/faqwiz/README
 
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/)