From: Bruno Haible Date: Tue, 24 Jul 2018 01:31:36 +0000 (+0200) Subject: doc: For module names, use texinfo markup @code{} or @samp{}. X-Git-Tag: v1.0~5511 X-Git-Url: https://gitweb.git.savannah.gnu.org/gitweb/?a=commitdiff_plain;h=b4f88b3c1163e6cbc6f63b76ee9f002d701031ed;p=gnulib.git doc: For module names, use texinfo markup @code{} or @samp{}. * doc/alloca.texi: Mark gnulib module names with @code. * doc/alloca-opt.texi: Likewise. * doc/quote.texi: Likewise. * doc/posix-functions/freopen.texi: Likewise. * doc/posix-functions/open.texi: Likewise. * doc/posix-functions/readlink.texi: Likewise. * doc/posix-functions/readlinkat.texi: Likewise. * doc/posix-functions/stdout.texi: Likewise. * doc/posix-functions/stderr.texi: Likewise. * doc/posix-functions/unlink.texi: Likewise. * doc/posix-functions/unlinkat.texi: Likewise. * doc/posix-functions/utime.texi: Likewise. * doc/posix-functions/utimensat.texi: Likewise. * doc/posix-functions/utimes.texi: Likewise. * doc/posix-headers/stdint.texi: Likewise. * doc/glibc-functions/futimesat.texi: Likewise. * doc/glibc-functions/lutimes.texi: Likewise. * doc/glibc-functions/memmem.texi: Likewise. --- diff --git a/ChangeLog b/ChangeLog index 79821f90d5..80dc2c244c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,25 @@ +2018-07-23 Bruno Haible + + doc: For module names, use texinfo markup @code{} or @samp{}. + * doc/alloca.texi: Mark gnulib module names with @code. + * doc/alloca-opt.texi: Likewise. + * doc/quote.texi: Likewise. + * doc/posix-functions/freopen.texi: Likewise. + * doc/posix-functions/open.texi: Likewise. + * doc/posix-functions/readlink.texi: Likewise. + * doc/posix-functions/readlinkat.texi: Likewise. + * doc/posix-functions/stdout.texi: Likewise. + * doc/posix-functions/stderr.texi: Likewise. + * doc/posix-functions/unlink.texi: Likewise. + * doc/posix-functions/unlinkat.texi: Likewise. + * doc/posix-functions/utime.texi: Likewise. + * doc/posix-functions/utimensat.texi: Likewise. + * doc/posix-functions/utimes.texi: Likewise. + * doc/posix-headers/stdint.texi: Likewise. + * doc/glibc-functions/futimesat.texi: Likewise. + * doc/glibc-functions/lutimes.texi: Likewise. + * doc/glibc-functions/memmem.texi: Likewise. + 2018-07-23 Werner LEMBERG doc: Avoid some overfull lines in the TeX output. diff --git a/doc/alloca-opt.texi b/doc/alloca-opt.texi index 379670c1fe..81cf13ed4b 100644 --- a/doc/alloca-opt.texi +++ b/doc/alloca-opt.texi @@ -9,14 +9,14 @@ @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 +The @code{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 +@code{alloca-opt} module provides no replacement, just a preprocessor macro HAVE_ALLOCA. The user can @code{#include } on all platforms, and use diff --git a/doc/alloca.texi b/doc/alloca.texi index 04c9cb3af6..546a0dc133 100644 --- a/doc/alloca.texi +++ b/doc/alloca.texi @@ -9,7 +9,7 @@ @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 +The @code{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. diff --git a/doc/glibc-functions/futimesat.texi b/doc/glibc-functions/futimesat.texi index ac7bb615da..8d1760a695 100644 --- a/doc/glibc-functions/futimesat.texi +++ b/doc/glibc-functions/futimesat.texi @@ -24,5 +24,5 @@ file ? utimensat(fd, file, times, 0) : futimens(fd, times) @end example -@noindent or the gnulib module fdutimensat, instead. +@noindent or the gnulib module @code{fdutimensat}, instead. @end itemize diff --git a/doc/glibc-functions/lutimes.texi b/doc/glibc-functions/lutimes.texi index d2603425dd..19a17e7b2f 100644 --- a/doc/glibc-functions/lutimes.texi +++ b/doc/glibc-functions/lutimes.texi @@ -16,7 +16,7 @@ Mac OS X 10.4, OpenBSD 3.8, Minix 3.1.8, AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, @item This function cannot set full timestamp resolution. Use @code{utimensat(AT_FDCWD,file,times,AT_SYMLINK_NOFOLLOW)}, or the -gnulib module utimens, instead. +gnulib module @code{utimens}, instead. @item The mere act of using @code{lstat} modifies the access time of symlinks on some platforms, so @code{lutimes} can only effectively diff --git a/doc/glibc-functions/memmem.texi b/doc/glibc-functions/memmem.texi index 017da71d0a..bdab0e0c58 100644 --- a/doc/glibc-functions/memmem.texi +++ b/doc/glibc-functions/memmem.texi @@ -5,7 +5,7 @@ Gnulib module: memmem or memmem-simple Both modules implement the same replacement for the @code{memmem} function -with the memmem module providing a replacement on more platforms where +with the @code{memmem} module providing a replacement on more platforms where the existing @code{memmem} function has a quadratic worst-case complexity. Portability problems fixed by either Gnulib module @code{memmem-simple} diff --git a/doc/posix-functions/freopen.texi b/doc/posix-functions/freopen.texi index 08d52cac8a..93f5e176a9 100644 --- a/doc/posix-functions/freopen.texi +++ b/doc/posix-functions/freopen.texi @@ -37,6 +37,6 @@ HP-UX 11.00, Solaris 9, Irix 5.3. @item Applications should not assume that @code{fileno(f)} will be the same before and after a call to @code{freopen(name,mode,f)}. However, the -module freopen-safer can at least protect @code{stdin}, @code{stdout}, +module @code{freopen-safer} can at least protect @code{stdin}, @code{stdout}, and @code{stderr}. @end itemize diff --git a/doc/posix-functions/open.texi b/doc/posix-functions/open.texi index 7e9df261d5..6cf22c2f62 100644 --- a/doc/posix-functions/open.texi +++ b/doc/posix-functions/open.texi @@ -6,7 +6,7 @@ POSIX specification:@* @url{http://www.opengroup.org/onlinepubs/9699919799/funct Gnulib module: open, fchdir -Portability problems fixed by the Gnulib module open: +Portability problems fixed by the Gnulib module @code{open}: @itemize @item Some platforms do not support @code{O_CLOEXEC}: @@ -28,7 +28,7 @@ On Windows platforms (excluding Cygwin), this function does usually not recognize the @file{/dev/null} filename. @end itemize -Portability problems fixed by the Gnulib module fchdir: +Portability problems fixed by the Gnulib module @code{fchdir}: @itemize @item On Windows platforms (excluding Cygwin), this function fails to open a diff --git a/doc/posix-functions/readlink.texi b/doc/posix-functions/readlink.texi index c1279ddef4..98bf1bd029 100644 --- a/doc/posix-functions/readlink.texi +++ b/doc/posix-functions/readlink.texi @@ -37,6 +37,6 @@ no indication if symlink contents were truncated if the return value matches the length. Furthermore, AIX 5.1 and HP-UX 11 set @code{errno} to @code{ERANGE} rather than returning truncated contents, and Linux sets @code{errno} to @code{EINVAL} if the -requested length is zero. Use the gnulib module areadlink for +requested length is zero. Use the gnulib module @code{areadlink} for improved ability to read symlink contents. @end itemize diff --git a/doc/posix-functions/readlinkat.texi b/doc/posix-functions/readlinkat.texi index 10ea3dce2c..f8c2bbd8bd 100644 --- a/doc/posix-functions/readlinkat.texi +++ b/doc/posix-functions/readlinkat.texi @@ -42,6 +42,6 @@ no indication if symlink contents were truncated if the return value matches the length. Furthermore, AIX 5.1 and HP-UX 11 set @code{errno} to @code{ERANGE} rather than returning truncated contents, and Linux sets @code{errno} to @code{EINVAL} if the -requested length is zero. Use the gnulib module areadlink for +requested length is zero. Use the gnulib module @code{areadlink} for improved ability to read symlink contents. @end itemize diff --git a/doc/posix-functions/stderr.texi b/doc/posix-functions/stderr.texi index 10a4e54e9f..b0ed173678 100644 --- a/doc/posix-functions/stderr.texi +++ b/doc/posix-functions/stderr.texi @@ -15,7 +15,7 @@ Portability problems not fixed by Gnulib: @item stderr is created in 32-bit mode instead of 64-bit mode: Cygwin 1.5.x. One workaround is to use freopen(NULL, ``r+'', stderr) on Cygwin 1.5.21 -or newer. Another is to use the gnulib ftello module and do +or newer. Another is to use the gnulib @code{ftello} module and do ftello(stderr). @item POSIX states that a setuid application can guarantee that fd 2 is diff --git a/doc/posix-functions/stdout.texi b/doc/posix-functions/stdout.texi index 208dafafef..8912373421 100644 --- a/doc/posix-functions/stdout.texi +++ b/doc/posix-functions/stdout.texi @@ -15,7 +15,7 @@ Portability problems not fixed by Gnulib: @item stdout is created in 32-bit mode instead of 64-bit mode: Cygwin 1.5.x. One workaround is to use freopen(NULL, ``w'', stdout) on Cygwin 1.5.21 -or newer. Another is to use the gnulib ftello module and do +or newer. Another is to use the gnulib @code{ftello} module and do ftello(stdout). @item POSIX states that a setuid application can guarantee that fd 1 is diff --git a/doc/posix-functions/unlink.texi b/doc/posix-functions/unlink.texi index 171e9facd6..9bf7cfdc52 100644 --- a/doc/posix-functions/unlink.texi +++ b/doc/posix-functions/unlink.texi @@ -26,7 +26,7 @@ not always the POSIX value of @code{EPERM}. Meanwhile, if a process has the ability to unlink directories, POSIX requires that @code{unlink("symlink-to-dir/")} remove @file{dir} and leave @file{symlink-to-dir} dangling; this behavior is counter-intuitive. -The gnulib module unlinkdir can help determine whether code must be +The gnulib module @code{unlinkdir} can help determine whether code must be cautious of unlinking directories. @item Removing an open file is non-portable: On Unix this allows the programs that diff --git a/doc/posix-functions/unlinkat.texi b/doc/posix-functions/unlinkat.texi index 85764a6d61..de9d517cee 100644 --- a/doc/posix-functions/unlinkat.texi +++ b/doc/posix-functions/unlinkat.texi @@ -44,7 +44,7 @@ not always the POSIX value of @code{EPERM}. Meanwhile, if a process has the ability to unlink directories, POSIX requires that @code{unlinkat(fd,"symlink-to-dir/",0)} remove @file{dir} and leave @file{symlink-to-dir} dangling; this behavior is counter-intuitive. -The gnulib module unlinkdir can help determine whether code must be +The gnulib module @code{unlinkdir} can help determine whether code must be cautious of unlinking directories. @item Removing an open file is non-portable: On Unix this allows the programs that diff --git a/doc/posix-functions/utime.texi b/doc/posix-functions/utime.texi index 99a9b97ef7..23c74d14a2 100644 --- a/doc/posix-functions/utime.texi +++ b/doc/posix-functions/utime.texi @@ -28,6 +28,6 @@ On some platforms, this function mis-handles trailing slash: Solaris 9. @item This function cannot set full timestamp resolution. Use -@code{utimensat(AT_FDCWD,file,times,0)}, or the gnulib module utimens, +@code{utimensat(AT_FDCWD,file,times,0)}, or the gnulib module @code{utimens}, instead. @end itemize diff --git a/doc/posix-functions/utimensat.texi b/doc/posix-functions/utimensat.texi index 4993c10a85..d0590bb01c 100644 --- a/doc/posix-functions/utimensat.texi +++ b/doc/posix-functions/utimensat.texi @@ -56,4 +56,4 @@ effectively change directory modification time: Cygwin 1.5.x. @end itemize -The gnulib module fdutimensat provides a similar interface. +The gnulib module @code{fdutimensat} provides a similar interface. diff --git a/doc/posix-functions/utimes.texi b/doc/posix-functions/utimes.texi index de53795125..90a453d8e9 100644 --- a/doc/posix-functions/utimes.texi +++ b/doc/posix-functions/utimes.texi @@ -25,7 +25,7 @@ FreeBSD 7.2, Solaris 9. @item This function cannot set full timestamp resolution. In particular, some platforms incorrectly round rather than truncate. Use -@code{utimensat(AT_FDCWD,file,times,0)}, or the gnulib module utimens, +@code{utimensat(AT_FDCWD,file,times,0)}, or the gnulib module @code{utimens}, instead. @item On some platforms, @code{utimes (file, NULL)} fails to set the diff --git a/doc/posix-headers/stdint.texi b/doc/posix-headers/stdint.texi index d8b8395608..87e5306b83 100644 --- a/doc/posix-headers/stdint.texi +++ b/doc/posix-headers/stdint.texi @@ -66,7 +66,7 @@ To work around these problems, compute the value of expressions like @code{#if}-time. @end itemize -The stdint.h module uses @code{#include_next}. If you wish to install +The @code{stdint} module uses @code{#include_next}. If you wish to install the generated stdint.h file under another name, typically in order to be able to use some of the types defined by stdint.h in your public header file, you could use the following Makefile.am-snippet: diff --git a/doc/quote.texi b/doc/quote.texi index b8102698e7..6a15967f24 100644 --- a/doc/quote.texi +++ b/doc/quote.texi @@ -39,6 +39,6 @@ Hence if you need more than one thing quoted at the same time, you need to use @code{quote_n}. @findex quotearg_alloc -Also, the quote module is not suited for multithreaded applications. +Also, the @code{quote} module is not suited for multithreaded applications. In that case, you have to use @code{quotearg_alloc}, defined in the @samp{quotearg} module, which is decidedly less convenient.