From: Bruno Haible Date: Wed, 26 Dec 2007 15:31:08 +0000 (+0100) Subject: Avoid using the syntax symbol() in formatted documentation. X-Git-Tag: v0.1~7903 X-Git-Url: http://erislabs.org.uk/gitweb/?a=commitdiff_plain;h=f0081f71b5ac063b48f242d6f770d7826f2ec196;p=gnulib.git Avoid using the syntax symbol() in formatted documentation. --- diff --git a/ChangeLog b/ChangeLog index 78fb2d7dd..07b659e62 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,28 @@ +2007-12-25 Paul Eggert + Bruno Haible + + 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. + 2007-12-25 Bruno Haible Fixup after 2007-10-16 commit. diff --git a/MODULES.html.sh b/MODULES.html.sh index e825ce39f..324b3f37d 100755 --- a/MODULES.html.sh +++ b/MODULES.html.sh @@ -1406,11 +1406,21 @@ func_module () element=''$1'' func_echo "$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 xxx. 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\2(),g' \ - -e 's,^ ,,'` + -e 's,^, ,' -e 's,$, ,' \ + -e 's,\([^a-zA-Z_]\)'"${posix_functions}"'() \(function\|macro\),\1\2 \3,g' \ + -e 's,\([^a-zA-Z_]\)'"${posix_functions}"' \(function\|macro\),\1\2 \3,g' \ + -e 's,\([^a-zA-Z_]\)'"${posix_functions}"'(),\1\2 what?? If you mean a function\, please say so.,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 what?? If you mean a function\, please say so.,g' \ + -e 's, '"'"'\([a-zA-Z0-9_ -]*\)'"'"'\([^a-zA-Z0-9_]\), \1\2,g' \ + -e 's,^ ,,' -e 's, $,,'` func_echo "$element" func_end TR diff --git a/doc/alloca-opt.texi b/doc/alloca-opt.texi index 307a8f12f..3fea8f359 100644 --- a/doc/alloca-opt.texi +++ b/doc/alloca-opt.texi @@ -1,6 +1,6 @@ @c Documentation of gnulib module 'alloca-opt'. -@c Copyright (C) 2004 Free Software Foundation, Inc. +@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,17 +9,33 @@ @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. +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. +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 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 must be -the first one after the autoconf-generated config.h. Thanks to AIX for this nice -restriction! +The user can @code{#include } 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 } 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 diff --git a/doc/alloca.texi b/doc/alloca.texi index 704103912..975cb998d 100644 --- a/doc/alloca.texi +++ b/doc/alloca.texi @@ -1,6 +1,6 @@ @c Documentation of gnulib module 'alloca'. -@c Copyright (C) 2004 Free Software Foundation, Inc. +@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,20 +9,35 @@ @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. +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 malloc() based emulation. This emulation will not free a +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 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. +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 #include and use alloca() on all platforms. Note -that the #include must be the first one after the autoconf-generated -config.h. Thanks to AIX for this nice restriction! +The user can @code{#include } and use @code{alloca} on all platforms. +Note that the @code{#include } must be the first one after the +autoconf-generated @file{config.h}, for AIX 3 compatibility. Thanks to IBM for +this nice restriction! -An alternative to this module is the 'alloca-opt' module. +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. diff --git a/doc/error.texi b/doc/error.texi index 3a80486f3..2f669db78 100644 --- a/doc/error.texi +++ b/doc/error.texi @@ -22,5 +22,5 @@ replacement @code{program_name}, and a GPL user should manually 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 +can be done implicitly. It requires that every @code{main} function be modified to set @code{program_name} as one of its first actions. diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index d5d740808..c42a20803 100644 --- a/doc/gnulib-intro.texi +++ b/doc/gnulib-intro.texi @@ -35,7 +35,7 @@ that. 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 +@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,7 +175,7 @@ C++ language or from the Linux kernel. @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 +@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. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index ca52fdc9c..c4f285d3c 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -2891,6 +2891,8 @@ If you need this particular function, you may write to @chapter Particular Modules @menu +* alloca:: +* alloca-opt:: * Quoting:: * error and progname:: * gcd:: @@ -2898,6 +2900,16 @@ If you need this particular function, you may write to * 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 diff --git a/modules/error b/modules/error index 1b58cdac7..7b57a8610 100644 --- a/modules/error +++ b/modules/error @@ -1,5 +1,5 @@ Description: -error() and error_at_line() functions: Error reporting. +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 diff --git a/modules/fnmatch b/modules/fnmatch index 82048e3e4..477cf33b4 100644 --- a/modules/fnmatch +++ b/modules/fnmatch @@ -1,5 +1,5 @@ Description: -GNU fnmatch() implementation. +GNU implementation of the fnmatch() function. Files: lib/fnmatch.in.h diff --git a/modules/full-read b/modules/full-read index c12ba9771..a97a76795 100644 --- a/modules/full-read +++ b/modules/full-read @@ -1,5 +1,5 @@ Description: -An interface to read() that reads all it is asked to read. +An interface to the read() function that reads all it is asked to read. Files: lib/full-read.h diff --git a/modules/full-write b/modules/full-write index cc8f8b291..4f8eeadc8 100644 --- a/modules/full-write +++ b/modules/full-write @@ -1,5 +1,5 @@ Description: -An interface to write() that writes all it is asked to write. +An interface to the write() function that writes all it is asked to write. Files: lib/full-write.h diff --git a/modules/safe-read b/modules/safe-read index e8f8d2363..bc575067b 100644 --- a/modules/safe-read +++ b/modules/safe-read @@ -1,5 +1,5 @@ Description: -An interface to read() that retries after interrupts. +An interface to the read() function that retries after interrupts. Files: lib/safe-read.h diff --git a/modules/safe-write b/modules/safe-write index 38535537c..235dc2339 100644 --- a/modules/safe-write +++ b/modules/safe-write @@ -1,5 +1,5 @@ Description: -An interface to write() that retries after interrupts. +An interface to the write() function that retries after interrupts. Files: lib/safe-write.h diff --git a/modules/strchrnul b/modules/strchrnul index 806aebbe0..f1daf7eb4 100644 --- a/modules/strchrnul +++ b/modules/strchrnul @@ -1,5 +1,6 @@ Description: -strchrnul(): Find the first occurrence of C in S or the final NUL byte. +strchrnul() function: Find the first occurrence of C in S or the final NUL +byte. Files: lib/strchrnul.c diff --git a/modules/trim b/modules/trim index 70286f8cd..66161d832 100644 --- a/modules/trim +++ b/modules/trim @@ -1,5 +1,5 @@ Description: -trim() removes leading and/or trailing whitespaces +trim() function: remove leading and/or trailing whitespaces Files: lib/trim.h diff --git a/modules/verror b/modules/verror index 5c43dfe42..c8431981d 100644 --- a/modules/verror +++ b/modules/verror @@ -1,5 +1,5 @@ Description: -verror() and verror_at_line() functions: Error reporting with va_list. +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