Clarify the guidelines surrounding the use of macros. The patch is

mostly unrelated to the attributed PR, and the attributed submitter
wasn't so much suggesting the patch for inclusion as providing it
for clarity.

PR:		9869
Submitted by:	bde

1 files changed, 16 insertions, 3 deletions

diff --git a/share/man/man9/style.9 b/share/man/man9/style.9
index 963d3c6..b2c5b88 100644
--- a/share/man/man9/style.9
+++ b/share/man/man9/style.9
@@ -85,12 +85,25 @@ Then, there's a blank line, and the user include files.
 #include "pathnames.h"		/* Local includes in double quotes. */
 .Ed
 .Pp
-Macros are capitalized, parenthesized, and should avoid side-effects.
+Do not #define or declare names in the implementation namespace except
+for implementing application interfaces.
+.Pp
+The names of
+.Dq Li unsafe
+macros (ones that have side effects), and the names of macros for
+manifest constants, are all in uppercase.
+The expansions of expression-like macros are either a single token
+or have outer parentheses.
 Put a single tab character between the 
 .Ql #define
 and the macro name.  
-If they are an inline expansion of a function, the function is defined
-all in lowercase, the macro has the same name all in uppercase.  If the
+If a macro is an inline expansion of a function, the function name is
+all in lowercase and the macro has the same name all in uppercase.
+.\" XXX the above conflicts with ANSI style where the names are the
+.\" same and you #undef the macro (if any) to get the function.
+.\" It is not followed for MALLOC(), and not very common if inline
+.\" functions are used.
+If a
 macro needs more than a single line, use braces
 .Po
 .Sq \&{