Avoid using the syntax symbol() in formatted documentation.

2 files changed, 93 insertions, 69 deletions

diff --git a/doc/libunistring.texi b/doc/libunistring.texi
index cde0360..6c907de 100644
--- a/doc/libunistring.texi
+++ b/doc/libunistring.texi
@@ -20,6 +20,30 @@
 
 @include version.texi
 
+@c Location of the POSIX specification on the web.
+@set POSIXURL http://www.opengroup.org/onlinepubs/9699919799
+
+@c Macro for referencing a POSIX function.
+@c We don't write it as func(), see section "GNU Manuals" of the
+@c GNU coding standards.
+@ifinfo
+@macro posixfunc{func}
+@code{\func\}
+@end macro
+@end ifinfo
+@ifnotinfo
+@macro posixfunc{func}
+@uref{@value{POSIXURL}/functions/\func\.html,,@code{\func\}}
+@end macro
+@end ifnotinfo
+
+@c Macro for referencing a normal function.
+@c We don't write it as func(), see section "GNU Manuals" of the
+@c GNU coding standards.
+@macro func{func}
+@code{\func\}
+@end macro
+
 @ifinfo
 @dircategory Software development
 @direntry
@@ -356,7 +380,7 @@ The formatting of date and time.  This is the @code{LC_TIME} category.
 In particular, the @code{LC_CTYPE} category of the current locale determines
 the character encoding.  This is the encoding of @samp{char *} strings.
 We also call it the ``locale encoding''.  GNU libunistring has a function,
-@code{locale_charset()}, that returns a standardized (platform independent)
+@func{locale_charset}, that returns a standardized (platform independent)
 name for this encoding.
 
 All locale encodings used on glibc systems are essentially ASCII compatible:
@@ -429,33 +453,33 @@ As a consequence:
 The @code{<ctype.h>} API is useless in this context; it does not work in
 multibyte locales.
 @item
-The @code{strlen()} function does not return the number of characters
+The @posixfunc{strlen} function does not return the number of characters
 in a string.  Nor does it return the number of screen columns occupied
 by a string after it is output.  It merely returns the number of
 @emph{bytes} occupied by a string.
 @item
-Truncating a string, for example, with @code{strncpy()}, can have the
+Truncating a string, for example, with @posixfunc{strncpy}, can have the
 effect of truncating it in the middle of a multibyte character.  Such
 a string will, when output, have a garbled character at its end, often
 represented by a hollow box.
 @item
-@code{strchr()} and @code{strrchr()} do not work with multibyte strings
+@posixfunc{strchr} and @posixfunc{strrchr} do not work with multibyte strings
 if the locale encoding is GB18030 and the character to be searched is
 a digit.
 @item
-@code{strstr()} does not work with multibyte strings if the locale encoding
+@posixfunc{strstr} does not work with multibyte strings if the locale encoding
 is different from UTF-8.
 @item
-@code{strcspn()}, @code{strpbrk()}, @code{strspn()} cannot work correctly
-in multibyte locales: they assume the second argument is a list of
+@posixfunc{strcspn}, @posixfunc{strpbrk}, @posixfunc{strspn} cannot work
+correctly in multibyte locales: they assume the second argument is a list of
 single-byte characters.  Even in this simple case, they do not work with
 multibyte strings if the locale encoding is GB18030 and one of the
 characters to be searched is a digit.
 @item
-@code{strsep()} and @code{strtok_r()} do not work with multibyte strings
+@posixfunc{strsep} and @posixfunc{strtok_r} do not work with multibyte strings
 unless all of the delimiter characters are ASCII characters < 0x30.
 @item
-The @code{strcasecmp()}, @code{strncasecmp()}, and @code{strcasestr()}
+The @posixfunc{strcasecmp}, @posixfunc{strncasecmp}, and @posixfunc{strcasestr}
 functions do not work with multibyte strings.
 @end itemize
 
@@ -466,26 +490,26 @@ gnulib has modules @samp{mbchar}, @samp{mbiter}, @samp{mbuiter} that
 represent multibyte characters and allow to iterate across a multibyte
 string with the same ease as through a unibyte string.
 @item
