[cpp.replace] Distribute examples from [cpp.scope]

where they fit more naturally, omitting some of the
now-redundant introductory phrases.

Author: jensmaurer

source/preprocessor.tex

@@ -868,6 +868,26 @@
 and the two replacement lists are identical,
 otherwise the program is ill-formed.
 
+\pnum
+\begin{example}
+The following sequence is valid:
+\begin{codeblock}
+#define OBJ_LIKE      (1-1)
+#define OBJ_LIKE      @\tcode{/* white space */ (1-1) /* other */}@
+#define FUNC_LIKE(a)   ( a )
+#define FUNC_LIKE( a )(     @\tcode{/* note the white space */ \textbackslash}@
+                a @\tcode{/* other stuff on this line}@
+                  @\tcode{*/}@ )
+\end{codeblock}
+But the following redefinitions are invalid:
+\begin{codeblock}
+#define OBJ_LIKE    (0)         // different token sequence
+#define OBJ_LIKE    (1 - 1)     // different white space
+#define FUNC_LIKE(b) ( a )      // different parameter usage
+#define FUNC_LIKE(b) ( b )      // different parameter spelling
+\end{codeblock}
+\end{example}
+
 \pnum
 \indextext{macro!replacement list}%
 There shall be white-space between the identifier and the replacement list
@@ -938,6 +958,16 @@
 The replacement list is then rescanned for more macro names as
 specified below.
 
+\pnum
+\begin{example}
+The simplest use of this facility is to define a ``manifest constant'',
+as in
+\begin{codeblock}
+#define TABSIZE 100
+int table[TABSIZE];
+\end{codeblock}
+\end{example}
+
 \pnum
 A preprocessing directive of the form
 \begin{ncsimplebnf}
@@ -983,6 +1013,27 @@
 arguments that would otherwise act as preprocessing directives,\footnote{A \grammarterm{conditionally-supported-directive} is a preprocessing directive regardless of whether the implementation supports it.}
 the behavior is undefined.
 
+\pnum
+\begin{example}
+The following defines a function-like
+macro whose value is the maximum of its arguments.
+It has the disadvantages of evaluating one or the other of its arguments
+a second time
+(including
+\indextext{side effects}%
+side effects)
+and generating more code than a function if invoked several times.
+It also cannot have its address taken,
+as it has none.
+
+\begin{codeblock}
+#define max(a, b) ((a) > (b) ? (a) : (b))
+\end{codeblock}
+
+The parentheses ensure that the arguments and
+the resulting expression are bound properly.
+\end{example}
+
 \pnum
 \indextext{macro!function-like!arguments}%
 If there is a \tcode{...} immediately preceding the \tcode{)} in the
@@ -1040,6 +1091,26 @@
 shall be treated as if it were a parameter, and the variable arguments shall form
 the preprocessing tokens used to replace it.
 
+\pnum
+\begin{example}
+\begin{codeblock}
+#define debug(...) fprintf(stderr, @\mname{VA_ARGS}@)
+#define showlist(...) puts(#@\mname{VA_ARGS}@)
+#define report(test, ...) ((test) ? puts(#test) : printf(@\mname{VA_ARGS}@))
+debug("Flag");
+debug("X = %d\n", x);
+showlist(The first, second, and third items.);
+report(x>y, "x is %d but y is %d", x, y);
+\end{codeblock}
+results in
+\begin{codeblock}
+fprintf(stderr, "Flag");
+fprintf(stderr, "X = %d\n", x);
+puts("The first, second, and third items.");
+((x>y) ? puts("x>y") : printf("x is %d but y is %d", x, y));
+\end{codeblock}
+\end{example}
+
 \pnum
 \indextext{__VA_OPT__@\mname{VA_OPT}}%
 The identifier \mname{VA_OPT}
