typos

[gnulib.git] / doc / gnulib.texi

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 9ecca81..59a9338 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -1,5 +1,5 @@
 \input texinfo   @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.5 2004-09-28 22:58:00 eggert Exp $
+@comment $Id: gnulib.texi,v 1.9 2005-05-23 11:05:53 jas Exp $
 @comment %**start of header
 @setfilename gnulib.info
 @settitle GNU Gnulib
@@ -7,14 +7,14 @@
 @syncodeindex pg cp
 @comment %**end of header
 
-@set UPDATED $Date: 2004-09-28 22:58:00 $
+@set UPDATED $Date: 2005-05-23 11:05:53 $
 
 @copying
 This manual is for GNU Gnulib (updated @value{UPDATED}),
 which is a library of common routines intended to be shared at the
 source level.
 
-Copyright @copyright{} 2004 Free Software Foundation, Inc.
+Copyright @copyright{} 2004, 2005 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -65,8 +65,9 @@ Software Foundation raise funds for GNU development.''
 @node Gnulib
 @chapter Gnulib
 
-This is not a real manual.  It's just a place to store random notes
-until someone (you?) gets around to actually writing a manual.
+This manual contains some bare-bones documentation, but not much more.
+It's mostly been a place to store notes until someone (you?) gets
+around to writing a coherent manual.
 
 Getting started:
 
@@ -123,8 +124,9 @@ underscore and either an uppercase letter or another underscore, for
 any use.  Thus, in theory, an application might not safely assume that
 @code{_FOO_H} has not already been defined by a library.  On the other
 hand, using @code{FOO_H} will likely lead the higher risk of
-collisions with other symbols (e.g., @code{COFF_LONG_H} which is a CPP
-macro function).  Your preference may depeend on whether you consider
+collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H},
+which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP
+macro function).  Your preference may depend on whether you consider
 the header file under discussion as part of the application (which has
 its own namespace for CPP symbols) or a supporting library (that
 shouldn't interfere with the application's CPP symbol namespace).
@@ -157,6 +159,19 @@ preference might depend on whether you consider the API exported by
 your header file as something available for C programs only, or for C
 and C++ programs alike.
 
+@subsection Include ordering
+
+When writing a gnulib module, or even in general, a good way to order
+the @samp{#include} directives is the following.
+
+@itemize
+@item First comes the #include "..." specifying the module being implemented.
+@item Then come all the #include <...> of system or system-replacement headers,
+in arbitrary order.
+@item Then come all the #include "..." of gnulib and private headers, in
+arbitrary order.
+@end itemize
+
 @node ctime
 @section ctime
 @findex ctime
@@ -278,6 +293,9 @@ Creating ./lib/Makefile.am...
 Creating ./m4/gnulib.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" and to mention
 "lib" in SUBDIRS in some Makefile.am.
@@ -289,6 +307,15 @@ macros in @file{m4/}.  You can override these paths by using
 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by
 adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
 @samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}.
+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 @code{--symbolic}
+(or @code{-s} for short) option to do this.
 
 @code{gnulib-tool} will overwrite any pre-existing files, in
 particular @file{Makefile.am}.  Unfortunately, separating the
@@ -382,14 +409,15 @@ If you are using a gnulib source base of @code{gl}, you would use:
 SUBDIRS += gl
 @end example
 
-Finally, you have add C flags and LD flags, so that you can make use
+Finally, you have to add compiler and linker flags in the appropriate
+source directories, so that you can make use
 of the gnulib library.  For example:
 
 @example
 ...
 AM_CPPFLAGS = -I$(top_srcdir)/lib
 ...
-LIBADD = lib/libgnu.la
+LIBADD = lib/libgnu.a
 ...
 @end example