changeset 6256:22062645e739

Move many things into separate files.
author Bruno Haible <bruno@clisp.org>
date Mon, 19 Sep 2005 15:48:03 +0000
parents 049aab67c353
children 83706e6d3215
files doc/ChangeLog doc/gnulib.texi
diffstat 2 files changed, 14 insertions(+), 393 deletions(-) [+]
line wrap: on
line diff
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,11 @@
+2005-09-19  Bruno Haible  <bruno@clisp.org>
+
+	* quote.texi: New file, extracted from gnulib.texi.
+	* ctime.texi: New file, extracted from gnulib.texi.
+	* inet_ntoa.texi: New file, extracted from gnulib.texi.
+	* gnulib-tool.texi: New file, extracted from gnulib.texi.
+	* gnulib.texi: Include them.
+
 2005-09-18  Bruno Haible  <bruno@clisp.org>
 
 	* gnulib.texi (Invoking gnulib-tool): 50% rewritten.
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -1,5 +1,5 @@
 \input texinfo   @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.18 2005-09-19 15:38:33 haible Exp $
+@comment $Id: gnulib.texi,v 1.19 2005-09-19 15:48:03 haible Exp $
 @comment %**start of header
 @setfilename gnulib.info
 @settitle GNU Gnulib
@@ -7,7 +7,7 @@
 @syncodeindex pg cp
 @comment %**end of header
 
-@set UPDATED $Date: 2005-09-19 15:38:33 $
+@set UPDATED $Date: 2005-09-19 15:48:03 $
 
 @copying
 This manual is for GNU Gnulib (updated @value{UPDATED}),
@@ -177,79 +177,13 @@
 @end itemize
 
 
