some doc reorganization
(too old to reply)
Bruno Haible
2017-05-10 18:38:12 UTC
Raw Message

In the gnulib doc:
1) The chapters "Miscellaneous Notes" and "Particular Modules" contain
sections that are a bit randomly assigned.
2) I'd like to have a chapter for describing topics relating to the native
Windows platforms.

Therefore I'm committing these changes.

2017-05-10 Bruno Haible <***@clisp.org>

Prepare for reordering sections in the manual.
* doc/gnulib.texi: Move several sections to separate files. Include
these files.
* doc/out-of-memory.texi: New file, extracted from doc/gnulib.texi.
* doc/obsolete.texi: Likewise.
* doc/extra-tests.texi: Likewise.
* doc/transversal.texi: Likewise.
* doc/namespace.texi: Likewise.
* doc/check-version.texi: Likewise.
* doc/windows-sockets.texi: Likewise.
* doc/windows-libtool.texi: Likewise.
* doc/licenses-texi.texi: Likewise.
* doc/build-automation.texi: Likewise.
* doc/c-locale.texi: Likewise.

2017-05-10 Bruno Haible <***@clisp.org>

doc: New chapter "Build Infrastructure Modules".
* doc/gnulib.texi (Build Infrastructure Modules): New chapter.

2017-05-10 Bruno Haible <***@clisp.org>

doc: Move section "Running self-tests under valgrind".
* doc/gnulib.texi: Move section "Running self-tests under valgrind"
from chapter "Particular Modules" to chapter "Miscellaneous Notes".

2017-05-10 Bruno Haible <***@clisp.org>

doc: Move section "Library version handling".
* doc/gnulib.texi: Move section "Library version handling"
from chapter "Miscellaneous Notes" to chapter "Particular Modules".

2017-05-10 Bruno Haible <***@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.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index bad61e2..378cee6 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:
+Native binaries, built using the MinGW tool chain.
+Native binaries, built using the MSVC (MS Visual C/C++) tool chain.
+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.
+* 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 d6eb314..7812559 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:

diff --git a/doc/windows-sockets.texi b/doc/windows-sockets.texi
index bdace46..f820b4b 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
-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
+@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