-gnulib has functions @code{mbslen()} and @code{mbswidth()} that can be
-used instead of @code{strlen()} when the number of characters or the
+gnulib has functions @func{mbslen} and @func{mbswidth} that can be
+used instead of @posixfunc{strlen} when the number of characters or the
 number of screen columns of a string is requested.
 @item
-gnulib has functions @code{mbschr()} and @code{mbsrrchr()} that are
-like @code{strchr()} and @code{strrchr()}, but work in multibyte locales.
+gnulib has functions @func{mbschr} and @func{mbsrrchr} that are
+like @posixfunc{strchr} and @posixfunc{strrchr}, but work in multibyte locales.
 @item
-gnulib has a function @code{mbsstr()}, like @code{strstr()}, but works
+gnulib has a function @func{mbsstr}, like @posixfunc{strstr}, but works
 in multibyte locales.
 @item
-gnulib has functions @code{mbscspn()}, @code{mbspbrk()}, @code{mbsspn()}
-that are like @code{strcspn()}, @code{strpbrk()}, @code{strspn()} , but
+gnulib has functions @func{mbscspn}, @func{mbspbrk}, @func{mbsspn}
+that are like @posixfunc{strcspn}, @posixfunc{strpbrk}, @posixfunc{strspn}, but
 work in multibyte locales.
 @item
-gnulib has functions @code{mbssep()} and @code{mbstok_r()} that are
-like @code{strsep()} and @code{strtok_r()} but work in multibyte locales.
+gnulib has functions @func{mbssep} and @func{mbstok_r} that are
+like @posixfunc{strsep} and @posixfunc{strtok_r} but work in multibyte locales.
 @item
-gnulib has functions @code{mbscasecmp()}, @code{mbsncasecmp()},
-@code{mbspcasecmp()}, and @code{mbscasestr()} that are like
-@code{strcasecmp()}, @code{strncasecmp()}, and @code{strcasestr()}, but
+gnulib has functions @func{mbscasecmp}, @func{mbsncasecmp},
+@func{mbspcasecmp}, and @func{mbscasestr} that are like @posixfunc{strcasecmp},
+@posixfunc{strncasecmp}, and @posixfunc{strcasestr}, but
 work in multibyte locales.  Still, the function @code{ulc_casecmp} is
 preferable to these functions; see below.
 @end itemize
@@ -558,11 +582,11 @@ and undocumented.  This means, if you want to know any property of a
 @code{wchar_t} character, other than the properties defined by
 @code{<wctype.h>} --- such as whether it's a dash, currency symbol,
 paragraph separator, or similar ---, you have to convert it to
-@code{char *} encoding first, by use of the function @code{wctomb()}.
+@code{char *} encoding first, by use of the function @posixfunc{wctomb}.
 
 @item
 When you read a stream of wide characters, through the functions
-@code{fgetwc()} and @code{fgetws()}, and when the input stream/file is
+@posixfunc{fgetwc} and @posixfunc{fgetws}, and when the input stream/file is
 not in the expected encoding, you have no way to determine the invalid
 byte sequence and do some corrective action.  If you use these
 functions, your program becomes ``garbage in - more garbage out'' or
diff --git a/doc/unistr.texi b/doc/unistr.texi
index 51f755a..b2f83b8 100644
--- a/doc/unistr.texi
+++ b/doc/unistr.texi
@@ -66,7 +66,7 @@ Returns the length (number of units) of the first character in @var{s}, which
 is no longer than @var{n}.  Returns 0 if it is the NUL character.  Returns -1
 upon failure.
 
-This function is similar to @code{mblen()}, except that it operates on a
+This function is similar to @posixfunc{mblen}, except that it operates on a
 Unicode string and that @var{s} must not be NULL.
 @end deftypefun
 
@@ -80,7 +80,7 @@ is returned.
 
 The number of available units, @var{n}, must be > 0.
 
