bpo-39160 Align the verbs, grammar and defaults for `./configure --help` (GH-17747)

4 files changed, 135 insertions, 95 deletions

diff --git a/Misc/NEWS.d/next/Build/2019-12-30-03-54-24.bpo-39160.aBmj13.rst b/Misc/NEWS.d/next/Build/2019-12-30-03-54-24.bpo-39160.aBmj13.rst
new file mode 100644
index 00000000000..9fb4088de0e
--- /dev/null
+++ b/Misc/NEWS.d/next/Build/2019-12-30-03-54-24.bpo-39160.aBmj13.rst
@@ -0,0 +1 @@
+Updated the documentation in `./configure --help` to show default values, reference documentation where required and add additional explanation where needed.
\ No newline at end of file
diff --git a/configure b/configure
index a2c7ddf595d..c8253b1455f 100755
--- a/configure
+++ b/configure
@@ -1483,80 +1483,102 @@ Optional Features:
   --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
   --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
   --enable-universalsdk[=SDKDIR]
-                          Build fat binary against Mac OS X SDK
+                          create a universal binary build. SDKDIR specifies
+                          which macOS SDK should be used to perform the build,
+                          see Mac/README.rst. (default is no)
   --enable-framework[=INSTALLDIR]
-                          Build (MacOSX|Darwin) framework
-  --enable-shared         disable/enable building shared python library
-  --enable-profiling      enable C-level code profiling
-  --enable-optimizations  Enable expensive, stable optimizations (PGO, etc).
-                          Disabled by default.
+                          create a Python.framework rather than a traditional
+                          Unix install. optional INSTALLDIR specifies the
+                          installation path. see Mac/README.rst (default is
+                          no)
+  --enable-shared         enable building a shared Python library (default is
+                          no)
+  --enable-profiling      enable C-level code profiling with gprof (default is
+                          no)
+  --enable-optimizations  enable expensive, stable optimizations (PGO, etc.)
+                          (default is no)
   --enable-loadable-sqlite-extensions
-                          support loadable extensions in _sqlite module
-  --enable-ipv6           Enable ipv6 (with ipv4) support
-  --disable-ipv6          Disable ipv6 support
-  --enable-big-digits[=BITS]
-                          use big digits for Python longs [[BITS=30]]
+                          support loadable extensions in _sqlite module, see
+                          Doc/library/sqlite3.rst (default is no)
+  --enable-ipv6           enable ipv6 (with ipv4) support, see
+                          Doc/library/socket.rst (default is yes if supported)
+  --enable-big-digits[=15|30]
+                          use big digits (30 or 15 bits) for Python longs
+                          (default is system-dependent)]
 
 Optional Packages:
   --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
   --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
   --with-universal-archs=ARCH
-                          select architectures for universal build ("32-bit",
-                          "64-bit", "3-way", "intel", "intel-32", "intel-64",
-                          or "all")
+                          specify the kind of universal binary that should be
+                          created. this option is only valid when
+                          --enable-universalsdk is set; options are:
+                          ("32-bit", "64-bit", "3-way", "intel", "intel-32",
+                          "intel-64", or "all") see Mac/README.rst
   --with-framework-name=FRAMEWORK
-                          specify an alternate name of the framework built
-                          with --enable-framework
-  --with-cxx-main=<compiler>
-                          compile main() and link python executable with C++
-                          compiler
-  --with-suffix=.exe      set executable suffix
-  --with-pydebug          build with Py_DEBUG defined
+                          specify the name for the python framework on macOS
+                          only valid when --enable-framework is set. see
+                          Mac/README.rst (default is 'Python')
+  --with-cxx-main[=COMPILER]
+                          compile main() and link Python executable with C++
+                          compiler specified in COMPILER (default is $CXX)
+  --with-suffix=SUFFIX    set executable suffix to SUFFIX (default is '.exe')
+  --with-pydebug          build with Py_DEBUG defined (default is no)
   --with-trace-refs       enable tracing references for debugging purpose
-  --with-assertions       build with C assertions enabled
-  --with-lto              Enable Link Time Optimization in any build. Disabled
-                          by default.
+                          (default is no)
+  --with-assertions       build with C assertions enabled (default is no)
+  --with-lto              enable Link-Time-Optimization in any build (default
+                          is no)
   --with-hash-algorithm=[fnv|siphash24]
