update NEWS.stable

[gnulib.git] / doc / gnulib.texi

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 74499b5..3e1599c 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -2,8 +2,14 @@
 @comment %**start of header
 @setfilename gnulib.info
 @settitle GNU Gnulib
 @comment %**start of header
 @setfilename gnulib.info
 @settitle GNU Gnulib

+@c Define a new index for the magic constants in regex.texi.
+@defcodeindex cn

 @syncodeindex fn cp
 @syncodeindex fn cp

+@syncodeindex ky cp

 @syncodeindex pg cp
 @syncodeindex pg cp

+@syncodeindex tp cp
+@syncodeindex vr cp
+@syncodeindex cn cp

 @ifclear texi2html
 @firstparagraphindent insert
 @end ifclear
 @ifclear texi2html
 @firstparagraphindent insert
 @end ifclear


@@ -54,6 +60,7 @@ Documentation License''.
 * Introduction::
 * Invoking gnulib-tool::
 * Writing modules::
 * Introduction::
 * Invoking gnulib-tool::
 * Writing modules::

+* Extending Gnulib::

 * Miscellaneous Notes::
 * POSIX Substitutes Library::       Building as a separate substitutes library.
 * Header File Substitutes::         Overriding system headers.
 * Miscellaneous Notes::
 * POSIX Substitutes Library::       Building as a separate substitutes library.
 * Header File Substitutes::         Overriding system headers.


@@ -62,6 +69,7 @@ Documentation License''.
 * Glibc Header File Substitutes::   Overriding system headers.
 * Glibc Function Substitutes::      Replacing system functions.
 * Particular Modules::              Documentation of individual modules.
 * Glibc Header File Substitutes::   Overriding system headers.
 * Glibc Function Substitutes::      Replacing system functions.
 * Particular Modules::              Documentation of individual modules.

+* Regular expressions::             The regex module.

 * GNU Free Documentation License::  Copying and sharing this manual.
 * Index::
 @end menu
 * GNU Free Documentation License::  Copying and sharing this manual.
 * Index::
 @end menu


@@ -117,8 +125,8 @@ Resources:
 @node Writing modules
 @chapter Writing modules
 
 @node Writing modules
 @chapter Writing modules
 

