X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=c2ea0a6ff8282575d11b396e7af073e8ad61ae95;hb=39bc7a80b6719b1c7d0f8fb1b01380649cb8e358;hp=0506a8cd645a943a19905e84cada29e7a9944012;hpb=e198412802cd9796992efdac69c3590958bde1be;p=gnulib.git

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 0506a8cd6..c2ea0a6ff 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -1,6 +1,15 @@
 @node Invoking gnulib-tool
 @chapter Invoking gnulib-tool
 
+@c Copyright (C) 2005, 2006, 2007 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.2 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, with no Front-Cover Texts, and with 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.
+
 @pindex gnulib-tool
 @cindex invoking @command{gnulib-tool}
 
@@ -39,29 +48,42 @@ 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}).
+the package portable to C89 and C99 (which don't have @code{strdup}).
 
 @example
 ~/src/libfoo$ gnulib-tool --import strdup
 Module list with included dependencies:
+  absolute-header
+  extensions
   strdup
+  string
 File list:
+  lib/dummy.c
   lib/strdup.c
-  lib/strdup.h
-  m4/onceonly_2_57.m4
+  lib/string_.h
+  m4/absolute-header.m4
+  m4/extensions.m4
+  m4/gnulib-common.m4
   m4/strdup.m4
-Copying file m4/gnulib-tool.m4
-Copying file m4/onceonly_2_57.m4
+  m4/string_h.m4
+Creating directory ./lib
+Creating directory ./m4
+Copying file lib/dummy.c
 Copying file lib/strdup.c
-Copying file lib/strdup.h
+Copying file lib/string_.h
+Copying file m4/absolute-header.m4
+Copying file m4/extensions.m4
+Copying file m4/gnulib-common.m4
+Copying file m4/gnulib-tool.m4
 Copying file m4/strdup.m4
+Copying file m4/string_h.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"
+  #include <string.h>
 
 Don't forget to
   - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
@@ -81,8 +103,14 @@ are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
 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.
+source files.  The option to specify for this is @samp{--symlink}, or
+@samp{-s} for short.  This can be useful to save a few kilobytes of disk
+space.  But it is likely to introduce bugs when @code{gnulib} is updated;
+it is more reliable to use @samp{gnulib-tool --update} (see below)
+to update to newer versions of @code{gnulib}.  Furthermore it requires
+extra effort to create self-contained tarballs, and it may disturb some
+mechanism the maintainer applies to the sources.  For these reasons,
+this option is generally discouraged.
 
 @code{gnulib-tool} will overwrite any pre-existing files, in
 particular @file{Makefile.am}.  Unfortunately, separating the
@@ -197,21 +225,19 @@ LDADD = 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"}
+example, you would need to make sure that @samp{#include <string.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.
+In the usual case where Autoconf is creating a @file{config.h} file,
+you should include @file{config.h} first, before any other include
+file.  That way, for example, if @file{config.h} defines
+@samp{restrict} to be the empty string on a pre-C99 host, the
+definition is consistent for all include files.
 
-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.
+You should include Gnulib-provided headers before system headers,
+so that Gnulib-provided headers can adjust how a system header
+behaves.
 
 A final word of warning: Gnulib currently assumes it will be
 responsible for @emph{all} functions that end up in the Autoconf
@@ -289,7 +315,8 @@ 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.
+argument and to the absence of the @samp{--no-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}