VMS documentation fixes

This mostly clarifies details.

Fixes #13789

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

5 files changed, 48 insertions, 26 deletions

diff --git a/Configurations/descrip.mms.tmpl b/Configurations/descrip.mms.tmpl
index 04fa0e0d46..3f015a0eb5 100644
--- a/Configurations/descrip.mms.tmpl
+++ b/Configurations/descrip.mms.tmpl
@@ -392,8 +392,13 @@ NODEBUG=@
         $(NODEBUG) !
         $(NODEBUG) ! Installation logical names
         $(NODEBUG) !
-        $(NODEBUG) installtop = F$PARSE(staging_instdir,"$(INSTALLTOP)","[]A.;",,"SYNTAX_ONLY,NO_CONCEAL") - ".][000000" - "[000000." - "][" - "]A.;" + ".]"
-        $(NODEBUG) datatop = F$PARSE(staging_datadir,"$(OPENSSLDIR)","[]A.;",,"SYNTAX_ONLY,NO_CONCEAL") - ".][000000" - "[000000." - "][" - "]A.;" + ".]"
+        $(NODEBUG) ! This also creates a few DCL variables that are used for
+        $(NODEBUG) ! the "install_msg" target.
+        $(NODEBUG) !
+        $(NODEBUG) installroot = F$PARSE(staging_instdir,"$(INSTALLTOP)","[]A.;",,"SYNTAX_ONLY,NO_CONCEAL") - ".][000000" - "[000000." - "][" - "]A.;"
+        $(NODEBUG) installtop = installroot + ".]"
+        $(NODEBUG) dataroot = F$PARSE(staging_datadir,"$(OPENSSLDIR)","[]A.;",,"SYNTAX_ONLY,NO_CONCEAL") - ".][000000" - "[000000." - "][" - "]A.;"
+        $(NODEBUG) datatop = dataroot + ".]"
         $(NODEBUG) DEFINE ossl_installroot 'installtop'
         $(NODEBUG) DEFINE ossl_dataroot 'datatop'
         $(NODEBUG) !
@@ -468,9 +473,9 @@ list-tests :
         @ WRITE SYS$OUTPUT "Tests are not supported with your chosen Configure options"
         @ ! {- output_on() if !$disabled{tests}; "" -}
 
-install : install_sw install_ssldirs install_docs install_final
+install : install_sw install_ssldirs install_docs install_msg
 
-install_final :
+install_msg :
         @ WRITE SYS$OUTPUT ""
         @ WRITE SYS$OUTPUT "######################################################################"
         @ WRITE SYS$OUTPUT ""
@@ -478,9 +483,8 @@ install_final :
              @{- sourcefile("VMS", "msg_install.com") -} "$(SYSTARTUP)" "{- $osslver -}"
         @ IF "$(DESTDIR)" .NES. "" THEN -
              @{- sourcefile("VMS", "msg_staging.com") -} -
-             'installtop' 'datatop' "$(INSTALLTOP)" "$(OPENSSLDIR)" -
-             "$(SYSTARTUP)" "{- $osslver -}" -
-             
+             "''installroot']" "''dataroot']" "$(INSTALLTOP)" "$(OPENSSLDIR)" -
+             "$(SYSTARTUP)" "{- $osslver -}"
 
 check_install :
         spawn/nolog @ossl_installroot:[SYSTEST]openssl_ivp{- $osslver -}.com
diff --git a/INSTALL.md b/INSTALL.md
index d9aa5c47c2..eec2f3a2b3 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -234,10 +234,7 @@ Use the following command to install OpenSSL.
 
 By default, OpenSSL will be installed to
 
-    SYS$COMMON:[OPENSSL-'version'...]
-
-where 'version' is the OpenSSL version number with underscores instead
-of periods.
+    SYS$COMMON:[OPENSSL]
 
 ### Windows
 
@@ -266,6 +263,9 @@ To install OpenSSL to a different location (for example into your home
 directory for testing purposes) run `Configure` as shown in the following
 examples.
 
+The options `--prefix` and `--openssldir` are explained in further detail in
+[Directories](#directories) below, and the values used here are mere examples.
+
 On Unix:
 
     $ ./Configure --prefix=/opt/openssl --openssldir=/usr/local/ssl
@@ -375,7 +375,7 @@ The top of the installation directory tree.  Defaults are:
 
     Unix:           /usr/local
     Windows:        C:\Program Files\OpenSSL
-    OpenVMS:        SYS$COMMON:[OPENSSL-'version']
+    OpenVMS:        SYS$COMMON:[OPENSSL]
 
 Compiler Warnings
 -----------------
@@ -1289,7 +1289,7 @@ its default):
 
 ### OpenVMS
 
-'arch' is replaced with the architecture name, `Alpha` or `ia64`,
+'arch' is replaced with the architecture name, `ALPHA` or `IA64`,
 'sover' is replaced with the shared library version (`0101` for 1.1), and
 'pz' is replaced with the pointer size OpenSSL was built with:
 