@@ -1194,6 +1265,49 @@
 \tcode{\#\#}
 operators is unspecified.
 
+\pnum
+\begin{example}
+The sequence
+\begin{codeblock}
+#define str(s)      # s
+#define xstr(s)     str(s)
+#define debug(s, t) printf("x" # s "= %d, x" # t "= %s", @\textbackslash@
+               x ## s, x ## t)
+#define INCFILE(n)  vers ## n
+#define glue(a, b)  a ## b
+#define xglue(a, b) glue(a, b)
+#define HIGHLOW     "hello"
+#define LOW         LOW ", world"
+
+debug(1, 2);
+fputs(str(strncmp("abc@\textbackslash@0d", "abc", '@\textbackslash@4')        // this goes away
+    == 0) str(: @\atsign\textbackslash@n), s);
+#include xstr(INCFILE(2).h)
+glue(HIGH, LOW);
+xglue(HIGH, LOW)
+\end{codeblock}
+results in
+\begin{codeblock}
+printf("x" "1" "= %d, x" "2" "= %s", x1, x2);
+fputs("strncmp(@\textbackslash@"abc@\textbackslash\textbackslash@0d@\textbackslash@", @\textbackslash@"abc@\textbackslash@", '@\textbackslash\textbackslash@4') == 0" ": @\atsign\textbackslash@n", s);
+#include "vers2.h"      @\textrm{(\textit{after macro replacement, before file access})}@
+"hello";
+"hello" ", world"
+\end{codeblock}
+or, after concatenation of the character string literals,
+\begin{codeblock}
+printf("x1= %d, x2= %s", x1, x2);
+fputs("strncmp(@\textbackslash@"abc@\textbackslash\textbackslash@0d@\textbackslash@", @\textbackslash@"abc@\textbackslash@", '@\textbackslash\textbackslash@4') == 0: @\atsign\textbackslash@n", s);
+#include "vers2.h"      @\textrm{(\textit{after macro replacement, before file access})}@
+"hello";
+"hello, world"
+\end{codeblock}
+
+Space around the \tcode{\#} and \tcode{\#\#} tokens in the macro definition
+is optional.
+\end{example}
+
+\pnum
 \begin{example}
 In the following fragment:
 
@@ -1220,6 +1334,21 @@
 \tcode{\#\#} operator.
 \end{example}
 
+\pnum
+\begin{example}
+To illustrate the rules for placemarker preprocessing tokens, the sequence
+\begin{codeblock}
+#define t(x,y,z) x ## y ## z
+int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),
+  t(10,,), t(,11,), t(,,12), t(,,) };
+\end{codeblock}
+results in
+\begin{codeblock}
+int j[] = { 123, 45, 67, 89,
+  10, 11, 12, };
+\end{codeblock}
+\end{example}
+
 \rSec2[cpp.rescan]{Rescanning and further replacement}%
 \indextext{macro!rescanning and replacement}%
 \indextext{rescanning and replacement|see{macro, rescanning and replacement}}
@@ -1231,6 +1360,40 @@
 subsequent preprocessing tokens of the source file, for more macro names
 to replace.
 
+\pnum
+\begin{example}
+The sequence
+\begin{codeblock}
+#define x       3
+#define f(a)    f(x * (a))
+#undef  x
+#define x       2
+#define g       f
+#define z       z[0]
+#define h       g(~
+#define m(a)    a(w)
+#define w       0,1
+#define t(a)    a
+#define p()     int
+#define q(x)    x
+#define r(x,y)  x ## y
+#define str(x)  # x
+
+f(y+1) + f(f(z)) % t(t(g)(0) + t)(1);
+g(x+(3,4)-w) | h 5) & m
+    (f)^m(m);
+p() i[q()] = { q(1), r(2,3), r(4,), r(,5), r(,) };
+char c[2][6] = { str(hello), str() };
+\end{codeblock}
+results in
+\begin{codeblock}
+f(2 * (y+1)) + f(2 * (f(2 * (z[0])))) % f(2 * (0)) + t(1);
+f(2 * (2+(3,4)-0,1)) | f(2 * (~ 5)) & f(2 * (0,1))^m(0,1);
+int i[] = { 1, 23, 4, 5, };
+char c[2][6] = { "hello", "" };
+\end{codeblock}
+\end{example}
+
 \pnum
 If the name of the macro being replaced is found during this scan of
 the replacement list
@@ -1274,180 +1437,6 @@
 It is ignored if the specified identifier is not currently defined as
 a macro name.
 
