[PATCH] Change Windows build docs to point to flex and bison from msys

>From 1430b3df7f571a4bc27e39bf3d64810e0e7c2900 Mon Sep 17 00:00:00 2001
From: Craig Ringer <ringerc@ringerc.id.au>
Date: Mon, 31 Dec 2012 14:46:40 +0800
Subject: [PATCH] Update Windows build docs to point to msys tools for bison
 and flex

---
 doc/src/sgml/install-windows.sgml | 75 +++++++++++++++++++++++++++------------
 1 file changed, 53 insertions(+), 22 deletions(-)

diff --git a/doc/src/sgml/install-windows.sgml b/doc/src/sgml/install-windows.sgml
index b6ea0ab..afce78b 100644
--- a/doc/src/sgml/install-windows.sgml
+++ b/doc/src/sgml/install-windows.sgml
@@ -92,21 +92,25 @@
  </para>
 
  <para>
-  The tools for building using <productname>Visual C++</productname>,
-  are in the <filename>src/tools/msvc</filename> directory. When building,
-  make sure there are no tools from <productname>MinGW</productname> or
+  The tools for building using <productname>Visual C++</productname> or the 
+  <productname>Platform SDK</productname> are in the
+  <filename>src/tools/msvc</filename> directory. When building, make sure there
+  are no tools from <productname>MinGW</productname> or
   <productname>Cygwin</productname> present in your system PATH. Also, make
   sure you have all the required Visual C++ tools available in the PATH. In
-  <productname>Visual Studio</productname>, start the
-  <application>Visual Studio Command Prompt</application>.
+  <productname>Visual Studio</productname>, start the <application>Visual
+  Studio Command Prompt</application>.
   If you wish to build a 64-bit version, you must use the 64-bit version of
-  the command, and vice versa.
+  the command, and vice versa, or use <command>vcvarsall</command> to change the
+  target environment.
   In the <productname>Microsoft Windows SDK</productname>, start the
   <application>CMD shell</application> listed under the SDK on the Start Menu.
-  In recent SDK versions you can change the targeted CPU architecture by using
-  the <command>setenv</command> command.
-  All commands should be run from the <filename>src\tools\msvc</filename>
-  directory.
+  In recent SDK versions you can change the targeted CPU architecture, build
+  type, and target OS by using the <command>setenv</command> command, eg
+  <command>setenv /x86 /release /xp</command> to target Windows XP or later
+  with a 32-bit release build. See <command>/?</command> for other options to
+  <command>setenv.cmd</command>.  All commands should be run from the
+  <filename>src\tools\msvc</filename> directory.
  </para>
 
  <para>
@@ -191,17 +195,32 @@ $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
     <varlistentry>
      <term><productname>Bison</productname> and
       <productname>Flex</productname></term>
-     <listitem><para>
-      Bison and Flex are required to build from Git, but not required when
-      building from a release file. Note that only Bison 1.875 or versions
-      2.2 and later will work. Also, Flex version 2.5.31 or later is required.
-      Bison can be downloaded from <ulink url="http://gnuwin32.sourceforge.net"></>.
-      Flex can be downloaded from
-      <ulink url="http://www.postgresql.org/ftp/misc/winflex/"></>.
-      If you are using <productname>msysGit</productname> for accessing the
-      PostgreSQL <productname>Git</productname> repository you probably already
-      have recent versions of bison and flex in your <productname>Git</productname>
-      binary directory.
+     <listitem>
+     <para>
+      <productname>Bison</productname> and <productname>Flex</productname> are
+      required to build from Git, but not required when building from a release
+      file. Only <productname>Bison</productname> 1.875 or versions 2.2 and later
+      will work. <productname>Flex</productname> must also be version 2.5.31 or later.
+     </para>
+
+     <para>
+      Both <productname>Bison</productname> and <productname>Flex</productname>
+      are included in the <productname>msys</productname> tool suite, available
+      from <ulink url="http://www.mingw.org/wiki/MSYS"></> as part of the
+      <productname>MinGW</productname> compiler suite. You can also get
+      <productname>msys</productname> as part of
+      <productname>msysGit</productname> from <ulink url="http://git-scm.com/"></>.
+     </para>
+
+     <para>
+      You will need to add the directory containing
+      <filename>flex.exe</filename> and <filename>bison.exe</filename> to the PATH
+      environment variable in  <filename>buildenv.pl</filename> unless they are
+      already on the PATH. In the case of MinGW, the directory is the
+      <filename>\msys\1.0\bin</filename> subdirectory of your MinGW
+      installation directory. For msysGit, it's the <filename>bin</filename>
+      directory in your Git install directory. Do not add the MinGW compiler
+      tools themselves to the PATH.
      </para>
 
      <note>
@@ -210,7 +229,19 @@ $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
         causes Bison to malfunction when installed in a directory with
         spaces in the name, such as the default location on English
         installations <filename>C:\Program Files\GnuWin32</filename>.
-        Consider installing into <filename>C:\GnuWin32</filename> instead.
+	Consider installing into <filename>C:\GnuWin32</filename> or using the
+	NTFS shortname path to GnuWin32 (typically
+	<filename>C:\PROGRA~1\GnuWin32</filename>, but you can check with the
+	"dir /X" command) in your PATH environment setting.
+       </para>
+     </note>
+
+     <note>
+       <para>
+       The obsolete "winflex" binaries distributed on the
+       PostgreSQL FTP site and referenced in older documentation will fail with
+       "flex: fatal internal error, exec failed" on 64-bit Windows hosts. Use flex
+       from msys instead.
        </para>
      </note>
      </listitem>
-- 
1.7.11.7