Re: gnulib/README -> gnulib.texi

[Paul Eggert]

On 04/21/2012 05:17 PM, Bruno Haible wrote:

> Patches welcome!

Here's a quick first cut.

---
 ChangeLog             |   15 +++
 README                |  230 +------------------------------------
 doc/gnulib-intro.texi |   15 +++
 doc/gnulib.texi       |  303 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 338 insertions(+), 225 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c99459a..081e74d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2012-04-21  Paul Eggert  <address@hidden>
+
+       doc: move contributor's guide from README to manual
+       Prompted by Karl Berry's suggestion in
+       <http://lists.gnu.org/archive/html/bug-gnulib/2012-04/msg00140.html>
+       and by Bruno Haible's followup suggestion in that thread.
+       * README (For more Information): New section.
+       (Contributing to Gnulib): Move contents to .texi files; see below.
+       * doc/gnulib-intro.texi (Target Platforms): Mention C version.
+       (Tested Development): New section, taken from README.
+       * doc/gnulib.texi (Contributing to Gnulib, Gnulib's Licensing)
+       (Indent with Spaces, How to Add a New Module)
+       (Portability Guidelines): New sections.
+       (Unit test modules): Add material about test suite.
+
 2012-04-22  Bruno Haible  <address@hidden>
 
        users.txt: Update.
diff --git a/README b/README
index 4bf10dd..2888c7c 100644
--- a/README
+++ b/README
@@ -75,232 +75,12 @@ to join the autotools-announce mailing list to be advised 
of such
 changes.
 
 
-Contributing to Gnulib
-======================
+For more Information
+====================
 
-All software here is copyrighted by the Free Software Foundation - you need
-to have filled out an assignment form for a project that uses the
-module for that contribution to be accepted here.
-
-If you have a piece of code that you would like to contribute, please
-email address@hidden  You can review the archives, subscribe, etc.,
-via http://lists.gnu.org/mailman/listinfo/bug-gnulib.
-
-Generally we are looking for files that fulfill at least one of the
-following requirements:
-
-    * If your .c and .h files define functions that are broken or
-missing on some other system, we should be able to include it.
-
-    * If your functions remove arbitrary limits from existing
-functions (either under the same name, or as a slightly different
-name), we should be able to include it.
-
-If your functions define completely new but rarely used functionality,
-you should probably consider packaging it as a separate library.
-
-
-License
--------
-Gnulib contains code both under GPL and LGPL.  Because several packages
-that use Gnulib are GPL, the files state they are licensed under GPL.
-However, to support LGPL projects as well, you may use some of the
-files under LGPL.  The "License:" information in the files under
-modules/ clarifies the real license that applies to the module source.
-
-Keep in mind that if you submit patches to files in Gnulib, you should
-license them under a compatible license, which means that sometimes
-the contribution will have to be LGPL, if the original file is
-available under LGPL via a "License: LGPL" information in the
-projects' modules/ file.
-
-
-Indent with spaces, not TABs
-----------------------------
-We use space-only indentation in nearly all files. This includes all
-*.h, *.c, *.y files, except for the regex module. Makefile and ChangeLog
-files are excluded, since TAB characters are part of their format.
-
-In order to tell your editor to produce space-only indentation, you
-can use these instructions.
-
-  * For Emacs: Add these lines to your Emacs initialization file
-    ($HOME/.emacs or similar):
-
-      ;; In gnulib, indent with spaces everywhere (not TABs).
-      ;; Exceptions: Makefile and ChangeLog modes.
-      (add-hook 'find-file-hook '(lambda ()
-        (if (and buffer-file-name
-                 (string-match "/gnulib\\>" (buffer-file-name))
-                 (not (string-equal mode-name "Change Log"))
-                 (not (string-equal mode-name "Makefile")))
-            (setq indent-tabs-mode nil))))
-
-  * For vi (vim): Add these lines to your $HOME/.vimrc file:
-
-      " Don't use tabs for indentation. Spaces are nicer to work with.
-      set expandtab
-
-    For Makefile and ChangeLog files, compensate this by adding this to
-    your $HOME/.vim/after/indent/make.vim and
-    $HOME/.vim/after/indent/changelog.vim files:
-
-      " Use tabs for indentation, regardless of the global setting.
-      set noexpandtab
-
-  * For Eclipse: In the "Window|Preferences" dialog (or "Eclipse|Preferences"
-    dialog on MacOS),
-    1. Under "General|Editors|Text Editors", select the "Insert spaces for 
tabs"
-       checkbox.
-    2. Under "C/C++|Code Style", select a code style profile that has the
-       "Indentation|Tab policy" combobox set to "Spaces only", such as the
-       "GNU [built-in]" policy.
-
-If you use the GNU indent program, pass it the option '--no-tabs'.
-
-
-How to add a new module
------------------------
-* Add the header files and source files to lib/.
-* If the module needs configure-time checks, write an autoconf
-  macro for it in m4/<module>.m4. See m4/README for details.
-* Write a module description modules/<module>, based on modules/TEMPLATE.
-* If the module contributes a section to the end-user documentation,
-  put this documentation in doc/<module>.texi and add it to the "Files"
-  section of modules/<module>.  Most modules don't do this; they have only
-  documentation for the programmer (= gnulib user).  Such documentation
-  usually goes into the lib/ source files.  It may also go into doc/;
-  but don't add it to the module description in this case.
-* Add the module to the list in MODULES.html.sh.
-
-You can test that a module builds correctly with:
-  $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
-  $ cd /tmp/testdir
-  $ ./configure && make
-
-Other things:
-* Check the license and copyright year of headers.
-* Check that the source code follows the GNU coding standards;
-  see <http://www.gnu.org/prep/standards>.
-* Add source files to config/srclist* if they are identical to upstream
-  and should be upgraded in gnulib whenever the upstream source changes.
-* Include header files in source files to verify the function prototypes.
-* Make sure a replacement function doesn't cause warnings or clashes on
-  systems that have the function.
-* Autoconf functions can use gl_* prefix. The AC_* prefix is for
-  autoconf internal functions.
-* Build files only if they are needed on a platform.  Look at the
-  alloca and fnmatch modules for how to achieve this.  If for some
-  reason you cannot do this, and you have a .c file that leads to an
-  empty .o file on some platforms (through some big #if around all the
-  code), then ensure that the compilation unit is not empty after
-  preprocessing.  One way to do this is to #include <stddef.h> or
-  <stdio.h> before the big #if.
-
-
-Portability guidelines
-----------------------
-
-Gnulib code is intended to be portable to a wide variety of platforms,
-not just GNU platforms.  See the documentation section "Target Platforms"
-for details.
-
-Many Gnulib modules exist so that applications need not worry about
-undesirable variability in implementations.  For example, an
-application that uses the 'malloc' module need not worry about (malloc
-(0)) returning NULL on some Standard C platforms; and 'time_r' users
-need not worry about localtime_r returning int (not 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
-<float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally.  It
-can also assume the existence of <ctime.h>, <errno.h>, <fcntl.h>,
-<locale.h>, <signal.h>, <stdio.h>, <stdlib.h>, <string.h>, and <time.h>.
-Similarly, many modules include <sys/types.h> even though it's not even
-in C99; that's OK since <sys/types.h> has been around nearly forever.
-
-Even if the include files exist, they may not conform to C89.
-However, GCC has a "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.
-For example, strtod and mktime have some bugs on some platforms.
-You can work around some of these problems by requiring the relevant
-modules, e.g., the Gnulib 'mktime' module supplies a working and
-conforming 'mktime'.
-
-The GNU coding standards allow one departure from strict C99: Gnulib
-code can assume that standard internal types like size_t are no wider
-than 'long'.  POSIX 1003.1-2001 and the GNU coding standards both
-require 'int' to be at least 32 bits wide, so Gnulib code assumes this
-as well.  Gnulib code makes the following additional assumptions:
-
- * Signed integer arithmetic is two's complement.
-
-   Previously, gnulib code sometimes assumed that signed integer
-   arithmetic wraps around, but modern compiler optimizations
-   sometimes do not guarantee this, and gnulib code with this
-   assumption is now considered to be questionable.  For more, please
-   see the file doc/intprops.texi.
-
-   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.
-   All practical gnulib targets use two's complement.
-
- * There are no "holes" in integer values: all the bits of an integer
-   contribute to its value in the usual way.
-
- * Addresses and sizes behave as if objects reside in a flat address space.
-   In particular:
-
-   - If two nonoverlapping objects have sizes S and T represented as
-     size_t values, then S + T cannot overflow.
-
-   - A pointer P points within an object O if and only if
-     (char *) &O <= (char *) P && (char *) P < (char *) (&O + 1).
-
-   - If an existing object has size S, and if T is sufficiently small
-     (e.g., 8 KiB), then S + T cannot overflow.  Overflow in this case
-     would mean that the rest of your program fits into T bytes, which
-     can't happen in realistic flat-address-space hosts.
-
- * Objects with all bits zero are treated as 0 or NULL.  For example,
-   memset (A, 0, sizeof A) initializes an array A of pointers to NULL.
-
- * Adding zero to a null pointer does not change the pointer.
-   For example, 0 + (char *) NULL == (char *) NULL.
-
-The above assumptions are not required by the C or POSIX standards but
-hold on all practical porting targets that we're familiar with.  If
-you have a porting target where these assumptions are not true, we'd
-appreciate hearing of any fixes.  We need fixes that do not increase
-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 'int') that do not conform to C99.
-
-
-High Quality
-============
-
-We develop and maintain a testsuite for Gnulib.  The goal is to have a
-100% firm interface so that maintainers can feel free to update to the
-code in git at *any* time and know that their application will not
-break.  This means that before any change can be committed to the
-repository, a test suite program must be produced that exposes the bug
-for regression testing.  All experimental work should be done on
-branches to help promote this.
+For more information about Gnulib, including instructions about how to
+contribute to Gnulib, please see the Gnulib manual, which can be found
+at <http://www.gnu.org/software/gnulib/manual/>.
 
 
 -----
diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi
index d962ace..73ae140 100644
--- a/doc/gnulib-intro.texi
+++ b/doc/gnulib-intro.texi
@@ -77,6 +77,10 @@ failed.
 @node Target Platforms
 @section Target Platforms
 
+Gnulib requires support for the C programming language.  Most Gnulib
+modules require only features from C89, the 1989 version of the C
+standard.  One module, @code{fts}, requires some C99 features.
+
 Gnulib supports a number of platforms that we call the ``reasonable
 portability targets''.  This class consists of widespread operating systems,
 for three years after their last availability, or --- for proprietary
@@ -421,6 +425,17 @@ contribution will have to be LGPL, if the original file is 
available
 under LGPL.  You can find out about it by looking for a "License: LGPL"
 information in the corresponding module description.
 
address@hidden Tested Development
address@hidden Tested Development
+Gnulib has a test suite that is developed and maintained along with
+the rest of the code.  The goal is to have a
+100% firm interface so that maintainers can feel free to update the
+code in Git at any time and know that their application will not
+break.  This means that before any change can be committed to the
+repository, a test suite program must be produced that exposes the bug
+for regression testing.  All experimental work should be done on
+branches to help promote this.
+
 @node Steady Development
 @section Steady Development
 
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 8725634..12e204d 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -59,6 +59,7 @@ Documentation License''.
 @menu
 * Introduction::
 * Invoking gnulib-tool::
+* Contributing to Gnulib::
 * Writing modules::
 * Extending Gnulib::
 * Miscellaneous Notes::
@@ -113,6 +114,7 @@ Resources:
 * Various Kinds of Modules::
 * Collaborative Development::
 * Copyright::
+* Tested Development::
 * Steady Development::
 * Openness::
 @end menu
@@ -122,6 +124,298 @@ Resources:
 
 @include gnulib-tool.texi
 
address@hidden Contributing to Gnulib
address@hidden Contributing to Gnulib
+
+All Gnulib software is copyrighted by the Free Software Foundation.
+You need to have filled out an assignment form for a project that uses the
+module for that contribution to be accepted here.
+
+If you have a piece of code that you would like to contribute, please
+email @email{bug-gnulib@@gnu.org}.  You can review the archives,
+subscribe, etc., via @url{http://lists.gnu.org/mailman/listinfo/bug-gnulib}.
+
+Generally we are looking for files that fulfill at least one of the
+following requirements:
+
address@hidden
address@hidden
+If your @code{.c} and @code{.h} files define functions that are broken or
+missing on some other system, we should be able to include it.
+
address@hidden
+If your functions remove arbitrary limits from existing functions
+(either under the same name, or as a slightly different name), we
+should be able to include it.
+
address@hidden
+If your functions define completely new but rarely used functionality,
+you should probably consider packaging it as a separate library.
address@hidden itemize
+
address@hidden
+* Gnulib's Licensing::
+* Indent with Spaces::
+* How to Add a New Module::
+* Portability Guidelines::
address@hidden menu
+
address@hidden Gnulib's Licensing
address@hidden Gnulib's Licensing
+
+Gnulib contains code both under the GPL and the address@hidden  Because
+several packages that use Gnulib are GPLed, the files state they are
+licensed under the address@hidden  However, to support LGPLed projects as well,
+you may use some of the files under the address@hidden  The ``License:''
+information in the files under @file{modules/} clarifies the real license
+that applies to the module source.
+
+Keep in mind that if you submit patches to files in Gnulib, you should
+license them under a compatible license, which means that sometimes
+the contribution will have to be LGPLed if the original file is
+available under LGPL via a ``License: LGPL'' information in the
+projects' @file{modules/} file.
+
address@hidden Indent with Spaces
address@hidden Indent with Spaces, not TABs
+
+We use space-only indentation in nearly all files. This includes all
address@hidden, @code{*.c}, @code{*.y} files, except for the @code{regex} 
module.
address@hidden and @file{ChangeLog}
+files are excluded, since TAB characters are part of their format.
+
+In order to tell your editor to produce space-only indentation, you
+can use these instructions.
+
address@hidden @asis
address@hidden For Emacs:
+Add these lines to your Emacs initialization file
+(@file{$HOME/.emacs} or similar):
+
address@hidden
+;; In gnulib, indent with spaces everywhere (not TABs).
+;; Exceptions: Makefile and ChangeLog modes.
+(add-hook 'find-file-hook '(lambda ()
+  (if (and buffer-file-name
+           (string-match "/gnulib\\>" (buffer-file-name))
+           (not (string-equal mode-name "Change Log"))
+           (not (string-equal mode-name "Makefile")))
+      (setq indent-tabs-mode nil))))
address@hidden example
+
address@hidden For vi (vim):
+Add these lines to your @file{$HOME/.vimrc} file:
+
address@hidden
+" Don't use tabs for indentation. Spaces are nicer to work with.
+set expandtab
address@hidden example
+
+For Makefile and ChangeLog files, compensate this by adding this to
+your @file{$HOME/.vim/after/indent/make.vim} and
address@hidden/.vim/after/indent/changelog.vim} files:
+
address@hidden
+" Use tabs for indentation, regardless of the global setting.
+set noexpandtab
address@hidden example
+
address@hidden For Eclipse:
+In the ``Window|Preferences'' dialog (or ``Eclipse|Preferences''
+dialog on MacOS),
+
address@hidden
address@hidden
+Under ``General|Editors|Text Editors'', select the ``Insert spaces for tabs''
+checkbox.
address@hidden
+Under ``C/C++|Code Style'', select a code style profile that has the
+``Indentation|Tab policy'' combobox set to ``Spaces only'', such as the
+``GNU [built-in]'' policy.
address@hidden enumerate
address@hidden table
+
+If you use the GNU indent program, pass it the option '--no-tabs'.
+
+
address@hidden How to Add a New Module
address@hidden How to Add a New Module
+
address@hidden
address@hidden
+Add the header files and source files to lib/.
+
address@hidden
+If the module needs configure-time checks, write an autoconf
+macro for it in @file{m4/@var{module}.m4}. See m4/README for details.
+
address@hidden
+Write a module description @file{modules/@var{module}}, based on
address@hidden/TEMPLATE}.
+
address@hidden
+If the module contributes a section to the end-user documentation, put
+this documentation in @file{doc/@var{module}.texi} and add it to the
+``Files'' section of @file{modules/@var{module}}.  Most modules don't
+do this; they have only documentation for the programmer (the gnulib
+user).  Such documentation usually goes into the @file{lib/} source
+files.  It may also go into @file{doc/}; but don't add it to the
+module description in this case.
+
address@hidden
+Add the module to the list in @file{MODULES.html.sh}.
address@hidden itemize
+
address@hidden
+You can test that a module builds correctly with:
+
address@hidden
+$ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
+$ cd /tmp/testdir
+$ ./configure && make
address@hidden example
+
address@hidden
+Other things:
+
address@hidden
address@hidden
+Check the license and copyright year of headers.
address@hidden
+Check that the source code follows the GNU coding standards;
+see @url{http://www.gnu.org/prep/standards}.
address@hidden
+Add source files to @file{config/srclist*} if they are identical to upstream
+and should be upgraded in gnulib whenever the upstream source changes.
address@hidden
+Include header files in source files to verify the function prototypes.
address@hidden
+Make sure a replacement function doesn't cause warnings or clashes on
+systems that have the function.
address@hidden
+Autoconf functions can use the @code{gl_*} prefix. The @code{AC_*} prefix is 
for
+Autoconf internal functions.
address@hidden
+Build files only if they are needed on a platform.  Look at the
address@hidden and @code{fnmatch} modules for how to achieve this.  If for some
+reason you cannot do this, and you have a @code{.c} file that leads to an
+empty @code{.o} file on some platforms (through some big @code{#if} around all 
the
+code), then ensure that the compilation unit is not empty after
+preprocessing.  One way to do this is to @code{#include <stddef.h>} or
address@hidden<stdio.h>} before the big @code{#if}.
address@hidden itemize
+
address@hidden Portability Guidelines
address@hidden Portability Guidelines
+
+Gnulib code is intended to be portable to a wide variety of platforms,
+not just GNU platforms.  @xref{Target Platforms}.
+
+Many Gnulib modules exist so that applications need not worry about
+undesirable variability in implementations.  For example, an
+application that uses the @code{malloc} module need not worry about
address@hidden (0)} returning NULL on some Standard C platforms; and
address@hidden users need not worry about @code{localtime_r} returning
address@hidden (not @code{char *}) on some platforms that predate POSIX
+1003.1-2001.
+
+Currently Gnulib assumes 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 Gnulib assumes a freestanding C89 compiler, Gnulib code can include
address@hidden<float.h>}, @code{<limits.h>}, @code{<stdarg.h>}, and
address@hidden<stddef.h>} unconditionally.  It can also assume the existence
+of @code{<ctime.h>}, @code{<errno.h>}, @code{<fcntl.h>},
address@hidden<locale.h>}, @code{<signal.h>}, @code{<stdio.h>},
address@hidden<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
+forever.
+
+Even if the include files exist, they may not conform to C89.
+However, GCC has a @code{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.
+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:
+
address@hidden
address@hidden
+Signed integer arithmetic is two's complement.
+
+Previously, Gnulib code sometimes assumed that signed integer
+arithmetic wraps around, but modern compiler optimizations
+sometimes do not guarantee this, and Gnulib code with this
+assumption is now considered to be questionable.  For more, please
+see the file doc/intprops.texi.
+
+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.
+All practical Gnulib targets use two's complement.
+
address@hidden
+There are no ``holes'' in integer values: all the bits of an integer
+contribute to its value in the usual way.
+
address@hidden
+Addresses and sizes behave as if objects reside in a flat address space.
+In particular:
+
address@hidden
address@hidden
+If two nonoverlapping objects have sizes @var{S} and @var{T}
+represented as @code{size_t} values, then @address@hidden + @var{T}}
+cannot overflow.
+
address@hidden
+A pointer @var{P} points within an object @var{O} if and only if
address@hidden(char *) &@var{O} <= (char *) @var{P} && (char *) @var{P} <
+(char *) (&@var{O} + 1)}.
+
address@hidden
+If an existing object has size @var{S}, and if @var{T} is sufficiently
+small (e.g., 8 KiB), then @address@hidden + @var{T}} cannot overflow.
+Overflow in this case would mean that the rest of your program fits
+into @var{T} bytes, which can't happen in realistic flat-address-space
+hosts.
address@hidden itemize
+
address@hidden
+Objects with all bits zero are treated as 0 or @address@hidden  For
+example, @code{memset (A, 0, sizeof A)} initializes an array @code{A}
+of pointers to @address@hidden
+
address@hidden
+Adding zero to a null pointer does not change the pointer.
+For example, @code{0 + (char *) NULL == (char *) address@hidden
address@hidden itemize
+
+The above assumptions are not required by the C or POSIX standards but
+hold on all practical porting targets that we're familiar with.  If
+you have a porting target where these assumptions are not true, we'd
+appreciate hearing of any fixes.  We need fixes that do not increase
+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.
 
 @node Writing modules
 @chapter Writing modules
@@ -518,6 +812,15 @@ maintenance.
 @node Unit test modules
 @section Unit test modules
 
+Gnulib has a test suite that is developed and maintained along with
+the rest of the code.  The goal is to have a
+100% firm interface so that maintainers can feel free to update the
+code in Git at any time and know that their application will not
+break.  This means that before any change can be committed to the
+repository, a test suite program must be produced that exposes the bug
+for regression testing.  All experimental work should be done on
+branches to help promote this.
+
 A unit test that is a simple C program usually has a module description as
 simple as this:
 
-- 
1.7.6.5