Here's what I'm committing.
2007-12-25 Paul Eggert <[EMAIL PROTECTED]>
Bruno Haible <[EMAIL PROTECTED]>
Avoid using the syntax symbol() in formatted documentation.
* MODULES.html.sh (func_module): When replacing symbol() with a
hyperlink, remove the parentheses. Show an error if some remain.
Recognize and render the '...' syntax.
* doc/alloca-opt.texi: Remove parentheses from symbol reference.
Rework. Add paragraph about GCC's inlining.
* doc/alloca.texi: Likewise.
* doc/error.texi: Remove parentheses from symbol reference.
* doc/gnulib-intro.texi: Likewise.
* doc/gnulib.texi (alloca, alloca-opt): New nodes.
* modules/fnmatch (Description): Reword to say "the ... function".
* modules/full-read (Description): Likewise.
* modules/full-write (Description): Likewise.
* modules/safe-read (Description): Likewise.
* modules/safe-write (Description): Likewise.
* modules/strchrnul (Description): Likewise.
* modules/trim (Description): Likewise.
* modules/error (Description): Remove parentheses from symbol
references.
* modules/verror (Description): Likewise.
Reported by Karl Berry.
*** MODULES.html.sh.orig 2007-12-25 22:38:04.000000000 +0100
--- MODULES.html.sh 2007-12-25 22:08:19.000000000 +0100
***************
*** 1406,1416 ****
element='<A HREF="#module='$1'">'$1'</A>'
func_echo "<TD ALIGN=LEFT VALIGN=TOP WIDTH=\"20%\">$element"
element=`gnulib-tool --extract-description $1 \
| sed -e "$sed_lt" -e "$sed_gt" -e
"$sed_remove_trailing_empty_line" \
! -e 's,^, ,' \
! -e 's,\([^a-zA-Z_]\)'"${posix_functions}"'(),\1<A
HREF="'"$POSIX2001_URL"'xsh/\2.html">\2</A>(),g' \
! -e 's,^ ,,'`
func_echo "<TD ALIGN=LEFT VALIGN=TOP WIDTH=\"80%\">$element"
func_end TR
--- 1406,1426 ----
element='<A HREF="#module='$1'">'$1'</A>'
func_echo "<TD ALIGN=LEFT VALIGN=TOP WIDTH=\"20%\">$element"
+ # Rendering the description:
+ # - Change the symbol() syntax as suitable for documentation, removing the
+ # parentheses (as per GNU standards, section "GNU Manuals").
+ # - Flag the remaining symbol() constructs as errors.
+ # - Change 'xxx' to <CODE>xxx</CODE>.
element=`gnulib-tool --extract-description $1 \
| sed -e "$sed_lt" -e "$sed_gt" -e
"$sed_remove_trailing_empty_line" \
! -e 's,^, ,' -e 's,$, ,' \
! -e 's,\([^a-zA-Z_]\)'"${posix_functions}"'()
\(function\|macro\),\1<A HREF="'"$POSIX2001_URL"'xsh/\2.html">\2</A> \3,g' \
! -e 's,\([^a-zA-Z_]\)'"${posix_functions}"'
\(function\|macro\),\1<A HREF="'"$POSIX2001_URL"'xsh/\2.html">\2</A> \3,g' \
! -e 's,\([^a-zA-Z_]\)'"${posix_functions}"'(),\1<A
HREF="'"$POSIX2001_URL"'xsh/\2.html">\2</A> <SPAN STYLE="color:#FF0000;">what??
If you mean a function\, please say so.</SPAN>,g' \
! -e 's,\([^a-zA-Z_]\)\([a-zA-Z_][a-zA-Z0-9_]*\)()
\(function\|macro\),\1\2 \3,g' \
! -e 's,\([^a-zA-Z_]\)\([a-zA-Z_][a-zA-Z0-9_]*\)(),\1\2
<SPAN STYLE="color:#FF0000;">what?? If you mean a function\, please say
so.</SPAN>,g' \
! -e 's, '"'"'\([a-zA-Z0-9_ -]*\)'"'"'\([^a-zA-Z0-9_]\),
<CODE>\1</CODE>\2,g' \
! -e 's,^ ,,' -e 's, $,,'`
func_echo "<TD ALIGN=LEFT VALIGN=TOP WIDTH=\"80%\">$element"
func_end TR
*** doc/alloca-opt.texi.orig 2007-12-25 22:38:04.000000000 +0100
--- doc/alloca-opt.texi 2007-12-25 21:39:34.000000000 +0100
***************
*** 1,6 ****
@c Documentation of gnulib module 'alloca-opt'.
! @c Copyright (C) 2004 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
--- 1,6 ----
@c Documentation of gnulib module 'alloca-opt'.
! @c Copyright (C) 2004, 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
***************
*** 9,25 ****
@c Texts. A copy of the license is included in the ``GNU Free
@c Documentation License'' file as part of this distribution.
! The alloca-opt module provides for a function alloca() which allocates memory
! on the stack, where the system allows it. A memory block allocated with
alloca()
! exists only until the function that calls alloca() returns or exits abruptly.
There are a few systems where this is not possible: HP-UX systems, and some
! other platforms when the C++ compiler is used. On these platforms the
alloca-opt
! module provides no replacement, just a preprocessor macro HAVE_ALLOCA.
! The user can #include <alloca.h> on all platforms, and use alloca() on those
! platforms where the preprocessor macro HAVE_ALLOCA evaluates to true. If
! HAVE_ALLOCA is false, the code should use a heap-based memory allocation
! based on malloc() or - in C++ - 'new'. Note that the #include <alloca.h> must
be
! the first one after the autoconf-generated config.h. Thanks to AIX for this
nice
! restriction!
--- 9,41 ----
@c Texts. A copy of the license is included in the ``GNU Free
@c Documentation License'' file as part of this distribution.
! The alloca-opt module provides for a function @code{alloca} which allocates
! memory on the stack, where the system allows it. A memory block allocated with
! @code{alloca} exists only until the function that calls @code{alloca} returns
! or exits abruptly.
There are a few systems where this is not possible: HP-UX systems, and some
! other platforms when the C++ compiler is used. On these platforms the
! alloca-opt module provides no replacement, just a preprocessor macro
! HAVE_ALLOCA.
! The user can @code{#include <alloca.h>} on all platforms, and use
! @code{alloca} on those platforms where the preprocessor macro HAVE_ALLOCA
! evaluates to true. If HAVE_ALLOCA is false, the code should use a heap-based
! memory allocation based on @code{malloc} or - in C++ - @code{new}. Note that
! the @code{#include <alloca.h>} must be the first one after the
! autoconf-generated @file{config.h}, for AIX 3 compatibility. Thanks to IBM for
! this nice restriction!
!
! Note that GCC 3.1 and 3.2 can @emph{inline} functions that call @code{alloca}.
! When this happens, the memory blocks allocated with @code{alloca} will not be
! freed until @emph{the end of the calling function}. If this calling function
! runs a loop calling the function that uses @code{alloca}, the program easily
! gets a stack overflow and crashes. To protect against this compiler behaviour,
! you can mark the function that uses @code{alloca} with the following
attribute:
!
! @smallexample
! #ifdef __GNUC__
! __attribute__ ((__noinline__))
! #endif
! @end smallexample
*** doc/alloca.texi.orig 2007-12-25 22:38:04.000000000 +0100
--- doc/alloca.texi 2007-12-25 21:39:21.000000000 +0100
***************
*** 1,6 ****
@c Documentation of gnulib module 'alloca'.
! @c Copyright (C) 2004 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
--- 1,6 ----
@c Documentation of gnulib module 'alloca'.
! @c Copyright (C) 2004, 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
***************
*** 9,28 ****
@c Texts. A copy of the license is included in the ``GNU Free
@c Documentation License'' file as part of this distribution.
! The alloca module provides for a function alloca() which allocates memory
! on the stack, where the system allows it. A memory block allocated with
alloca()
! exists only until the function that calls alloca() returns or exits abruptly.
There are a few systems where this is not possible: HP-UX systems, and some
other platforms when the C++ compiler is used. On these platforms the alloca
! module provides a malloc() based emulation. This emulation will not free a
memory block immediately when the calling function returns, but rather will
! wait until the next alloca() call from a function with the same or a shorter
! stack length. Thus, in some cases, a few memory blocks will be kept although
! they are not needed any more.
!
! The user can #include <alloca.h> and use alloca() on all platforms. Note
! that the #include <alloca.h> must be the first one after the
autoconf-generated
! config.h. Thanks to AIX for this nice restriction!
! An alternative to this module is the 'alloca-opt' module.
--- 9,43 ----
@c Texts. A copy of the license is included in the ``GNU Free
@c Documentation License'' file as part of this distribution.
! The alloca module provides for a function @code{alloca} which allocates
! memory on the stack, where the system allows it. A memory block allocated with
! @code{alloca} exists only until the function that calls @code{alloca} returns
! or exits abruptly.
There are a few systems where this is not possible: HP-UX systems, and some
other platforms when the C++ compiler is used. On these platforms the alloca
! module provides a @code{malloc} based emulation. This emulation will not free
a
memory block immediately when the calling function returns, but rather will
! wait until the next @code{alloca} call from a function with the same or a
! shorter stack length. Thus, in some cases, a few memory blocks will be kept
! although they are not needed any more.
!
! The user can @code{#include <alloca.h>} and use @code{alloca} on all
platforms.
! Note that the @code{#include <alloca.h>} must be the first one after the
! autoconf-generated @file{config.h}, for AIX 3 compatibility. Thanks to IBM for
! this nice restriction!
!
! Note that GCC 3.1 and 3.2 can @emph{inline} functions that call @code{alloca}.
! When this happens, the memory blocks allocated with @code{alloca} will not be
! freed until @emph{the end of the calling function}. If this calling function
! runs a loop calling the function that uses @code{alloca}, the program easily
! gets a stack overflow and crashes. To protect against this compiler behaviour,
! you can mark the function that uses @code{alloca} with the following
attribute:
!
! @smallexample
! #ifdef __GNUC__
! __attribute__ ((__noinline__))
! #endif
! @end smallexample
! An alternative to this module is the @samp{alloca-opt} module.
*** doc/error.texi.orig 2007-12-25 22:38:04.000000000 +0100
--- doc/error.texi 2007-12-25 21:40:35.000000000 +0100
***************
*** 22,26 ****
specify using the @code{progname} module.
Additionally, using the @code{progname} module is not something that
! can be done implicitly. It requires that every @code{main()} function
be modified to set @code{program_name} as one of its first actions.
--- 22,26 ----
specify using the @code{progname} module.
Additionally, using the @code{progname} module is not something that
! can be done implicitly. It requires that every @code{main} function
be modified to set @code{program_name} as one of its first actions.
*** doc/gnulib-intro.texi.orig 2007-12-25 22:38:04.000000000 +0100
--- doc/gnulib-intro.texi 2007-12-25 21:45:17.000000000 +0100
***************
*** 35,41 ****
Similarly, Gnulib has a facility for executing a command in a
subprocess. It is at the same time a portability enhancement (it
works on GNU, Unix, and Windows, compared to the classical
! @code{fork()}/@code{exec()} which is not portable to Windows), as well
as an application aid: it takes care of redirecting stdin and/or
stdout if desired, and emits an error message if the subprocess
failed.
--- 35,41 ----
Similarly, Gnulib has a facility for executing a command in a
subprocess. It is at the same time a portability enhancement (it
works on GNU, Unix, and Windows, compared to the classical
! @code{fork}/@code{exec} idiom which is not portable to Windows), as well
as an application aid: it takes care of redirecting stdin and/or
stdout if desired, and emits an error message if the subprocess
failed.
***************
*** 175,181 ****
@subsection Interfaces to external libraries
Examples are the @samp{iconv} module, which interfaces to the
! @code{iconv()} facility, regardless whether it is contained in libc or in
an external @code{libiconv}. Or the @samp{readline} module, which
interfaces to the GNU readline library.
--- 175,181 ----
@subsection Interfaces to external libraries
Examples are the @samp{iconv} module, which interfaces to the
! @code{iconv} facility, regardless whether it is contained in libc or in
an external @code{libiconv}. Or the @samp{readline} module, which
interfaces to the GNU readline library.
*** doc/gnulib.texi.orig 2007-12-25 22:38:04.000000000 +0100
--- doc/gnulib.texi 2007-12-25 21:24:18.000000000 +0100
***************
*** 2891,2896 ****
--- 2891,2898 ----
@chapter Particular Modules
@menu
+ * alloca::
+ * alloca-opt::
* Quoting::
* error and progname::
* gcd::
***************
*** 2898,2903 ****
--- 2900,2915 ----
* Supporting Relocation::
@end menu
+ @node alloca
+ @section alloca
+ @findex alloca
+ @include alloca.texi
+
+ @node alloca-opt
+ @section alloca-opt
+ @findex alloca
+ @include alloca-opt.texi
+
@include quote.texi
@include error.texi
@include gcd.texi
*** modules/error.orig 2007-12-25 22:38:04.000000000 +0100
--- modules/error 2007-12-25 22:36:22.000000000 +0100
***************
*** 1,5 ****
Description:
! error() and error_at_line() functions: Error reporting.
Notice:
If you are using GNU gettext version 0.16.1 or older, add the following
options
--- 1,5 ----
Description:
! error and error_at_line functions: Error reporting.
Notice:
If you are using GNU gettext version 0.16.1 or older, add the following
options
*** modules/fnmatch.orig 2007-12-25 22:38:04.000000000 +0100
--- modules/fnmatch 2007-12-25 21:49:12.000000000 +0100
***************
*** 1,5 ****
Description:
! GNU fnmatch() implementation.
Files:
lib/fnmatch.in.h
--- 1,5 ----
Description:
! GNU implementation of the fnmatch() function.
Files:
lib/fnmatch.in.h
*** modules/full-read.orig 2007-12-25 22:38:04.000000000 +0100
--- modules/full-read 2007-12-25 21:48:26.000000000 +0100
***************
*** 1,5 ****
Description:
! An interface to read() that reads all it is asked to read.
Files:
lib/full-read.h
--- 1,5 ----
Description:
! An interface to the read() function that reads all it is asked to read.
Files:
lib/full-read.h
*** modules/full-write.orig 2007-12-25 22:38:04.000000000 +0100
--- modules/full-write 2007-12-25 21:48:37.000000000 +0100
***************
*** 1,5 ****
Description:
! An interface to write() that writes all it is asked to write.
Files:
lib/full-write.h
--- 1,5 ----
Description:
! An interface to the write() function that writes all it is asked to write.
Files:
lib/full-write.h
*** modules/safe-read.orig 2007-12-25 22:38:04.000000000 +0100
--- modules/safe-read 2007-12-25 21:48:06.000000000 +0100
***************
*** 1,5 ****
Description:
! An interface to read() that retries after interrupts.
Files:
lib/safe-read.h
--- 1,5 ----
Description:
! An interface to the read() function that retries after interrupts.
Files:
lib/safe-read.h
*** modules/safe-write.orig 2007-12-25 22:38:04.000000000 +0100
--- modules/safe-write 2007-12-25 21:48:16.000000000 +0100
***************
*** 1,5 ****
Description:
! An interface to write() that retries after interrupts.
Files:
lib/safe-write.h
--- 1,5 ----
Description:
! An interface to the write() function that retries after interrupts.
Files:
lib/safe-write.h
*** modules/strchrnul.orig 2007-12-25 22:38:05.000000000 +0100
--- modules/strchrnul 2007-12-25 22:35:05.000000000 +0100
***************
*** 1,5 ****
Description:
! strchrnul(): Find the first occurrence of C in S or the final NUL byte.
Files:
lib/strchrnul.c
--- 1,6 ----
Description:
! strchrnul() function: Find the first occurrence of C in S or the final NUL
! byte.
Files:
lib/strchrnul.c
*** modules/trim.orig 2007-12-25 22:38:05.000000000 +0100
--- modules/trim 2007-12-25 22:35:24.000000000 +0100
***************
*** 1,5 ****
Description:
! trim() removes leading and/or trailing whitespaces
Files:
lib/trim.h
--- 1,5 ----
Description:
! trim() function: remove leading and/or trailing whitespaces
Files:
lib/trim.h
*** modules/verror.orig 2007-12-25 22:38:05.000000000 +0100
--- modules/verror 2007-12-25 22:36:23.000000000 +0100
***************
*** 1,5 ****
Description:
! verror() and verror_at_line() functions: Error reporting with va_list.
Notice:
If you are using GNU gettext version 0.16.1 or older, add the following
options
--- 1,5 ----
Description:
! verror and verror_at_line functions: Error reporting with va_list.
Notice:
If you are using GNU gettext version 0.16.1 or older, add the following
options
