Document libcdecl's slice of the C namespaces.

Now that we rename gnulib symbols, this should actually be true.
Document it.

diff --git a/doc/man/libcdecl.3 b/doc/man/libcdecl.3
index 97fc41a568bf19c99bcc9f11078e67030c470366..d92dcbfe478daf49790d5c5d6282e79aeccb05b1 100644 (file)
--- a/doc/man/libcdecl.3
+++ b/doc/man/libcdecl.3
@@ -28,6 +28,31 @@ manual page.
 is intended to be portable to any system with a working C implementation that
 at least makes an effort to support C99.  The library is thread-safe when
 appropriate facilities exist and are enabled at build time.
+.Sh NAMESPACE
+.Nm
+reserves all identifiers beginning with either
+.Li cdecl_
+or
+.Li CDECL_
+in both the tag and ordinary identifier namespaces.  All external names
+beginning with
+.Li cdecl_
+are reserved, and the library headers may define object-like macros beginning
+with
+.Li CDECL_ .
+The
+.Nm
+library headers may use other identifiers where they do not pollute the global
+namespaces, such as struct members or function parameter names.  Such internal
+identifiers shall not contain any upper-case letters.  As these internal
+identifiers can only conflict with object-like macros, this practice is safe as
+long as the convention of defining object-like macros using upper-case letters
+is adhered to.
+.Pp
+External names beginning with
+.Li cdecl
+followed by two consecutive underscores are not considered part of the ABI and
+are thus subject to change at any time.
 .Sh ABSTRACT SYNTAX TREE
 The functions in
 .Nm