Documentation changes for the Windows Build

- Fix markup
- Specific quoted command line for Visual Studio
  build
- Caveat about line ending for gawk
- Add comments about python versions
- makeinfo.exe is no longer available from cygwin
- Add some words about APPVER setting

windows/README.md

@@ -1,14 +1,14 @@
 Building Heimdal for Windows
 ===================
 
-1. Introduction
----------------
+# 1. Introduction
+
 
 Heimdal can be built and run on Windows XP or later.  Older OSs may
 work, but have not been tested.
 
-2. Prerequisites
-----------------
+# 2. Prerequisites
+
 
 * __Microsoft Visual C++ Compiler__: Heimdal has been tested with
   Microsoft Visual C/C++ compiler version 15.x.  This corresponds to
@@ -25,7 +25,8 @@ work, but have not been tested.
 * __Perl__: A recent version of Perl.  Tested with ActiveState
   ActivePerl.
 
-* __Python__: Tested with Python 2.5 and 2.6.
+* __Python__: Tested with Python 2.5 and 2.6.  Python 3.9 is known to not
+  work.
 
 * __WiX__: The Windows [Installer XML toolkit (WiX)][1] Version 3.x is
   used to build the installers.
@@ -37,6 +38,8 @@ work, but have not been tested.
   However, a recent build of `makeinfo` is required for building the
   documentation. Cygwin makeinfo 4.7 is known to work.
 
+  - Native `makeinfo.exe` is no longer available from cygwin.
+
 * __Certificate for code-signing__: The Heimdal build produces a
   number of Assemblies that should be signed if they are to be
   installed via Windows Installer.  In addition, all executable
@@ -48,14 +51,14 @@ work, but have not been tested.
 
 [1]: http://wix.sourceforge.net/
 
-3. Setting up the build environment
------------------------------------
+# 3. Setting up the build environment
 
-* Start with a Windows SDK or Visual Studio build environment.  The
+
+* Starting with a Windows SDK environment:  The
   target platform, OS and build type (debug / release) is determined
   by the build environment.
 
-  E.g.: If you are using the Windows SDK, you can use the `SetEnv.Cmd`
+  E.g.: You can use the `SetEnv.Cmd`
   script to set up a build environment targetting 64-bit Windows XP or
   later with:
 
@@ -67,6 +70,16 @@ work, but have not been tested.
 
   the build will produce release binaries.
 
+*  Starting with a Visual Studio build: The target platform and OS is determined
+   by the build environment.
+
+   E.g.: You can use the `vcvarsall.bat` script to set up an environ,ent
+   script to set up a build environment targetting 64-bit Windows 10 with:
+
+       vcvarsall.bat x64 10.0.19041.0  -vcvars_ver=14.29 -vcvars_spectre_libs=spectre
+
+   The choice of Debug or Release is made on the `nmake` command line.
+
 * Add any directories to `PATH` as necessary for tools required by
   the build to be found.  The build scripts will check for build
   tools at the start of the build and will indicate which ones are
@@ -114,6 +127,11 @@ work, but have not been tested.
         set CODESIGN=c:\scripts\mycodesigner.cmd
 	set CODESIGN_SHA256=c:\scripts\mycodesigner256.cmd
 
+   - 'APPVER'.  This environment variable controls the version passed to
+     the `-subsystem` qualifier for linker.  Additionally it helps
+     locate the runtime library (or otherwise) associated with the
+     compiler (Not sure how to build for XP with VC2017)
+
 * Define the code sign public key token.  This is contained in the
   environment variable `CODESIGN_PKT` and is needed to build the
   Heimdal assemblies.  If you are not using a code-sign certificate,
@@ -133,15 +151,21 @@ work, but have not been tested.
 
       set CODESIGN_PKT=abcdef0123456789
 
-4. Running the build
---------------------
+# 4. Running the build
+
+_If you checkout from git, you should ensure that and `awk` input files
+retain unix (LF only) line endings._
 
 Change the current directory to the root of the Heimdal source tree
 and run:
 
     nmake /f NTMakefile
 
-This should build the binaries, assemblies and the installers.
+This should build the binaries, assemblies and the installers.  If you are
+building with the Visual Studio tools you can build the release versions
+by setting the NODEBUG variable
+
+    nmake /f NTMakefile NODEBUG=TRUE
 
 The build can also be invoked from any subdirectory that contains an
 `NTMakefile` using the same command.  Keep in mind that there are
@@ -163,3 +187,16 @@ be built.  First build for X86 and then build AMD64
     nmake /f NTMakefile MULTIPLATFORM_INSTALLER=1
 
 The build must be executed under cmd.exe.
+
+# 5. Makeinfo
+
+Makeinfo is no longer available from cygwin (see
+[this mail thread][2]).The following appears to work
+(added to NTMakefile.w32)
+
+    MAKEINFO=$(PERL) C:\cygwin64\bin\texi2any
+
+You should expect a certain amount of debugging to ensure that all the required
+Perl libraries are installed.
+
+[2]: https://sourceware.org/legacy-ml/cygwin/2015-03/msg00503.html