Mercurial > hg > octave-shane > gnulib-hg
changeset 9550:6bc27027a2d6
Avoid using the syntax symbol() in formatted documentation.
| author | Bruno Haible <bruno@clisp.org> |
|---|---|
| date | Wed, 26 Dec 2007 16:31:08 +0100 |
| parents | de8a758aeb9a |
| children | bd08c714fb5a |
| files | ChangeLog MODULES.html.sh doc/alloca-opt.texi doc/alloca.texi doc/error.texi doc/gnulib-intro.texi doc/gnulib.texi modules/error modules/fnmatch modules/full-read modules/full-write modules/safe-read modules/safe-write modules/strchrnul modules/trim modules/verror |
| diffstat | 16 files changed, 118 insertions(+), 39 deletions(-) [+] |
line wrap: on
line diff
--- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,28 @@ +2007-12-25 Paul Eggert <eggert@cs.ucla.edu> + Bruno Haible <bruno@clisp.org> + + 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 <bruno@clisp.org> Fixup after 2007-10-16 commit.
--- a/MODULES.html.sh +++ b/MODULES.html.sh @@ -1406,11 +1406,21 @@ 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,\([^a-zA-Z_]\)'"${posix_functions}"'(),\1<A HREF="'"$POSIX2001_URL"'xsh/\2.html">\2</A>(),g' \ - -e 's,^ ,,'` + -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
--- 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 @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! -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! +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
--- 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 @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! -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! +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: -An alternative to this module is the 'alloca-opt' module. +@smallexample +#ifdef __GNUC__ +__attribute__ ((__noinline__)) +#endif +@end smallexample + +An alternative to this module is the @samp{alloca-opt} module.
--- a/doc/error.texi +++ b/doc/error.texi @@ -22,5 +22,5 @@ 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.
--- a/doc/gnulib-intro.texi +++ b/doc/gnulib-intro.texi @@ -35,7 +35,7 @@ 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 @@ @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.
--- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -2891,6 +2891,8 @@ @chapter Particular Modules @menu +* alloca:: +* alloca-opt:: * Quoting:: * error and progname:: * gcd:: @@ -2898,6 +2900,16 @@ * 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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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