# HG changeset patch
# User Paul Eggert <eggert@cs.ucla.edu>
# Date 1356557902 28800
# Node ID e7b6814b7d212579becddd0d8f3b10edd5ae516f
# Parent  4aaecb5536cf92e463a1b23ae1424d5e77a5d085
doc: move README into manual

* README: Move contents to new file doc/gnulib-readme.texi.
Replace with a one-line summary.
* doc/gnulib.texi (Brief Overview): New section,
with old intro preface.  Include gnulib-readme.texi for contents.
(Philosophy): Rename from "Introduction", since this
section no longer introduces the rest.  Write a new preface.
* doc/gnulib-readme.texi: New file, with the old contents of
README texinfo-ized.  This way, the README info appears
in the online and printed manual.

diff -r 4aaecb5536cf -r e7b6814b7d21 ChangeLog
--- a/ChangeLog	Tue Dec 25 21:18:14 2012 -0800
+++ b/ChangeLog	Wed Dec 26 13:38:22 2012 -0800
@@ -1,3 +1,16 @@
+2012-12-27  Paul Eggert  <eggert@cs.ucla.edu>
+
+	doc: move README into manual
+	* README: Move contents to new file doc/gnulib-readme.texi.
+	Replace with a one-line summary.
+	* doc/gnulib.texi (Brief Overview): New section,
+	with old intro preface.  Include gnulib-readme.texi for contents.
+	(Philosophy): Rename from "Introduction", since this
+	section no longer introduces the rest.  Write a new preface.
+	* doc/gnulib-readme.texi: New file, with the old contents of
+	README texinfo-ized.  This way, the README info appears
+	in the online and printed manual.
+
 2012-12-25  Ben Pfaff  <blp@cs.stanford.edu>
 
 	c-xvasprintf: Fix "implicit declaration of function" GCC warning.
