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, 22 insertions, 8 deletions

diff --git a/src/lib/libssl/man/OPENSSL_init_ssl.3 b/src/lib/libssl/man/OPENSSL_init_ssl.3
index 5c9f51fe49..f37dccfaac 100644
--- a/src/lib/libssl/man/OPENSSL_init_ssl.3
+++ b/src/lib/libssl/man/OPENSSL_init_ssl.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OPENSSL_init_ssl.3,v 1.3 2019/06/12 09:36:30 schwarze Exp $
+.\" $OpenBSD: OPENSSL_init_ssl.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: June 12 2019 $
+.Dd $Mdocdate: June 14 2019 $
 .Dt OPENSSL_INIT_SSL 3
 .Os
 .Sh NAME
@@ -27,13 +27,27 @@
 .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
 .Fn OPENSSL_init_ssl
 calls
-.Xr OPENSSL_init_crypto 3
-and also allocates various resources used internally by the ssl library.
-.Pp
-Calling it is never useful because it is automatically called
-internally when needed.
+.Xr OPENSSL_init_crypto 3 ,
+.Xr SSL_load_error_strings 3 ,
+and
+.Xr SSL_library_init 3 .
 .Pp
 The
 .Fa options
@@ -50,7 +64,7 @@ none of the calls except the first one have any effect.
 is intended to return 1 on success or 0 on error.
 .Sh SEE ALSO
 .Xr CONF_modules_load_file 3 ,
-.Xr OPENSSL_init_crypto 3 ,
+.Xr OPENSSL_config 3 ,
 .Xr ssl 3
 .Sh HISTORY
 .Fn OPENSSL_init_ssl