Commit b542c0fb by Neil Booth Committed by Neil Booth

cpp.texi: Update documentation...

        * cpp.texi: Update documentation, including some clarifications,
        the treatment of various newline combinations, and space
        between backslash and newline.

From-SVN: r36514
parent 800a6a0c
Mon 18-Sep-2000 22:12:44 BST Neil Booth <NeilB@earthling.net>
* cpp.texi: Update documentation, including some clarifications,
the treatment of various newline combinations, and space between
backslash and newline.
Mon Sep 18 21:00:47 2000 J"orn Rennecke <amylaar@redhat.co.uk> Mon Sep 18 21:00:47 2000 J"orn Rennecke <amylaar@redhat.co.uk>
* sdbout.c (PUT_SDB_DEF, PUT_SDB_TAG, PUT_SDB_EPILOGUE_END): * sdbout.c (PUT_SDB_DEF, PUT_SDB_TAG, PUT_SDB_EPILOGUE_END):
......
...@@ -149,28 +149,45 @@ must also use @samp{-pedantic}. @xref{Invocation}. ...@@ -149,28 +149,45 @@ must also use @samp{-pedantic}. @xref{Invocation}.
Most C preprocessor features are inactive unless you give specific Most C preprocessor features are inactive unless you give specific
directives to request their use. (Preprocessing directives are lines directives to request their use. (Preprocessing directives are lines
starting with a @samp{#} token, possibly preceded by whitespace; starting with a @samp{#} token, possibly preceded by whitespace;
@pxref{Directives}). However, there are three transformations that the @pxref{Directives}). However, there are four transformations that the
preprocessor always makes on all the input it receives, even in the preprocessor always makes on all the input it receives, even in the
absence of directives. absence of directives. These are, in order:
@itemize @bullet @enumerate
@item @item
Trigraphs, if enabled, are replaced with the character they represent. Trigraphs, if enabled, are replaced with the character they represent.
Conceptually, this is the very first action undertaken, just before
backslash-newline deletion.
@item @item
Backslash-newline sequences are deleted, no matter where. This Backslash-newline sequences are deleted, no matter where. This
feature allows you to break long lines for cosmetic purposes without feature allows you to break long lines for cosmetic purposes without
changing their meaning. changing their meaning.
Recently, the non-traditional preprocessor has relaxed its treatment of
escaped newlines. Previously, the newline had to immediately follow a
backslash. The current implementation allows whitespace in the form of
spaces, horizontal and vertical tabs, and form feeds between the
backslash and the subsequent newline. The preprocessor issues a
warning, but treats it as a valid escaped newline and combines the two
lines to form a single logical line. This works within comments and
tokens, including multi-line strings, as well as between tokens.
Comments are @emph{not} treated as whitespace for the purposes of this
relaxation, since they have not yet been replaced with spaces.
@item @item
All C comments are replaced with single spaces. All comments are replaced with single spaces.
@item @item
Predefined macro names are replaced with their expansions Predefined macro names are replaced with their expansions
(@pxref{Predefined}). (@pxref{Predefined}).
@end itemize @end enumerate
For end-of-line indicators, any of \n, \r\n, \n\r and \r are recognised,
and treated as ending a single line. As a result, if you mix these in a
single file you might get incorrect line numbering, because the
preprocessor would interpret the two-character versions as ending just
one line. Previous implementations would only handle UNIX-style \n
correctly, so DOS-style \r\n would need to be passed through a filter
first.
The first three transformations are done @emph{before} all other parsing The first three transformations are done @emph{before} all other parsing
and before preprocessing directives are recognized. Thus, for example, and before preprocessing directives are recognized. Thus, for example,
...@@ -199,7 +216,7 @@ bar" ...@@ -199,7 +216,7 @@ bar"
is equivalent to @code{"foo\bar"}, not to @code{"foo\\bar"}. To avoid is equivalent to @code{"foo\bar"}, not to @code{"foo\\bar"}. To avoid
having to worry about this, do not use the GNU extension which permits having to worry about this, do not use the GNU extension which permits
multiline strings. Instead, use string constant concatenation: multi-line strings. Instead, use string constant concatenation:
@example @example
"foo\\" "foo\\"
...@@ -208,24 +225,23 @@ multiline strings. Instead, use string constant concatenation: ...@@ -208,24 +225,23 @@ multiline strings. Instead, use string constant concatenation:
Your program will be more portable this way, too. Your program will be more portable this way, too.
There are a few exceptions to all three transformations. There are a few things to note about the above four transformations.
@itemize @bullet @itemize @bullet
@item @item
Comments and predefined macro names (or any macro names, for that Comments and predefined macro names (or any macro names, for that
matter) are not recognized inside the argument of an @samp{#include} matter) are not recognized inside the argument of an @samp{#include}
directive, whether it is delimited with quotes or with @samp{<} and directive, when it is delimited with quotes or with @samp{<} and
@samp{>}. @samp{>}.
@item @item
Comments and predefined macro names are never recognized within a Comments and predefined macro names are never recognized within a
character or string constant. (Strictly speaking, this is the rule, character or string constant.
not an exception, but it is worth noting here anyway.)
@item @item
ISO ``trigraphs'' are converted before backslash-newlines are deleted. ISO ``trigraphs'' are converted before backslash-newlines are deleted.
If you write what looks like a trigraph with a backslash-newline inside, If you write what looks like a trigraph with a backslash-newline inside,
the backslash-newline is deleted as usual, but it is then too late to the backslash-newline is deleted as usual, but it is too late to
recognize the trigraph. recognize the trigraph.
This is relevant only if you use the @samp{-trigraphs} option to enable This is relevant only if you use the @samp{-trigraphs} option to enable
...@@ -2787,7 +2803,7 @@ of the preprocessor may subtly change such behavior or even remove the ...@@ -2787,7 +2803,7 @@ of the preprocessor may subtly change such behavior or even remove the
feature altogether. feature altogether.
Preservation of the form of whitespace between tokens is unlikely to Preservation of the form of whitespace between tokens is unlikely to
change from current behavior (see @ref{Output}), but you are advised not change from current behavior (@ref{Output}), but you are advised not
to rely on it. to rely on it.
The following are undocumented and subject to change:- The following are undocumented and subject to change:-
...@@ -2795,25 +2811,27 @@ The following are undocumented and subject to change:- ...@@ -2795,25 +2811,27 @@ The following are undocumented and subject to change:-
@itemize @bullet @itemize @bullet
@item Interpretation of the filename between @samp{<} and @samp{>} tokens @item Interpretation of the filename between @samp{<} and @samp{>} tokens
resulting from a macro-expanded @samp{#include} directive resulting from a macro-expanded filename in a @samp{#include} directive
The text between the @samp{<} and @samp{>} is taken literally if given The text between the @samp{<} and @samp{>} is taken literally if given
directly within a @samp{#include} or similar directive. If a directive directly within a @samp{#include} or similar directive. If the
of this form is obtained through macro expansion, however, behavior like angle-bracketed filename is obtained through macro expansion, however,
preservation of whitespace, and interpretation of backslashes and quotes preservation of whitespace and interpretation of backslashes and quotes
is undefined. @xref{Include Syntax}. is undefined. @xref{Include Syntax}.
@item Precedence of ## operators with respect to each other @item Precedence of ## operators with respect to each other
It is not defined whether a sequence of ## operators are evaluated Whether a sequence of ## operators is evaluated left-to-right,
left-to-right, right-to-left or indeed in a consistent direction at all. right-to-left or indeed in a consistent direction at all is not
An example of where this might matter is pasting the arguments @samp{1}, specified. An example of where this might matter is pasting the
@samp{e} and @samp{-2}. This would be fine for left-to-right pasting, arguments @samp{1}, @samp{e} and @samp{-2}. This would be fine for
but right-to-left pasting would produce an invalid token @samp{e-2}. left-to-right pasting, but right-to-left pasting would produce an
invalid token @samp{e-2}. It is possible to guarantee precedence by
suitable use of nested macros.
@item Precedence of # operator with respect to the ## operator @item Precedence of # operator with respect to the ## operator
It is undefined which of these two operators is evaluated first. Which of these two operators is evaluated first is not specified.
@end itemize @end itemize
...@@ -3135,7 +3153,9 @@ comment, or whenever a backslash-newline appears in a @samp{//} comment. ...@@ -3135,7 +3153,9 @@ comment, or whenever a backslash-newline appears in a @samp{//} comment.
@item -Wtrigraphs @item -Wtrigraphs
@findex -Wtrigraphs @findex -Wtrigraphs
Warn if any trigraphs are encountered. This option used to take effect Warn if any trigraphs are encountered. This option used to take effect
only if @samp{-trigraphs} was also specified, but now works independently. only if @samp{-trigraphs} was also specified, but now works
independently. Warnings are not given for trigraphs within comments, as
we feel this is obnoxious.
@item -Wwhite-space @item -Wwhite-space
@findex -Wwhite-space @findex -Wwhite-space
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment