Further improve the documentation of library initialization and configuration.

Among other improvements:
* Use a uniform wording at the top of the DECSRIPTION for obsolete pages.
* Better explain how to use a non-standard configuration file.
* Remove obsolete functions from SEE ALSO.
Triggered by some suggestions from tb@.
Tweaks and OK tb@.

1 files changed, 23 insertions, 11 deletions

diff --git a/src/lib/libcrypto/man/OPENSSL_init_crypto.3 b/src/lib/libcrypto/man/OPENSSL_init_crypto.3
index 3a532550ae..e6dac13fed 100644
--- a/src/lib/libcrypto/man/OPENSSL_init_crypto.3
+++ b/src/lib/libcrypto/man/OPENSSL_init_crypto.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.3 2018/03/23 23:18:17 schwarze Exp $
+.\" $OpenBSD: OPENSSL_init_crypto.3,v 1.4 2019/06/14 13:41:31 schwarze Exp $
 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -13,7 +13,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 23 2018 $
+.Dd $Mdocdate: June 14 2019 $
 .Dt OPENSSL_INIT_CRYPTO 3
 .Os
 .Sh NAME
@@ -27,10 +27,30 @@
 .Fa "const void *dummy"
 .Fc
 .Sh DESCRIPTION
+This function is deprecated.
+It is never useful for any application program to call it explicitly.
+The library automatically calls it internally with an
+.Fa options
+argument of 0 whenever needed.
+It is safest to assume that any function may do so.
+.Pp
+To enable or disable the standard configuration file, instead use
+.Xr OPENSSL_config 3
+or
+.Xr OPENSSL_no_config 3 ,
+respectively.
+To load a non-standard configuration file, refer to
+.Xr CONF_modules_load_file 3 .
+.Pp
 If
 .Fn OPENSSL_init_crypto
 is called before any other crypto or ssl functions, the crypto
-library is initialised by allocating various internal resources.
+library is initialised by allocating various internal resources,
+in particular calling
+.Xr ERR_load_crypto_strings 3 ,
+.Xr OpenSSL_add_all_ciphers 3 ,
+and
+.Xr OpenSSL_add_all_digests 3 .
 .Pp
 The following
 .Fa options
@@ -54,13 +74,6 @@ The
 .Fa dummy
 argument has no effect.
 .Pp
-Calling this function is almost never useful because it is internally
-called with an
-.Fa options
-argument of 0 by those functions in the crypto and ssl libraries
-that require it.
-It is safest to assume that any function may do so.
-.Pp
 If this function is called more than once, none of the calls except
 the first one have any effect.
 .Sh RETURN VALUES
@@ -69,7 +82,6 @@ is intended to return 1 on success or 0 on error.
 .Sh SEE ALSO
 .Xr CONF_modules_load_file 3 ,
 .Xr OPENSSL_config 3 ,
-.Xr OPENSSL_init_ssl 3 ,
 .Xr OPENSSL_load_builtin_modules 3 ,
 .Xr openssl.cnf 5
 .Sh HISTORY