Item12952: clean up doc and messages for autoconfigure, to make it ea…

…sier for a user to use
foswiki · Sep 25, 2014 · 975f24e · 975f24e
1 parent 8f22137
commit 975f24e
Show file tree

Hide file tree

Showing 3 changed files with 126 additions and 152 deletions.
diff --git a/core/lib/Foswiki.spec b/core/lib/Foswiki.spec
@@ -1768,73 +1768,41 @@ $Foswiki::cfg{Cache}{DBI}{PostgreSQL}{Password} = '';
 
 #############################################################################
 #---+ Mail
-# Settings controlling if and how Foswiki sends email.
-# You can select the destination mail server or local email agent used for
-# forwarding email.
+# Settings controlling if and how Foswiki sends email. Mail is used by Foswiki
+# to send out notifications of events, such as topic changes.
+# Foswiki can send mail using a SMTP server, or using a local mail program
+# such as =sendmail=. Mail can be sent in plain text or over SSL. You can
+# set up S/MIME certificates to sign mails sent by Foswiki.
 
 #---++ Basic Setup
-# Settings controlling if and how Foswiki handles email including the
-# identity of the sender and other expert settings controlling the email
-# process.
+# Basic settings controlling if and how Foswiki handles email including the
+# identity of the sender.
 #
-# Certificates for Secure Email may be obtained from a vendor or private
-# certificate authority.  You can also use the action buttons to generate
-# certificates or certificate requests if OpenSSL is installed.
-
 # **BOOLEAN FEEDBACK="label='Auto-configure Email'; wizard='AutoConfigureEmail'; method='autoconfigure'" **
 # Enable email globally.  Un-check this option to disable all outgoing
-# email from Foswiki.  Use the button to auto-configure e-mail services.
+# email from Foswiki.
+#
+# Before you run auto-configuration, you must have provided a minimum of
+# information in the settings here. At least your {SMTP}{MAILHOST} is required
+# if you are using SMTP (and possibly your {SMTP}{SENDERHOST}.
 #
+# Auto-configure Email may change configuration settings (it will tell you
+# what it changed.) These settings will only be made permanent when you save
+# the configuration.
 $Foswiki::cfg{EnableEmail} = $FALSE;
 
 # **EMAILADDRESS 30 FEEDBACK="label='Send Test Email';wizard='SendTestEmail'; method='send'"**
 # Wiki administrator's e-mail address. For example =webmaster@example.com=
-# Used in =%WIKIWEBMASTER%=
-# Must be a single valid email address
+# Must be a single valid email address.
 $Foswiki::cfg{WebMasterEmail} = '';
 
-# **STRING 30 \
-#   FEEDBACK="label='Generate S/MIME Certificate';span=2; \
-#             title='Generate a self-signed certficate for the WebMaster.  \
-#                    This allows immediate use of signed email.'; \
-#             wizard='SMIMECertificate'; method='generate_cert'"\
-#   FEEDBACK="label='Generate S/MIME CSR';col=1;\
-#             title='Generate a Certificate Signing Request for the \
-#                    WebMaster. This request must be signed by a \
-#                    Certificate Authority to create a certificate, \
-#                    then installed.';\
-#             wizard='SMIMECertificate'; method='request_cert'"\
-#   FEEDBACK="label='Cancel CSR';\
-#             title='Cancel a pending Certificate Signing request. \
-#                    This destroys the private key associated with \
-#                    the request.';\
-#             wizard='SMIMECertificate'; method='cancel_cert'"\
-# **
+# **STRING 30**
 # Wiki administrator's name address.
 # For use in mails (first name and last name, for example =Fred Smith=).
-# Used in %WIKIWEBMASTERNAME%.
-#
-# The action buttons are used to generate certificates for S/MIME
-# signed email.  There are two ways to use this:
-#
-# *Self signed certificates:*
-# The =Generate S/MIME Certificate= button will generate a self-signed
-# S/MIME certificate and install it.  If you use this option, you will
-# have to arrange for your users' e-mail clients to trust this certificate.
-# This type of certificate is adequate for a small user base and for testing.
-# 
-# *Certificate Authority signed certificates:*
-# The =Generate S/MIME CSR= button is used to build a "Certificate Signing
-# Request" for use by your private Certificate Authority or
-# by a trusted commercial Certificate authority.  Use the
-# =Generate S/MIME CSR= button to create a private key and signing request.
-# The Cancel button is used to delete a pending request.
-# The S/MIME Certificate information on the S/MIME tab must be completed
-# for these buttons to work correctly.
 $Foswiki::cfg{WebMasterName} = 'Wiki Administrator';
 
 # **STRING 30 **
