/[emacs]/emacs/man/cc-mode.texi
ViewVC logotype

Diff of /emacs/man/cc-mode.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.18.4.3 by uid65618, Sun Dec 28 05:19:58 2003 UTC revision 1.18.4.4 by miles, Tue Jul 6 09:31:24 2004 UTC
# Line 354  Syntactic analysis for indentation is do Line 354  Syntactic analysis for indentation is do
354  indented to the same level as the previous one, and @kbd{TAB}  indented to the same level as the previous one, and @kbd{TAB}
355  (@code{c-indent-command}) adjusts the indentation in steps of  (@code{c-indent-command}) adjusts the indentation in steps of
356  @code{c-basic-offset}.  The indentation style has no effect, nor any of  @code{c-basic-offset}.  The indentation style has no effect, nor any of
357  the indentation associated variables, e.g. @code{c-special-indent-hook}.  the indentation associated variables, e.g., @code{c-special-indent-hook}.
358  @end defopt  @end defopt
359    
360  @menu  @menu
# Line 381  elements (in lisp parlance, a @emph{cons Line 381  elements (in lisp parlance, a @emph{cons
381  a @dfn{syntactic symbol}, the second being a @dfn{relative  a @dfn{syntactic symbol}, the second being a @dfn{relative
382  buffer position}.  Syntactic symbols describe elements of C code  buffer position}.  Syntactic symbols describe elements of C code
383  @footnote{Unless otherwise noted, the term ``C code'' refers to all  @footnote{Unless otherwise noted, the term ``C code'' refers to all
384  the C-like languages.}, e.g. @code{statement}, @code{substatement},  the C-like languages.}, e.g., @code{statement}, @code{substatement},
385  @code{class-open}, @code{class-close}, etc.  @xref{Syntactic Symbols},  @code{class-open}, @code{class-close}, etc.  @xref{Syntactic Symbols},
386  for a complete list of currently recognized syntactic symbols and their  for a complete list of currently recognized syntactic symbols and their
387  semantics.  The style variable @code{c-offsets-alist} also contains the  semantics.  The style variable @code{c-offsets-alist} also contains the
# Line 411  We can use the command @kbd{C-c C-s} (bo Line 411  We can use the command @kbd{C-c C-s} (bo
411  @code{c-show-syntactic-information}) to simply report what the  @code{c-show-syntactic-information}) to simply report what the
412  syntactic analysis is for the current line.  Running this command on  syntactic analysis is for the current line.  Running this command on
413  line 4 of this example, we'd see in the echo area@footnote{With a  line 4 of this example, we'd see in the echo area@footnote{With a
414  universal argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted  universal argument (i.e., @kbd{C-u C-c C-s}) the analysis is inserted
415  into the buffer as a comment on the current line.}:  into the buffer as a comment on the current line.}:
416    
417  @example  @example
# Line 677  definition.  These constructs are also k Line 677  definition.  These constructs are also k
677  whitespace} since they are usually ignored when scanning C code.}.  whitespace} since they are usually ignored when scanning C code.}.
678    
679  @item  @item
680  No numeric argument was supplied to the command (i.e. it was typed as  No numeric argument was supplied to the command (i.e., it was typed as
681  normal, with no @kbd{C-u} prefix).  normal, with no @kbd{C-u} prefix).
682  @end itemize  @end itemize
683    
# Line 702  normal, with no @kbd{C-u} prefix). Line 702  normal, with no @kbd{C-u} prefix).
702  @kindex @{  @kindex @{
703  @kindex @}  @kindex @}
704    
705  When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}),  When you type either an open or close brace (i.e., @kbd{@{} or @kbd{@}}),
706  the electric command @code{c-electric-brace} gets run.  This command has  the electric command @code{c-electric-brace} gets run.  This command has
707  two electric formatting behaviors.  First, it will perform some  two electric formatting behaviors.  First, it will perform some
708  reindentation of the line the brace was typed on, and second, it will  reindentation of the line the brace was typed on, and second, it will
# Line 973  modes except IDL mode, since CORBA IDL d Line 973  modes except IDL mode, since CORBA IDL d
973  @dfn{Clean-ups} are mechanisms complementary to colon and brace hanging.  @dfn{Clean-ups} are mechanisms complementary to colon and brace hanging.
974  On the surface, it would seem that clean-ups overlap the functionality  On the surface, it would seem that clean-ups overlap the functionality
975  provided by the @code{c-hanging-*-alist} variables.  Clean-ups are  provided by the @code{c-hanging-*-alist} variables.  Clean-ups are
976  however used to adjust code ``after-the-fact,'' i.e. to adjust the  however used to adjust code ``after-the-fact,'' i.e., to adjust the
977  whitespace in constructs after they are typed.  whitespace in constructs after they are typed.
978    
979  Most of the clean-ups are only applicable to counteract automatically  Most of the clean-ups are only applicable to counteract automatically
# Line 1146  minor mode: Line 1146  minor mode:
1146  @item space-before-funcall  @item space-before-funcall
1147  Insert a space between the function name and the opening parenthesis of  Insert a space between the function name and the opening parenthesis of
1148  a function call.  This produces function calls in the style mandated by  a function call.  This produces function calls in the style mandated by
1149  the GNU coding standards, e.g. @samp{signal (SIGINT, SIG_IGN)} and  the GNU coding standards, e.g., @samp{signal (SIGINT, SIG_IGN)} and
1150  @samp{abort ()}.  Clean up occurs when the opening parenthesis is typed.  @samp{abort ()}.  Clean up occurs when the opening parenthesis is typed.
1151    
1152  @item compact-empty-funcall  @item compact-empty-funcall
# Line 1154  Clean up any space between the function Line 1154  Clean up any space between the function
1154  of a function call that has no arguments.  This is typically used  of a function call that has no arguments.  This is typically used
1155  together with @code{space-before-funcall} if you prefer the GNU function  together with @code{space-before-funcall} if you prefer the GNU function
1156  call style for functions with arguments but think it looks ugly when  call style for functions with arguments but think it looks ugly when
1157  it's only an empty parenthesis pair.  I.e. you will get @samp{signal  it's only an empty parenthesis pair.  I.e., you will get @samp{signal
1158  (SIGINT, SIG_IGN)}, but @samp{abort()}.  Clean up occurs when the  (SIGINT, SIG_IGN)}, but @samp{abort()}.  Clean up occurs when the
1159  closing parenthesis is typed.  closing parenthesis is typed.
1160  @end table  @end table
# Line 1278  whether hungry-delete mode is enabled or Line 1278  whether hungry-delete mode is enabled or
1278    
1279  Since there's a lot of normal text in comments and string literals,  Since there's a lot of normal text in comments and string literals,
1280  @ccmode{} provides features to edit these like in text mode.  The goal  @ccmode{} provides features to edit these like in text mode.  The goal
1281  is to do it as seamlessly as possible, i.e. you can use auto fill mode,  is to do it as seamlessly as possible, i.e., you can use auto fill mode,
1282  sentence and paragraph movement, paragraph filling, adaptive filling etc  sentence and paragraph movement, paragraph filling, adaptive filling etc
1283  wherever there's a piece of normal text without having to think much  wherever there's a piece of normal text without having to think much
1284  about it.  @ccmode{} should keep the indentation, fix the comment line  about it.  @ccmode{} should keep the indentation, fix the comment line
# Line 1333  like Line 1333  like
1333  @noindent  @noindent
1334  with zero or more stars at the beginning of every line.  If you change  with zero or more stars at the beginning of every line.  If you change
1335  this variable, please make sure it still matches the comment starter  this variable, please make sure it still matches the comment starter
1336  (i.e. @code{//}) of line comments @emph{and} the line prefix inside  (i.e., @code{//}) of line comments @emph{and} the line prefix inside
1337  block comments.  block comments.
1338    
1339  @findex c-setup-paragraph-variables  @findex c-setup-paragraph-variables
# Line 1352  mode hook, since @ccmode{} sets up all v Line 1352  mode hook, since @ccmode{} sets up all v
1352  @cindex paragraph filling  @cindex paragraph filling
1353  Line breaks are by default handled (almost) the same regardless whether  Line breaks are by default handled (almost) the same regardless whether
1354  they are made by auto fill mode (@pxref{Auto Fill,,, emacs, The Emacs  they are made by auto fill mode (@pxref{Auto Fill,,, emacs, The Emacs
1355  Editor}), paragraph filling (e.g. with @kbd{M-q}), or explicitly with  Editor}), paragraph filling (e.g., with @kbd{M-q}), or explicitly with
1356  @kbd{M-j} or similar methods.  In string literals, the new line gets the  @kbd{M-j} or similar methods.  In string literals, the new line gets the
1357  same indentation as the previous nonempty line (may be changed with the  same indentation as the previous nonempty line (may be changed with the
1358  @code{string} syntactic symbol).  In comments, @ccmode{} uses  @code{string} syntactic symbol).  In comments, @ccmode{} uses
# Line 1364  lines in the comment. Line 1364  lines in the comment.
1364  @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, The  @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, The
1365  Emacs Editor}) to make Emacs correctly keep the line prefix when filling  Emacs Editor}) to make Emacs correctly keep the line prefix when filling
1366  paragraphs.  That also makes Emacs preserve the text indentation  paragraphs.  That also makes Emacs preserve the text indentation
1367  @emph{inside} the comment line prefix.  E.g. in the following comment,  @emph{inside} the comment line prefix.  e.g., in the following comment,
1368  both paragraphs will be filled with the left margins of the texts kept  both paragraphs will be filled with the left margins of the texts kept
1369  intact:  intact:
1370    
# Line 1394  by default).  A patch for that is availa Line 1394  by default).  A patch for that is availa
1394  @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},  @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.},
1395  which handles things like bulleted lists nicely.  There's a convenience  which handles things like bulleted lists nicely.  There's a convenience
1396  function @code{c-setup-filladapt} that tunes the relevant variables in  function @code{c-setup-filladapt} that tunes the relevant variables in
1397  Filladapt for use in @ccmode{}.  Call it from a mode hook, e.g. with  Filladapt for use in @ccmode{}.  Call it from a mode hook, e.g., with
1398  something like this in your @file{.emacs}:  something like this in your @file{.emacs}:
1399    
1400  @example  @example
# Line 1443  most common comment styles, see @ref{Ind Line 1443  most common comment styles, see @ref{Ind
1443  @defopt c-ignore-auto-fill  @defopt c-ignore-auto-fill
1444  @vindex ignore-auto-fill (c-)  @vindex ignore-auto-fill (c-)
1445  When auto fill mode is enabled, @ccmode{} can selectively ignore it  When auto fill mode is enabled, @ccmode{} can selectively ignore it
1446  depending on the context the line break would occur in, e.g. to never  depending on the context the line break would occur in, e.g., to never
1447  break a line automatically inside a string literal.  This variable  break a line automatically inside a string literal.  This variable
1448  takes a list of symbols for the different contexts where auto-filling  takes a list of symbols for the different contexts where auto-filling
1449  never should occur:  never should occur:
# Line 1458  Inside a C++ style line comment. Line 1458  Inside a C++ style line comment.
1458  @item cpp  @item cpp
1459  Inside a preprocessor directive.  Inside a preprocessor directive.
1460  @item code  @item code
1461  Anywhere else, i.e. in normal code.  Anywhere else, i.e., in normal code.
1462  @end table  @end table
1463    
1464  By default, @code{c-ignore-auto-fill} is set to @code{'(string cpp  By default, @code{c-ignore-auto-fill} is set to @code{'(string cpp
# Line 1514  Note that @ccmode{} sets @code{comment-m Line 1514  Note that @ccmode{} sets @code{comment-m
1514  startup.  The reason is that @kbd{M-j} could otherwise produce sequences  startup.  The reason is that @kbd{M-j} could otherwise produce sequences
1515  of single line block comments for texts that should logically be treated  of single line block comments for texts that should logically be treated
1516  as one comment, and the rest of the paragraph handling code  as one comment, and the rest of the paragraph handling code
1517  (e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to  (e.g., @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to
1518  inconsistent behavior.  inconsistent behavior.
1519    
1520  @item @kbd{M-x c-context-line-break}  @item @kbd{M-x c-context-line-break}
# Line 1523  inconsistent behavior. Line 1523  inconsistent behavior.
1523  This is a function that works like @code{indent-new-comment-line} in  This is a function that works like @code{indent-new-comment-line} in
1524  comments and @code{newline-and-indent} elsewhere, thus combining those  comments and @code{newline-and-indent} elsewhere, thus combining those
1525  two in a way that uses each one in the context it's best suited for.  two in a way that uses each one in the context it's best suited for.
1526  I.e. in comments the comment line prefix and indentation is kept for  I.e., in comments the comment line prefix and indentation is kept for
1527  the new line, and in normal code it's indented according to context by  the new line, and in normal code it's indented according to context by
1528  the indentation engine.  the indentation engine.
1529    
# Line 1540  It's not bound to a key by default, but Line 1540  It's not bound to a key by default, but
1540  @findex c-context-open-line  @findex c-context-open-line
1541  @findex context-open-line (c-)  @findex context-open-line (c-)
1542  This is to @kbd{C-o} (@kbd{M-x open-line}) as  This is to @kbd{C-o} (@kbd{M-x open-line}) as
1543  @code{c-context-line-break} is to @kbd{RET}.  I.e. it works just like  @code{c-context-line-break} is to @kbd{RET}.  I.e., it works just like
1544  @code{c-context-line-break} but leaves the point before the inserted  @code{c-context-line-break} but leaves the point before the inserted
1545  line break.  line break.
1546  @end table  @end table
# Line 1555  line break. Line 1555  line break.
1555  @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!  @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1556    
1557  Preprocessor directives are handled as syntactic whitespace from other  Preprocessor directives are handled as syntactic whitespace from other
1558  code, i.e. they can be interspersed anywhere without affecting the  code, i.e., they can be interspersed anywhere without affecting the
1559  syntactic analysis, just like comments.  syntactic analysis, just like comments.
1560    
1561  The code inside macro definitions is still analyzed syntactically so  The code inside macro definitions is still analyzed syntactically so
1562  that you get relative indentation there just as you'd get if the same  that you get relative indentation there just as you'd get if the same
1563  code was outside a macro.  However, since there is no hint about the  code was outside a macro.  However, since there is no hint about the
1564  syntactic context, i.e. whether the macro expands to an expression, to some  syntactic context, i.e., whether the macro expands to an expression, to some
1565  statements, or perhaps to whole functions, the syntactic recognition can be  statements, or perhaps to whole functions, the syntactic recognition can be
1566  wrong.  @ccmode{} manages to figure it out correctly most of the time,  wrong.  @ccmode{} manages to figure it out correctly most of the time,
1567  though.  @xref{Syntactic Symbols}, for details about the indentation.  though.  @xref{Syntactic Symbols}, for details about the indentation.
# Line 1601  the region ends at the start of a line, Line 1601  the region ends at the start of a line,
1601  These variables control the alignment columns for line continuation  These variables control the alignment columns for line continuation
1602  backslashes in multiline macros.  They are used by the functions that  backslashes in multiline macros.  They are used by the functions that
1603  automatically insert or align such backslashes,  automatically insert or align such backslashes,
1604  e.g. @code{c-backslash-region} and @code{c-context-line-break}.  e.g., @code{c-backslash-region} and @code{c-context-line-break}.
1605    
1606  @code{c-backslash-column} specifies the minimum column for the  @code{c-backslash-column} specifies the minimum column for the
1607  backslashes.  If any line in the macro exceeds it then the next tab  backslashes.  If any line in the macro exceeds it then the next tab
# Line 1616  lines which are too long ``stick out'' i Line 1616  lines which are too long ``stick out'' i
1616  @vindex auto-align-backslashes (c-)  @vindex auto-align-backslashes (c-)
1617  Align automatically inserted line continuation backslashes if  Align automatically inserted line continuation backslashes if
1618  non-@code{nil}.  When line continuation backslashes are inserted  non-@code{nil}.  When line continuation backslashes are inserted
1619  automatically for line breaks in multiline macros, e.g. by  automatically for line breaks in multiline macros, e.g., by
1620  @code{c-context-line-break}, they are aligned with the other backslashes  @code{c-context-line-break}, they are aligned with the other backslashes
1621  in the same macro if this flag is set.  Otherwise the inserted  in the same macro if this flag is set.  Otherwise the inserted
1622  backslashes are preceded by a single space.  backslashes are preceded by a single space.
# Line 1738  additional regexps to match those you us Line 1738  additional regexps to match those you us
1738  For each language there's a variable @code{*-font-lock-extra-types},  For each language there's a variable @code{*-font-lock-extra-types},
1739  where @samp{*} stands for the language in question.  It contains a list  where @samp{*} stands for the language in question.  It contains a list
1740  of regexps that matches identifiers that should be recognized as types,  of regexps that matches identifiers that should be recognized as types,
1741  e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}  e.g., @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t}
1742  as is customary in C code.  Each regexp should not match more than a  as is customary in C code.  Each regexp should not match more than a
1743  single identifier.  single identifier.
1744    
# Line 1835  labels. Line 1835  labels.
1835  @vindex font-lock-builtin-face  @vindex font-lock-builtin-face
1836  @vindex font-lock-reference-face  @vindex font-lock-reference-face
1837  Preprocessor directives get @code{font-lock-preprocessor-face} if it  Preprocessor directives get @code{font-lock-preprocessor-face} if it
1838  exists (i.e. XEmacs).  In Emacs they get @code{font-lock-builtin-face}  exists (i.e., XEmacs).  In Emacs they get @code{font-lock-builtin-face}
1839  or @code{font-lock-reference-face}, for lack of a closer equivalent.  or @code{font-lock-reference-face}, for lack of a closer equivalent.
1840    
1841  @item  @item
# Line 1861  since those aren't syntactic errors in t Line 1861  since those aren't syntactic errors in t
1861  @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!  @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1862    
1863  There are various tools to supply documentation in the source as  There are various tools to supply documentation in the source as
1864  specially structured comments, e.g. the standard Javadoc tool in Java.  specially structured comments, e.g., the standard Javadoc tool in Java.
1865  @ccmode{} provides an extensible mechanism to fontify such comments and  @ccmode{} provides an extensible mechanism to fontify such comments and
1866  the special markup inside them.  the special markup inside them.
1867    
1868  @defopt c-doc-comment-style  @defopt c-doc-comment-style
1869  @vindex doc-comment-style (c-)  @vindex doc-comment-style (c-)
1870  This is a style variable that specifies which documentation comment  This is a style variable that specifies which documentation comment
1871  style to recognize, e.g. @code{javadoc} for Javadoc comments.  style to recognize, e.g., @code{javadoc} for Javadoc comments.
1872    
1873  The value may also be a list of styles, in which case all of them are  The value may also be a list of styles, in which case all of them are
1874  recognized simultaneously (presumably with markup cues that don't  recognized simultaneously (presumably with markup cues that don't
# Line 1883  and its value is used instead. Line 1883  and its value is used instead.
1883  Note that @ccmode{} uses this variable to set other variables that  Note that @ccmode{} uses this variable to set other variables that
1884  handle fontification etc.  That's done at mode initialization or when  handle fontification etc.  That's done at mode initialization or when
1885  you switch to a style which sets this variable.  Thus, if you change it  you switch to a style which sets this variable.  Thus, if you change it
1886  in some other way, e.g. interactively in a CC Mode buffer, you will need  in some other way, e.g., interactively in a CC Mode buffer, you will need
1887  to do @kbd{M-x java-mode} (or whatever mode you're currently using) to  to do @kbd{M-x java-mode} (or whatever mode you're currently using) to
1888  reinitialize.  reinitialize.
1889    
# Line 1993  Indents the entire top-level function, c Line 1993  Indents the entire top-level function, c
1993  encompassing point.  It leaves point unchanged.  This function can't be  encompassing point.  It leaves point unchanged.  This function can't be
1994  used to reindent a nested brace construct, such as a nested class or  used to reindent a nested brace construct, such as a nested class or
1995  function, or a Java method.  The top-level construct being reindented  function, or a Java method.  The top-level construct being reindented
1996  must be complete, i.e. it must have both a beginning brace and an ending  must be complete, i.e., it must have both a beginning brace and an ending
1997  brace.  brace.
1998    
1999  @item @kbd{C-M-\} (@code{indent-region})  @item @kbd{C-M-\} (@code{indent-region})
# Line 2239  whether to do sentence motion in or near Line 2239  whether to do sentence motion in or near
2239  A popular programming style, especially for object-oriented languages  A popular programming style, especially for object-oriented languages
2240  such as C++ is to write symbols in a mixed case format, where the first  such as C++ is to write symbols in a mixed case format, where the first
2241  letter of each word is capitalized, and not separated by underscores.  letter of each word is capitalized, and not separated by underscores.
2242  E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}.  e.g., @samp{SymbolsWithMixedCaseAndNoUnderlines}.
2243    
2244  This command moves point forward to next capitalized word.  With prefix  This command moves point forward to next capitalized word.  With prefix
2245  argument @var{n}, move @var{n} times.  argument @var{n}, move @var{n} times.
# Line 2295  styles. Line 2295  styles.
2295  Only syntactic symbols not already bound on @code{c-offsets-alist} will  Only syntactic symbols not already bound on @code{c-offsets-alist} will
2296  be set from styles.  This means that any association you set on it, be  be set from styles.  This means that any association you set on it, be
2297  it before or after mode initialization, will not be changed.  The  it before or after mode initialization, will not be changed.  The
2298  @code{c-offsets-alist} variable may therefore be used from e.g. the  @code{c-offsets-alist} variable may therefore be used from e.g., the
2299  Customization interface@footnote{Available in Emacs 20 and later, and  Customization interface@footnote{Available in Emacs 20 and later, and
2300  XEmacs 19.15 and later.} to easily change indentation offsets without  XEmacs 19.15 and later.} to easily change indentation offsets without
2301  having to bother about styles.  Initially @code{c-offsets-alist} is  having to bother about styles.  Initially @code{c-offsets-alist} is
# Line 2563  this manual does not cover how that work Line 2563  this manual does not cover how that work
2563    
2564  Variables set like this at the top level in @file{.emacs} take effect in  Variables set like this at the top level in @file{.emacs} take effect in
2565  all @ccmode{} buffers, regardless of language.  The indentation style  all @ccmode{} buffers, regardless of language.  The indentation style
2566  related variables, e.g. @code{c-offsets-alist}, that you don't set this  related variables, e.g., @code{c-offsets-alist}, that you don't set this
2567  way get their value from the style system (@pxref{Styles}), and they  way get their value from the style system (@pxref{Styles}), and they
2568  therefore depend on the setting of @code{c-default-style}.  Note that if  therefore depend on the setting of @code{c-default-style}.  Note that if
2569  you use Customize, this means that the greyed-out default values  you use Customize, this means that the greyed-out default values
# Line 2571  presented there might not be the ones yo Line 2571  presented there might not be the ones yo
2571  values depend on the style, which may very well be different for  values depend on the style, which may very well be different for
2572  different languages.  different languages.
2573    
2574  If you want to make more advanced configurations, e.g. language-specific  If you want to make more advanced configurations, e.g., language-specific
2575  customization, setting global variables isn't enough.  For that you can  customization, setting global variables isn't enough.  For that you can
2576  use the language hooks, see @ref{Hooks}, and/or the style system, see  use the language hooks, see @ref{Hooks}, and/or the style system, see
2577  @ref{Styles}.  @ref{Styles}.
# Line 2940  This variable takes an association list Line 2940  This variable takes an association list
2940  automatically institute these offsets using @code{c-set-offset}.  automatically institute these offsets using @code{c-set-offset}.
2941  @end defvar  @end defvar
2942    
2943  Note that file style settings (i.e. @code{c-file-style}) are applied  Note that file style settings (i.e., @code{c-file-style}) are applied
2944  before file offset settings (i.e. @code{c-file-offsets}).  Also, if  before file offset settings (i.e., @code{c-file-offsets}).  Also, if
2945  either of these are set in a file's local variable section, all the  either of these are set in a file's local variable section, all the
2946  style variable values are made local to that buffer.  style variable values are made local to that buffer.
2947    
# Line 3086  These @var{action} functions are called Line 3086  These @var{action} functions are called
3086  syntactic symbol for the brace, and the buffer position at which the  syntactic symbol for the brace, and the buffer position at which the
3087  brace was inserted.  The @var{action} function is expected to return a  brace was inserted.  The @var{action} function is expected to return a
3088  list containing some combination of @code{before} and @code{after},  list containing some combination of @code{before} and @code{after},
3089  including neither of them (i.e. @code{nil}).  This return value has the  including neither of them (i.e., @code{nil}).  This return value has the
3090  normal brace hanging semantics.  normal brace hanging semantics.
3091    
3092  As an example, @ccmode{} itself uses this feature to dynamically  As an example, @ccmode{} itself uses this feature to dynamically
# Line 3181  No determination is made, and the next f Line 3181  No determination is made, and the next f
3181  If every function in the list is called without a determination being  If every function in the list is called without a determination being
3182  made, then no newline is added. The default value for this variable is a  made, then no newline is added. The default value for this variable is a
3183  list containing a single function which inserts newlines only after  list containing a single function which inserts newlines only after
3184  semicolons which do not appear inside parenthesis lists (i.e. those  semicolons which do not appear inside parenthesis lists (i.e., those
3185  that separate @code{for}-clause statements).  that separate @code{for}-clause statements).
3186  @end defopt  @end defopt
3187    
# Line 3215  statements.  In addition to Line 3215  statements.  In addition to
3215  @ccmode{} also comes with the criteria function  @ccmode{} also comes with the criteria function
3216  @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses  @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses
3217  newlines after semicolons inside one-line inline method definitions  newlines after semicolons inside one-line inline method definitions
3218  (e.g. in C++ or Java).  (e.g., in C++ or Java).
3219  @end defun  @end defun
3220    
3221    
# Line 3242  every line is indented by @ccmode{}.  Yo Line 3242  every line is indented by @ccmode{}.  Yo
3242  indentation or line adjustments your style dictates, such as adding  indentation or line adjustments your style dictates, such as adding
3243  extra indentation to constructors or destructor declarations in a  extra indentation to constructors or destructor declarations in a
3244  class definition, etc.  Note that you should not change point or mark  class definition, etc.  Note that you should not change point or mark
3245  inside your @code{c-special-indent-hook} functions, i.e. you'll  inside your @code{c-special-indent-hook} functions, i.e., you'll
3246  probably want to wrap your function in a @code{save-excursion}.  probably want to wrap your function in a @code{save-excursion}.
3247    
3248  Setting @code{c-special-indent-hook} in your style definition is  Setting @code{c-special-indent-hook} in your style definition is
# Line 3388  Lines continuing an Objective-C method d Line 3388  Lines continuing an Objective-C method d
3388  @item objc-method-call-cont  @item objc-method-call-cont
3389  Lines continuing an Objective-C method call.  Lines continuing an Objective-C method call.
3390  @item extern-lang-open  @item extern-lang-open
3391  Brace that opens an @code{extern} block (e.g. @code{extern "C" @{...@}}).  Brace that opens an @code{extern} block (e.g., @code{extern "C" @{...@}}).
3392  @item extern-lang-close  @item extern-lang-close
3393  Brace that closes an @code{extern} block.  Brace that closes an @code{extern} block.
3394  @item inextern-lang  @item inextern-lang
# Line 3411  Analogous to the above, but for CORBA CI Line 3411  Analogous to the above, but for CORBA CI
3411  C++ template argument list continuations.  C++ template argument list continuations.
3412  @item inlambda  @item inlambda
3413  Analogous to @code{inclass} syntactic symbol, but used inside lambda  Analogous to @code{inclass} syntactic symbol, but used inside lambda
3414  (i.e. anonymous) functions.  Only used in Pike mode.  (i.e., anonymous) functions.  Only used in Pike mode.
3415  @item lambda-intro-cont  @item lambda-intro-cont
3416  Lines continuing the header of a lambda function, i.e. between the  Lines continuing the header of a lambda function, i.e., between the
3417  @code{lambda} keyword and the function body.  Only used in Pike mode.  @code{lambda} keyword and the function body.  Only used in Pike mode.
3418  @item inexpr-statement  @item inexpr-statement
3419  A statement block inside an expression.  The gcc C extension of this is  A statement block inside an expression.  The gcc C extension of this is
# Line 3468  top-level construct introduction so it h Line 3468  top-level construct introduction so it h
3468  the brace that opens a top-level function definition.  Line 9 is the  the brace that opens a top-level function definition.  Line 9 is the
3469  corresponding  corresponding
3470  @code{defun-close} since it contains the brace that closes the top-level  @code{defun-close} since it contains the brace that closes the top-level
3471  function definition.  Line 4 is a @code{defun-block-intro}, i.e. it is  function definition.  Line 4 is a @code{defun-block-intro}, i.e., it is
3472  the first line of a brace-block, enclosed in a  the first line of a brace-block, enclosed in a
3473  top-level function definition.  top-level function definition.
3474    
# Line 3793  where @code{inextern-lang} is a modifier Line 3793  where @code{inextern-lang} is a modifier
3793    
3794  There are various other top level blocks like @code{extern}, and they  There are various other top level blocks like @code{extern}, and they
3795  are all treated in the same way except that the symbols are named after  are all treated in the same way except that the symbols are named after
3796  the keyword that introduces the block.  E.g. C++ namespace blocks get  the keyword that introduces the block.  e.g., C++ namespace blocks get
3797  the three symbols @code{namespace-open}, @code{namespace-close} and  the three symbols @code{namespace-open}, @code{namespace-close} and
3798  @code{innamespace}.  The currently recognized top level blocks are:  @code{innamespace}.  The currently recognized top level blocks are:
3799    
# Line 3950  Line 17 is assigned @code{stream-op} syn Line 3950  Line 17 is assigned @code{stream-op} syn
3950  @cindex syntactic whitespace  @cindex syntactic whitespace
3951  @ssindex cpp-define-intro  @ssindex cpp-define-intro
3952  Multiline preprocessor macro definitions are normally handled just like  Multiline preprocessor macro definitions are normally handled just like
3953  other code, i.e. the lines inside them are indented according to the  other code, i.e., the lines inside them are indented according to the
3954  syntactic analysis of the preceding lines inside the macro.  The first  syntactic analysis of the preceding lines inside the macro.  The first
3955  line inside a macro definition (i.e. the line after the starting line of  line inside a macro definition (i.e., the line after the starting line of
3956  the cpp directive itself) gets @code{cpp-define-intro}.  In this example:  the cpp directive itself) gets @code{cpp-define-intro}.  In this example:
3957    
3958  @example  @example
# Line 3968  line 1 is given the syntactic symbol @co Line 3968  line 1 is given the syntactic symbol @co
3968  of a cpp directive is always given that symbol.  Line 2 is given  of a cpp directive is always given that symbol.  Line 2 is given
3969  @code{cpp-define-intro}, so that you can give the macro body as a whole  @code{cpp-define-intro}, so that you can give the macro body as a whole
3970  some extra indentation.  Lines 3 through 5 are then analyzed as normal  some extra indentation.  Lines 3 through 5 are then analyzed as normal
3971  code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause}  code, i.e., @code{substatement} on lines 3 and 4, and @code{else-clause}
3972  on line 5.  on line 5.
3973    
3974  The syntactic analysis inside macros can be turned off with  The syntactic analysis inside macros can be turned off with
# Line 4094  code @footnote{a.k.a. K&R C, or Kernigha Line 4094  code @footnote{a.k.a. K&R C, or Kernigha
4094    
4095  Here, line 2 is the first line in an argument declaration list and so is  Here, line 2 is the first line in an argument declaration list and so is
4096  given the @code{knr-argdecl-intro} syntactic symbol.  Subsequent lines  given the @code{knr-argdecl-intro} syntactic symbol.  Subsequent lines
4097  (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl}  (i.e., lines 3 and 4 in this example), are given @code{knr-argdecl}
4098  syntax.  syntax.
4099    
4100    
# Line 4322  if (  x < 10 Line 4322  if (  x < 10
4322    
4323  Since this function doesn't do anything for lines without an infix  Since this function doesn't do anything for lines without an infix
4324  operator you typically want to use it together with some other lineup  operator you typically want to use it together with some other lineup
4325  settings, e.g. as follows (the @code{arglist-close} setting is just a  settings, e.g., as follows (the @code{arglist-close} setting is just a
4326  suggestion to get a consistent style):  suggestion to get a consistent style):
4327    
4328  @example  @example
# Line 4383  to handle most of the common comment sty Line 4383  to handle most of the common comment sty
4383  @end example  @end example
4384    
4385  The style variable @code{c-comment-prefix-regexp} is used to recognize  The style variable @code{c-comment-prefix-regexp} is used to recognize
4386  the comment line prefix, e.g. the @samp{*} that usually starts every  the comment line prefix, e.g., the @samp{*} that usually starts every
4387  line inside a comment.  line inside a comment.
4388    
4389  @workswith The @code{c} syntactic symbol.  @workswith The @code{c} syntactic symbol.
# Line 4512  int dribble() @{ Line 4512  int dribble() @{
4512    
4513  If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the  If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the
4514  function returns the relative indentation to the macro start line to  function returns the relative indentation to the macro start line to
4515  allow accumulation with other offsets.  E.g. in the following cases,  allow accumulation with other offsets.  e.g., in the following cases,
4516  @code{cpp-define-intro} is combined with the  @code{cpp-define-intro} is combined with the
4517  @code{statement-block-intro} that comes from the @samp{do @{} that hangs  @code{statement-block-intro} that comes from the @samp{do @{} that hangs
4518  on the @samp{#define} line:  on the @samp{#define} line:
# Line 4611  arglist lineups, e.g. Line 4611  arglist lineups, e.g.
4611  @defun c-lineup-inexpr-block  @defun c-lineup-inexpr-block
4612  @findex lineup-inexpr-block (c-)  @findex lineup-inexpr-block (c-)
4613  This can be used with the in-expression block symbols to indent the  This can be used with the in-expression block symbols to indent the
4614  whole block to the column where the construct is started.  E.g. for Java  whole block to the column where the construct is started.  e.g., for Java
4615  anonymous classes, this lines up the class under the @samp{new} keyword,  anonymous classes, this lines up the class under the @samp{new} keyword,
4616  and in Pike it lines up the lambda function body under the @samp{lambda}  and in Pike it lines up the lambda function body under the @samp{lambda}
4617  keyword.  Returns @code{nil} if the block isn't part of such a  keyword.  Returns @code{nil} if the block isn't part of such a
# Line 4828  expressions. Line 4828  expressions.
4828    
4829  @defun c-lineup-streamop  @defun c-lineup-streamop
4830  @findex lineup-streamop (c-)  @findex lineup-streamop (c-)
4831  Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}).  Line up C++ stream operators (i.e., @samp{<<} and @samp{>>}).
4832    
4833  @workswith @code{stream-op}.  @workswith @code{stream-op}.
4834  @end defun  @end defun
# Line 4956  In the first case the indentation is kep Line 4956  In the first case the indentation is kep
4956  @workswith @code{defun-close}, @code{defun-block-intro},  @workswith @code{defun-close}, @code{defun-block-intro},
4957  @code{block-close}, @code{brace-list-close}, @code{brace-list-intro},  @code{block-close}, @code{brace-list-close}, @code{brace-list-intro},
4958  @code{statement-block-intro} and all @code{in*} symbols,  @code{statement-block-intro} and all @code{in*} symbols,
4959  e.g. @code{inclass} and @code{inextern-lang}.  e.g., @code{inclass} and @code{inextern-lang}.
4960  @end defun  @end defun
4961    
4962    
# Line 5050  pairs.  See @ref{AWK Mode Defuns} for a Line 5050  pairs.  See @ref{AWK Mode Defuns} for a
5050  work on AWK ``defuns''.  work on AWK ``defuns''.
5051    
5052  Since there is no preprocessor in AWK, the commands which move to  Since there is no preprocessor in AWK, the commands which move to
5053  preprocessor directives (e.g. @code{c-up-conditional}) are meaningless  preprocessor directives (e.g., @code{c-up-conditional}) are meaningless
5054  in AWK mode and are not bound in the AWK mode keymap.  in AWK mode and are not bound in the AWK mode keymap.
5055    
5056  @item Auto-newline Insertion and Clean-ups  @item Auto-newline Insertion and Clean-ups
# Line 5230  present on the association list, CC Mode Line 5230  present on the association list, CC Mode
5230    
5231  The default is to set @code{require-final-newline} to @code{t} in the  The default is to set @code{require-final-newline} to @code{t} in the
5232  languages that mandates that source files should end with newlines,  languages that mandates that source files should end with newlines,
5233  i.e. C, C++ and Objective-C.  i.e., C, C++ and Objective-C.
5234  @end defopt  @end defopt
5235    
5236  @defopt c-echo-syntactic-information-p  @defopt c-echo-syntactic-information-p
# Line 5271  pathological code can cause @ccmode{} to Line 5271  pathological code can cause @ccmode{} to
5271  section gives some insight in how @ccmode{} operates, how that interacts  section gives some insight in how @ccmode{} operates, how that interacts
5272  with some coding styles, and what you can use to improve performance.  with some coding styles, and what you can use to improve performance.
5273    
5274  The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take  The overall goal is that @ccmode{} shouldn't be overly slow (i.e., take
5275  more than a fraction of a second) in any interactive operation.  more than a fraction of a second) in any interactive operation.
5276  I.e. it's tuned to limit the maximum response time in single operations,  i.e., it's tuned to limit the maximum response time in single operations,
5277  which sometimes is at the expense of batch-like operations like  which sometimes is at the expense of batch-like operations like
5278  reindenting whole blocks.  If you find that @ccmode{} gradually gets  reindenting whole blocks.  If you find that @ccmode{} gradually gets
5279  slower and slower in certain situations, perhaps as the file grows in  slower and slower in certain situations, perhaps as the file grows in
# Line 5292  gets. Line 5292  gets.
5292  @findex beginning-of-defun  @findex beginning-of-defun
5293  @findex defun-prompt-regexp  @findex defun-prompt-regexp
5294  One of the simplest things you can do to reduce scan time, is make sure  One of the simplest things you can do to reduce scan time, is make sure
5295  any brace that opens a top-level construct@footnote{E.g. a function in  any brace that opens a top-level construct@footnote{e.g., a function in
5296  C, or outermost class definition in C++ or Java.} always appears in the  C, or outermost class definition in C++ or Java.} always appears in the
5297  leftmost column.  This is actually an Emacs constraint, as embodied in  leftmost column.  This is actually an Emacs constraint, as embodied in
5298  the @code{beginning-of-defun} function which @ccmode{} uses heavily.  If  the @code{beginning-of-defun} function which @ccmode{} uses heavily.  If
# Line 5334  XEmacs users can set the variable Line 5334  XEmacs users can set the variable
5334  tells @ccmode{} to use XEmacs-specific built-in functions which, in some  tells @ccmode{} to use XEmacs-specific built-in functions which, in some
5335  circumstances, can locate the top-most opening brace much more quickly than  circumstances, can locate the top-most opening brace much more quickly than
5336  @code{beginning-of-defun}.  Preliminary testing has shown that for  @code{beginning-of-defun}.  Preliminary testing has shown that for
5337  styles where these braces are hung (e.g. most JDK-derived Java styles),  styles where these braces are hung (e.g., most JDK-derived Java styles),
5338  this hack can improve performance of the core syntax parsing routines  this hack can improve performance of the core syntax parsing routines
5339  from 3 to 60 times.  However, for styles which @emph{do} conform to  from 3 to 60 times.  However, for styles which @emph{do} conform to
5340  Emacs' recommended style of putting top-level braces in column zero,  Emacs' recommended style of putting top-level braces in column zero,
# Line 5345  in Emacs since the necessary built-in fu Line 5345  in Emacs since the necessary built-in fu
5345  21.3 as of this writing in May 2003).  21.3 as of this writing in May 2003).
5346    
5347  Text properties are used to speed up skipping over syntactic whitespace,  Text properties are used to speed up skipping over syntactic whitespace,
5348  i.e. comments and preprocessor directives.  Indenting a line after a  i.e., comments and preprocessor directives.  Indenting a line after a
5349  huge macro definition can be slow the first time, but after that the  huge macro definition can be slow the first time, but after that the
5350  text properties are in place and it should be fast (even after you've  text properties are in place and it should be fast (even after you've
5351  edited other parts of the file and then moved back).  edited other parts of the file and then moved back).
# Line 5353  edited other parts of the file and then Line 5353  edited other parts of the file and then
5353  Font locking can be a CPU hog, especially the font locking done on  Font locking can be a CPU hog, especially the font locking done on
5354  decoration level 3 which tries to be very accurate.  Note that that  decoration level 3 which tries to be very accurate.  Note that that
5355  level is designed to be used with a font lock support mode that only  level is designed to be used with a font lock support mode that only
5356  fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time  fontifies the text that's actually shown, i.e., Lazy Lock or Just-in-time
5357  Lock mode, so make sure you use one of them.  Fontification of a whole  Lock mode, so make sure you use one of them.  Fontification of a whole
5358  buffer with some thousand lines can often take over a minute.  That is  buffer with some thousand lines can often take over a minute.  That is
5359  a known weakness; the idea is that it never should happen.  a known weakness; the idea is that it never should happen.
# Line 5386  geared to be used interactively to edit Line 5386  geared to be used interactively to edit
5386  intention to change this goal.  intention to change this goal.
5387    
5388  If you want to reformat old code, you're probably better off using some  If you want to reformat old code, you're probably better off using some
5389  other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent'  other tool instead, e.g., @ref{Top, , GNU indent, indent, The `indent'
5390  Manual}, which has more powerful reformatting capabilities than  Manual}, which has more powerful reformatting capabilities than
5391  @ccmode{}.  @ccmode{}.
5392    
# Line 5526  to include any code that appears @emph{b Line 5526  to include any code that appears @emph{b
5526  you think it might affect our ability to reproduce it.  you think it might affect our ability to reproduce it.
5527    
5528  Please try to produce the problem in an Emacs instance without any  Please try to produce the problem in an Emacs instance without any
5529  customizations loaded (i.e. start it with the @code{-q -no-site-file}  customizations loaded (i.e., start it with the @samp{-q --no-site-file}
5530  arguments).  If it works correctly there, the problem might be caused by  arguments).  If it works correctly there, the problem might be caused by
5531  faulty customizations in either your own or your site configuration.  In  faulty customizations in either your own or your site configuration.  In
5532  that case, we'd appreciate if you isolate the Emacs Lisp code that trigs  that case, we'd appreciate if you isolate the Emacs Lisp code that trigs

Legend:
Removed from v.1.18.4.3  
changed lines
  Added in v.1.18.4.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26