Document the meaning of obsolete modules.

diff --git a/ChangeLog b/ChangeLog
index 8220dc9d73de9a3d17bb516b843ce0faa3f7ed65..0276b341c7e70b38468325d04f59cdd8ea94b4bf 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2009-01-24  Bruno Haible  <bruno@clisp.org>
+
+       * doc/gnulib.texi (Obsolete modules): New section.
+       Reported by Mike Frysinger <vapier@gentoo.org>.
+
 2009-01-24  Bruno Haible  <bruno@clisp.org>
 
        * doc/Makefile (%.pdf): Clarify where to find texmf.cnf.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 429bf4c175c5c68b5df3f1c3903157c0a5f12f87..29e08b150877f9e3ca4485f787d8a8f5392ff25c 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -1,5 +1,4 @@
 \input texinfo   @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.44 2007-09-09 13:20:45 haible Exp $
 @comment %**start of header
 @setfilename gnulib.info
 @settitle GNU Gnulib
@@ -18,8 +17,7 @@ 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, 2005, 2006, 2007, 2008 Free Software
-Foundation, Inc.
+Copyright @copyright{} 2004-2009 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -122,6 +120,7 @@ Resources:
 * Comments::
 * Header files::
 * Out of memory handling::
+* Obsolete modules::
 * Library version handling::
 * Windows sockets::
 * Libtool and Windows::
@@ -263,6 +262,30 @@ must be taken to not allocate more memory, as that will likely also
 fail.
 
 
+@node Obsolete modules
+@section Obsolete modules
+
+Modules can be marked obsolete.  This means that the problems they fix
+don't occur any more on the platforms that are reasonable porting targets
+now.  @code{gnulib-tool} warns when obsolete modules are mentioned on the
+command line, and by default ignores dependencies from modules to obsolete
+modules.  When you pass the option @code{--with-obsolete} to
+@code{gnulib-tool}, dependencies to obsolete modules will be included,
+however, unless blocked through an @code{--avoid} option.  This option
+is useful if your package should be portable even to very old platforms.
+
+In order to mark a module obsolete, you need to add this to the module
+description:
+
+@example
+Status:
+obsolete
+
+Notice:
+This module is obsolete.
+@end example
+
+
 @node Library version handling
 @section Library version handling