--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2013-06-18  Paul Eggert  <eggert@cs.ucla.edu>
 
+	doc: document extern-inline
+	* doc/extern-inline.texi: New file.
+	* doc/gnulib.texi (alloca-opt): Include it.
+	* m4/extern-inline.m4: Move some comments to documentation,
+	and others closer to what they describe.
+
 	doc: chatter less
 	* doc/Makefile (NEWEST_GNULIB_TEXI_FILE): New macro.
 	(updated-stamp): Use it.  This causes 'make' to output just

new file mode 100644
--- /dev/null
+++ b/doc/extern-inline.texi
@@ -0,0 +1,96 @@
+@c GNU extern-inline module documentation
+
+@c Copyright (C) 2013 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
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and 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.
+
+@c Written by Paul Eggert.
+
+@node extern inline
+@section Extern inline functions
+
+@cindex extern inline
+@cindex inline
+
+The @code{extern-inline} module supports the use of C99-style
+@code{extern inline} functions so that the code still runs on pre-C99
+compilers.
+
+C code ordinarily should not use @code{inline}.  Typically it is
+better to let the compiler figure out whether to inline, as compilers
+are pretty good about optimization nowadays.  In this sense,
+@code{inline} is like @code{register}, another keyword that is
+typically no longer needed.
+
+Functions defined (not merely declared) in headers are an exception,
+as avoiding @code{inline} would commonly cause problems for these
+functions.  Suppose @file{aaa.h} defines the function @code{aaa_fun},
+and @file{aaa.c}, @file{bbb.c} and @file{ccc.c} all include
+@file{aaa.h}.  If code is intended to portable to pre-C99 compilers,
+@code{aaa_fun} cannot be declared with the C99 @code{inline} keyword.
+This problem cannot be worked around by making @code{aaa_fun} an
+ordinary function, as it would be defined three times with external
+linkage and the definitions would clash.  Although @code{aaa_fun}
+could be a static function, with separate compilation if
+@code{aaa_fun} is not inlined its code will appear in the executable
+three times.
+
+To avoid this code bloat, @file{aaa.h} can do this:
+
+@example
+/* aaa.h */
+/* #include any other headers here */
+_GL_INLINE_HEADER_BEGIN
+#ifndef AAA_INLINE
+# define AAA_INLINE _GL_INLINE
+#endif
+...
+AAA_INLINE int
+aaa_fun (int i)
+@{
+  return i + 1;
+@}
+...
+_GL_INLINE_HEADER_END
+@end example
+
+@noindent
+and @file{aaa.c} can do this:
+
+@example
+/* aaa.c */
+#include <config.h>
+#define AAA_INLINE _GL_EXTERN_INLINE
+#include <aaa.h>
+@end example
+
+@noindent
+whereas @file{bbb.c} and @file{ccc.c} can include @file{aaa.h} in the
+usual way.  C99 compilers expand @code{AAA_INLINE} to C99-style
+@code{inline} usage, where @code{aaa_fun} is declared @code{extern
+inline} in @file{aaa.c} and plain @code{inline} in other modules.
+Pre-C99 compilers that are compatible with GCC use GCC-specific syntax
+to accomplish the same ends.  Other pre-C99 compilers use @code{static
+inline} so they suffer from code bloat, but they are not mainline
+platforms and will die out eventually.
+
+@findex _GL_INLINE
+@code{_GL_INLINE} is a portable alternative to C99 plain @code{inline}.
+
+@findex _GL_EXTERN_INLINE
+@code{_GL_EXTERN_INLINE} is a portable alternative to C99 @code{extern inline}.
+
+@findex _GL_INLINE_HEADER_BEGIN
+Invoke @code{_GL_INLINE_HEADER_BEGIN} before all uses of
+@code{_GL_INLINE} in an include file.  If an include file includes
+other files, it is better to invoke this macro after including the
+other files.
+
+@findex _GL_INLINE_HEADER_END
+Invoke @code{_GL_INLINE_HEADER_END} after all uses of
+@code{_GL_INLINE} in an include file.

--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -6679,6 +6679,7 @@
 * Safe Allocation Macros::
 * Compile-time Assertions::
 * Integer Properties::
+* extern inline::
 * String Functions in C Locale::
 * Quoting::
 * error and progname::
@@ -6712,6 +6713,8 @@
 
 @include intprops.texi
 
+@include extern-inline.texi
+
 @node String Functions in C Locale
 @section Character and String Functions in C Locale
 

--- a/m4/extern-inline.m4
+++ b/m4/extern-inline.m4
@@ -8,15 +8,7 @@
 AC_DEFUN([gl_EXTERN_INLINE],
 [
   AH_VERBATIM([extern_inline],
-[/* _GL_INLINE is a portable alternative to ISO C99 plain 'inline'.
-   _GL_EXTERN_INLINE is a portable alternative to 'extern inline'.
-   _GL_INLINE_HEADER_BEGIN contains useful stuff to put
-     in an include file, before uses of _GL_INLINE.
-     It suppresses GCC's bogus "no previous prototype for 'FOO'" diagnostic,
-     when FOO is an inline function in the header; see
-     <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=54113>.
-   _GL_INLINE_HEADER_END contains useful stuff to put
-     in the same include file, after uses of _GL_INLINE.
+[/* Please see the Gnulib manual for how to use these macros.
 
    Suppress extern inline with HP-UX cc, as it appears to be broken; see
    <http://lists.gnu.org/archive/html/bug-texinfo/2013-02/msg00030.html>.
@@ -59,6 +51,10 @@
 #  define _GL_INLINE_HEADER_CONST_PRAGMA \
      _Pragma ("GCC diagnostic ignored \"-Wsuggest-attribute=const\"")
 # endif
+  /* Suppress GCC's bogus "no previous prototype for 'FOO'"
+     and "no previous declaration for 'FOO'"  diagnostics,
+     when FOO is an inline function in the header; see
+     <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=54113>.  */
 # define _GL_INLINE_HEADER_BEGIN \
     _Pragma ("GCC diagnostic push") \
     _Pragma ("GCC diagnostic ignored \"-Wmissing-prototypes\"") \