diff -r 4aaecb5536cf -r e7b6814b7d21 README
--- a/README	Tue Dec 25 21:18:14 2012 -0800
+++ b/README	Wed Dec 26 13:38:22 2012 -0800
@@ -1,320 +1,1 @@
-Gnulib
-======
-
-While portability across operating systems is not one of GNU's primary
-goals, it has helped introduce many people to the GNU system, and is
-worthwhile when it can be achieved at a low cost.  This collection helps
-lower that cost.
-
-Gnulib is intended to be the canonical source for most of the important
-"portability" and/or common files for GNU projects.  These are files
-intended to be shared at the source level; Gnulib is not a typical
-library meant to be installed and linked against.  Thus, unlike most
-projects, Gnulib does not normally generate a source tarball
-distribution; instead, developers grab modules directly from the
-source repository.
-
-The easiest, and recommended, way to do this is to use the gnulib-tool
-script.  Since there is no installation procedure for Gnulib,
-gnulib-tool needs to be run directly in the directory that contains the
-Gnulib source code.  You can do this either by specifying the absolute
-filename of gnulib-tool, or by using a symbolic link from a
-place inside your PATH to the gnulib-tool file of your preferred
-Gnulib checkout.  For example:
-  $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
-
-The home page for Gnulib is http://www.gnu.org/software/gnulib.
-
-
-git and CVS
-===========
-
-Gnulib is available for anonymous checkout.  In any Bourne-shell the
-following should work:
-  $ git clone git://git.sv.gnu.org/gnulib.git
-
-For a read-write checkout you need to have a login on savannah.gnu.org and be
-a member of the gnulib project at http://savannah.gnu.org/projects/gnulib .
-Then, instead of the URL
-  git://git.sv.gnu.org/gnulib
-use the URL
-  ssh://<user>@git.sv.gnu.org/srv/git/gnulib
-where <user> is your login name on savannah.gnu.org.
-
-git resources:
-  Overview: http://en.wikipedia.org/wiki/Git_(software)
-  Homepage: http://git.or.cz/
-  Download: http://www.kernel.org/pub/software/scm/git/
-  Tutorial: http://git.or.cz/course/
-            http://www.kernel.org/pub/software/scm/git/docs/tutorial.html
-  FAQ:      http://git.or.cz/gitwiki/GitFaq
-
-When you use "git annotate" or "git blame" with gnulib, it's recommended that
-you use the "-w" option, in order to ignore massive whitespace changes that
-happened in 2009.
-
-CVS checkouts are also supported:
-  $ cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
-
-Gnulib is hosted on savannah.gnu.org.  The project page is
-http://savannah.gnu.org/projects/gnulib.
-
-
-Keeping Up-to-date
-==================
-
-The best way to work with Gnulib is to check it out of git.
-Subscribing to the bug-gnulib@gnu.org mailing list will help you to
-plan when to update your local copy of Gnulib (which you use to
-maintain your software) from git.  To synchronize, you can use "git pull",
-or "cvs update -dP" if you are still using CVS.
-
-Sometimes, using an updated version of Gnulib will require you to use
-newer versions of GNU Automake or Autoconf.  You may find it helpful
-to join the autotools-announce mailing list to be advised of such
-changes.
-
-
-Contributing to Gnulib
-======================
-
-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 bug-gnulib@gnu.org.  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 Mac OS),
-    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.
-
-
------
-Copyright 2001, 2003-2012 Free Software Foundation, Inc.
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
+Please see doc/gnulib-readme.texi for basic information about Gnulib.
diff -r 4aaecb5536cf -r e7b6814b7d21 doc/gnulib-readme.texi
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/gnulib-readme.texi	Wed Dec 26 13:38:22 2012 -0800
@@ -0,0 +1,432 @@
+@c Gnulib README
+
+@c Copyright 2001, 2003-2012 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts.  A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
+@menu
+* Gnulib Basics::
+* git and CVS::
+* Keeping Up-to-date::
+* Contributing to Gnulib::
+* High Quality::
+@end menu
+
+@node Gnulib Basics
+@section Gnulib Basics
+
+While portability across operating systems is not one of GNU's primary
+goals, it has helped introduce many people to the GNU system, and is
+worthwhile when it can be achieved at a low cost.  This collection helps
+lower that cost.
+
+Gnulib is intended to be the canonical source for most of the important
+``portability'' and/or common files for GNU projects.  These are files
+intended to be shared at the source level; Gnulib is not a typical
+library meant to be installed and linked against.  Thus, unlike most
+projects, Gnulib does not normally generate a source tarball
+distribution; instead, developers grab modules directly from the
+source repository.
+
+The easiest, and recommended, way to do this is to use the
+@command{gnulib-tool} script.  Since there is no installation
+procedure for Gnulib, @command{gnulib-tool} needs to be run directly
+in the directory that contains the Gnulib source code.  You can do
+this either by specifying the absolute filename of
+@command{gnulib-tool}, or by using a symbolic link from a place inside
+your @env{PATH} to the @command{gnulib-tool} file of your preferred
+Gnulib checkout.  For example:
+
+@example
+$ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
+@end example
+
+The home page for Gnulib is @url{http://www.gnu.org/software/gnulib}.
+
+@node git and CVS
+@section git and CVS
+
+Gnulib is available for anonymous checkout.  In any Bourne-shell the
+following should work:
+
+@example
+$ git clone git://git.sv.gnu.org/gnulib.git
+@end example
+
+For a read-write checkout you need to have a login on
+@samp{savannah.gnu.org} and be a member of the Gnulib project at
+@url{http://savannah.gnu.org/projects/gnulib}.  Then, instead of the
+URL @url{git://git.sv.gnu.org/gnulib}, use the URL
+@samp{ssh://@var{user}@@git.sv.gnu.org/srv/git/gnulib} where
+@var{user} is your login name on savannah.gnu.org.
+
+git resources:
+
+@table @asis
+@item Overview:
+@url{http://en.wikipedia.org/wiki/Git_(software)}
+@item Homepage:
+@url{http://git.or.cz/}
+@item Download:
+@url{http://www.kernel.org/pub/software/scm/git/}
+@item Tutorial:
+@url{http://git.or.cz/course/}
+@url{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}
+@item FAQ:
+@url{http://git.or.cz/gitwiki/GitFaq}
+@end table
+
+When you use @code{git annotate} or @code{git blame} with Gnulib, it's
+recommended that you use the @option{-w} option, in order to ignore
+massive whitespace changes that happened in 2009.
+
+CVS checkouts are also supported:
+
+@example
+$ cvs -d :pserver:anonymous@@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD
+@end example
+
+Gnulib is hosted on @samp{savannah.gnu.org}.  The project page is
+@url{http://savannah.gnu.org/projects/gnulib}.
+
+@node Keeping Up-to-date
+@section Keeping Up-to-date
+
+The best way to work with Gnulib is to check it out of git.
+Subscribing to the @email{bug-gnulib@@gnu.org} mailing list will help you to
+plan when to update your local copy of Gnulib (which you use to
+maintain your software) from git.  To synchronize, you can use @code{git pull},
+or @code{cvs update -dP} if you are still using CVS.
+
+Sometimes, using an updated version of Gnulib will require you to use
+newer versions of GNU Automake or Autoconf.  You may find it helpful
+to join the autotools-announce mailing list to be advised of such
+changes.
+
+@node Contributing to Gnulib
+@section Contributing to Gnulib
+
+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 @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:
+
+@itemize
+@item
+If your @file{.c} and @file{.h} files define functions that are broken or
+missing on some other system, we should be able to include it.
+
+@item
+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.
+@end itemize
+
+If your functions define completely new but rarely used functionality,
+you should probably consider packaging it as a separate library.
+
+@menu
+* Gnulib licensing::
+* Indent with spaces not TABs::
+* How to add a new module::
+* Portability guidelines::
+@end menu
+
+@node Gnulib licensing
+@subsection Gnulib licensing
+
+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.
+
+@node Indent with spaces not TABs
+@subsection Indent with spaces not TABs
+
+We use space-only indentation in nearly all files. This includes all
+@file{*.h}, @file{*.c}, @file{*.y} files, except for the @code{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.
+
+@itemize
+@item
+For Emacs: Add these lines to your Emacs initialization file
+(@file{$HOME/.emacs} or similar):
+
+@example
+;; 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))))
+@end example
+
+@item
+For vi (vim): Add these lines to your @file{$HOME/.vimrc} file:
+
+@example
+" Don't use tabs for indentation. Spaces are nicer to work with.
+set expandtab
+@end example
+
+For Makefile and ChangeLog files, compensate this by adding this to
+your @file{$HOME/.vim/after/indent/make.vim} and
+@file{$HOME/.vim/after/indent/changelog.vim} files:
+
+@example
+" Use tabs for indentation, regardless of the global setting.
+set noexpandtab
+@end example
+
+@item
+For Eclipse: In the ``Window|Preferences'' dialog (or ``Eclipse|Preferences''
+dialog on Mac OS),
+
+@enumerate
+@item
+Under ``General|Editors|Text Editors'', select the ``Insert spaces for tabs''
+checkbox.
+
+@item
+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.
+@end enumerate
+
+If you use the GNU indent program, pass it the option @option{--no-tabs}.
+@end itemize
+
+@node How to add a new module
+@subsection How to add a new module
+
+@itemize
+@item
+Add the header files and source files to @file{lib/}.
+
+@item
+If the module needs configure-time checks, write an Autoconf
+macro for it in @file{m4/@var{module}.m4}. See @file{m4/README} for details.
+
+@item
+Write a module description @file{modules/@var{module}}, based on
+@file{modules/TEMPLATE}.
+
+@item
+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 (= 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.
+
+@item
+Add the module to the list in @file{MODULES.html.sh}.
+@end itemize
+
+@noindent
+You can test that a module builds correctly with:
+
+@example
+$ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
+$ cd /tmp/testdir
+$ ./configure && make
+@end example
+
+@noindent
+Other things:
+
+@itemize
+@item
+Check the license and copyright year of headers.
+
+@item
+Check that the source code follows the GNU coding standards;
+see @url{http://www.gnu.org/prep/standards}.
+
+@item
+Add source files to @file{config/srclist*} if they are identical to upstream
+and should be upgraded in Gnulib whenever the upstream source changes.
+
+@item
+Include header files in source files to verify the function prototypes.
+
+@item
+Make sure a replacement function doesn't cause warnings or clashes on
+systems that have the function.
+
+@item
+Autoconf functions can use @samp{gl_*} prefix. The @samp{AC_*} prefix is for
+autoconf internal functions.
+
+@item
+Build files only if they are needed on a platform.  Look at the
+@code{alloca} and @code{fnmatch} modules for how to achieve this.  If
+for some reason you cannot do this, and you have a @file{.c} file that
+leads to an empty @file{.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 @code{<stdio.h>} before the big
+@code{#if}.
+@end itemize
+
+@node Portability guidelines
+@subsection 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 @code{malloc} module need not worry about
+@code{malloc@ (0)} returning @code{NULL} on some Standard C
+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
+@code{<float.h>}, @code{<limits.h>}, @code{<stdarg.h>}, and
+@code{<stddef.h>} unconditionally.  It can also assume the existence
+of @code{<ctime.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
+forever.
+
+Even if the include files exist, they may not conform to C89.
+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.
+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:
+
+@itemize
+@item
+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.
+@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.
+All practical Gnulib targets use two's complement.
+
+@item
+There are no ``holes'' in integer values: all the bits of an integer
+contribute to its value in the usual way.
+
+@item
+Addresses and sizes behave as if objects reside in a flat address space.
+In particular:
+
+@itemize
+@item
+If two nonoverlapping objects have sizes @var{S} and @var{T} represented as
+@code{size_t} values, then @code{@var{S} + @var{T}} cannot overflow.
+
+@item
+A pointer @var{P} points within an object @var{O} if and only if
+@code{(char *) &@var{O} <= (char *) @var{P} && (char *) @var{P} <
+(char *) (&@var{O} + 1)}.
+
+@item
+If an existing object has size @var{S}, and if @var{T} is sufficiently
+small (e.g., 8 KiB), then @code{@var{S} + @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.
+
+@item
+Objects with all bits zero are treated as 0 or NULL@.  For example,
+@code{memset@ (A, 0, sizeof@ A)} initializes an array @code{A} of
+pointers to NULL.
+
+@item
+Adding zero to a null pointer does not change the pointer.
+For example, @code{0 + (char *) NULL == (char *) NULL}.
+@end itemize
+@end 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 High Quality
+@section 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 @emph{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.
+
+@c This copyright notice applies to this file.
+@c Generate it as output too, if the file is being formatted by itself.
+@c Otherwise, it should be formatted as part of a larger document
+@c that contains the relevant copyright notice.
+@ifset standalone
+Copyright @copyright{} 2001, 2003--2012 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the ``GNU Free
+Documentation License'' file as part of this distribution.
+@end ifset
diff -r 4aaecb5536cf -r e7b6814b7d21 doc/gnulib.texi
--- a/doc/gnulib.texi	Tue Dec 25 21:18:14 2012 -0800
+++ b/doc/gnulib.texi	Wed Dec 26 13:38:22 2012 -0800
@@ -57,7 +57,8 @@
 @end ifnottex
 
 @menu
-* Introduction::
+* Brief Overview::
+* Philosophy::
 * Invoking gnulib-tool::
 * Writing modules::
 * Extending Gnulib::
@@ -87,8 +88,8 @@
 @end macro
 
 
-@node Introduction
-@chapter Introduction
+@node Brief Overview
+@chapter Brief Overview
 
 Gnulib is a source code library. It provides basic functionality to
 programs and libraries.  Currently (as of October 2006) more than 30
@@ -104,6 +105,15 @@
       @url{http://www.gnu.org/software/gnulib/}.
 @end itemize
 
+@include gnulib-readme.texi
+
+@node Philosophy
+@chapter Philosophy
+
+Gnulib's design and development philosophy is organized around steady,
+collaborative, and open development of reusable modules that are
+suitable for a reasonably wide variety of platforms.
+
 @menu
 * Benefits::
 * Library vs Reusable Code::