Reformat some NOTES and README files

Formatting is still very mixed in the NOTES and README files.
This commit tries to make formatting more consistent with the one
introduced in pull request #10545.

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14042)

NOTES-PERL.md

@@ -1,12 +1,14 @@
-TOC
-===
-
- - Notes on Perl
- - Notes on Perl on Windows
- - Notes on Perl modules we use
- - Notes on installing a perl module
-
 Notes on Perl
+=============
+
+ - [General Notes](#general-notes)
+ - [Perl on Windows](#perl-on-windows)
+ - [Perl on VMS](#perl-on-vms)
+ - [Required Perl modules](#required-perl-modules)
+ - [Notes on installing a Perl module](#notes-on-installing-a-perl-module])
+
+
+General Notes
 -------------
 
 For our scripts, we rely quite a bit on Perl, and increasingly on
@@ -27,13 +29,13 @@ TOC
 requirement is due to our use of regexp backslash sequence \R among
 other features that didn't exist in core Perl before that version.
 
- Notes on Perl on Windows
+Perl on Windows
- ------------------------
+---------------
 
 There are a number of build targets that can be viewed as "Windows".
 Indeed, there are `VC-*` configs targeting VisualStudio C, as well as
- MinGW and Cygwin. The key recommendation is to use "matching" Perl,
+MinGW and Cygwin. The key recommendation is to use a Perl installation
- one that matches build environment. For example, if you will build
+that matches the build environment. For example, if you will build
 on Cygwin be sure to use the Cygwin package manager to install Perl.
 For MSYS builds use the MSYS provided Perl.
 For VC-* builds we recommend Strawberry Perl, from <http://strawberryperl.com>.
@@ -41,8 +43,8 @@ TOC
 for which you may need to explicitly select the Perl module Win32/Console.pm
 available via <https://platform.activestate.com/ActiveState>.
 
- Notes on Perl on VMS
+Perl on VMS
- --------------------
+-----------
 
 You will need to install Perl separately.  One way to do so is to
 download the source from <http://perl.org/>, unpacking it, reading
@@ -50,12 +52,24 @@ TOC
 `.PCSI` file from <http://www.vmsperl.com/> and install it using the
 POLYCENTER install tool.
 
- Notes on Perl modules we use
+Required Perl modules
- ----------------------------
+---------------------
 
- We make increasing use of Perl modules, and do our best to limit
+We do our best to limit ourselves to core Perl modules to keep the
- ourselves to core Perl modules to keep the requirements down.  There
+requirements down. There are just a few exceptions.
- are just a few exceptions:
+
+
+## For Building
+
+ * `Text::Template`
+
+   This module is not part of the core Perl modules.
+   As a matter of fact, the core Perl modules do not
+   include any templating module to date.
+   This module is absolutely needed,
+   configuration depends on it.
+
+## For Testing
 
  * `Test::More`
 
@@ -66,13 +80,7 @@ TOC
    If you don't plan on running the tests,
    you don't need to bother with this one.
 
-  * `Text::Template`
 
-    This module is not part of the core Perl modules.
-    As a matter of fact, the core Perl modules do not
-    include any templating module to date.
-    This module is absolutely needed,
-    configuration depends on it.
 
 To avoid unnecessary initial hurdles, we have bundled a copy of the
 following modules in our source.  They will work as fallbacks if
@@ -80,7 +88,7 @@ TOC
 
    Text::Template
 
- Notes on installing a perl module
+Notes on installing a Perl module
 ---------------------------------
 
 There are a number of ways to install a perl module.  In all

NOTES-VMS.md

@@ -1,6 +1,14 @@
-NOTES FOR THE OPENVMS PLATFORM
+Notes for the OpenVMS platform
 ==============================
 
+ - [Requirement details](#requirement-details)
+ - [About ANSI C compiler](#about-ansi-c-compiler)
+ - [About ODS-5 directory names and Perl](#about-ods-5-directory-names-and-perl)
+ - [About MMS and DCL](#about-mms-and-dcl)
+ - [About debugging](#about-debugging)
+ - [Checking the distribution](#checking-the-distribution)
+
+
 Requirement details
 -------------------
 

NOTES-WINDOWS.md

@@ -1,6 +1,12 @@
-NOTES FOR WINDOWS PLATFORMS
+Notes for Windows platforms
 ===========================
 
+ - [Native builds using Visual C++](#native-builds-using-visual-c++)
+ - [Native builds using MinGW](#native-builds-using-mingw)
+ - [Linking native applications](#linking-native-applications)
+ - [Hosted builds using Cygwin](#hosted-builds-using-cygwin)
+
+
 There are various options to build and run OpenSSL on the Windows platforms.
 
 "Native" OpenSSL uses the Windows APIs directly at run time.
@@ -16,8 +22,10 @@ NOTES FOR WINDOWS PLATFORMS
 for building (using GNU/Unix shell, compiler, and tools) and at run time.
 For this option you can use Cygwin.
 
- Visual C++ native builds, aka VC-*
+Native builds using Visual C++
- =====================================
+==============================
+
+The native builds using Visual C++ have a VC-* prefix.
 
 Requirement details
 -------------------
@@ -25,19 +33,22 @@ NOTES FOR WINDOWS PLATFORMS
 In addition to the requirements and instructions listed in INSTALL.md,
 these are required as well:
 
- - Perl.
+### Perl
+
 We recommend Strawberry Perl, available from <http://strawberryperl.com/>
 Please read NOTES.PERL for more information, including the use of CPAN.
 An alternative is ActiveState Perl, <https://www.activestate.com/ActivePerl>
 for which you may need to explicitly build the Perl module Win32/Console.pm
 via <https://platform.activestate.com/ActiveState> and then download it.
 
- - Microsoft Visual C compiler.
+### Microsoft Visual C compiler.
+
 Since these are proprietary and ever-changing we cannot test them all.
 Older versions may not work. Use a recent version wherever possible.
 
- - Netwide Assembler (NASM), available from <https://www.nasm.us>
+### Netwide Assembler (NASM)
-   Note that NASM is the only supported assembler.
+
+NASM is the only supported assembler. It is available from <https://www.nasm.us>.
 
 Quick start
 -----------
@@ -108,8 +119,8 @@ NOTES FOR WINDOWS PLATFORMS
    "vcvarsall.bat" before you compile. For example, if you want to build
    "arm64" builds, you should run "vcvarsall.bat x86_arm64 uwp".
 
- Native OpenSSL built using MinGW
+Native builds using MinGW
- ================================
+=========================
 
 MinGW offers an alternative way to build native OpenSSL, by cross compilation.
 
@@ -140,6 +151,7 @@ NOTES FOR WINDOWS PLATFORMS
        ./Configure mingw64 ...
    or
        ./Configure ...
+
    for the default architecture.
 
    Apart from that, follow the Unix / Linux instructions in INSTALL.md.
@@ -156,10 +168,10 @@ NOTES FOR WINDOWS PLATFORMS
    This requires that you've installed the necessary add-on packages for
    mingw[64] cross compilation.
 
- Linking your application
+Linking native applications
- ========================
+===========================
 
- This section applies to all "native" builds.
+This section applies to all native builds.
 
 If you link with static OpenSSL libraries then you're expected to
 additionally link your application with WS2_32.LIB, GDI32.LIB,
@@ -189,8 +201,8 @@ NOTES FOR WINDOWS PLATFORMS
 the glue between the OpenSSL BIO layer and your compiler run-time.
 See also the OPENSSL_Applink manual page.
 
- Hosted OpenSSL built using Cygwin
+Hosted builds using Cygwin
- =================================
+==========================
 
 Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the
 Windows subsystem and provides a Bash shell and GNU tools environment.