doc: modernize for C11 etc.

* doc/gnulib-readme.texi (Portability guidelines): Modernize a bit
for C11, MinGW, etc.  This responds to Paul Smith's question in:
http://lists.gnu.org/archive/html/bug-gnulib/2017-01/msg00014.html

2 files changed, 44 insertions, 20 deletions

diff --git a/ChangeLog b/ChangeLog
index 66ea430136..76c7569272 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2017-01-02  Paul Eggert  <eggert@cs.ucla.edu>
 
+	doc: modernize for C11 etc.
+	* doc/gnulib-readme.texi (Portability guidelines): Modernize a bit
+	for C11, MinGW, etc.  This responds to Paul Smith's question in:
+	http://lists.gnu.org/archive/html/bug-gnulib/2017-01/msg00014.html
+
 	dfa: prefer functions to FETCH_WC macro
 	* lib/dfa.c (FETCH_WC): Remove, replacing with ...
 	(fetch_wc, bracket_fetch_wc): ... new functions.  These store the
diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi
index 256a289a61..ecd94c3ef2 100644
--- a/doc/gnulib-readme.texi
+++ b/doc/gnulib-readme.texi
@@ -292,41 +292,57 @@ platforms; and @code{time_r} users need not worry about
 @code{localtime_r} returning @code{int} (not @code{char@ *}) on some
 platforms that predate POSIX 1003.1-2001.
 
-Currently we assume at least a freestanding C89 compiler, possibly
-operating with a C library that predates C89.  The oldest environments
-currently ported to are probably HP-UX 10.20 and IRIX 5.3, though we
-are not testing these platforms very often.
-
-Because we assume a freestanding C89 compiler, Gnulib code can include
+Gnulib attempts to be portable to platforms that are still supported
+by their providers, even if these systems are not the latest version.
+Currently Gnulib assumes at least a freestanding C89 compiler,
+possibly operating with a C library that predates C89; with time this
+assumption will likely be strengthened to later versions of the C
+standard.  Old platforms currently supported include AIX 6.1, HP-UX
+11i v1 and Solaris 10, though these platforms are rarely tested.
+Gnulib itself is so old that it contains contains many fixes for
+obsolete platforms, fixes that may be removed in the future.
+
+Because of the freestanding C89 assumption, Gnulib code can include
 @code{<float.h>}, @code{<limits.h>}, @code{<stdarg.h>}, and
 @code{<stddef.h>} unconditionally.  It can also assume the existence
 of @code{<ctype.h>}, @code{<errno.h>}, @code{<fcntl.h>},
 @code{<locale.h>}, @code{<signal.h>}, @code{<stdio.h>},
 @code{<stdlib.h>}, @code{<string.h>}, and @code{<time.h>}.  Similarly,
 many modules include @code{<sys/types.h>} even though it's not even in
-C99; that's OK since @code{<sys/types.h>} has been around nearly
+C11; that's OK since @code{<sys/types.h>} has been around nearly
 forever.
 
-Even if the include files exist, they may not conform to C89.
+Even if the include files exist, they may not conform to the C standard.
 However, GCC has a @command{fixincludes} script that attempts to fix most
 C89-conformance problems.  So Gnulib currently assumes include files
 largely conform to C89 or better.  People still using ancient hosts
 should use fixincludes or fix their include files manually.
 
-Even if the include files conform to C89, the library itself may not.
+Even if the include files conform, the library itself may not.
 For example, @code{strtod} and @code{mktime} have some bugs on some platforms.
 You can work around some of these problems by requiring the relevant
 modules, e.g., the Gnulib @code{mktime} module supplies a working and
 conforming @code{mktime}.
 
-The GNU coding standards allow one departure from strict C99: Gnulib
-code can assume that standard internal types like @code{size_t} are no wider
-than @code{long}.  POSIX 1003.1-2001 and the GNU coding standards both
-require @code{int} to be at least 32 bits wide, so Gnulib code assumes this
-as well.  Gnulib code makes the following additional assumptions:
+The GNU coding standards allow one departure from strict C: Gnulib
+code can assume that standard internal types like @code{size_t} are no
+wider than @code{long}.  POSIX requires implementations to support at
+least one programming environment where this is true, and such
+environments are recommended for Gnulib-using applications.  When it
+is easy to port to non-POSIX platforms like MinGW where these types
+are wider than @code{long}, new Gnulib code should do so, e.g., by
+using @code{ptrdiff_t} instead of @code{long}.  However, it is not
+always that easy, and no effort has been made to check that all Gnulib
+modules work on MinGW-like environments.
+
+Gnulib code makes the following additional assumptions:
 
 @itemize
 @item
+@code{int} and @code{unsigned int} are at least 32 bits wide.  POSIX
+and the GNU coding standards both require this.
+
+@item
 Signed integer arithmetic is two's complement.
 
 Previously, Gnulib code sometimes assumed that signed integer
@@ -335,9 +351,9 @@ sometimes do not guarantee this, and Gnulib code with this
 assumption is now considered to be questionable.
 @xref{Integer Properties}.
 
-Some Gnulib modules contain explicit support for the other signed
-integer representations allowed by C99 (ones' complement and signed
-magnitude), but these modules are the exception rather than the rule.
+Although some Gnulib modules contain explicit support for the other signed
+integer representations allowed by the C standard (ones' complement and signed
+magnitude), these modules are the exception rather than the rule.
 All practical Gnulib targets use two's complement.
 
 @item
@@ -384,9 +400,12 @@ runtime overhead on standard hosts and that are relatively easy to
 maintain.
 
 With the above caveats, Gnulib code should port without problem to new
-hosts, e.g., hosts conforming to C99 or to recent POSIX standards.
-Hence Gnulib code should avoid using constructs (e.g., undeclared
-functions return @code{int}) that do not conform to C99.
+hosts, e.g., hosts conforming to recent C and POSIX standards.  Hence
+Gnulib code should avoid using constructs that these newer standards
+no longer require, without first testing for the presence of these
+constructs.  For example, because C11 made variable length arrays
+optional, Gnulib code should avoid them unless it first uses the
+@code{vararrays} module to check whether they are supported.
 
 @node High Quality
 @section High Quality