-This function is similar to @code{mbtowc()}, except that it operates on a
+This function is similar to @posixfunc{mbtowc}, except that it operates on a
 Unicode string, @var{puc} and @var{s} must not be NULL, @var{n} must be > 0,
 and the NUL character is not treated specially.
 @end deftypefun
@@ -104,7 +104,7 @@ sequence of units, -2 is returned for an incomplete sequence of units.
 The number of available units, @var{n}, must be > 0.
 
 This function is similar to @code{u8_mbtouc}, except that the return value
-gives more details about the failure, similar to @code{mbrtowc()}.
+gives more details about the failure, similar to @posixfunc{mbrtowc}.
 @end deftypefun
 
 The following function stores a Unicode character as a Unicode string in
@@ -117,7 +117,7 @@ Puts the multibyte character represented by @var{uc} in @var{s}, returning its
 length.  Returns -1 upon failure, -2 if the number of available units, @var{n},
 is too small.  The latter case cannot occur if @var{n} >= 6/2/1, respectively.
 
-This function is similar to @code{wctomb()}, except that it operates on a
+This function is similar to @posixfunc{wctomb}, except that it operates on a
 Unicode strings, @var{s} must not be NULL, and the argument @var{n} must be
 specified.
 @end deftypefun
@@ -129,7 +129,7 @@ The following functions copy Unicode strings in memory.
 @deftypefunx {uint32_t *} u32_cpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 Copies @var{n} units from @var{src} to @var{dest}.
 
-This function is similar to @code{memcpy()}, except that it operates on
+This function is similar to @posixfunc{memcpy}, except that it operates on
 Unicode strings.
 @end deftypefun
 
@@ -139,7 +139,7 @@ Unicode strings.
 Copies @var{n} units from @var{src} to @var{dest}, guaranteeing correct
 behavior for overlapping memory areas.
 
-This function is similar to @code{memmove()}, except that it operates on
+This function is similar to @posixfunc{memmove}, except that it operates on
 Unicode strings.
 @end deftypefun
 
@@ -151,7 +151,7 @@ The following function fills a Unicode string.
 Sets the first @var{n} characters of @var{s} to @var{uc}.  @var{uc} should be
 a character that occupies only 1 unit.
 
-This function is similar to @code{memset()}, except that it operates on
+This function is similar to @posixfunc{memset}, except that it operates on
 Unicode strings.
 @end deftypefun
 
@@ -165,7 +165,7 @@ Returns a negative value if @var{s1} compares smaller than @var{s2},
 a positive value if @var{s1} compares larger than @var{s2}, or 0 if
 they compare equal.
 
-This function is similar to @code{memcmp()}, except that it operates on
+This function is similar to @posixfunc{memcmp}, except that it operates on
 Unicode strings.
 @end deftypefun
 
@@ -178,7 +178,7 @@ Searches the string at @var{s} for @var{uc}.  Returns a pointer to the first
 occurrence of @var{uc} in @var{s}, or NULL if @var{uc} does not occur in
 @var{s}.
 
-This function is similar to @code{memchr()}, except that it operates on
+This function is similar to @posixfunc{memchr}, except that it operates on
 Unicode strings.
 @end deftypefun
 
@@ -190,7 +190,7 @@ The following function counts the number of Unicode characters.
 Counts and returns the number of Unicode characters in the @var{n} units
 from @var{s}.
 
-This function is similar to the gnulib function @code{mbsnlen()}, except that
+This function is similar to the gnulib function @func{mbsnlen}, except that
 it operates on Unicode strings.
 @end deftypefun
 
@@ -252,8 +252,8 @@ The following functions determine the length of a Unicode string.
 @deftypefunx size_t u32_strlen (const uint32_t *@var{s})
 Returns the number of units in @var{s}.
 
-This function is similar to @code{strlen()} and @code{wcslen()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strlen} and @posixfunc{wcslen}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun size_t u8_strnlen (const uint8_t *@var{s}, size_t @var{maxlen})
@@ -261,8 +261,8 @@ it operates on Unicode strings.
 @deftypefunx size_t u32_strnlen (const uint32_t *@var{s}, size_t @var{maxlen})
 Returns the number of units in @var{s}, but at most @var{maxlen}.
 