-# Mail host for outgoing mail. This is only used if Net::SMTP is used.
+# SMTP mail host for outgoing mail, if Net::SMTP is being used.
 # Examples: =mail.your.company= If the smtp server uses a different port
 # than the default 25, use the syntax =mail.your.company:portnumber=,
 # or omit it to allow autoconfiguration to attempt to discover it for you.
@@ -1843,33 +1811,76 @@ $Foswiki::cfg{WebMasterName} = 'Wiki Administrator';
 # the syntax =192.0.2.11= or =[2001:db8::beef]=.  If necessary,
 # a port number may be added to either form =:587=.
 #
-# For Gmail, set MailMethod to Net::SMTP, set MAILHOST to =smtp.gmail.com=
+# For Gmail, set {SMTP}{MAILHOST} to =smtp.gmail.com=,
 # provide your gmail email address and password for authentication, and use
 # auto-configuration.
 $Foswiki::cfg{SMTP}{MAILHOST} = '';
 
-# **STRING 30 DISPLAY_IF="/^Net::SMTP/.test({Email}{MailMethod})"**
+# **STRING 30**
+# Mail domain sending mail. SMTP requires that you identify yourself.
+# This option specifies a string to pass to the mail host as your mail
+# domain. If not given, then EHLO/HELO will not be sent to the mail host,
+# which may result in your connection being rejected.
+# Example: foswiki.your.company.
+$Foswiki::cfg{SMTP}{SENDERHOST} = '';
+
+# **STRING 30**
 # Username for SMTP. Only required if your mail server requires authentication.
 # If this is left blank, Foswiki will not attempt to authenticate the mail
 # sender.
 $Foswiki::cfg{SMTP}{Username} = '';
 
-# **PASSWORD 30 DISPLAY_IF="/^Net::SMTP/.test({Email}{MailMethod})"**
+# **PASSWORD 30**
 # Password for your {SMTP}{Username}.
 $Foswiki::cfg{SMTP}{Password} = '';
 
-#---++ Secure Email
-# Settings for secure (S/MIME-signed) email.
+#---++ Signed Email (S/MIME)
+# Settings for S/MIME-signed email.
 # Configure signing of outgoing email. (Secure/Multipurpose Internet
 # Mail Extensions) is a standard for public key encryption and signing
 # of MIME encoded email messages. Messages generated by the server will
 # be signed using an X.509 certificate.
-
-# **BOOLEAN DISPLAY_IF="{EnableEmail}"**
-# Enable to cause all e-mails sent by Foswiki to be signed using S/MIME.
+#
+# Certificates for Secure Email may be obtained from a vendor or private
+# certificate authority.  You can also use the action buttons to generate
+# certificates or certificate requests if OpenSSL is installed.
+# The buttons are used to generate certificates for S/MIME
+# signed Secure Email.  There are two ways to use this:
+#
+# *Self signed certificates:*
+# The =Generate S/MIME Certificate= button will generate a self-signed
+# S/MIME certificate and install it. If you use this option, you will
+# have to arrange for your users' e-mail clients to trust this certificate.
+# This type of certificate is adequate for a small user base and for testing.
+# 
+# *Certificate Authority signed certificates:*
+# The =Generate S/MIME CSR= button is used to create private key and
+# a _Certificate Signing Request_ (CSR) for use by your private Certificate
+# Authority or by a trusted commercial Certificate authority.
+# The =Cancel CSR= button is used to delete a pending request.
+# The S/MIME Certificate information in the *Certificate Management*
+# section must be completed for CSR's to work correctly.
+#
+# **BOOLEAN \
+#   FEEDBACK="label='Generate S/MIME Certificate';span=2; \
+#             title='Generate a self-signed certficate for the WebMaster.  \
+#                    This allows immediate use of signed email.'; \
+#             wizard='SMIMECertificate'; method='generate_cert'"\
+#   FEEDBACK="label='Generate S/MIME CSR';col=1;\
+#             title='Generate a Certificate Signing Request for the \
+#                    WebMaster. This request must be signed by a \
+#                    Certificate Authority to create a certificate, \
+#                    then installed.';\
+#             wizard='SMIMECertificate'; method='request_cert'"\
+#   FEEDBACK="label='Cancel CSR';\
+#             title='Cancel a pending Certificate Signing request. \
+#                    This destroys the private key associated with \
+#                    the request.';\
+#             wizard='SMIMECertificate'; method='cancel_cert'" **
+# Enable to sign all e-mails sent by Foswiki using S/MIME.
 $Foswiki::cfg{Email}{EnableSMIME} = $FALSE;
 