-                          select hash algorithm
+                          select hash algorithm for use in Python/pyhash.c
+                          (default is SipHash24)
   --with-address-sanitizer
-                          enable AddressSanitizer (asan)
-  --with-memory-sanitizer enable MemorySanitizer (msan)
+                          enable AddressSanitizer memory error detector,
+                          'asan' (default is no)
+  --with-memory-sanitizer enable MemorySanitizer allocation error detector,
+                          'msan' (default is no)
   --with-undefined-behavior-sanitizer
-                          enable UndefinedBehaviorSanitizer (ubsan)
-  --with-libs='lib1 ...'  link against additional libs
+                          enable UndefinedBehaviorSanitizer undefined
+                          behaviour detector, 'ubsan' (default is no)
+  --with-libs='lib1 ...'  link against additional libs (default is no)
   --with-system-expat     build pyexpat module using an installed expat
-                          library
-  --with-system-ffi       build _ctypes module using an installed ffi library
+                          library, see Doc/library/pyexpat.rst (default is no)
+  --with-system-ffi       build _ctypes module using an installed ffi library,
+                          see Doc/library/ctypes.rst (default is
+                          system-dependent)
   --with-system-libmpdec  build _decimal module using an installed libmpdec
-                          library
+                          library, see Doc/library/decimal.rst (default is no)
   --with-tcltk-includes='-I...'
                           override search for Tcl and Tk include files
   --with-tcltk-libs='-L...'
                           override search for Tcl and Tk libs
   --with-dbmliborder=db1:db2:...
