Update docs

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24450)

diff --git a/doc/man1/openssl-version.pod.in b/doc/man1/openssl-version.pod.in
index 7b6e2e9788b961e2ed8cbf88af68841bb4c1e2b5..dcfd60b9c343bbca323f24ca5727e5263086163c 100644 (file)
--- a/doc/man1/openssl-version.pod.in
+++ b/doc/man1/openssl-version.pod.in
@@ -80,11 +80,28 @@ The OpenSSL CPU settings info.
 
 =item B<-w>
 
-The OpenSSL WININSTALLCONTEXT build time variable, if set.
-Used for computing Windows registry key names
+The OpenSSL B<OSSL_WINCTX> build time variable, if set.
+Used for computing Windows registry key names.  This option is unavailable on
+non-Windows platforms.
 
 =back
 
+=head1 HISTORY
+
+In OpenSSL versions prior to 3.4, OpenSSL had a limitation regarding the
+B<OPENSSLDIR>, B<MODULESDIR> and B<ENGINESDIR> build time macros.  These macros
+were defined at build time, and represented filesystem paths.  This is common
+practice on unix like systems, as there was an expectation that a given build
+would be installed to a pre-determined location.  On Windows however, there is
+no such expectation, as libraries can be installed to arbitrary locations.
+B<OSSL_WINCTX> was introduced as a new build time variable to define a set of
+registry keys identified by the name openssl-<version>-<ctx>, in which the
+<version> value is derived from the version string in the openssl source, and
+the <ctx> extension is derived from the B<OSSL_WINCTX> variable.  The values of
+B<OPENSSLDIR>, B<ENGINESDIR> and B<MODULESDIR> can be set to various paths
+underneath this key to break the requirement to predict the installation path at
+build time.
+
 =head1 NOTES
 
 The output of C<openssl version -a> would typically be used when sending