-# **PATH DISPLAY_IF="{EnableEmail} && {Email}{EnableSMIME}"**
+# **PATH**
 # Specify the file containing the administrator's X.509 certificate.  It
 # must be in PEM format.
 #
@@ -1881,7 +1892,7 @@ $Foswiki::cfg{Email}{EnableSMIME} = $FALSE;
 # or a certificate installed from a Foswiki-generated CSR.
 $Foswiki::cfg{Email}{SmimeCertificateFile} = '';
 
-# **PATH DISPLAY_IF="{EnableEmail} && {Email}{EnableSMIME}"**
+# **PATH**
 # Specify the file containing the private key corresponding to the
 # administrator's X.509 certificate. It must be in PEM format.
 #
@@ -1892,7 +1903,7 @@ $Foswiki::cfg{Email}{SmimeCertificateFile} = '';
 # or a certificate installed from a Foswiki-generated CSR.
 $Foswiki::cfg{Email}{SmimeKeyFile} = '';
 
-# **PASSWORD 30 DISPLAY_IF="{EnableEmail} && {Email}{EnableSMIME}"**
+# **PASSWORD 30**
 # If the file containing the certificate's private key is encrypted, specify
 # the password. Otherwise leave blank.
 #
@@ -1910,26 +1921,24 @@ $Foswiki::cfg{Email}{SmimeKeyPassword} = '';
 # The following parameters can be used to specify commonly used components
 # of the subject name for Certificate Signing Requests.
 #
-# You can also install a signed certificate with the action button if
-# OpenSSL is installed.
 
-# **STRING DISPLAY_IF="{EnableEmail}"**
+# **STRING**
 # ISO country code (2 letters)
 $Foswiki::cfg{Email}{SmimeCertC} = '';
 
-# **STRING DISPLAY_IF="{EnableEmail}"**
+# **STRING**
 # State or Province
 $Foswiki::cfg{Email}{SmimeCertST} = '';
 
-# **STRING DISPLAY_IF="{EnableEmail}"**
+# **STRING**
 # Locality (city or town)
 $Foswiki::cfg{Email}{SmimeCertL} = '';
 
-# **STRING DISPLAY_IF="{EnableEmail}"**
+# **STRING**
 # Organization
 $Foswiki::cfg{Email}{SmimeCertO} = '';
 
-# **STRING DISPLAY_IF="{EnableEmail}"**
+# **STRING**
 # Organizational unit. For example Department.
 $Foswiki::cfg{Email}{SmimeCertOU} = '';
 
@@ -1979,12 +1988,6 @@ $Foswiki::cfg{SMTP}{DebugFlags} = '-X /dev/stderr';
 # mode in SMTP. Output will go to the webserver error log.
 $Foswiki::cfg{SMTP}{Debug} = 0;
 
-# **STRING 30 DISPLAY_IF="{EnableEmail} && /^Net::SMTP/.test({Email}{MailMethod})"**
-# Mail domain sending mail, required. SMTP
-# requires that you identify the server sending mail.
-# Example: foswiki.your.company.
-$Foswiki::cfg{SMTP}{SENDERHOST} = '';
-
 # **BOOLEAN \
 #           DISPLAY_IF="{EnableEmail} && /^Net::SMTP/.test({Email}{MailMethod})"**
 # Verify that server's certificate contains the expected hostname when using