-This chapter explains how to write modules of your own, either for your own
-package (to be used with gnulib-tool's @samp{--local-dir} option), or for
+This chapter explains how to write modules of your own, either to
+extend Gnulib for your own package (@pxref{Extending Gnulib}), or for

 inclusion in gnulib proper.
 
 The guidelines in this chapter do not necessarily need to be followed for
 inclusion in gnulib proper.
 
 The guidelines in this chapter do not necessarily need to be followed for


@@ -608,6 +616,84 @@ before every release.
 @end enumerate
 
 
 @end enumerate
 
 

+@node Extending Gnulib
+@chapter Extending Gnulib
+
+Gnulib modules are intended to be suitable for widespread use.  Most
+problems with Gnulib can and should be fixed in a generic way, so that
+all of Gnulib's users can benefit from the change.  But occasionally a
+problem arises that is difficult or undesirable to fix generically, or
+a project that uses Gnulib may need to work around an issue before the
+Gnulib maintainers commit a final fix.  Maintainers may also want to
+add their own pools of modules to projects as Gnulib ``staging
+areas.''
+
+The obvious way to make local changes to Gnulib modules is to use
+@command{gnulib-tool} to check out pristine modules, then to modify
+the results in-place.  This works well enough for short-lived
+experiments.  It is harder to keep modified versions of Gnulib modules
+for a long time, even though Git (or another distributed version
+control systems) can help out a lot with this during the development
+process.
+
+Git, however, doesn't address the distribution issue.  When a package
+``foobar'' needs a modified version of, say, @file{stdint.in.h}, it
+either has to put a comment into @file{foobar/autogen.sh} saying
+``Attention! This doesn't work with a pristine Gnulib, you need this
+and that patch after checking out Gnulib,'' or it has to use the
+@samp{--avoid=stdint} option and provide the modified @code{stdint}
+module in a different directory.
+
+The @option{--local-dir} option to @command{gnulib-tool} solves this
+problem.  It allows the package to override or augment Gnulib.  This
+means:
+
+@itemize @bullet
+@item
+You can store files that are to override Gnulib files or modules.
+
+@item
+You can store context diffs to be applied to Gnulib files.
+
+@item
+You can add modules of your own, that are not (yet) in Gnulib.
+
+@item
+You can also add unstructured amounts of code to the library, by
+grouping the non-Gnulib files of the library in a single kitchen-sink
+``module.''  (This kind of kitchen-sink module is not needed when you
+use the @command{gnulib-tool} option @samp{--makefile-name}.)
+@end itemize
+
+In a release tarball, you can distribute the contents of this
+@option{--local-dir} directory that will be combinable with newer
+versions of Gnulib, barring incompatible changes to Gnulib.
+
+If the @samp{--local-dir=@var{directory}} option is specified, then
+@command{gnulib-tool} looks in @file{@var{directory}} whenever it
+reads a file from the Gnulib directory.  Suppose @command{gnulib-tool}
+is looking for @var{file}.  Then:
+
+@itemize @bullet
+@item
+If @file{@var{directory}/@var{file}} exists, then @samp{gnulib-tool} uses
+it instead of the file included in Gnulib.
+
+@item
+Otherwise, if @file{@var{directory}/@var{file}.diff} exists, then
+@command{gnulib-tool} uses the file from Gnulib after applying the diff
+using the @command{patch} program.
+
+@item
+Otherwise, @command{gnulib-tool} uses the file included in Gnulib.
+@end itemize
+
+Please make wise use of this option.  It also allows you to easily
+hold back modifications you make to Gnulib macros in cases it may be
+better to share them.
+
+
+

 @node Miscellaneous Notes
 @chapter Miscellaneous Notes
 
 @node Miscellaneous Notes
 @chapter Miscellaneous Notes
 


@@ -629,40 +715,37 @@ before every release.
 
 @cindex Out of Memory handling
 @cindex Memory allocation failure
 
 @cindex Out of Memory handling
 @cindex Memory allocation failure

-The GSS API does not have a standard error code for the out of memory
-error condition.  Instead of adding a non-standard error code, this
-library has chosen to adopt a different strategy.  Out of memory
-handling happens in rare situations, but performing the out of memory
-error handling after almost all API function invocations pollute your
-source code and might make it harder to spot more serious problems.
-The strategy chosen improves code readability and robustness.
+The gnulib API does not have a standard error code for the out of memory
+error condition.  Instead of adding a non-standard error code, gnulib
+has chosen to adopt a different strategy.  Out of memory handling
+happens in rare situations, but performing the out of memory error
+handling after almost all API function invocations pollute your source
+code and might make it harder to spot more serious problems.  The
+strategy chosen improves code readability and robustness.

 
 @cindex Aborting execution
 For most applications, aborting the application with an error message
 when the out of memory situation occurs is the best that can be wished
 
 @cindex Aborting execution
 For most applications, aborting the application with an error message
 when the out of memory situation occurs is the best that can be wished

-for.  This is how the library behaves by default.
-
-@vindex xalloc_fail_func
-However, we realize that some applications may not want to have the
-GSS library abort execution in any situation.  The GSS library supports
-a hook to let the application regain control and perform its own
-cleanups when an out of memory situation has occurred.  The application
-can define a function (having a @code{void} prototype, i.e., no return
-value and no parameters) and set the library variable
-@code{xalloc_fail_func} to that function.  The variable should be
+for.  This is how the library behaves by default (using
+the @samp{xalloc-die} module).
+
+@vindex xalloc_die
+However, we realize that some applications may not want to abort
+execution in any situation.  Gnulib supports a hook to let the
+application regain control and perform its own cleanups when an out of
+memory situation has occurred.  The application can define a function
+(having a @code{void} prototype, i.e., no return value and no
+parameters) and set the library variable
+@code{xalloc_die} to that function.  The variable should be

 declared as follows.
 
 @example
 declared as follows.
 
 @example

-extern void (*xalloc_fail_func) (void);
+extern void (*xalloc_die) (void);

 @end example
 
 @end example
 

-The GSS library will invoke this function if an out of memory error
-occurs.  Note that after this the GSS library is in an undefined
-state, so you must unload or restart the application to continue call
-GSS library functions.  The hook is only intended to allow the
-application to log the situation in a special way.  Of course, care
-must be taken to not allocate more memory, as that will likely also
-fail.
+Gnulib will invoke this function if an out of memory error occurs.  Note
+that the function should not return.  Of course, care must be taken to
+not allocate more memory, as that will likely also fail.

 
 
 @node Obsolete modules
 
 
 @node Obsolete modules


@@ -739,8 +822,16 @@ When @code{gnulib-tool} receives the option @code{--with-all-tests},
 it will include all tests regardless of their status attributes.
 
 @code{gnulib-tool --create-testdir} and
 it will include all tests regardless of their status attributes.
 
 @code{gnulib-tool --create-testdir} and

-@code{gnulib-tool --create-megatestdir} always include all tests
-regardless of their status attributes.
+@code{gnulib-tool --create-megatestdir} by default include all tests of
+modules specified on the command line, regardless of their status
+attributes.  Tests of modules occurring as dependencies are not included
+by default if they have one of these status attributes.  The options
+@code{--with-c++-tests}, @code{--with-longrunning-tests},
+@code{--with-privileged-tests}, @code{--with-unportable-tests} are
+recognized here as well.  Additionally, @code{gnulib-tool} also
+understands the options @code{--without-c++-tests},
+@code{--without-longrunning-tests}, @code{--without-privileged-tests},
+@code{--without-unportable-tests}.

 
 In order to mark a module with a status attribute, you need to add it
 to the module description, like this:
 
 In order to mark a module with a status attribute, you need to add it
 to the module description, like this:


@@ -898,7 +989,7 @@ XP.  The function declaration is present if @code{WINVER >= 0x0501}.
 Windows 2000 does not have getaddrinfo in its @file{WS2_32.DLL}.
 
 Thus, if you want to assume Windows XP or later, you can add
 Windows 2000 does not have 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 to (partial) getaddrinfo
+AC_DEFINE(WINVER, 0x0501) to avoid compiling the (partial) getaddrinfo

 implementation.
 
 If you want to support Windows 2000, don't do anything.  The
 implementation.
 
 If you want to support Windows 2000, don't do anything.  The


@@ -6399,7 +6490,6 @@ This list of functions is sorted according to the header that declares them.
 * Quoting::
 * error and progname::
 * gcd::
 * Quoting::
 * error and progname::
 * gcd::

-* Regular expressions::

 * Searching for Libraries::
 * Exported Symbols of Shared Libraries::
 * LD Version Scripts::
 * Searching for Libraries::
 * Exported Symbols of Shared Libraries::
 * LD Version Scripts::


@@ -6408,6 +6498,7 @@ This list of functions is sorted according to the header that declares them.
 * func::
 * warnings::
 * manywarnings::
 * func::
 * warnings::
 * manywarnings::

+* Running self-tests under valgrind::

 @end menu
 
 @node alloca
 @end menu
 
 @node alloca


@@ -6480,16 +6571,6 @@ ASCII characters.
 
 @include gcd.texi
 
 
 @include gcd.texi
 

-@node Regular expressions
-@section Regular expressions
-
-Gnulib supports many different types of regular expressions; although
-the underlying features are the same or identical, the syntax used
-varies.  The descriptions given here for the different types are
-generated automatically.
-
-@include regexprops-generic.texi
-

 @include havelib.texi
 
 @include lib-symbol-visibility.texi
 @include havelib.texi
 
 @include lib-symbol-visibility.texi


@@ -6506,6 +6587,36 @@ generated automatically.
 
 @include manywarnings.texi
 
 
 @include manywarnings.texi
 

+@include valgrind-tests.texi
+
+@node Regular expressions
+@chapter Regular expressions
+
+@menu
+* Overview::
+* Regular Expression Syntax::
+* Common Operators::
+* GNU Operators::
+* GNU Emacs Operators::
+* What Gets Matched?::
+* Programming with Regex::
+* Regular expression syntaxes::
+@end menu
+
+@lowersections
+@include regex.texi
+@raisesections
+
+@node Regular expression syntaxes
+@section Regular expression syntaxes
+
+Gnulib supports many different types of regular expressions; although
+the underlying features are the same or identical, the syntax used
+varies.  The descriptions given here for the different types are
+generated automatically.
+
+@include regexprops-generic.texi
+

 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License