-This function is similar to @code{strnlen()} and @code{wcsnlen()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strnlen} and @posixfunc{wcsnlen}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 The following functions copy portions of Unicode strings in memory.
@@ -272,8 +272,8 @@ The following functions copy portions of Unicode strings in memory.
 @deftypefunx {uint32_t *} u32_strcpy (uint32_t *@var{dest}, const uint32_t *@var{src})
 Copies @var{src} to @var{dest}.
 
-This function is similar to @code{strcpy()} and @code{wcscpy()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strcpy} and @posixfunc{wcscpy}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun {uint8_t *} u8_stpcpy (uint8_t *@var{dest}, const uint8_t *@var{src})
@@ -282,7 +282,7 @@ it operates on Unicode strings.
 Copies @var{src} to @var{dest}, returning the address of the terminating NUL
 in @var{dest}.
 
-This function is similar to @code{stpcpy()}, except that it operates on
+This function is similar to @posixfunc{stpcpy}, except that it operates on
 Unicode strings.
 @end deftypefun
 
@@ -291,8 +291,8 @@ Unicode strings.
 @deftypefunx {uint32_t *} u32_strncpy (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 Copies no more than @var{n} units of @var{src} to @var{dest}.
 
-This function is similar to @code{strncpy()} and @code{wcsncpy()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strncpy} and @posixfunc{wcsncpy}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun {uint8_t *} u8_stpncpy (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
@@ -301,7 +301,7 @@ it operates on Unicode strings.
 Copies no more than @var{n} units of @var{src} to @var{dest}, returning the
 address of the last unit written into @var{dest}.
 
-This function is similar to @code{stpncpy()}, except that it operates on
+This function is similar to @posixfunc{stpncpy}, except that it operates on
 Unicode strings.
 @end deftypefun
 
@@ -310,8 +310,8 @@ Unicode strings.
 @deftypefunx {uint32_t *} u32_strcat (uint32_t *@var{dest}, const uint32_t *@var{src})
 Appends @var{src} onto @var{dest}.
 
-This function is similar to @code{strcat()} and @code{wcscat()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strcat} and @posixfunc{wcscat}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun {uint8_t *} u8_strncat (uint8_t *@var{dest}, const uint8_t *@var{src}, size_t @var{n})
@@ -319,8 +319,8 @@ it operates on Unicode strings.
 @deftypefunx {uint32_t *} u32_strncat (uint32_t *@var{dest}, const uint32_t *@var{src}, size_t @var{n})
 Appends no more than @var{n} units of @var{src} onto @var{dest}.
 
-This function is similar to @code{strncat()} and @code{wcsncat()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strncat} and @posixfunc{wcsncat}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 The following functions compare two Unicode strings.
@@ -333,8 +333,8 @@ Returns a negative value if @var{s1} compares smaller than @var{s2},
 a positive value if @var{s1} compares larger than @var{s2}, or 0 if
 they compare equal.
 
-This function is similar to @code{strcmp()} and @code{wcscmp()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strcmp} and @posixfunc{wcscmp}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun int u8_strcoll (const uint8_t *@var{s1}, const uint8_t *@var{s2})
@@ -345,8 +345,8 @@ locale.
 Returns -1 if @var{s1} < @var{s2}, 0 if @var{s1} = @var{s2}, 1 if
 @var{s1} > @var{s2}.  Upon failure, sets @code{errno} and returns any value.
 
-This function is similar to @code{strcoll()} and @code{wcscoll()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strcoll} and @posixfunc{wcscoll}, except
+that it operates on Unicode strings.
 
 Note that this function may consider different canonical normalizations
 of the same string as having a large distance.  It is therefore better to
@@ -358,8 +358,8 @@ use the function @code{u8_normcoll} instead of this one; see @ref{uninorm.h}.
 @deftypefunx int u32_strncmp (const uint32_t *@var{s1}, const uint32_t *@var{s2}, size_t @var{n})
 Compares no more than @var{n} units of @var{s1} and @var{s2}.
 
-This function is similar to @code{strncmp()} and @code{wcsncmp()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strncmp} and @posixfunc{wcsncmp}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 The following function allocates a duplicate of a Unicode string.
@@ -369,8 +369,8 @@ The following function allocates a duplicate of a Unicode string.
 @deftypefunx {uint32_t *} u32_strdup (const uint32_t *@var{s})
 Duplicates @var{s}, returning an identical malloc'd string.
 
-This function is similar to @code{strdup()} and @code{wcsdup()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strdup} and @posixfunc{wcsdup}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 The following functions search for a given Unicode character.
@@ -380,8 +380,8 @@ The following functions search for a given Unicode character.
 @deftypefunx {uint32_t *} u32_strchr (const uint32_t *@var{str}, ucs4_t @var{uc})
 Finds the first occurrence of @var{uc} in @var{str}.
 
-This function is similar to @code{strchr()} and @code{wcschr()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strchr} and @posixfunc{wcschr}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun {uint8_t *} u8_strrchr (const uint8_t *@var{str}, ucs4_t @var{uc})
@@ -389,8 +389,8 @@ it operates on Unicode strings.
 @deftypefunx {uint32_t *} u32_strrchr (const uint32_t *@var{str}, ucs4_t @var{uc})
 Finds the last occurrence of @var{uc} in @var{str}.
 
-This function is similar to @code{strrchr()} and @code{wcsrchr()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strrchr} and @posixfunc{wcsrchr}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 The following functions seach for the first occurrence of some Unicode
@@ -402,8 +402,8 @@ character in or outside a given set of Unicode characters.
 Returns the length of the initial segment of @var{str} which consists entirely
 of Unicode characters not in @var{reject}.
 
-This function is similar to @code{strcspn()} and @code{wcscspn()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strcspn} and @posixfunc{wcscspn}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun size_t u8_strspn (const uint8_t *@var{str}, const uint8_t *@var{accept})
@@ -412,8 +412,8 @@ it operates on Unicode strings.
 Returns the length of the initial segment of @var{str} which consists entirely
 of Unicode characters in @var{accept}.
 
-This function is similar to @code{strspn()} and @code{wcsspn()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strspn} and @posixfunc{wcsspn}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun {uint8_t *} u8_strpbrk (const uint8_t *@var{str}, const uint8_t *@var{accept})
@@ -421,8 +421,8 @@ it operates on Unicode strings.
 @deftypefunx {uint32_t *} u32_strpbrk (const uint32_t *@var{str}, const uint32_t *@var{accept})
 Finds the first occurrence in @var{str} of any character in @var{accept}.
 
-This function is similar to @code{strpbrk()} and @code{wcspbrk()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strpbrk} and @posixfunc{wcspbrk}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 The following functions search whether a given Unicode string is a substring
@@ -433,8 +433,8 @@ of another Unicode string.
 @deftypefunx {uint32_t *} u32_strstr (const uint32_t *@var{haystack}, const uint32_t *@var{needle})
 Finds the first occurrence of @var{needle} in @var{haystack}.
 
-This function is similar to @code{strstr()} and @code{wcsstr()}, except that
-it operates on Unicode strings.
+This function is similar to @posixfunc{strstr} and @posixfunc{wcsstr}, except
+that it operates on Unicode strings.
 @end deftypefun
 
 @deftypefun bool u8_startswith (const uint8_t *@var{str}, const uint8_t *@var{prefix})
@@ -456,7 +456,7 @@ The following function does one step in tokenizing a Unicode string.
 @deftypefunx {uint32_t *} u32_strtok (uint32_t *@var{str}, const uint32_t *@var{delim}, uint32_t **@var{ptr})
 Divides @var{str} into tokens separated by characters in @var{delim}.
 
-This function is similar to @code{strtok_r()} and @code{wcstok()}, except that
-it operates on Unicode strings.  Its interface is actually more similar to
+This function is similar to @posixfunc{strtok_r} and @posixfunc{wcstok}, except
+that it operates on Unicode strings.  Its interface is actually more similar to
 @code{wcstok} than to @code{strtok}.
 @end deftypefun