diff --git a/NOTES-VMS.md b/NOTES-VMS.md
index c317e82de2..ebb1e8e152 100644
--- a/NOTES-VMS.md
+++ b/NOTES-VMS.md
@@ -84,9 +84,9 @@ NOTES FOR THE OPENVMS PLATFORM
  Unix mount point.
 
  The easiest way to check if everything got through as it should is to
- check for one of the following files:
+ check that this file exists:
 
-    [.crypto]opensslconf^.h.in
+    [.include.openssl]configuration^.h.in
 
  The best way to get a correct distribution is to download the gzipped
  tar file from ftp://ftp.openssl.org/source/, use `GZIP -d` to uncompress
@@ -99,3 +99,10 @@ NOTES FOR THE OPENVMS PLATFORM
  Should you need it, you can find UnZip for VMS here:
 
    <http://www.info-zip.org/UnZip.html>
+
+ How the value of 'arch' is determined
+ -------------------------------------
+
+ 'arch' is mentioned in INSTALL.  It's value is determined like this:
+
+    arch = f$edit( f$getsyi( "arch_name"), "upcase")
diff --git a/VMS/msg_install.com b/VMS/msg_install.com
index ed8444edfe..d1eec7c982 100644
--- a/VMS/msg_install.com
+++ b/VMS/msg_install.com
@@ -9,6 +9,11 @@ $       osslver = p2
 $
 $       WRITE SYS$OUTPUT "Installation complete"
 $       WRITE SYS$OUTPUT ""
-$       WRITE SYS$OUTPUT "Run @''systartup'openssl_startup''osslver' to set up logical names"
-$       WRITE SYS$OUTPUT "then run @''systartup'openssl_utils''osslver' to define commands"
+$       WRITE SYS$OUTPUT "The following commands need to be executed to enable you to use OpenSSL:"
+$       WRITE SYS$OUTPUT ""
+$       WRITE SYS$OUTPUT "- to set up OpenSSL logical names:"
+$       WRITE SYS$OUTPUT "  @''systartup'openssl_startup''osslver'"
+$       WRITE SYS$OUTPUT ""
+$       WRITE SYS$OUTPUT "- to define the OpenSSL command"
+$       WRITE SYS$OUTPUT "  @''systartup'openssl_utils''osslver'"
 $       WRITE SYS$OUTPUT ""
diff --git a/VMS/msg_staging.com b/VMS/msg_staging.com
index d1d2a7dc40..11cd80870d 100644
--- a/VMS/msg_staging.com
+++ b/VMS/msg_staging.com
@@ -18,14 +18,20 @@ $       osslver = p6
 $
 $       WRITE SYS$OUTPUT "Staging installation complete"
 $       WRITE SYS$OUTPUT ""
-$       WRITE SYS$OUTPUT "Finish or package in such a way that the contents of the directory tree"
-$       WRITE SYS$OUTPUT staging_instdir
-$       WRITE SYS$OUTPUT "ends up in ''final_instdir',"
-$       WRITE SYS$OUTPUT "and that the contents of the contents of the directory tree"
-$       WRITE SYS$OUTPUT staging_datadir
-$       WRITE SYS$OUTPUT "ends up in ''final_datadir"
+$       WRITE SYS$OUTPUT "Finish or package in such a way that the contents of the following directory"
+$       WRITE SYS$OUTPUT "trees end up being copied:"
 $       WRITE SYS$OUTPUT ""
-$       WRITE SYS$OUTPUT "When in its final destination,"
-$       WRITE SYS$OUTPUT "Run @''systartup'openssl_startup''osslver' to set up logical names"
-$       WRITE SYS$OUTPUT "then run @''systartup'openssl_utils''osslver' to define commands"
+$       WRITE SYS$OUTPUT "- from ", staging_instdir
+$       WRITE SYS$OUTPUT "  to   ", final_instdir
+$       WRITE SYS$OUTPUT "- from ", staging_datadir
+$       WRITE SYS$OUTPUT "  to   ", final_datadir
+$       WRITE SYS$OUTPUT ""
+$       WRITE SYS$OUTPUT "When in its final destination, the following commands need to be executed"
+$       WRITE SYS$OUTPUT "to use OpenSSL:"
+$       WRITE SYS$OUTPUT ""
+$       WRITE SYS$OUTPUT "- to set up OpenSSL logical names:"
+$       WRITE SYS$OUTPUT "  @''systartup'openssl_startup''osslver'"
+$       WRITE SYS$OUTPUT ""
+$       WRITE SYS$OUTPUT "- to define the OpenSSL command"
+$       WRITE SYS$OUTPUT "  @''systartup'openssl_utils''osslver'"
 $       WRITE SYS$OUTPUT ""