-@node Quoting
-@section Quoting
-
-@cindex Quoting
-@findex quote
-@findex quotearg
-
-Gnulib provides @samp{quote} and @samp{quotearg} modules to help with
-quoting text, such as file names, in messages to the user.  Here's an
-example of using @samp{quote}:
-
-@example
-#include <quote.h>
- ...
-  error (0, errno, _("cannot change owner of %s"), quote (fname));
-@end example
-
-This differs from
-
-@example
-  error (0, errno, _("cannot change owner of `%s'"), fname);
-@end example
-
-@noindent in that @code{quote} escapes unusual characters in
-@code{fname}, e.g., @samp{'} and control characters like @samp{\n}.
-
-@findex quote_n
-However, a caveat: @code{quote} reuses the storage that it returns.
-Hence if you need more than one thing quoted at the same time, you
-need to use @code{quote_n}.
-
-@findex quotearg_alloc
-Also, the quote module is not suited for multithreaded applications.
-In that case, you have to use @code{quotearg_alloc}, defined in the
-@samp{quotearg} module, which is decidedly less convenient.
+@include quote.texi
 
 
-@node ctime
-@section ctime
-@findex ctime
-
-The @code{ctime} function need not be reentrant, and consequently is
-not required to be thread safe.  Implementations of @code{ctime}
-typically write the time stamp into static buffer.  If two threads
-call @code{ctime} at roughly the same time, you might end up with the
-wrong date in one of the threads, or some undefined string.  There is
-a re-entrant interface @code{ctime_r}, that take a pre-allocated
-buffer and length of the buffer, and return @code{NULL} on errors.
-The input buffer should be at least 26 bytes in size.  The output
-string is locale-independent.  However, years can have more than 4
-digits if @code{time_t} is sufficiently wide, so the length of the
-required output buffer is not easy to determine.  Increasing the
-buffer size when @code{ctime_r} return @code{NULL} is not necessarily
-sufficient. The @code{NULL} return value could mean some other error
-condition, which will not go away by increasing the buffer size.
-
-A more flexible function is @code{strftime}.  However, note that it is
-locale dependent.
+@include ctime.texi
 
 
-@node inet_ntoa
-@section inet_ntoa
-@findex inet_ntoa
-
-The @code{inet_ntoa} function need not be reentrant, and consequently
-is not required to be thread safe.  Implementations of
-@code{inet_ntoa} typically write the time stamp into static buffer.
-If two threads call @code{inet_ntoa} at roughly the same time, you
-might end up with the wrong date in one of the threads, or some
-undefined string.  Further, @code{inet_ntoa} is specific for
-@acronym{IPv4} addresses.
-
-A protocol independent function is @code{inet_ntop}.
+@include inet_ntoa.texi
 
 
 @node Out of memory handling
@@ -358,329 +292,8 @@
 @include regexprops-generic.texi
 
 
-@node Invoking gnulib-tool
-@chapter Invoking gnulib-tool
-
-@pindex gnulib-tool
-@cindex invoking @command{gnulib-tool}
-
-@command{gnulib-tool} is the way to import Gnulib modules.  It is also
-possible to borrow Gnulib modules in a package without using
-@command{gnulib-tool}, relying only on the metainformation stored in
-the @file{modules/*} files, but with a growing number of modules this
-becomes tedious.  @command{gnulib-tool} simplifies the management of
-source files, @file{Makefile.am}s and @file{configure.ac} in packages
-incorporating Gnulib modules.
-
-Run @samp{gnulib-tool --help}.  To get familiar with @command{gnulib-tool},
-you can also try some commands with the option @samp{--dry-run}; then
-@code{gnulib-tool} will only report which actions it would perform in a
-real run.
-
-@menu
-* Initial import::              First import of Gnulib modules.
-* Modified imports::            Changing the import specification.
-* Simple update::               Tracking Gnulib development.
-* CVS Issues::                  Integration with CVS.
-@end menu
-
-
-@node Initial import
-@section Initial import
-@cindex initial import
-
-Gnulib assumes your project uses Autoconf and Automake.  Invoking
-@samp{gnulib-tool --import} will copy source files, create a
-@file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with
-Autoconf M4 macro declarations used by @file{configure.ac}, and generate
-a file @file{gnulib-cache.m4} containing the cached specification of how
-Gnulib is used.
-
-Our example will be a library that uses Autoconf, Automake and
-Libtool.  It calls @code{strdup}, and you wish to use gnulib to make
-the package portable to C89 (which doesn't have @code{strdup}).
-
-@example
-~/src/libfoo$ gnulib-tool --import strdup
-Module list with included dependencies:
-  strdup
-File list:
-  lib/strdup.c
-  lib/strdup.h
-  m4/onceonly_2_57.m4
-  m4/strdup.m4
-Copying file m4/gnulib-tool.m4
-Copying file m4/onceonly_2_57.m4
-Copying file lib/strdup.c
-Copying file lib/strdup.h
-Copying file m4/strdup.m4
-Creating lib/Makefile.am
-Creating m4/gnulib-cache.m4
-Creating m4/gnulib-comp.m4
-Finished.
-
-You may need to add #include directives for the following .h files.
-  #include "strdup.h"
-
-Don't forget to
-  - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
-  - mention "lib" in SUBDIRS in Makefile.am,
-  - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
-  - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
-  - invoke gl_INIT in ./configure.ac.
-~/src/libfoo$
-@end example
-
-By default, the source code is copied into @file{lib/} and the M4
-macros in @file{m4/}.  You can override these paths by using
-@code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}.  Some
-modules also provide other files necessary for building. These files
-are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
-@file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option.  If
-neither is specified, the current directory is assumed.
-
-@code{gnulib-tool} can make symbolic links instead of copying the
-source files.  Use the @samp{--symbolic} (or @samp{-s} for short) option
-to do this.
-
-@code{gnulib-tool} will overwrite any pre-existing files, in
-particular @file{Makefile.am}.  Unfortunately, separating the
-generated @file{Makefile.am} content (for building the gnulib library)
-into a separate file, say @file{gnulib.mk}, that could be included
-by your handwritten @file{Makefile.am} is not possible, due to how
-variable assignments are handled by Automake.
-
-Consequently, it is a good idea to choose directories that are not
-already used by your projects, to separate gnulib imported files from
-your own files.  This approach is also useful if you want to avoid
-conflicts between other tools (e.g., @code{gettextize} that also copy
-M4 files into your package.  Simon Josefsson successfully uses a source
-base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
-packages.
-
-After the @samp{--import} option on the command line comes the list of
-Gnulib modules that you want to incorporate in your package.  The names
-of the modules coincide with the filenames in Gnulib's @file{modules/}
-directory.
-
-Some Gnulib modules depend on other Gnulib modules.  @code{gnulib-tool}
-will automatically add the needed modules as well; you need not list
-them explicitly.  @code{gnulib-tool} will also memoize which dependent
-modules it has added, so that when someday a dependency is dropped, the
-implicitly added module is dropped as well (unless you have explicitly
-requested that module).
-
-If you want to cut a dependency, i.e. not add a module although one of
-your requested modules depends on it, you may use the option
-@samp{--avoid=@var{module}} to do so.  Multiple uses of this option are
-possible.  Of course, you will then need to implement the same interface
-as the removed module.
-
-A few manual steps are required to finish the initial import.
-@code{gnulib-tool} printed a summary of these steps.
-
-First, you need to make sure Autoconf can find the macro definitions
-in @file{gnulib-comp.m4}.  Use the @code{ACLOCAL_AMFLAGS} specifier in your
-top-level @file{Makefile.am} file, as in:
-
-@example
-ACLOCAL_AMFLAGS = -I m4
-@end example
-
-You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
-@file{configure.ac}.  The macro @code{gl_EARLY} must be called as soon
-as possible after verifying that the C compiler is working.
-Typically, this is immediately after @code{AC_PROG_CC}, as in:
-
-@example
-...
-AC_PROG_CC
-gl_EARLY
-...
-@end example
-
-The core part of the gnulib checks are done by the macro
-@code{gl_INIT}.  Place it further down in the file, typically where
-you normally check for header files or functions.  For example:
-
-@example
-...
-# For gnulib.
-gl_INIT
-...
-@end example
-
-@code{gl_INIT} will in turn call the macros related with the
-gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
-or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or
-@code{AM_FUNC_GETLINE}.  So there is no need to call those macros yourself
-when you use the corresponding gnulib modules.
-
-You must also make sure that the gnulib library is built.  Add the
-@code{Makefile} in the gnulib source base directory to
-@code{AC_CONFIG_FILES}, as in:
+@include gnulib-tool.texi
 
-@example
-AC_CONFIG_FILES(... lib/Makefile ...)
-@end example
-
-You must also make sure that @code{make} will recurse into the gnulib
-directory.  To achieve this, add the gnulib source base directory to a
-@code{SUBDIRS} Makefile.am statement, as in:
-
-@example
-SUBDIRS = lib
-@end example
-
-or if you, more likely, already have a few entries in @code{SUBDIRS},
-you can add something like:
-
-@example
-SUBDIRS += lib
-@end example
-
-Finally, you have to add compiler and linker flags in the appropriate
-source directories, so that you can make use of the gnulib library.
-Since some modules (@samp{getopt}, for example) may copy files into
-the build directory, @file{top_builddir/lib} is needed as well
-as @file{top_srcdir/lib}.  For example:
-
-@example
-...
-AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
-...
-LIBADD = lib/libgnu.a
-...
-@end example
-
-Don't forget to @code{#include} the various header files.  In this
-example, you would need to make sure that @samp{#include "strdup.h"}
-is evaluated when compiling all source code files, that want to make
-use of @code{strdup}.
-
-When an include file is provided by Gnulib
-you shouldn't try to include the corresponding system header files
-yourself, but let the gnulib header file do it.  The ordering
-of the definition for some symbols may be significant; the Gnulib
-header files take care of that.
-
-For example, to use the @code{time_r} gnulib module you should
-use include header file provided by the gnulib, and so
-@samp{#include "time_r.h"}, but you shouldn't explicitly
-@samp{#include <time.h>} as it is already done in @file{time_r.h}
-before the redefinition of some symbols.
-
-@node Modified imports
-@section Modified imports
-
-You can at any moment decide to use Gnulib differently than the last time.
-
-If you only want to use more Gnulib modules, simply invoke
-@command{gnulib-tool --import @var{new-modules}}.  @code{gnulib-tool}
-remembers which modules were used last time.  The list of modules that
-you pass after @samp{--import} is @emph{added} to the previous list of
-modules.
-
-For most changes, such as added or removed modules, or even different
-choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there
-are two ways to perform the change.
-
-The standard way is to modify manually the file @file{gnulib-cache.m4}
-in the M4 macros directory, then launch @samp{gnulib-tool --import}.
-
-The other way is to call @command{gnulib-tool} again, with the changed
-command-line options.  Note that this doesn't let you remove modules,
-because as you just learned, the list of modules is always cumulated.
-Also this way is often impractical, because you don't remember the way
-you invoked @code{gnulib-tool} last time.
-
-The only change for which this doesn't work is a change of the
-@samp{--m4-base} directory.  Because, when you pass a different value of
-@samp{--m4-base}, @code{gnulib-tool} will not find the previous
-@file{gnulib-cache.m4} file any more... A possible solution is to manually
-copy the @file{gnulib-cache.m4} into the new M4 macro directory.
-
-In the @file{gnulib-cache.m4}, the macros have the following meaning:
-@table @code
-@item gl_MODULES
-The argument is a space separated list of the requested modules, not including
-dependencies.
-
-@item gl_AVOID
-The argument is a space separated list of modules that should not be used,
-even if they occur as dependencies.  Corresponds to the @samp{--avoid}
-command line argument.
-
-@item gl_SOURCE_BASE
-The argument is the relative pathname of the directory containing the gnulib
-source files (mostly *.c and *.h files).  Corresponds to the
-@samp{--source-base} command line argument.
-
-@item gl_M4_BASE
-The argument is the relative pathname of the directory containing the gnulib
-M4 macros (*.m4 files).  Corresponds to the @samp{--m4-base} command line
-argument.
-
-@item gl_TESTS_BASE
-The argument is the relative pathname of the directory containing the gnulib
-unit test files.  Corresponds to the @samp{--tests-base} command line argument.
-
-@item gl_LIB
-The argument is the name of the library to be created.  Corresponds to the
-@samp{--lib} command line argument.
-
-@item gl_LGPL
-The presence of this macro corresponds to the @samp{--lgpl} command line
-argument.  It takes no arguments.
-
-@item gl_LIBTOOL
-The presence of this macro corresponds to the @samp{--libtool} command line
-argument.  It takes no arguments.
-
-@item gl_MACRO_PREFIX
-The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
-file.  Corresponds to the @samp{--macro-prefix} command line argument.
-@end table
-
-@node Simple update
-@section Simple update
-
-When you want to update to a more recent version of Gnulib, without
-changing the list of modules or other parameters, a simple call
-does it:
-
-@smallexample
-$ gnulib-tool --import
-@end smallexample
-
-This will create, update or remove files, as needed.
-
-@node CVS Issues
-@section CVS Issues
-
-All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
-should be treated like generated source files, like for example a
-@file{parser.c} file is generated from @file{parser.y}.
-
-In projects which commit all source files, whether generated or not, into
-CVS, the @code{gnulib-tool} generated files should all be committed.
-
-In projects which customarily omit from the CVS all files that generated
-from other source files, all these files and directories would not be
-added into CVS.  The only file that must be added to CVS is
-@file{gnulib-cache.m4} in the M4 macros directory.  Also, the script for
-restoring files not in CVS, customarily called @file{autogen.sh} or
-@file{bootstrap.sh}, will typically contain the statement for restoring
-the omitted files:
-
-@smallexample
-$ gnulib-tool --update
-@end smallexample
-
-The @samp{--update} option operates much like the @samp{--import} option,
-but it does not offer the possibility to change the way Gnulib is used.
-Also it does not report in the ChangeLogs the files that it had to add
-because they were missing.
 
 @node Copying This Manual
 @appendix Copying This Manual