-\pnum
-\begin{example}
-The simplest use of this facility is to define a ``manifest constant'',
-as in
-\begin{codeblock}
-#define TABSIZE 100
-int table[TABSIZE];
-\end{codeblock}
-\end{example}
-
-\pnum
-\begin{example}
-The following defines a function-like
-macro whose value is the maximum of its arguments.
-It has the advantages of working for any compatible types of the arguments
-and of generating in-line code without the overhead of function calling.
-It has the disadvantages of evaluating one or the other of its arguments
-a second time
-(including
-\indextext{side effects}%
-side effects)
-and generating more code than a function if invoked several times.
-It also cannot have its address taken,
-as it has none.
-
-\begin{codeblock}
-#define max(a, b) ((a) > (b) ? (a) : (b))
-\end{codeblock}
-
-The parentheses ensure that the arguments and
-the resulting expression are bound properly.
-\end{example}
-
-\pnum
-\begin{example}
-To illustrate the rules for redefinition and reexamination,
-the sequence
-\begin{codeblock}
-#define x       3
-#define f(a)    f(x * (a))
-#undef  x
-#define x       2
-#define g       f
-#define z       z[0]
-#define h       g(~
-#define m(a)    a(w)
-#define w       0,1
-#define t(a)    a
-#define p()     int
-#define q(x)    x
-#define r(x,y)  x ## y
-#define str(x)  # x
-
-f(y+1) + f(f(z)) % t(t(g)(0) + t)(1);
-g(x+(3,4)-w) | h 5) & m
-    (f)^m(m);
-p() i[q()] = { q(1), r(2,3), r(4,), r(,5), r(,) };
-char c[2][6] = { str(hello), str() };
-\end{codeblock}
-results in
-\begin{codeblock}
-f(2 * (y+1)) + f(2 * (f(2 * (z[0])))) % f(2 * (0)) + t(1);
-f(2 * (2+(3,4)-0,1)) | f(2 * (~ 5)) & f(2 * (0,1))^m(0,1);
-int i[] = { 1, 23, 4, 5, };
-char c[2][6] = { "hello", "" };
-\end{codeblock}
-\end{example}
-
-\pnum
-\begin{example}
-To illustrate the rules for creating character string literals
-and concatenating tokens,
-the sequence
-\begin{codeblock}
-#define str(s)      # s
-#define xstr(s)     str(s)
-#define debug(s, t) printf("x" # s "= %d, x" # t "= %s", @\textbackslash@
-               x ## s, x ## t)
-#define INCFILE(n)  vers ## n
-#define glue(a, b)  a ## b
-#define xglue(a, b) glue(a, b)
-#define HIGHLOW     "hello"
-#define LOW         LOW ", world"
-
-debug(1, 2);
-fputs(str(strncmp("abc@\textbackslash@0d", "abc", '@\textbackslash@4')        // this goes away
-    == 0) str(: @\atsign\textbackslash@n), s);
-#include xstr(INCFILE(2).h)
-glue(HIGH, LOW);
-xglue(HIGH, LOW)
-\end{codeblock}
-results in
-\begin{codeblock}
-printf("x" "1" "= %d, x" "2" "= %s", x1, x2);
-fputs("strncmp(@\textbackslash@"abc@\textbackslash\textbackslash@0d@\textbackslash@", @\textbackslash@"abc@\textbackslash@", '@\textbackslash\textbackslash@4') == 0" ": @\atsign\textbackslash@n", s);
-#include "vers2.h"      @\textrm{(\textit{after macro replacement, before file access})}@
-"hello";
-"hello" ", world"
-\end{codeblock}
-or, after concatenation of the character string literals,
-\begin{codeblock}
-printf("x1= %d, x2= %s", x1, x2);
-fputs("strncmp(@\textbackslash@"abc@\textbackslash\textbackslash@0d@\textbackslash@", @\textbackslash@"abc@\textbackslash@", '@\textbackslash\textbackslash@4') == 0: @\atsign\textbackslash@n", s);
-#include "vers2.h"      @\textrm{(\textit{after macro replacement, before file access})}@
-"hello";
-"hello, world"
-\end{codeblock}
-
-Space around the
-\tcode{\#}
-and
-\tcode{\#\#}
-tokens in the macro definition is optional.
-\end{example}
-
-\pnum
-\begin{example}
-To illustrate the rules for placemarker preprocessing tokens, the sequence
-\begin{codeblock}
-#define t(x,y,z) x ## y ## z
-int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),
-  t(10,,), t(,11,), t(,,12), t(,,) };
-\end{codeblock}
-results in
-\begin{codeblock}
-int j[] = { 123, 45, 67, 89,
-  10, 11, 12, };
-\end{codeblock}
-\end{example}
-
-\pnum
-\begin{example}
-To demonstrate the redefinition rules,
-the following sequence is valid.
-
-\begin{codeblock}
-#define OBJ_LIKE      (1-1)
-#define OBJ_LIKE      @\tcode{/* white space */ (1-1) /* other */}@
-#define FUNC_LIKE(a)   ( a )
-#define FUNC_LIKE( a )(     @\tcode{/* note the white space */ \textbackslash}@
-                a @\tcode{/* other stuff on this line}@
-                  @\tcode{*/}@ )
-\end{codeblock}
-
-But the following redefinitions are invalid:
-\begin{codeblock}
-#define OBJ_LIKE    (0)         // different token sequence
-#define OBJ_LIKE    (1 - 1)     // different white space
-#define FUNC_LIKE(b) ( a )      // different parameter usage
-#define FUNC_LIKE(b) ( b )      // different parameter spelling
-\end{codeblock}
-\end{example}
-
-\pnum
-\begin{example}
-Finally, to show the variable argument list macro facilities:
-\begin{codeblock}
-#define debug(...) fprintf(stderr, @\mname{VA_ARGS}@)
-#define showlist(...) puts(#@\mname{VA_ARGS}@)
-#define report(test, ...) ((test) ? puts(#test) : printf(@\mname{VA_ARGS}@))
-debug("Flag");
-debug("X = %d\n", x);
-showlist(The first, second, and third items.);
-report(x>y, "x is %d but y is %d", x, y);
-\end{codeblock}
-results in
-\begin{codeblock}
-fprintf(stderr, "Flag");
-fprintf(stderr, "X = %d\n", x);
-puts("The first, second, and third items.");
-((x>y) ? puts("x>y") : printf("x is %d but y is %d", x, y));
-
-\end{codeblock}
-\end{example}
 \indextext{macro!replacement|)}
 
 \rSec1[cpp.line]{Line control}%