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, 27 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/CONF_modules_load_file.3 b/src/lib/libcrypto/man/CONF_modules_load_file.3
index d0401d520b..972752f7a3 100644
--- a/src/lib/libcrypto/man/CONF_modules_load_file.3
+++ b/src/lib/libcrypto/man/CONF_modules_load_file.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: CONF_modules_load_file.3,v 1.8 2019/03/20 04:02:07 schwarze Exp $
+.\"     $OpenBSD: CONF_modules_load_file.3,v 1.9 2019/06/14 13:41:31 schwarze Exp $
 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 20 2019 $
+.Dd $Mdocdate: June 14 2019 $
 .Dt CONF_MODULES_LOAD_FILE 3
 .Os
 .Sh NAME
@@ -95,6 +95,13 @@ is used.
 The behaviour can be customized using
 .Fa flags .
 .Pp
+See the
+.Sx EXAMPLES
+section for additional functions that may need to be called.
+Calling configuration functions in the right order for the intended
+effect can be tricky because many configuration functions internally
+call each other.
+.Pp
 .Fn CONF_modules_load
 is identical to
 .Fn CONF_modules_load_file
@@ -180,9 +187,12 @@ if (CONF_modules_load_file(NULL, "myapp",
 }
 .Ed
 .Pp
-Load custom configuration file and section, only print warnings on
-error, missing configuration file ignored:
+Load custom configuration file and section instead of the standard one,
+only print warnings on error, missing configuration file ignored:
 .Bd -literal
+OPENSSL_no_config();
+ENGINE_load_builtin_engines();
+OPENSSL_load_builtin_modules();
 if (CONF_modules_load_file("/something/app.cnf", "myapp",
     CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
         fprintf(stderr, "WARNING: error loading configuration file\en");
@@ -190,6 +200,17 @@ if (CONF_modules_load_file("/something/app.cnf", "myapp",
 }
 .Ed
 .Pp
+In the previous example, the call to
+.Xr OPENSSL_no_config 3
+is required first to suppress automatic loading
+of the standard configuration file, and the calls to
+.Xr ENGINE_load_builtin_engines 3
+and
+.Xr OPENSSL_load_builtin_modules 3
+are needed so that the configuration of builtin modules and engines
+is also loaded in addition to the configuration of
+.Qq myapp .
+.Pp
 Load and parse configuration file manually, custom error handling:
 .Bd -literal
 FILE    *fp;
@@ -218,9 +239,10 @@ if (fp == NULL) {
 .Ed
 .Sh SEE ALSO
 .Xr CONF_modules_free 3 ,
+.Xr ENGINE_load_builtin_engines 3 ,
 .Xr ERR 3 ,
 .Xr OPENSSL_config 3 ,
-.Xr OPENSSL_init_crypto 3
+.Xr OPENSSL_load_builtin_modules 3
 .Sh HISTORY
 .Fn CONF_modules_load_file
 and