Index: captcha.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/captcha/captcha.module,v
retrieving revision 1.42.2.21
diff -u -b -B -u -p -r1.42.2.21 captcha.module
--- captcha.module	17 Aug 2007 20:57:23 -0000	1.42.2.21
+++ captcha.module	19 Aug 2007 22:18:27 -0000
@@ -378,10 +378,11 @@ function captcha_form_alter($form_id, &$
  */
 function captcha_validate($form_values) {
   // Get answer and preprocess if needed
-  $captcha_response = $form_values['#post']['captcha_response'];
   $validationdata = $form_values['validationdata']['#value'];
   if ($validationdata['preprocess']) {
-    $captcha_response = module_invoke($validationdata['module'], 'captcha', 'preprocess', $validationdata['type'], $captcha_response);
+    $captcha_response = module_invoke($validationdata['module'], 'captcha', 'preprocess', $validationdata['type'], $form_values['#post']);
+  } else {
+    $captcha_response = $form_values['#post']['captcha_response'];
   }
   $form_id = $validationdata['form_id'];
   $captcha_token = $form_values['#post']['captcha_token'];
Index: captcha_api.txt
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/captcha/Attic/captcha_api.txt,v
retrieving revision 1.1.4.5
diff -u -b -B -u -p -r1.1.4.5 captcha_api.txt
--- captcha_api.txt	17 Aug 2007 18:43:13 -0000	1.1.4.5
+++ captcha_api.txt	19 Aug 2007 22:18:27 -0000
@@ -23,7 +23,7 @@ Let's give a simple example to make this
 We create the captcha challenge 'Foo captcha', which requires the user to
 enter "foo" in a textfield.
 
-"""
+<?php
 /**
  * Implementation of hook_captcha().
  */
@@ -44,7 +44,7 @@ function foo_captcha_captcha($op, $captc
       break;
   }
 }
-"""
+?>
 
 Validation of the answer against the solution and other stuff is done by the
 base captcha module.
@@ -60,12 +60,12 @@ Optionally you could put your module in 
 For our simple foo captcha module this would mean the following lines in the
 file foo_captcha.info:
 
-"""
+<code>
 name = "Foo captcha"
 description = "The foo captcha requires the user to enter the word 'foo'."
 package = "Spam control"
 dependencies = captcha
-"""
+</code>
 
 
 
@@ -78,7 +78,7 @@ MENU_LOCAL_TASK menu entry under 'admin/
 
 For our simple foo captcha module this would mean:
 
-"""
+<?php
 /**
  * Implementation of hook_menu().
  */
@@ -95,7 +95,7 @@ function foo_captcha_menu($may_cache) {
   }
   return $items;
 }
-"""
+?>
 
 You should of course implement a function foo_captcha_settings_form() which
 returns the form of your configuration page.
@@ -109,7 +109,7 @@ normal hook_help() system.
 
 For our simple foo captcha module this would mean:
 
-"""
+<?php
 /**
  * Implementation of hook_help().
  */
@@ -120,19 +120,22 @@ function foo_captcha_help($section) {
   }
   return $output;
 }
-"""
+?>
 
 
-=== Optional: preprocess the response ===
+=== Optional: preprocess the response or create multi widget challenges ===
 In some situations it could be necessary to preprocess the response before
-letting the captcha module validate it. For example: if you want the validation
+letting the captcha module validate it. For example, if you want the validation
 to be case insensitive, you could convert the reponse to lower case.
-To enable response preprocessing:
+Or you want to create a captcha challenge that involves several form items.
+Remember that without preprocesssing, the captcha API would only validate
+one form item, named 'captcha_response'.
+To make this possible, the captcha API provides a 'preprocess' hook.
 
-* Add a non zero 'preprocess' entry to $captcha in the 'generate' part of
-  hook_captcha(). E.g.:
+To enable preprocessing, you have to add a non false 'preprocess' entry
+to $captcha in the 'generate' part of hook_captcha(). E.g.:
 
-"""
+<?php
 function foo_captcha_captcha($op, $captcha_type='') {
   switch($op) {
     ...
@@ -141,20 +144,42 @@ function foo_captcha_captcha($op, $captc
         ...
         $captcha['preprocess'] = TRUE,
         ...
-"""
+?>
 
-* Add a 'preprocess' operation to hook_captcha() and add a $response argument
-  to the function signature. E.g.:
+To implement the preprocesssing itself: add a 'preprocess' operation to
+hook_captcha() and add a $post_data argument to the function signature.
+This array $post_data will contain all the submitted data, so you are not
+limited to one form item ('captcha_response'). You should return the preprocessed
+answer, which will be validated against the solution by the base captcha module.
+
+E.g. convert to lower case:
+<?php
+function foo_captcha_captcha($op, $captcha_type='', $post_data=array()) {
+  switch($op) {
+    ...
+    case 'preprocess':
+      if ($captcha_type == "Foo captcha") {
+        $captcha_response = $post_data['captcha_response'];
+        return strtolower($captcha_response);
+      }
+      break;
+    ...
+?>
 
-"""
-function foo_captcha_captcha($op, $captcha_type='', $response='') {
+E.g. combine two form items:
+<?php
+function foo_captcha_captcha($op, $captcha_type='', $post_data=array()) {
   switch($op) {
     ...
     case 'preprocess':
       if ($captcha_type == "Foo captcha") {
-        return strtolower($response);
+        return $post_data['captcha_response'] . $post_data['captcha_response2'];
       }
       break;
     ...
-"""
+?>
 
+Because of this preprocessing, it is not required any more to use a form item
+called 'captcha_response'. It is however a good idea to call the most
+important form item 'captcha_response', because this one will be highlighted
+when the captcha is answered incorrectly.