doc: New chapter "Native Windows Support".

* doc/gnulib.texi (Native Windows Support): New chapter.
* doc/windows-libtool.texi: Small wording changes.
* doc/windows-sockets.texi: Small wording and formatting changes.

4 files changed, 47 insertions, 21 deletions

diff --git a/ChangeLog b/ChangeLog
index 00f64ac4d5..a173eb5c85 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2017-05-10 Bruno Haible  <bruno@clisp.org>
 
+	doc: New chapter "Native Windows Support".
+	* doc/gnulib.texi (Native Windows Support): New chapter.
+	* doc/windows-libtool.texi: Small wording changes.
+	* doc/windows-sockets.texi: Small wording and formatting changes.
+
+2017-05-10 Bruno Haible  <bruno@clisp.org>
+
 	doc: Move section "Library version handling".
 	* doc/gnulib.texi: Move section "Library version handling"
 	from chapter "Miscellaneous Notes" to chapter "Particular Modules".
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index bad61e27bd..378cee642f 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -69,6 +69,7 @@ Documentation License''.
 * Legacy Function Substitutes::     Replacing system functions.
 * Glibc Header File Substitutes::   Overriding system headers.
 * Glibc Function Substitutes::      Replacing system functions.
+* Native Windows Support::          Support for the native Windows platforms.
 * Particular Modules::              Documentation of individual modules.
 * Regular expressions::             The regex module.
 * Build Infrastructure Modules::    Modules that extend the GNU Build System.
@@ -725,8 +726,6 @@ better to share them.
 * Extra tests modules::
 * Modules that modify the way other modules work::
 * A C++ namespace for gnulib::      A different way of using Gnulib in C++
-* Windows sockets::
-* Libtool and Windows::
 * Running self-tests under valgrind::
 * License Texinfo sources::
 * Build robot for gnulib::
@@ -742,10 +741,6 @@ better to share them.
 
 @include namespace.texi
 
-@include windows-sockets.texi
-
-@include windows-libtool.texi
-
 @include valgrind-tests.texi
 
 @include licenses-texi.texi
@@ -6308,6 +6303,34 @@ This list of functions is sorted according to the header that declares them.
 @c @node Glibc wordexp.h
 @c @section Glibc Extensions to @code{<wordexp.h>}
 
+
+@node Native Windows Support
+@chapter Native Windows Support
+
+There are three ways to create binaries that run on Microsoft Windows:
+@itemize
+@item
+Native binaries, built using the MinGW tool chain.
+@item
+Native binaries, built using the MSVC (MS Visual C/C++) tool chain.
+@item
+Binaries for the Cygwin environment.
+@end itemize
+
+This chapter deals with the MinGW and MSVC platforms, commonly called
+``native Windows'' platforms.  Cygwin, on the other hand, is close enough
+to POSIX that it can be treated like any other Unix-like platform.
+
+@menu
+* Libtool and Windows::
+* Windows sockets::
+@end menu
+
+@include windows-libtool.texi
+
+@include windows-sockets.texi
+
+
 @node Particular Modules
 @chapter Particular Modules
 
diff --git a/doc/windows-libtool.texi b/doc/windows-libtool.texi
index d6eb314a1a..7812559a06 100644
--- a/doc/windows-libtool.texi
+++ b/doc/windows-libtool.texi
@@ -1,8 +1,8 @@
 @node Libtool and Windows
 @section Libtool and Windows
 
-If you want it to be possible to cross-compile your program to MinGW
-and you use Libtool, you need to use the @code{win32-dll} option of
+If you want it to be possible to compile your program for a native Windows
+platform and you use Libtool, you need to use the @code{win32-dll} option of
 @code{LT_INIT}. In other words, put:
 
 @example
diff --git a/doc/windows-sockets.texi b/doc/windows-sockets.texi
index bdace46bd5..f820b4b2ee 100644
--- a/doc/windows-sockets.texi
+++ b/doc/windows-sockets.texi
@@ -1,27 +1,23 @@
 @node Windows sockets
 @section Windows sockets
 
-There are several issues when building applications that should work
-under Windows.  The most problematic part is for applications that use
-sockets.
-
-Hopefully, we can add helpful notes to this section that will help you
-port your application to Windows using gnulib.
+One of the portability problems for native Windows are sockets and
+networking functions.
 
 @subsection Getaddrinfo and WINVER
 
-This was written for the getaddrinfo module, but may be applicable to
+This was written for the @code{getaddrinfo} module, but may be applicable to
 other functions too.
 
-The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
-XP.  The function declaration is present if @code{WINVER >= 0x0501}.
-Windows 2000 does not have getaddrinfo in its @file{WS2_32.DLL}.
+The @code{getaddrinfo} function exists in @code{ws2tcpip.h} and @code{-lws2_32}
+on Windows XP.  The function declaration is present if @code{WINVER >= 0x0501}.
+Windows 2000 does not have @code{getaddrinfo} in its @file{WS2_32.DLL}.
 
 Thus, if you want to assume Windows XP or later, you can add
-AC_DEFINE(WINVER, 0x0501) to avoid compiling the (partial) getaddrinfo
-implementation.
+@code{AC_DEFINE([WINVER], [0x0501])} to avoid compiling the (partial)
+@code{getaddrinfo} implementation.
 
 If you want to support Windows 2000, don't do anything.  The
 replacement function will open @file{WS2_32.DLL} during run-time to
-see if there is a getaddrinfo function available, and use it when
+see if there is a @code{getaddrinfo} function available, and use it when
 available.