From: Nick Bowler <nbowler@draconx.ca>
Date: Thu, 29 Sep 2011 01:03:50 +0000 (-0400)
Subject: Document libcdecl's slice of the C namespaces.
X-Git-Tag: v1~92
X-Git-Url: https://git.draconx.ca/gitweb/cdecl99.git/commitdiff_plain/148832244970c409dfe187b66cb6c7aed5f60083

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 97fc41a..d92dcbf 100644
--- 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