Merge pull request #981 from nep/nep-patch-captcha

Improving CAPTCHA documentation

Author: TomJaeger

docs/control-panel/settings/captcha.md

@@ -17,15 +17,19 @@ This section of the Control Panel allows you to set the [CAPTCHA](security/captc
 
 ### Require CAPTCHA?
 
-If you enable this preference, then site visitors will be required to pass a CAPTCHA to submit any front-end form, including Channel Form, comment forms, contact forms, and member registrations. If members are logged in, they will not have to enter a CAPTCHA unless the [Require CAPTCHA while logged in?](#require-captcha-while-logged-in) preference is enabled.
+If you enable this preference, then site visitors will be required to pass a CAPTCHA to submit any front-end form, including [channel forms](security/captchas.md#channel-forms), [comment forms](security/captchas.md#comment-forms), contact and tell-a-friend email forms](#contact-and-tell-a-friend-email-forms), and [member registrations](security/captchas.md#member-registration-forms). 
+
+If members are logged in, they will not have to enter a CAPTCHA unless the [Require CAPTCHA while logged in?](#require-captcha-while-logged-in) preference is enabled.
+
+Superadmins are not required to submit a captcha and are never shown one.
 
 ### Require CAPTCHA while logged in?
 
 If you enable this preference, then even members who are logged in will need to fill out CAPTCHA information in order to post, for example, comments (assuming you've enabled CAPTCHA support for comment posting). If you disable this setting, then members who are logged in will bypass the CAPTCHA check.
 
 ### Use reCAPTCHA v3?
 
-If you enable this preference then the system will use reCAPTCHA v3 in place of the built-in image based solution.
+If you enable this preference then the system will use reCAPTCHA v3 in place of the built-in image based solution. You will also want to ensure that you [update any code](security/captchas.md#captcha-code) used to output CAPTCHAs on your site.
 
 ## Built-in CAPTCHA Settings
 
@@ -57,7 +61,9 @@ If you do not know what to use for your full server path, contact your Host or s
 
 ## reCAPTCHA v3 Settings
 
-If you wish to use (Google reCAPTCHA v3)[https://cloud.google.com/security/products/recaptcha#how-it-works] as a replacement for the built-in functionality, you will need to ensure that the site is set up with Google with the required site key and secret. Note that there is currently a monthly limit on the number of free CAPTCHAs that Google provides. See https://www.google.com/recaptcha/admin/create
+If you wish to use (Google reCAPTCHA v3)[https://cloud.google.com/security/products/recaptcha#how-it-works] as a replacement for the built-in functionality, you will need to ensure that the site is set up with Google with the required site key and secret.
+
+Note that there is currently a monthly limit on the number of free CAPTCHAs that Google provides. See https://www.google.com/recaptcha/admin/create
 
 ### reCAPTCHA site key
 

docs/security/captchas.md

@@ -11,52 +11,68 @@
 
 [TOC]
 
-ExpressionEngine supports what are known as "CAPTCHAs", or Completely Automated Public Turing tests to tell Computers and Humans Apart. A CAPTCHA is a computer-generated test that humans can easily pass, but that is computationally difficult for a computer to do.
+A CAPTCHA, as a general concept, is a computer-generated test that humans can easily pass, but that is computationally difficult for a computer to do. They are used when you want to ensure that a human is performing an action, not an automated script -- often to block spam.
 
-So how does this work? An image is generated in real time for a user loading a web page. This image contains a word that the user must enter in a form. The concept is effective because computers are generally not very good at reading images, but it is something humans can do with little effort.
+ExpressionEngine has built-in support for CAPTCHAs (Completely Automated Public Turing tests to tell Computers and Humans Apart), and can also use (Google's reCAPTCHA v3)[https://cloud.google.com/security/products/recaptcha].
+
+So how does the built-in CAPTCHA functionality work? 
+
+When a user loads a web page with a form protected by a CAPTCHA, EE generates a unique image in real time. This image contains a word that the user must enter when they submit a form. The CAPTCHA is effective because computers are generally not very good at reading images, but it is something humans can do with little effort.
 
 In ExpressionEngine, CAPTCHAs can be used in several places:
 
-- [CAPTCHAs](#captchas) 
-- [Comment Forms](#comment-forms) 
-- [Member Registration Form](#member-registration-form)
-- [Contact and Tell-a-Friend Email Forms](#contact-and-tell-a-friend-email-forms) 
-- [CAPTCHA Code](#captcha-code) 
-- [Notes](#notes) 
-- [CAPTCHA Words](#captcha-words)
+- [To submit a comment](#comment-forms) 
+- [To register a new member](#member-registration-forms)
+- [In the Contact and Tell-a-Friend email forms](#contact-and-tell-a-friend-email-forms) 
+- [In Channel Forms](#channel-forms) 
+
+The settings to require CAPTCHAs for these forms are located at [`Settings --> CAPTCHA`](control-panel/settings/captcha.md) in the control panel. 
 
-The settings to require CAPTCHAs for these forms are located at `Settings --> CAPTCHA` in the control panel.
+The CAPTCHA settings are applied site-wide. If you have CAPTCHAS required, they will be required for all of the following uses with the same settings. If other add-ons integrate the use of EE's captcha system, they will also be controlled by the same settings.
 
 ## Comment Forms
 
-Once you have the preference turned on, you'll need to add the CAPTCHA code to your [Comment Submission Form](comment/form.md). See below for the [CAPTCHA Code](#captcha-code).
+If you have CAPTCHAS required, you'll need to add the CAPTCHA code to your [Comment Submission Form](comment/form.md). See below for the [CAPTCHA Code](#captcha-code).
 
-## Member Registration Form
+## Member Registration Forms
 
 The necessary CAPTCHA code already exists in the Member Templates by default, so you should not need to add it. If you have a version of ExpressionEngine from before the CAPTCHA feature was added or if you otherwise need the code, see below for the [CAPTCHA Code](#captcha-code).
 
 ## Contact and Tell-a-Friend Email Forms
 
-Once you have the preference turned on, you'll need to add the CAPTCHA code. See below for the [CAPTCHA Code](#captcha-code).
+If you have CAPTCHAS required, you'll need to add the CAPTCHA code to these forms in order to submit properly. See below for the [CAPTCHA Code](#captcha-code).
+
+## Channel Forms
+
+If you have CAPTCHAS required, you'll need to add the CAPTCHA code to your [Channel Entry Form](channels/channel-form/overview.md#captcha). See below for the [CAPTCHA Code](#captcha-code).
 
 ## CAPTCHA Code
 
+This is the code for Comment forms, Contact forms, and Channel Entry forms.
+
     {if captcha}
         <p>Please enter the word you see in the image below:</p>
-        <p>{captcha}<br /> <input type="text" name="captcha" value="{captcha_word}" size="20" maxlength="20" style="width:140px;" /></p>
+        <p>{captcha}<br />
+        <input type="text" name="captcha" value="{captcha_word}" size="20" maxlength="20" style="width:140px;" /></p>
     {/if}
 
-The contents of the conditional {if captcha} tag will only appear if you have the CAPTCHA preference turned on for either the comment or member registration forms.
+The contents of the conditional `{if captcha}` tag will be displayed if you:
+
+- have the CAPTCHA setting turned on
+- are not logged in as a superadmin (Superadmins never have to pass a CAPTCHA test)
+- are not logged in (only if you have "Require CAPTCHA while logged in?" enabled)
+
+The `{captcha}` tag itself will be an image tag if you are using the built-in CAPTCHA. 
 
-The code used inside the Member Registration Form is very similar, with only the omission of the {captcha_word} variable:
+The code used in the Member Registration Form is very similar, with only the omission of the {captcha_word} variable:
 
     {if captcha}
         <p>Please enter the word you see in the image below:</p>
         <p>{captcha}<br />
         <input type="text" name="captcha" value="" size="20" maxlength="20" style="width:140px;" /></p>
     {/if}
 
-If using using [reCAPTCHA v3](security/captchas.md), use a simplified tag that will output the required javascript, with the CAPTCHA otherwise invisible.
+If you are using [Google's  reCAPTCHA v3](security/captchas.md), use this simplified code in all cases. The `{captcha}` tag will output the required JavaScript, the CAPTCHA is invisible, and there is no need for an input field.
 
     {if captcha}
         {captcha}
@@ -72,7 +88,7 @@ For ExpressionEngine installations that power multiple domains or subdomains, yo
 
 ## CAPTCHA Words
 
-The CAPTCHA system uses a default dictionary. You can override these by adding a special user config file and returning an array of words you want to use instead. Create a PHP file at `system/user/config/captcha.php` with the format:
+The CAPTCHA system uses a default dictionary. You can override these by adding a special user config file that returns an array of words you want to use instead. Create a PHP file at `system/user/config/captcha.php` with the format:
 
     <?php
 

docs/troubleshooting/templates.md

@@ -64,16 +64,17 @@ Ensure that the channel field is being called within the template. For example,
 
 ## CAPTCHA images not appearing
 
-CAPTCHAs are enabling but there is a blank space where they should appear.
+CAPTCHAs are enabled but there is a blank space where they should appear.
 
 ### Troubleshooting missing CAPTCHA Images
 
 There are several possible reasons for CAPTCHA images to not appear:
 
-- The path and/or URL to the CAPTCHA directory is not specified correctly under `Settings --> CAPTCHA`.
+- The path and/or URL to the CAPTCHA directory is not specified correctly under [`Settings --> CAPTCHA`](control-panel/settings/captcha.md).
 - The `images/captchas/` directory is not writable. See [File Permissions](troubleshooting/general.md#file-permissions) for details.
 - The server does not support True Type Fonts. TrueType Fonts can be disabled in `Settings --> CAPTCHA`.
 - GD library isn't installed and/or working correctly
+- You are logged in as a superadmin, and superadmins are not required to solve CAPTCHAs
 
 ## Can not save a template with the {exp:query} tag