python/src/Tools/faqwiz/README - toolchain/benchmark - Git at Google

 FAQ Wizard
 ----------

 Author: Guido van Rossum <guido@python.org>
 Version: 1.0
 Date:  6 April 1998


 This is a CGI program that maintains a user-editable FAQ.  It uses RCS
 to keep track of changes to individual FAQ entries.  It is fully
 configurable; everything you might want to change when using this
 program to maintain some other FAQ than the Python FAQ is contained in
 the configuration module, faqconf.py.

 Note that the bulk of the code is not an executable script; it's an
 importable module.  The actual script in cgi-bin is minimal.

 Files:

 faqw.py		executable script to be edited and installed in cgi-bin
 faqwiz.py	main module, lives in same directory as FAQ entry files
 faqconf.py	main configuration module
 faqcust.py	additional local customization module (optional)
 move-faqwiz.sh  Script to move faqwiz entries.


 What's New?
 -----------

 Version 1.0 corrects some minor bugs and uses tab-agnostic
 indentation; it is otherwise unchanged from version 0.9.0.

 Version 0.9.0 uses the re module (Perl style regular expressions) for
 all its regular expression needs, instead of the regex and regsub
 modules (Emacs style).  This affects the syntax for regular
 expressions entered by the user as search strings (with "regular
 expression" checked), hence the version number jump.


 Setup Information
 -----------------

 This assumes you are familiar with Python, with your http server, and
 with running CGI scripts under your http server.  You need Python 1.5
 or better.

 Select a place where the Python modules that constitute the FAQ wizard
 will live (the directory where you unpacked it is an obvious choice).
 This will be called the SRCDIR.  This directory should not be writable
 by other users of your system (since they would be able to execute
 arbitrary code by invoking the FAQ wizard's CGI script).

 Create a dedicated working directory, preferably one that's not
 directly reachable from your http server.  This will be called the
 FAQDIR.  Create a subdirectory named RCS.  Make both the working
 directory and the RCS subdirectory wrld-writable.  (This is essential,
 since the FAQ wizard runs as use nobody, and needs to create
 additional files here!)

 Edit faqconf.py to reflect your setup.  You only need to edit the top
 part, up till the line of all dashes.  The comments should guide you
 in your edits.  (Actually, you can also choose to add your changes to
 faqcust.py and leave faqconf.py alone.  This is essential if you are
 maintaining multiple FAQs; see below.)

 Don't forget to edit the SECTION_TITLES variables to reflect the set
 of section titles for your FAQ!

 Next, edit faqw.py to reflect the pathname of your Python interpreter
 and the values for SRCDIR and FAQDIR that you just chose.  Then
 install faqw.py in your cgi-bin directory.  Make sure that it is
 world-executable.  You should now be able to connect to the FAQ wizard
 by entering the following URL in your web client (subsituting the
 appropriate host and port for "your.web.server", and perhaps
 specifying a different directory for "cgi-bin" if local conventions so
 dictate):

 	http://your.web.server/cgi-bin/faqw.py

 If you are unable to get this working, check your server's error_log
 file.  The documentation for Python's cgi module in the Python Library
 Reference Manual gives plentyu additional information about installing
 and debugging CGI scripts, including setup debugging.  This
 documentation is repeated in the doc string in the cgi module; try
 ``import cgi; print cgi.__doc__''.

 Assuming this works, you should now be able to add the first entry to
 your FAQ using the FAQ wizard interface.  This creates a file
 faq01.001.htp in your working directory and an RCS revision history
 file faq01.001.htp,v in the RCS subdirectory.  You can now exercise
 the other FAQ wizard features (search, index, whole FAQ, what's new,
 roulette, and so on).


 Maintaining Multiple FAQs
 -------------------------

 If you have multiple FAQs, you need a separate FAQDIR per FAQ, and a
 different customization file per FAQ.  The easiest thing to do would
 be to have the faqcust.py for each FAQ live in the FAQDIR for that
 FAQ, but that creates some security concerns, since the FAQDIR must be
 world writable: *if* someone who breaks into your system (or a
 legitimate user) manages to edit the faqcust.py file they can get
 arbitrary code to execute through the FAQ wizard.  Therefore, you will
 need a more complex setup.

 The best way is probably to have a directory that is only writable by
 you for each FAQ, where you place the copy of faqcust.py for that FAQ,
 and have a world-writable subdirectory DATA for the data.  You then
 set FAQDIR to point to the DATA directory and change the faqw.py
 bootstrap script to add FAQDIR/.. to sys.path (in front of SRCDIR, so
 the dummy faqcust.py from SRCDIR is ignored).

 --Guido van Rossum (home page: http://www.python.org/~guido/)
	FAQ Wizard
	----------

	Author: Guido van Rossum <guido@python.org>
	Version: 1.0
	Date: 6 April 1998


	This is a CGI program that maintains a user-editable FAQ. It uses RCS
	to keep track of changes to individual FAQ entries. It is fully
	configurable; everything you might want to change when using this
	program to maintain some other FAQ than the Python FAQ is contained in
	the configuration module, faqconf.py.

	Note that the bulk of the code is not an executable script; it's an
	importable module. The actual script in cgi-bin is minimal.

	Files:

	faqw.py executable script to be edited and installed in cgi-bin
	faqwiz.py main module, lives in same directory as FAQ entry files
	faqconf.py main configuration module
	faqcust.py additional local customization module (optional)
	move-faqwiz.sh Script to move faqwiz entries.


	What's New?
	-----------

	Version 1.0 corrects some minor bugs and uses tab-agnostic
	indentation; it is otherwise unchanged from version 0.9.0.

	Version 0.9.0 uses the re module (Perl style regular expressions) for
	all its regular expression needs, instead of the regex and regsub
	modules (Emacs style). This affects the syntax for regular
	expressions entered by the user as search strings (with "regular
	expression" checked), hence the version number jump.


	Setup Information
	-----------------

	This assumes you are familiar with Python, with your http server, and
	with running CGI scripts under your http server. You need Python 1.5
	or better.

	Select a place where the Python modules that constitute the FAQ wizard
	will live (the directory where you unpacked it is an obvious choice).
	This will be called the SRCDIR. This directory should not be writable
	by other users of your system (since they would be able to execute
	arbitrary code by invoking the FAQ wizard's CGI script).

	Create a dedicated working directory, preferably one that's not
	directly reachable from your http server. This will be called the
	FAQDIR. Create a subdirectory named RCS. Make both the working
	directory and the RCS subdirectory wrld-writable. (This is essential,
	since the FAQ wizard runs as use nobody, and needs to create
	additional files here!)

	Edit faqconf.py to reflect your setup. You only need to edit the top
	part, up till the line of all dashes. The comments should guide you
	in your edits. (Actually, you can also choose to add your changes to
	faqcust.py and leave faqconf.py alone. This is essential if you are
	maintaining multiple FAQs; see below.)

	Don't forget to edit the SECTION_TITLES variables to reflect the set
	of section titles for your FAQ!

	Next, edit faqw.py to reflect the pathname of your Python interpreter
	and the values for SRCDIR and FAQDIR that you just chose. Then
	install faqw.py in your cgi-bin directory. Make sure that it is
	world-executable. You should now be able to connect to the FAQ wizard
	by entering the following URL in your web client (subsituting the
	appropriate host and port for "your.web.server", and perhaps
	specifying a different directory for "cgi-bin" if local conventions so
	dictate):

	http://your.web.server/cgi-bin/faqw.py

	If you are unable to get this working, check your server's error_log
	file. The documentation for Python's cgi module in the Python Library
	Reference Manual gives plentyu additional information about installing
	and debugging CGI scripts, including setup debugging. This
	documentation is repeated in the doc string in the cgi module; try
	``import cgi; print cgi.__doc__''.

	Assuming this works, you should now be able to add the first entry to
	your FAQ using the FAQ wizard interface. This creates a file
	faq01.001.htp in your working directory and an RCS revision history
	file faq01.001.htp,v in the RCS subdirectory. You can now exercise
	the other FAQ wizard features (search, index, whole FAQ, what's new,
	roulette, and so on).


	Maintaining Multiple FAQs
	-------------------------

	If you have multiple FAQs, you need a separate FAQDIR per FAQ, and a
	different customization file per FAQ. The easiest thing to do would
	be to have the faqcust.py for each FAQ live in the FAQDIR for that
	FAQ, but that creates some security concerns, since the FAQDIR must be
	world writable: if someone who breaks into your system (or a
	legitimate user) manages to edit the faqcust.py file they can get
	arbitrary code to execute through the FAQ wizard. Therefore, you will
	need a more complex setup.

	The best way is probably to have a directory that is only writable by
	you for each FAQ, where you place the copy of faqcust.py for that FAQ,
	and have a world-writable subdirectory DATA for the data. You then
	set FAQDIR to point to the DATA directory and change the faqw.py
	bootstrap script to add FAQDIR/.. to sys.path (in front of SRCDIR, so
	the dummy faqcust.py from SRCDIR is ignored).

	--Guido van Rossum (home page: http://www.python.org/~guido/)