Update -Wunused-macros documentation

Update -Wunused-macros documentation

[Neil Booth]

Following the recent discussion, this clarifies the behaviour
w.r.t. skipped conditional blocks, and tests for it.

Neil.

	* doc/cppopts.texi: Update.
testsuite:
	* gcc.dg/cpp/trad/Wunused.c, gcc.dg/cpp/Wunused.c: Add test
	for documented behaviour.

Index: doc/cppopts.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/cppopts.texi,v
retrieving revision 1.9
diff -u -p -r1.9 cppopts.texi
--- doc/cppopts.texi	23 Jul 2002 22:57:49 -0000	1.9
+++ doc/cppopts.texi	26 Jul 2002 16:30:33 -0000
@@ -120,6 +120,17 @@ time it is redefined or undefined.
 Built-in macros, macros defined on the command line, and macros
 defined in include files are not warned about.
 
+@strong{Note:} If a macro is actually used, but only used in skipped
+conditional blocks, then CPP will report it as unused.  To avoid the
+warning in such a case, you might improve the scope of the macro's
+definition by, for example, moving it into the first skipped block.
+Alternatively, you could provide a dummy use with something like:
+
+@smallexample
+#if defined the_macro_causing_the_warning
+#endif
+@end smallexample
+
 @item -Wendif-labels
 @opindex Wendif-labels
 Warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
Index: testsuite/gcc.dg/cpp/trad/Wunused.c
===================================================================
RCS file: /cvs/gcc/gcc/gcc/testsuite/gcc.dg/cpp/trad/Wunused.c,v
retrieving revision 1.1
diff -u -p -r1.1 Wunused.c
--- testsuite/gcc.dg/cpp/trad/Wunused.c	23 Jul 2002 22:57:49 -0000	1.1
+++ testsuite/gcc.dg/cpp/trad/Wunused.c	26 Jul 2002 16:30:33 -0000
@@ -26,6 +26,12 @@
 #endif
 used4
 
+unused7;			/* This does not count as a use.  */
+
+#if 0
+unused5				/* This does not count as a use.  */
+#endif
+
 #undef unused5
 #define unused6
 unused6
Index: testsuite/gcc.dg/cpp/Wunused.c
===================================================================
RCS file: /cvs/gcc/gcc/gcc/testsuite/gcc.dg/cpp/Wunused.c,v
retrieving revision 1.1
diff -u -p -r1.1 Wunused.c
--- testsuite/gcc.dg/cpp/Wunused.c	23 Jul 2002 22:57:49 -0000	1.1
+++ testsuite/gcc.dg/cpp/Wunused.c	26 Jul 2002 16:30:33 -0000
@@ -26,7 +26,12 @@
 #endif
 used4
 
-unused7
+unused7				/* This does not count as a use.  */
+
+#if 0
+unused5				/* This does not count as a use.  */
+#endif
 #undef unused5
+
 #define unused6
 unused6