X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=39081801c3e8dc6e83c3eae180b0d06e595c2567;hb=fbe6ced5d2fdadeeea4194725d05a52cf3b5ebd7;hp=5531b9af208302bdfdeb365d349584bc8a43243b;hpb=16848adccf878d7866531a7e2556fe25c0a12a28;p=gnulib.git

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 5531b9af2..39081801c 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -1,7 +1,7 @@
 @node Invoking gnulib-tool
 @chapter Invoking gnulib-tool
 
-@c Copyright (C) 2005-2008 Free Software Foundation, Inc.
+@c Copyright (C) 2005-2010 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 or
@@ -21,6 +21,17 @@ 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.
 
+@file{gnulib-tool} is not installed in a standard directory that is
+contained in the @code{PATH} variable.  It 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 @file{gnulib-tool}, or
+you can also use a symbolic link from a place inside your @code{PATH}
+to the @file{gnulib-tool} file of your preferred and most up-to-date
+Gnulib checkout, like this:
+@smallexample
+$ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
+@end smallexample
+
 Run @samp{gnulib-tool --help} for information.  To get familiar with
 @command{gnulib-tool} without affecting your sources, you can also try
 some commands with the option @samp{--dry-run}; then
@@ -28,6 +39,7 @@ some commands with the option @samp{--dry-run}; then
 a real run without changing anything.
 
 @menu
+* Which modules?::              Determining the needed set of Gnulib modules
 * Initial import::              First import of Gnulib modules.
 * Modified imports::            Changing the import specification.
 * Simple update::               Tracking Gnulib development.
@@ -39,12 +51,44 @@ a real run without changing anything.
 @end menu
 
 
+@node Which modules?
+@section Finding modules
+@cindex Finding modules
+
+There are three ways of finding the names of Gnulib modules that you can use
+in your package:
+
+@itemize
+@item
+You have the complete module list, sorted according to categories, in
+@url{http://www.gnu.org/software/gnulib/MODULES.html}.
+
+@item
+If you are looking for a particular POSIX header or function replacement,
+look in the chapters @ref{Header File Substitutes} and
+@ref{Function Substitutes}.  For headers and functions that are provided by
+Glibc but not standardized by POSIX, look in the chapters
+@ref{Glibc Header File Substitutes} and @ref{Glibc Function Substitutes}.
+
+@item
+If you have already found the source file in Gnulib and are looking for the
+module that contains this source file, you can use the command
+@samp{gnulib-tool --find @var{filename}}.
+@end itemize
+
+
 @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
+Gnulib assumes that your project uses Autoconf.  When using Gnulib, you
+will need to have Autoconf and Automake among your build tools.  Note that
+while the use of Automake in your project's top level directory is an
+easy way to fulfil the Makefile conventions of the GNU coding standards,
+Gnulib does not require it.  But when you use Gnulib, Automake will be
+used at least in a subdirectory of your project.
+
+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