-                          order to check db backends for dbm. Valid value is a
-                          colon separated string with the backend names
-                          `ndbm', `gdbm' and `bdb'.
-  --with(out)-doc-strings disable/enable documentation strings
-  --with(out)-pymalloc    disable/enable specialized mallocs
-  --with(out)-c-locale-coercion
-                          disable/enable C locale coercion to a UTF-8 based
-                          locale
-  --with-valgrind         Enable Valgrind support
-  --with(out)-dtrace      disable/enable DTrace support
-  --with-libm=STRING      math library
-  --with-libc=STRING      C library
-  --with(out)-computed-gotos
-                          Use computed gotos in evaluation loop (enabled by
+                          override order to check db backends for dbm; a valid
+                          value is a colon separated string with the backend
+                          names `ndbm', `gdbm' and `bdb'.
+  --with-doc-strings      enable documentation strings (default is yes)
+  --with-pymalloc         enable specialized mallocs (default is yes)
+  --with-c-locale-coercion
+                          enable C locale coercion to a UTF-8 based locale
+                          (default is yes)
+  --with-valgrind         enable Valgrind support (default is no)
+  --with-dtrace           enable DTrace support (default is no)
+  --with-libm=STRING      override libm math library to STRING (default is
+                          system-dependent)
+  --with-libc=STRING      override libc C library to STRING (default is
+                          system-dependent)
+  --with-computed-gotos   enable computed gotos in evaluation loop (enabled by
                           default on supported compilers)
-  --with(out)-ensurepip=[=upgrade]
-                          "install" or "upgrade" using bundled pip
-  --with-openssl=DIR      root of the OpenSSL directory
+  --with-ensurepip[=install|upgrade|no]
+                          "install" or "upgrade" using bundled pip (default is
+                          upgrade)
+  --with-openssl=DIR      override root of the OpenSSL directory to DIR
   --with-ssl-default-suites=[python|openssl|STRING]
-                          Override default cipher suites string, python: use
+                          override default cipher suites string, python: use
                           Python's preferred selection (default), openssl:
                           leave OpenSSL's defaults untouched, STRING: use a
-                          custom string, PROTOCOL_SSLv2 ignores the setting
+                          custom string, PROTOCOL_SSLv2 ignores the setting,
+                          see Doc/library/ssl.rst
 
 Some influential environment variables:
   MACHDEP     name for machine-dependent library files
@@ -3248,7 +3270,7 @@ _ACEOF
 
 ##AC_ARG_WITH(dyld,
 ##            AS_HELP_STRING([--with-dyld],
-##                           [Use (OpenStep|Rhapsody) dynamic linker]))
+##                           [use (OpenStep|Rhapsody) dynamic linker]))
 ##
 # Set name for machine-dependent library files
 
diff --git a/configure.ac b/configure.ac
index 57dca35723c..bcef99c4962 100644
--- a/configure.ac
+++ b/configure.ac
@@ -149,7 +149,10 @@ CONFIG_ARGS="$ac_configure_args"
 
 AC_MSG_CHECKING([for --enable-universalsdk])
 AC_ARG_ENABLE(universalsdk,
-	AS_HELP_STRING([--enable-universalsdk@<:@=SDKDIR@:>@], [Build fat binary against Mac OS X SDK]),
+	AS_HELP_STRING([--enable-universalsdk@<:@=SDKDIR@:>@],
+	               [create a universal binary build.
+	                SDKDIR specifies which macOS SDK should be used to perform the build,
+	                see Mac/README.rst. (default is no)]),
 [
 	case $enableval in
 	yes)
@@ -212,7 +215,11 @@ fi
 AC_SUBST(LIPO_32BIT_FLAGS)
 AC_MSG_CHECKING(for --with-universal-archs)
 AC_ARG_WITH(universal-archs,
-    AS_HELP_STRING([--with-universal-archs=ARCH], [select architectures for universal build ("32-bit", "64-bit", "3-way", "intel", "intel-32", "intel-64", or "all")]),
+    AS_HELP_STRING([--with-universal-archs=ARCH],
+                   [specify the kind of universal binary that should be created. this option is
+                    only valid when --enable-universalsdk is set; options are:
+                    ("32-bit", "64-bit", "3-way", "intel", "intel-32", "intel-64", or "all")
+                    see Mac/README.rst]),
 [
 	UNIVERSAL_ARCHS="$withval"
 ],
@@ -226,7 +233,9 @@ fi
 
 AC_ARG_WITH(framework-name,
               AS_HELP_STRING([--with-framework-name=FRAMEWORK],
-                             [specify an alternate name of the framework built with --enable-framework]),
+                             [specify the name for the python framework on macOS
+                              only valid when --enable-framework is set. see Mac/README.rst
+                              (default is 'Python')]),
 [
     PYTHONFRAMEWORK=${withval}
     PYTHONFRAMEWORKDIR=${withval}.framework
@@ -238,7 +247,10 @@ AC_ARG_WITH(framework-name,
 ])
 dnl quadrigraphs "@<:@" and "@:>@" produce "[" and "]" in the output
 AC_ARG_ENABLE(framework,
-              AS_HELP_STRING([--enable-framework@<:@=INSTALLDIR@:>@], [Build (MacOSX|Darwin) framework]),
+              AS_HELP_STRING([--enable-framework@<:@=INSTALLDIR@:>@],
+                             [create a Python.framework rather than a traditional Unix install.
+                              optional INSTALLDIR specifies the installation path. see Mac/README.rst
+                              (default is no)]),
 [
 	case $enableval in
 	yes)
@@ -357,7 +369,7 @@ AC_DEFINE_UNQUOTED(_PYTHONFRAMEWORK, "${PYTHONFRAMEWORK}", [framework name])
 
 ##AC_ARG_WITH(dyld,
 ##            AS_HELP_STRING([--with-dyld],
-##                           [Use (OpenStep|Rhapsody) dynamic linker]))
+##                           [use (OpenStep|Rhapsody) dynamic linker]))
 ##
 # Set name for machine-dependent library files
 AC_ARG_VAR([MACHDEP], [name for machine-dependent library files])
@@ -647,8 +659,8 @@ AC_SUBST(CXX)
 AC_SUBST(MAINCC)
 AC_MSG_CHECKING(for --with-cxx-main=<compiler>)
 AC_ARG_WITH(cxx_main,
-            AS_HELP_STRING([--with-cxx-main=<compiler>],
-                           [compile main() and link python executable with C++ compiler]),
+            AS_HELP_STRING([--with-cxx-main@<:@=COMPILER@:>@],
+                           [compile main() and link Python executable with C++ compiler specified in COMPILER (default is $CXX)]),
 [
 
 	case $withval in
@@ -928,7 +940,7 @@ esac
 AC_EXEEXT
 AC_MSG_CHECKING(for --with-suffix)
 AC_ARG_WITH(suffix,
-            AS_HELP_STRING([--with-suffix=.exe], [set executable suffix]),
+            AS_HELP_STRING([--with-suffix=SUFFIX], [set executable suffix to SUFFIX (default is '.exe')]),
 [
 	case $withval in
 	no)	EXEEXT=;;
@@ -1050,7 +1062,7 @@ AC_MSG_RESULT($GNULD)
 
 AC_MSG_CHECKING(for --enable-shared)
 AC_ARG_ENABLE(shared,
-              AS_HELP_STRING([--enable-shared], [disable/enable building shared python library]))
+              AS_HELP_STRING([--enable-shared], [enable building a shared Python library (default is no)]))
 
 if test -z "$enable_shared"
 then
@@ -1065,7 +1077,7 @@ AC_MSG_RESULT($enable_shared)
 
 AC_MSG_CHECKING(for --enable-profiling)
 AC_ARG_ENABLE(profiling,
-              AS_HELP_STRING([--enable-profiling], [enable C-level code profiling]))
+              AS_HELP_STRING([--enable-profiling], [enable C-level code profiling with gprof (default is no)]))
 if test "x$enable_profiling" = xyes; then
   ac_save_cc="$CC"
   CC="$CC -pg"
@@ -1216,7 +1228,7 @@ ABIFLAGS=""
 # Check for --with-pydebug
 AC_MSG_CHECKING(for --with-pydebug)
 AC_ARG_WITH(pydebug,
-            AS_HELP_STRING([--with-pydebug], [build with Py_DEBUG defined]),
+            AS_HELP_STRING([--with-pydebug], [build with Py_DEBUG defined (default is no)]),
 [
 if test "$withval" != no
 then
@@ -1233,7 +1245,9 @@ fi],
 # --with-trace-refs
 AC_MSG_CHECKING(for --with-trace-refs)
 AC_ARG_WITH(trace-refs,
-  AS_HELP_STRING([--with-trace-refs],[enable tracing references for debugging purpose]),,
+  AS_HELP_STRING(
+    [--with-trace-refs],
+    [enable tracing references for debugging purpose (default is no)]),,
   with_trace_refs=no)
 AC_MSG_RESULT($with_trace_refs)
 
@@ -1247,7 +1261,7 @@ fi
 assertions='false'
 AC_MSG_CHECKING(for --with-assertions)
 AC_ARG_WITH(assertions,
-            AS_HELP_STRING([--with-assertions],[build with C assertions enabled]),
+            AS_HELP_STRING([--with-assertions],[build with C assertions enabled (default is no)]),
 [
 if test "$withval" != no
 then
@@ -1268,7 +1282,9 @@ AC_SUBST(DEF_MAKE_ALL_RULE)
 AC_SUBST(DEF_MAKE_RULE)
 Py_OPT='false'
 AC_MSG_CHECKING(for --enable-optimizations)
-AC_ARG_ENABLE(optimizations, AS_HELP_STRING([--enable-optimizations], [Enable expensive, stable optimizations (PGO, etc).  Disabled by default.]),
+AC_ARG_ENABLE(optimizations, AS_HELP_STRING(
+                [--enable-optimizations],
+                [enable expensive, stable optimizations (PGO, etc.) (default is no)]),
 [
 if test "$enableval" != no
 then
@@ -1323,7 +1339,7 @@ fi
 
 # Enable LTO flags
 AC_MSG_CHECKING(for --with-lto)
-AC_ARG_WITH(lto, AS_HELP_STRING([--with-lto], [Enable Link Time Optimization in any build. Disabled by default.]),
+AC_ARG_WITH(lto, AS_HELP_STRING([--with-lto], [enable Link-Time-Optimization in any build (default is no)]),
 [
 if test "$withval" != no
 then
@@ -2907,7 +2923,7 @@ AC_MSG_CHECKING(for --with-hash-algorithm)
 dnl quadrigraphs "@<:@" and "@:>@" produce "[" and "]" in the output
 AC_ARG_WITH(hash_algorithm,
             AS_HELP_STRING([--with-hash-algorithm=@<:@fnv|siphash24@:>@],
-                           [select hash algorithm]),
+                           [select hash algorithm for use in Python/pyhash.c (default is SipHash24)]),
 [
 AC_MSG_RESULT($withval)
 case "$withval" in
@@ -2927,7 +2943,7 @@ esac
 AC_MSG_CHECKING(for --with-address-sanitizer)
 AC_ARG_WITH(address_sanitizer,
             AS_HELP_STRING([--with-address-sanitizer],
-                           [enable AddressSanitizer (asan)]),
+                           [enable AddressSanitizer memory error detector, 'asan' (default is no)]),
 [
 AC_MSG_RESULT($withval)
 BASECFLAGS="-fsanitize=address -fno-omit-frame-pointer $BASECFLAGS"
@@ -2940,7 +2956,7 @@ with_pymalloc="no"
 AC_MSG_CHECKING(for --with-memory-sanitizer)
 AC_ARG_WITH(memory_sanitizer,
             AS_HELP_STRING([--with-memory-sanitizer],
-                           [enable MemorySanitizer (msan)]),
+                           [enable MemorySanitizer allocation error detector, 'msan' (default is no)]),
 [
 AC_MSG_RESULT($withval)
 BASECFLAGS="-fsanitize=memory -fsanitize-memory-track-origins=2 -fno-omit-frame-pointer $BASECFLAGS"
@@ -2953,7 +2969,7 @@ with_pymalloc="no"
 AC_MSG_CHECKING(for --with-undefined-behavior-sanitizer)
 AC_ARG_WITH(undefined_behavior_sanitizer,
             AS_HELP_STRING([--with-undefined-behavior-sanitizer],
-                           [enable UndefinedBehaviorSanitizer (ubsan)]),
+                           [enable UndefinedBehaviorSanitizer undefined behaviour detector, 'ubsan' (default is no)]),
 [
 AC_MSG_RESULT($withval)
 BASECFLAGS="-fsanitize=undefined $BASECFLAGS"
@@ -2967,7 +2983,7 @@ AC_CHECK_LIB(socket, socket, [LIBS="-lsocket $LIBS"], [], $LIBS) # SVR4 sockets
 
 AC_MSG_CHECKING(for --with-libs)
 AC_ARG_WITH(libs,
-            AS_HELP_STRING([--with-libs='lib1 ...'], [link against additional libs]),
+            AS_HELP_STRING([--with-libs='lib1 ...'], [link against additional libs (default is no)]),
 [
 AC_MSG_RESULT($withval)
 LIBS="$withval $LIBS"
@@ -2979,7 +2995,7 @@ PKG_PROG_PKG_CONFIG
 # Check for use of the system expat library
 AC_MSG_CHECKING(for --with-system-expat)
 AC_ARG_WITH(system_expat,
-            AS_HELP_STRING([--with-system-expat], [build pyexpat module using an installed expat library]),
+            AS_HELP_STRING([--with-system-expat], [build pyexpat module using an installed expat library, see Doc/library/pyexpat.rst (default is no)]),
             [],
             [with_system_expat="no"])
 
@@ -2988,7 +3004,7 @@ AC_MSG_RESULT($with_system_expat)
 # Check for use of the system libffi library
 AC_MSG_CHECKING(for --with-system-ffi)
 AC_ARG_WITH(system_ffi,
-            AS_HELP_STRING([--with-system-ffi], [build _ctypes module using an installed ffi library]),,,)
+            AS_HELP_STRING([--with-system-ffi], [build _ctypes module using an installed ffi library, see Doc/library/ctypes.rst (default is system-dependent)]),,,)
 
 if test "$ac_sys_system" = "Darwin"
 then
@@ -3022,7 +3038,7 @@ AC_SUBST(LIBFFI_INCLUDEDIR)
 # Check for use of the system libmpdec library
 AC_MSG_CHECKING(for --with-system-libmpdec)
 AC_ARG_WITH(system_libmpdec,
-            AS_HELP_STRING([--with-system-libmpdec], [build _decimal module using an installed libmpdec library]),
+            AS_HELP_STRING([--with-system-libmpdec], [build _decimal module using an installed libmpdec library, see Doc/library/decimal.rst (default is no)]),
             [],
             [with_system_libmpdec="no"])
 
@@ -3031,7 +3047,8 @@ AC_MSG_RESULT($with_system_libmpdec)
 # Check for support for loadable sqlite extensions
 AC_MSG_CHECKING(for --enable-loadable-sqlite-extensions)
 AC_ARG_ENABLE(loadable-sqlite-extensions,
-              AS_HELP_STRING([--enable-loadable-sqlite-extensions], [support loadable extensions in _sqlite module]),
+              AS_HELP_STRING([--enable-loadable-sqlite-extensions],
+                             [support loadable extensions in _sqlite module, see Doc/library/sqlite3.rst (default is no)]),
               [],
               [enable_loadable_sqlite_extensions="no"])
 
@@ -3068,7 +3085,7 @@ fi
 # Check for --with-dbmliborder
 AC_MSG_CHECKING(for --with-dbmliborder)
 AC_ARG_WITH(dbmliborder,
-            AS_HELP_STRING([--with-dbmliborder=db1:db2:...], [order to check db backends for dbm. Valid value is a colon separated string with the backend names `ndbm', `gdbm' and `bdb'.]),
+            AS_HELP_STRING([--with-dbmliborder=db1:db2:...], [override order to check db backends for dbm; a valid value is a colon separated string with the backend names `ndbm', `gdbm' and `bdb'.]),
 [
 if test x$with_dbmliborder = xyes
 then
@@ -3240,8 +3257,8 @@ fi
 AH_TEMPLATE(ENABLE_IPV6, [Define if --enable-ipv6 is specified])
 AC_MSG_CHECKING([if --enable-ipv6 is specified])
 AC_ARG_ENABLE(ipv6,
-[  --enable-ipv6           Enable ipv6 (with ipv4) support
-  --disable-ipv6          Disable ipv6 support],
+    AS_HELP_STRING([--enable-ipv6],
+               [enable ipv6 (with ipv4) support, see Doc/library/socket.rst (default is yes if supported)]),
 [ case "$enableval" in
   no)
        AC_MSG_RESULT(no)
@@ -3412,7 +3429,7 @@ AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[ /* CAN_RAW_FD_FRAMES available check */
 # Check for --with-doc-strings
 AC_MSG_CHECKING(for --with-doc-strings)
 AC_ARG_WITH(doc-strings,
-            AS_HELP_STRING([--with(out)-doc-strings], [disable/enable documentation strings]))
+            AS_HELP_STRING([--with-doc-strings], [enable documentation strings (default is yes)]))
 
 if test -z "$with_doc_strings"
 then with_doc_strings="yes"
@@ -3427,7 +3444,7 @@ AC_MSG_RESULT($with_doc_strings)
 # Check for Python-specific malloc support
 AC_MSG_CHECKING(for --with-pymalloc)
 AC_ARG_WITH(pymalloc,
-            AS_HELP_STRING([--with(out)-pymalloc], [disable/enable specialized mallocs]))
+            AS_HELP_STRING([--with-pymalloc], [enable specialized mallocs (default is yes)]))
 
 if test -z "$with_pymalloc"
 then
@@ -3443,8 +3460,8 @@ AC_MSG_RESULT($with_pymalloc)
 # Check for --with-c-locale-coercion
 AC_MSG_CHECKING(for --with-c-locale-coercion)
 AC_ARG_WITH(c-locale-coercion,
-            AS_HELP_STRING([--with(out)-c-locale-coercion],
-              [disable/enable C locale coercion to a UTF-8 based locale]))
+            AS_HELP_STRING([--with-c-locale-coercion],
+              [enable C locale coercion to a UTF-8 based locale (default is yes)]))
 
 if test -z "$with_c_locale_coercion"
 then
@@ -3460,7 +3477,7 @@ AC_MSG_RESULT($with_c_locale_coercion)
 # Check for Valgrind support
 AC_MSG_CHECKING([for --with-valgrind])
 AC_ARG_WITH([valgrind],
-  AS_HELP_STRING([--with-valgrind], [Enable Valgrind support]),,
+  AS_HELP_STRING([--with-valgrind], [enable Valgrind support (default is no)]),,
   with_valgrind=no)
 AC_MSG_RESULT([$with_valgrind])
 if test "$with_valgrind" != no; then
@@ -3474,7 +3491,7 @@ fi
 # Check for DTrace support
 AC_MSG_CHECKING(for --with-dtrace)
 AC_ARG_WITH(dtrace,
-  AS_HELP_STRING([--with(out)-dtrace],[disable/enable DTrace support]),,
+  AS_HELP_STRING([--with-dtrace],[enable DTrace support (default is no)]),,
   with_dtrace=no)
 AC_MSG_RESULT($with_dtrace)
 
@@ -4321,7 +4338,7 @@ Darwin) ;;
 esac
 AC_MSG_CHECKING(for --with-libm=STRING)
 AC_ARG_WITH(libm,
-            AS_HELP_STRING([--with-libm=STRING], [math library]),
+            AS_HELP_STRING([--with-libm=STRING], [override libm math library to STRING (default is system-dependent)]),
 [
 if test "$withval" = no
 then LIBM=
@@ -4337,7 +4354,7 @@ fi],
 AC_SUBST(LIBC)
 AC_MSG_CHECKING(for --with-libc=STRING)
 AC_ARG_WITH(libc,
-            AS_HELP_STRING([--with-libc=STRING], [C library]),
+            AS_HELP_STRING([--with-libc=STRING], [override libc C library to STRING (default is system-dependent)]),
 [
 if test "$withval" = no
 then LIBC=
@@ -4555,7 +4572,7 @@ AC_CHECK_DECLS([RTLD_LAZY, RTLD_NOW, RTLD_GLOBAL, RTLD_LOCAL, RTLD_NODELETE, RTL
 # determine what size digit to use for Python's longs
 AC_MSG_CHECKING([digit size for Python's longs])
 AC_ARG_ENABLE(big-digits,
-AS_HELP_STRING([--enable-big-digits@<:@=BITS@:>@],[use big digits for Python longs [[BITS=30]]]),
+AS_HELP_STRING([--enable-big-digits@<:@=15|30@:>@],[use big digits (30 or 15 bits) for Python longs (default is system-dependent)]]),
 [case $enable_big_digits in
 yes)
   enable_big_digits=30 ;;
@@ -5267,8 +5284,8 @@ fi
 # Check for --with-computed-gotos
 AC_MSG_CHECKING(for --with-computed-gotos)
 AC_ARG_WITH(computed-gotos,
-            AS_HELP_STRING([--with(out)-computed-gotos],
-                           [Use computed gotos in evaluation loop (enabled by default on supported compilers)]),
+            AS_HELP_STRING([--with-computed-gotos],
+                           [enable computed gotos in evaluation loop (enabled by default on supported compilers)]),
 [
 if test "$withval" = yes
 then
@@ -5464,8 +5481,8 @@ fi
 # ensurepip option
 AC_MSG_CHECKING(for ensurepip)
 AC_ARG_WITH(ensurepip,
-    [AS_HELP_STRING([--with(out)-ensurepip=@<:@=upgrade@:>@],
-        ["install" or "upgrade" using bundled pip])],
+    [AS_HELP_STRING([--with-ensurepip@<:@=install|upgrade|no@:>@],
+        ["install" or "upgrade" using bundled pip (default is upgrade)])],
     [],
     [with_ensurepip=upgrade])
 AS_CASE($with_ensurepip,
@@ -5621,11 +5638,11 @@ AH_TEMPLATE(PY_SSL_DEFAULT_CIPHER_STRING,
 AC_MSG_CHECKING(for --with-ssl-default-suites)
 AC_ARG_WITH(ssl-default-suites,
             AS_HELP_STRING([--with-ssl-default-suites=@<:@python|openssl|STRING@:>@],
-                           [Override default cipher suites string,
+                           [override default cipher suites string,
                             python: use Python's preferred selection (default),
                             openssl: leave OpenSSL's defaults untouched,
                             STRING: use a custom string,
-                            PROTOCOL_SSLv2 ignores the setting]),
+                            PROTOCOL_SSLv2 ignores the setting, see Doc/library/ssl.rst]),
 [
 AC_MSG_RESULT($withval)
 case "$withval" in
diff --git a/m4/ax_check_openssl.m4 b/m4/ax_check_openssl.m4
index 28e48cbefb6..2846fd14c49 100644
--- a/m4/ax_check_openssl.m4
+++ b/m4/ax_check_openssl.m4
@@ -39,7 +39,7 @@ AC_DEFUN([AX_CHECK_OPENSSL], [
     found=false
     AC_ARG_WITH([openssl],
         [AS_HELP_STRING([--with-openssl=DIR],
-            [root of the OpenSSL directory])],
+            [override root of the OpenSSL directory to DIR])],
         [
             case "$withval" in
             "" | y | ye | yes | n | no)