From: Miles Bader Date: Thu, 11 Oct 2007 16:14:00 +0000 (+0000) Subject: Merge from emacs--devo--0 X-Git-Tag: emacs-pretest-23.0.90~8295^2~320 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=ecb21060d5c1752d41d7a742be565c59b5fcb855;p=emacs.git Merge from emacs--devo--0 Patches applied: * emacs--devo--0 (patch 866-879) - Merge multi-tty branch - Update from CVS - Merge from emacs--rel--22 Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-257 --- ecb21060d5c1752d41d7a742be565c59b5fcb855 diff --cc configure index c8382e4bf2c,e90fb524bb5..8d5e5c98f8c --- a/configure +++ b/configure @@@ -1324,12 -1317,13 +1324,14 @@@ if test -n "$ac_init_help"; the Optional Features: --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE[=ARG] include FEATURE [ARG=yes] - --enable-carbon-app[=DIR] [DIR=/Application] + --enable-carbon-app[=DIR] specify install directory for Emacs.app on Mac OS X + [DIR=/Application] + --enable-font-backend compile code of font-backend support --enable-asserts compile code with asserts enabled - --enable-maintainer-mode enable make rules and dependencies not useful - (and sometimes confusing) to the casual installer + --enable-maintainer-mode + enable make rules and dependencies not useful (and + sometimes confusing) to the casual installer --enable-locallisppath=PATH directories Emacs should search for lisp files specific to this site @@@ -12059,82 -12049,129 +12079,86 @@@ _ACEO fi fi -### Link with -lXft if available to work around a bug. -HAVE_XFT=maybe -if test "${HAVE_GTK}" = "yes"; then - if test "X${with_pkg_config_prog}" != X; then - PKG_CONFIG="${with_pkg_config_prog}" - fi - - - succeeded=no - - if test -z "$PKG_CONFIG"; then - # Extract the first word of "pkg-config", so it can be a program name with args. -set dummy pkg-config; ac_word=$2 -{ echo "$as_me:$LINENO: checking for $ac_word" >&5 -echo $ECHO_N "checking for $ac_word... $ECHO_C" >&6; } -if test "${ac_cv_path_PKG_CONFIG+set}" = set; then +HAVE_XAW3D=no +if test x"${USE_X_TOOLKIT}" = xmaybe || test x"${USE_X_TOOLKIT}" = xLUCID; then + if test x"${HAVE_X11R5}" != xyes; then + USE_X_TOOLKIT=none + else - { echo "$as_me:$LINENO: checking for xaw3d" >&5 ++ if test "$with_xaw3d" != no; then ++ { echo "$as_me:$LINENO: checking for xaw3d" >&5 +echo $ECHO_N "checking for xaw3d... $ECHO_C" >&6; } - if test "${emacs_cv_xaw3d+set}" = set; then ++ if test "${emacs_cv_xaw3d+set}" = set; then echo $ECHO_N "(cached) $ECHO_C" >&6 else - case $PKG_CONFIG in - [\\/]* | ?:[\\/]*) - ac_cv_path_PKG_CONFIG="$PKG_CONFIG" # Let the user override the test with a path. - ;; - *) - as_save_IFS=$IFS; IFS=$PATH_SEPARATOR -for as_dir in $PATH -do - IFS=$as_save_IFS - test -z "$as_dir" && as_dir=. - for ac_exec_ext in '' $ac_executable_extensions; do - if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then - ac_cv_path_PKG_CONFIG="$as_dir/$ac_word$ac_exec_ext" - echo "$as_me:$LINENO: found $as_dir/$ac_word$ac_exec_ext" >&5 - break 2 - fi -done -done -IFS=$as_save_IFS + cat >conftest.$ac_ext <<_ACEOF +/* confdefs.h. */ +_ACEOF +cat confdefs.h >>conftest.$ac_ext +cat >>conftest.$ac_ext <<_ACEOF +/* end confdefs.h. */ - test -z "$ac_cv_path_PKG_CONFIG" && ac_cv_path_PKG_CONFIG="no" - ;; +#include +#include +int +main () +{ + + ; + return 0; +} +_ACEOF +rm -f conftest.$ac_objext conftest$ac_exeext +if { (ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; esac -fi -PKG_CONFIG=$ac_cv_path_PKG_CONFIG -if test -n "$PKG_CONFIG"; then - { echo "$as_me:$LINENO: result: $PKG_CONFIG" >&5 -echo "${ECHO_T}$PKG_CONFIG" >&6; } +eval "echo \"\$as_me:$LINENO: $ac_try_echo\"") >&5 + (eval "$ac_link") 2>conftest.er1 + ac_status=$? + grep -v '^ *+' conftest.er1 >conftest.err + rm -f conftest.er1 + cat conftest.err >&5 + echo "$as_me:$LINENO: \$? = $ac_status" >&5 + (exit $ac_status); } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && + $as_test_x conftest$ac_exeext; then + emacs_cv_xaw3d=yes else - { echo "$as_me:$LINENO: result: no" >&5 -echo "${ECHO_T}no" >&6; } -fi - + echo "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 - fi + emacs_cv_xaw3d=no +fi - if test "$PKG_CONFIG" = "no" ; then - HAVE_XFT=no - else - PKG_CONFIG_MIN_VERSION=0.9.0 - if $PKG_CONFIG --atleast-pkgconfig-version $PKG_CONFIG_MIN_VERSION; then - { echo "$as_me:$LINENO: checking for xft >= 0.13.0" >&5 -echo $ECHO_N "checking for xft >= 0.13.0... $ECHO_C" >&6; } +rm -f core conftest.err conftest.$ac_objext conftest_ipa8_conftest.oo \ + conftest$ac_exeext conftest.$ac_ext +fi - if $PKG_CONFIG --exists "xft >= 0.13.0" 2>&5; then - { echo "$as_me:$LINENO: result: yes" >&5 -echo "${ECHO_T}yes" >&6; } - succeeded=yes ++ else ++ emacs_cv_xaw3d=no ++ fi + if test $emacs_cv_xaw3d = yes; then + { echo "$as_me:$LINENO: result: yes; using Lucid toolkit" >&5 +echo "${ECHO_T}yes; using Lucid toolkit" >&6; } + USE_X_TOOLKIT=LUCID + HAVE_XAW3D=yes - { echo "$as_me:$LINENO: checking XFT_CFLAGS" >&5 -echo $ECHO_N "checking XFT_CFLAGS... $ECHO_C" >&6; } - XFT_CFLAGS=`$PKG_CONFIG --cflags "xft >= 0.13.0"|sed -e 's,///*,/,g'` - { echo "$as_me:$LINENO: result: $XFT_CFLAGS" >&5 -echo "${ECHO_T}$XFT_CFLAGS" >&6; } +cat >>confdefs.h <<\_ACEOF +#define HAVE_XAW3D 1 +_ACEOF - { echo "$as_me:$LINENO: checking XFT_LIBS" >&5 -echo $ECHO_N "checking XFT_LIBS... $ECHO_C" >&6; } - XFT_LIBS=`$PKG_CONFIG --libs "xft >= 0.13.0"|sed -e 's,///*,/,g'` - { echo "$as_me:$LINENO: result: $XFT_LIBS" >&5 -echo "${ECHO_T}$XFT_LIBS" >&6; } - else - { echo "$as_me:$LINENO: result: no" >&5 + else + { echo "$as_me:$LINENO: result: no" >&5 echo "${ECHO_T}no" >&6; } - XFT_CFLAGS="" - XFT_LIBS="" - ## If we have a custom action on failure, don't print errors, but - ## do set a variable so people can do so. - XFT_PKG_ERRORS=`$PKG_CONFIG --errors-to-stdout --print-errors "xft >= 0.13.0"` - - fi - - - - else - echo "*** Your version of pkg-config is too old. You need version $PKG_CONFIG_MIN_VERSION or newer." - echo "*** See http://www.freedesktop.org/software/pkgconfig" - fi - fi - - if test $succeeded = yes; then - : - else - HAVE_XFT=no - fi - - if test "$HAVE_XFT" != no; then - OLD_CFLAGS="$CPPFLAGS" - OLD_CPPFLAGS="$CFLAGS" - OLD_LIBS="$LIBS" - CPPFLAGS="$CPPFLAGS $XFT_CFLAGS" - CFLAGS="$CFLAGS $XFT_CFLAGS" - LIBS="$XFT_LIBS $LIBS" - if test "${ac_cv_header_X11_Xft_Xft_h+set}" = set; then - { echo "$as_me:$LINENO: checking for X11/Xft/Xft.h" >&5 -echo $ECHO_N "checking for X11/Xft/Xft.h... $ECHO_C" >&6; } -if test "${ac_cv_header_X11_Xft_Xft_h+set}" = set; then + { echo "$as_me:$LINENO: checking for libXaw" >&5 +echo $ECHO_N "checking for libXaw... $ECHO_C" >&6; } + if test "${emacs_cv_xaw+set}" = set; then echo $ECHO_N "(cached) $ECHO_C" >&6 -fi -{ echo "$as_me:$LINENO: result: $ac_cv_header_X11_Xft_Xft_h" >&5 -echo "${ECHO_T}$ac_cv_header_X11_Xft_Xft_h" >&6; } else - # Is the header compilable? -{ echo "$as_me:$LINENO: checking X11/Xft/Xft.h usability" >&5 -echo $ECHO_N "checking X11/Xft/Xft.h usability... $ECHO_C" >&6; } -cat >conftest.$ac_ext <<_ACEOF + cat >conftest.$ac_ext <<_ACEOF /* confdefs.h. */ _ACEOF cat confdefs.h >>conftest.$ac_ext diff --cc configure.in index 690e0348746,0f101a0edc3..d1b8f492a41 --- a/configure.in +++ b/configure.in @@@ -98,47 -104,29 +104,36 @@@ this option's value should be `yes', `n esac with_x_toolkit=$val ]) - AC_ARG_WITH(xpm, - [ --with-xpm use -lXpm for displaying XPM images]) - AC_ARG_WITH(jpeg, - [ --with-jpeg use -ljpeg for displaying JPEG images]) - AC_ARG_WITH(tiff, - [ --with-tiff use -ltiff for displaying TIFF images]) - AC_ARG_WITH(gif, - [ --with-gif use -lgif (or -lungif) for displaying GIF images]) - AC_ARG_WITH(png, - [ --with-png use -lpng for displaying PNG images]) - AC_ARG_WITH(freetype, - [ --with-freetype use -lfreetype for local fonts support]) - AC_ARG_WITH(xft, - [ --with-xft use -lXft for anti aliased fonts]) - AC_ARG_WITH(gpm, - [ --with-gpm use -lgpm for mouse support on a GNU/Linux console]) - AC_ARG_WITH(rsvg, - [ --with-rsvg use -lrsvg-2 for displaying SVG images]) - AC_ARG_WITH(gtk, - [ --with-gtk use GTK (same as --with-x-toolkit=gtk)]) - AC_ARG_WITH(pkg-config-prog, - [ --with-pkg-config-prog Path to pkg-config to use for finding GTK and librsvg]) - AC_ARG_WITH(toolkit-scroll-bars, - [ --without-toolkit-scroll-bars - don't use Motif or Xaw3d scroll bars]) - AC_ARG_WITH(xim, - [ --without-xim don't use X11 XIM]) - AC_ARG_WITH(carbon, - [ --without-carbon don't use Carbon GUI on Mac OS X]) + + EMACS_ARG_Y([xpm],[use -lXpm for displaying XPM images]) + EMACS_ARG_Y([jpeg],[use -ljpeg for displaying JPEG images]) + EMACS_ARG_Y([tiff],[use -ltiff for displaying TIFF images]) + EMACS_ARG_Y([gif],[use -lgif (or -lungif) for displaying GIF images]) + EMACS_ARG_Y([png],[use -lpng for displaying PNG images]) ++EMACS_ARG_Y([freetype],[use -lfreetype for local fonts support]) ++EMACS_ARG_Y([xft],[use -lXft for anti aliased fonts]) + EMACS_ARG_Y([gpm],[use -lgpm for mouse support on a GNU/Linux console]) + EMACS_ARG_Y([rsvg],[use -lrsvg-2 for displaying SVG images]) + EMACS_ARG_Y([gtk],[use GTK (same as --with-x-toolkit=gtk)]) + EMACS_ARG_Y([pkg-config-prog],[Path to pkg-config for finding GTK and librsvg]) + EMACS_ARG_N([toolkit-scroll-bars],[don't use Motif or Xaw3d scroll bars]) + EMACS_ARG_N([xaw3d],[don't use Xaw3d]) + EMACS_ARG_N([xim],[don't use X11 XIM]) + EMACS_ARG_N([carbon],[don't use Carbon GUI on Mac OS X]) + AC_ARG_ENABLE(carbon-app, - [[ --enable-carbon-app[=DIR] [DIR=/Application] - specify install directory for Emacs.app on Mac OS X]], + [AS_HELP_STRING([--enable-carbon-app@<:@=DIR@:>@], + [specify install directory for Emacs.app on Mac OS X + [DIR=/Application]])], [ carbon_appdir_x=${enableval}]) +AC_ARG_ENABLE(font-backend, +[ --enable-font-backend compile code of font-backend support], + USE_FONT_BACKEND=$enableval, + USE_FONT_BACKEND=no) + AC_ARG_ENABLE(asserts, - [ --enable-asserts compile code with asserts enabled], + [AS_HELP_STRING([--enable-asserts], [compile code with asserts enabled])], USE_XASSERTS=$enableval, USE_XASSERTS=no) diff --cc doc/misc/cc-mode.texi index 00000000000,ac77ca04d85..eb69733b61c mode 000000,100644..100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@@ -1,0 -1,6998 +1,6998 @@@ + \input texinfo + @c Notes to self regarding line handling: + @c + @c Empty lines are often significant before @end directives; avoid them. + @c + @c Empty lines before and after @example directives are significant in + @c info output but not in TeX. Empty lines inside @example directives + @c are significant. + + @c Conventions for formatting examples: + @c o If the example contains empty lines then put the surrounding empty + @c lines inside the @example directives. Put them outside otherwise. + @c o Use @group inside the example only if it shows indentation where + @c the relation between lines inside is relevant. + @c o Format line number columns like this: + @c 1: foo + @c 2: bar + @c ^ one space + @c ^^ two columns, right alignment + @c o Check line lengths in TeX output; they can typically be no longer + @c than 70 chars, 60 if the paragraph is indented. + + @comment TBD: Document the finer details of statement anchoring? + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment %**start of header (This is for running Texinfo on a region) + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment How to make the various output formats: + @comment (Thanks to Robert Chassell for supplying this information.) + @comment Note that Texinfo 4.7 (or later) is needed. + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @ignore + In each of the following pairs of commands, the first generates a + version with cross references pointing to the GNU Emacs manuals, + the second with them pointing to the XEmacs manuals. + ## Info output + makeinfo cc-mode.texi + makeinfo -DXEMACS cc-mode.texi + + ## DVI output + ## You may need to set up the environment variable TEXINPUTS so + ## that tex can find the file texinfo.tex - See the tex + ## manpage. + texi2dvi cc-mode.texi + texi2dvi -t "@set XEMACS " cc-mode.texi + + ## HTML output. (The --no-split parameter is optional) + makeinfo --html --no-split cc-mode.texi + makeinfo --html --no-split -DXEMACS cc-mode.texi + + ## Plain text output + makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ + --no-headers --output=cc-mode.txt cc-mode.texi + makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ + --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi + + ## DocBook output + makeinfo --docbook --no-split --paragraph-indent=0 \ + cc-mode.texi + makeinfo --docbook --no-split --paragraph-indent=0 \ + -DXEMACS cc-mode.texi + + ## XML output + makeinfo --xml --no-split --paragraph-indent=0 \ + cc-mode.texi + makeinfo --xml --no-split --paragraph-indent=0 \ + -DXEMACS cc-mode.texi + + #### (You must be in the same directory as the viewed file.) + + ## View DVI output + xdvi cc-mode.dvi & + + ## View HTML output + mozilla cc-mode.html + @end ignore + + @comment No overfull hbox marks in the dvi file. + @finalout + + @setfilename ../../info/ccmode + @settitle CC Mode Manual + @footnotestyle end + + @c The following four macros generate the filenames and titles of the + @c main (X)Emacs manual and the Elisp/Lispref manual. Leave the + @c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it + @c to generate an XEmacs version, e.g. with + @c "makeinfo -DXEMACS cc-mode.texi". + @ifset XEMACS + @macro emacsman + xemacs + @end macro + @macro emacsmantitle + XEmacs User's Manual + @end macro + @macro lispref + lispref + @end macro + @macro lispreftitle + XEmacs Lisp Reference Manual + @end macro + @end ifset + + @ifclear XEMACS + @macro emacsman + emacs + @end macro + @macro emacsmantitle + GNU Emacs Manual + @end macro + @macro lispref + elisp + @end macro + @macro lispreftitle + GNU Emacs Lisp Reference Manual + @end macro + @end ifclear + + + @macro ccmode + CC Mode + @end macro + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment @setchapternewpage odd !! we don't want blank pages !! + @comment %**end of header (This is for running Texinfo on a region) + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment + @comment Texinfo manual for CC Mode + @comment Generated from the original README file by Krishna Padmasola + @comment + @comment + @comment Authors: + @comment Barry A. Warsaw + @comment Martin Stjernholm + @comment Alan Mackenzie + @comment + @comment Maintained by Martin Stjernholm and Alan Mackenzie + @comment + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @comment Define an index for syntactic symbols. + @ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss + @c For Info, unlike tex, @syncodeindex needs a matching @defindex. + @defindex ss + @end ifnottex + + @comment Combine key, syntactic symbol and concept indices into one. + @syncodeindex ss cp + @syncodeindex ky cp + + @copying + This manual is for CC Mode in Emacs. + + Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, + 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. + + @quotation + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 or + any later version published by the Free Software Foundation; with the + Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and + ``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU + Manual'', and with the Back-Cover Texts as in (a) below. A copy of the + license is included in the section entitled ``GNU Free Documentation + License'' in the Emacs manual. + + (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify + this GNU Manual, like GNU software. Copies published by the Free + Software Foundation raise funds for GNU development.'' + + This document is part of a collection distributed under the GNU Free + Documentation License. If you want to distribute this document + separately from the collection, you can do so by adding a copy of the + license to the document, as described in section 6 of the license. + @end quotation + @end copying + + @comment Info directory entry for use by install-info. The indentation + @comment here is by request from the FSF folks. + @dircategory Emacs + @direntry + * CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, + Java, Pike, AWK, and CORBA IDL code. + @end direntry + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment TeX title page + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @titlepage + @sp 10 + + @center @titlefont{CC Mode 5.31} + @sp 2 + @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} + @sp 2 + @center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie + + @page + @vskip 0pt plus 1filll + @insertcopying + -This manual was generated from $Revision$ of $RCSfile$, which can be ++This manual was generated from $Revision: 1.2 $ of $RCSfile: cc-mode.texi,v $, which can be + downloaded from + @url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/doc/misc/cc-mode.texi}. + @end titlepage + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment The Top node contains the master menu for the Info file. + @comment This appears only in the Info file, not the printed manual. + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @node Top, Introduction, (dir), (dir) + @comment node-name, next, previous, up + + @ifinfo + @top @ccmode{} + + @ccmode{} is a GNU Emacs mode for editing files containing C, C++, + Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike + and AWK code. It provides syntax-based indentation, font locking, and + has several handy commands and some minor modes to make the editing + easier. It does not provide tools to look up and navigate between + functions, classes etc - there are other packages for that. + @end ifinfo + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @menu + * Introduction:: + * Overview:: + * Getting Started:: + * Commands:: + * Font Locking:: + * Config Basics:: + * Custom Filling and Breaking:: + * Custom Auto-newlines:: + * Clean-ups:: + * Indentation Engine Basics:: + * Customizing Indentation:: + * Custom Macros:: + * Odds and Ends:: + * Sample .emacs File:: + * Performance Issues:: + * Limitations and Known Bugs:: + * FAQ:: + * Updating CC Mode:: + * Mailing Lists and Bug Reports:: + * GNU Free Documentation License:: + * Command and Function Index:: + * Variable Index:: + * Concept and Key Index:: + + @detailmenu + --- The Detailed Node Listing --- + + Commands + + * Indentation Commands:: + * Comment Commands:: + * Movement Commands:: + * Filling and Breaking:: + * Minor Modes:: + * Electric Keys:: + * Auto-newlines:: + * Hungry WS Deletion:: + * Subword Movement:: + * Other Commands:: + + Font Locking + + * Font Locking Preliminaries:: + * Faces:: + * Doc Comments:: + * AWK Mode Font Locking:: + + Configuration Basics + + * CC Hooks:: + * Style Variables:: + * Styles:: + + Styles + + * Built-in Styles:: + * Choosing a Style:: + * Adding Styles:: + * File Styles:: + + Customizing Auto-newlines + + * Hanging Braces:: + * Hanging Colons:: + * Hanging Semicolons and Commas:: + + Hanging Braces + + * Custom Braces:: + + Indentation Engine Basics + + * Syntactic Analysis:: + * Syntactic Symbols:: + * Indentation Calculation:: + + Syntactic Symbols + + * Function Symbols:: + * Class Symbols:: + * Conditional Construct Symbols:: + * Switch Statement Symbols:: + * Brace List Symbols:: + * External Scope Symbols:: + * Paren List Symbols:: + * Literal Symbols:: + * Multiline Macro Symbols:: + * Objective-C Method Symbols:: + * Anonymous Class Symbol:: + * Statement Block Symbols:: + * K&R Symbols:: + + Customizing Indentation + + * c-offsets-alist:: + * Interactive Customization:: + * Line-Up Functions:: + * Custom Line-Up:: + * Other Indentation:: + + Line-Up Functions + + * Brace/Paren Line-Up:: + * List Line-Up:: + * Operator Line-Up:: + * Comment Line-Up:: + * Misc Line-Up:: + + @end detailmenu + @end menu + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Introduction, Overview, Top, Top + @comment node-name, next, previous, up + @chapter Introduction + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex BOCM + @cindex history + @cindex awk-mode.el + @cindex c-mode.el + @cindex c++-mode.el + + Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, + C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and + CIDL), Pike and AWK code. This incarnation of the mode is descended + from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM + @t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been + maintaining since 1992, and @file{awk-mode.el}, a long neglected mode + in the (X)Emacs base. + + Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} + Maintainers Team, and implemented the Pike support. In 2000 Martin + took over as the sole maintainer. In 2001 Alan Mackenzie joined the + team, implementing AWK support in version 5.30. @ccmode{} did not + originally contain the font lock support for its languages --- that + was added in version 5.30. + + This manual describes @ccmode{} + @comment The following line must appear on its own, so that the + version 5.31. + @comment Release.py script can update the version number automatically + + @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, + Java, CORBA's Interface Definition Language, Pike@footnote{A C-like + scripting language with its roots in the LPC language used in some MUD + engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this + way, you can easily set up consistent font locking and coding styles for + use in editing all of these languages, although AWK is not yet as + uniformly integrated as the other languages. + + @findex c-mode + @findex c++-mode + @findex objc-mode + @findex java-mode + @findex idl-mode + @findex pike-mode + @findex awk-mode + Note that the name of this package is ``@ccmode{}'', but there is no top + level @code{cc-mode} entry point. All of the variables, commands, and + functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and + @code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, + @code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are + provided. This package is intended to be a replacement for + @file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. + + A special word of thanks goes to Krishna Padmasola for his work in + converting the original @file{README} file to Texinfo format. I'd + also like to thank all the @ccmode{} victims who help enormously + during the early beta stages of @ccmode{}'s development. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Overview, Getting Started, Introduction, Top + @comment node-name, next, previous, up@cindex organization of the manual + @chapter Overview of the Manual + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @noindent + The manual starts with several introductory chapters (including this + one). + + @noindent + The next chunk of the manual describes the day to day @emph{use} of + @ccmode{} (as contrasted with how to customize it). + + @itemize @bullet + @item + The chapter ``Commands'' describes in detail how to use (nearly) all + of @ccmode{}'s features. There are extensive cross-references from + here to the corresponding sections later in the manual which tell you + how to customize these features. + + @item + ``Font Locking'' describes how ``syntax highlighting'' is applied to + your buffers. It is mainly background information and can be skipped + over at a first reading. + @end itemize + + @noindent + The next chunk of the manual describes how to @emph{customize} + @ccmode{}. Typically, an overview of a topic is given at the chapter + level, then the sections and subsections describe the material in + increasing detail. + + @itemize @bullet + @item + The chapter ``Configuration Basics'' tells you @emph{how} to write + customizations - whether in hooks, in styles, in both, or in neither, + depending on your needs. It describes the @ccmode{} style system and + lists the standard styles that @ccmode{} supplies. + + @item + The next few chapters describe in detail how to customize the various + features of @ccmode{}. + + @item + Finally, there is a sample @file{.emacs} fragment, which might help you + in creating your own customization. + @end itemize + + @noindent + The manual ends with ``this and that'', things that don't fit cleanly + into any of the previous chunks. + + @itemize @bullet + @item + Two chapters discuss the performance of @ccmode{} and known + bugs/limitations. + + @item + The FAQ contains a list of common problems and questions. + + @item + The next two chapters tell you how to get in touch with the @ccmode{} + project - whether for updating @ccmode{} or submitting bug reports. + @end itemize + + @noindent + Finally, there are the customary indices. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Getting Started, Commands, Overview, Top + @comment node-name, next, previous, up + @chapter Getting Started + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + If you got this version of @ccmode{} with Emacs or XEmacs, it should + work just fine right out of the box. Note however that you might not + have the latest @ccmode{} release and might want to upgrade your copy + (see below). + + You should probably start by skimming through the entire chapter + @ref{Commands} to get an overview of @ccmode{}'s capabilities. + + After trying out some commands, you may dislike some aspects of + @ccmode{}'s default configuration. Here is an outline of how to + change some of the settings that newcomers to @ccmode{} most often + want to change: + + @table @asis + @item c-basic-offset + This Lisp variable holds an integer, the number of columns @ccmode{} + indents nested code. To set this value to 6, customize + @code{c-basic-offset} or put this into your @file{.emacs}: + + @example + (setq c-basic-offset 6) + @end example + + @item The (indentation) style + The basic ``shape'' of indentation created by @ccmode{}---by default, + this is @code{gnu} style (except for Java and AWK buffers). A list of + the available styles and their descriptions can be found in + @ref{Built-in Styles}. A complete specification of the @ccmode{} + style system, including how to create your own style, can be found in + the chapter @ref{Styles}. To set your style to @code{linux}, either + customize @code{c-default-style} or put this into your @file{.emacs}: + + @example + (setq c-default-style '((java-mode . "java") + (awk-mode . "awk") + (other . "linux"))) + @end example + + @item Electric Indentation + Normally, when you type ``punctuation'' characters such as @samp{;} or + @samp{@{}, @ccmode{} instantly reindents the current line. This can + be disconcerting until you get used to it. To disable @dfn{electric + indentation} in the current buffer, type @kbd{C-c C-l}. Type the same + thing to enable it again. To have electric indentation disabled by + default, put the following into your @file{.emacs} file@footnote{There + is no ``easy customization'' facility for making this change.}: + + @example + (setq-default c-electric-flag nil) + @end example + + @noindent + Details of this and other similar ``Minor Modes'' appear in the + section @ref{Minor Modes}. + + @item Making the @key{RET} key indent the new line + The standard Emacs binding for @key{RET} just adds a new line. If you + want it to reindent the new line as well, rebind the key. Note that + the action of rebinding would fail if the pertinent keymap didn't yet + exist---we thus need to delay the action until after @ccmode{} has + been loaded. Put the following code into your @file{.emacs}: + + @example + (defun my-make-CR-do-indent () + (define-key c-mode-base-map "\C-m" 'c-context-line-break)) + (add-hook 'c-initialization-hook 'my-make-CR-do-indent) + @end example + + @noindent + This example demonstrates the use of a very powerful @ccmode{} (and + Emacs) facility, the hook. The use of @ccmode{}'s hooks is described + in @ref{CC Hooks}. + @end table + + All these settings should occur in your @file{.emacs} @emph{before} + any @ccmode{} buffers get loaded---in particular, before any call of + @code{desktop-read}. + + As you get to know the mode better, you may want to make more + ambitious changes to your configuration. For this, you should start + reading the chapter @ref{Config Basics}. + + If you are upgrading an existing @ccmode{} installation, please see + the @file{README} file for installation details. In particular, if + you are going to be editing AWK files, @file{README} describes how to + configure your (X)Emacs so that @ccmode{} will supersede the obsolete + @code{awk-mode.el} which might have been supplied with your (X)Emacs. + @ccmode{} might not work with older versions of Emacs or XEmacs. See + the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net} + for the latest information on Emacs version and package compatibility + (@pxref{Updating CC Mode}). + + @deffn Command c-version + @findex version (c-) + You can find out what version of @ccmode{} you are using by visiting a C + file and entering @kbd{M-x c-version RET}. You should see this message in + the echo area: + + @example + Using CC Mode version 5.XX + @end example + + @noindent + where @samp{XX} is the minor release number. + @end deffn + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Commands, Font Locking, Getting Started, Top + @comment node-name, next, previous, up + @chapter Commands + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + This chapter specifies all of CC Mode's commands, and thus contains + nearly everything you need to know to @emph{use} @ccmode{} (as + contrasted with configuring it). @dfn{Commands} here means both + control key sequences and @dfn{electric keys}, these being characters + such as @samp{;} which, as well as inserting themselves into the + buffer, also do other things. + + You might well want to review + @ifset XEMACS + @ref{Lists,,,@emacsman{}, @emacsmantitle{}}, + @end ifset + @ifclear XEMACS + @ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}}, + @end ifclear + which describes commands for moving around brace and parenthesis + structures. + + + @menu + * Indentation Commands:: + * Comment Commands:: + * Movement Commands:: + * Filling and Breaking:: + * Minor Modes:: + * Electric Keys:: + * Auto-newlines:: + * Hungry WS Deletion:: + * Subword Movement:: + * Other Commands:: + @end menu + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Indentation Commands, Comment Commands, Commands, Commands + @comment node-name, next, previous,up + @section Indentation Commands + @cindex indentation + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The following commands reindent C constructs. Note that when you + change your coding style, either interactively or through some other + means, your file does @emph{not} automatically get reindented. You + will need to execute one of the following commands to see the effects + of your changes. + + @cindex GNU indent program + Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} + (@pxref{Custom Auto-newlines}) only affect how on-the-fly code is + formatted. Changing the ``hanginess'' of a brace and then + reindenting, will not move the brace to a different line. For this, + you're better off getting an external program like GNU @code{indent}, + which will rearrange brace location, amongst other things. + + Preprocessor directives are handled as syntactic whitespace from other + code, i.e. they can be interspersed anywhere without affecting the + indentation of the surrounding code, just like comments. + + The code inside macro definitions is, by default, still analyzed + syntactically so that you get relative indentation there just as you'd + get if the same code was outside a macro. However, since there is no + hint about the syntactic context, i.e. whether the macro expands to an + expression, to some statements, or perhaps to whole functions, the + syntactic recognition can be wrong. @ccmode{} manages to figure it + out correctly most of the time, though. + + Reindenting large sections of code can take a long time. When + @ccmode{} reindents a region of code, it is essentially equivalent to + hitting @key{TAB} on every line of the region. + + These commands indent code: + + @table @asis + @item @kbd{@key{TAB}} (@code{c-indent-command}) + @kindex TAB + @findex c-indent-command + @findex indent-command (c-) + This command indents the current line. That is all you need to know + about it for normal use. + + @code{c-indent-command} does different things, depending on the + setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine + Basics}): + + @itemize @bullet + @item + When it's non-@code{nil} (which it normally is), the command indents + the line according to its syntactic context. With a prefix argument + (@kbd{C-u @key{TAB}}), it will re-indent the entire + expression@footnote{this is only useful for a line starting with a + comment opener or an opening brace, parenthesis, or string quote.} + that begins at the line's left margin. + + @item + When it's @code{nil}, the command indents the line by an extra + @code{c-basic-offset} columns. A prefix argument acts as a + multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1, + removing @code{c-basic-offset} columns from the indentation. + @end itemize + + The precise behavior is modified by several variables: With + @code{c-tab-always-indent}, you can make @key{TAB} insert whitespace + in some circumstances---@code{c-insert-tab-function} then defines + precisely what sort of ``whitespace'' this will be. Set the standard + Emacs variable @code{indent-tabs-mode} to @code{t} if you want real + @samp{tab} characters to be used in the indentation, to @code{nil} if + you want only spaces. @xref{Just Spaces,,, @emacsman{}, + @emacsmantitle{}}. + + @defopt c-tab-always-indent + @vindex tab-always-indent (c-) + @cindex literal + This variable modifies how @key{TAB} operates. + @itemize @bullet + @item + When it is @code{t} (the default), @key{TAB} simply indents the + current line. + @item + When it is @code{nil}, @key{TAB} (re)indents the line only if point is + to the left of the first non-whitespace character on the line. + Otherwise it inserts some whitespace (a tab or an equivalent number of + spaces - see below) at point. + @item + With some other value, the line is reindented. Additionally, if point + is within a string or comment, some whitespace is inserted. + @end itemize + @end defopt + + @defopt c-insert-tab-function + @vindex insert-tab-function (c-) + @findex tab-to-tab-stop + When ``some whitespace'' is inserted as described above, what actually + happens is that the function stored in @code{c-insert-tab-function} is + called. Normally, this is @code{insert-tab}, which inserts a real tab + character or the equivalent number of spaces (depending on + @code{indent-tabs-mode}). Some people, however, set + @code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get + hard tab stops when indenting. + @end defopt + @end table + + @noindent + The kind of indentation the next five commands do depends on the + setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine + Basics}): + @itemize @bullet + @item + when it is non-@code{nil} (the default), the commands indent lines + according to their syntactic context; + @item + when it is @code{nil}, they just indent each line the same amount as + the previous non-blank line. The commands that indent a region aren't + very useful in this case. + @end itemize + + @table @asis + @item @kbd{C-j} (@code{newline-and-indent}) + @kindex C-j + @findex newline-and-indent + Inserts a newline and indents the new blank line, ready to start + typing. This is a standard (X)Emacs command. + + @item @kbd{C-M-q} (@code{c-indent-exp}) + @kindex C-M-q + @findex c-indent-exp + @findex indent-exp (c-) + Indents an entire balanced brace or parenthesis expression. Note that + point must be on the opening brace or parenthesis of the expression + you want to indent. + + @item @kbd{C-c C-q} (@code{c-indent-defun}) + @kindex C-c C-q + @findex c-indent-defun + @findex indent-defun (c-) + Indents the entire top-level function, class or macro definition + encompassing point. It leaves point unchanged. This function can't be + used to reindent a nested brace construct, such as a nested class or + function, or a Java method. The top-level construct being reindented + must be complete, i.e. it must have both a beginning brace and an ending + brace. + + @item @kbd{C-M-\} (@code{indent-region}) + @kindex C-M-\ + @findex indent-region + Indents an arbitrary region of code. This is a standard Emacs command, + tailored for C code in a @ccmode{} buffer. Note, of course, that point + and mark must delineate the region you want to indent. + + @item @kbd{C-M-h} (@code{c-mark-function}) + @kindex C-M-h + @findex c-mark-function + @findex mark-function (c-) + While not strictly an indentation command, this is useful for marking + the current top-level function or class definition as the current + region. As with @code{c-indent-defun}, this command operates on + top-level constructs, and can't be used to mark say, a Java method. + @end table + + These variables are also useful when indenting code: + + @defopt indent-tabs-mode + This is a standard Emacs variable that controls how line indentation + is composed. When it's non-@code{nil}, tabs can be used in a line's + indentation, otherwise only spaces are used. + @end defopt + + @defopt c-progress-interval + @vindex progress-interval (c-) + When indenting large regions of code, this variable controls how often a + progress message is displayed. Set this variable to @code{nil} to + inhibit the progress messages, or set it to an integer which is how + often (in seconds) progress messages are to be displayed. + @end defopt + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Comment Commands, Movement Commands, Indentation Commands, Commands + @comment node-name, next, previous, up + @section Comment Commands + @cindex comments (insertion of) + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @table @asis + @item @kbd{C-c C-c} (@code{comment-region}) + @kindex C-c C-c + @findex comment-region + This command comments out the lines that start in the region. With a + negative argument, it does the opposite - it deletes the comment + delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU + Emacs Manual}, for fuller details. @code{comment-region} isn't + actually part of @ccmode{} - it is given a @ccmode{} binding for + convenience. + + @item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.}) + @kindex M-; + @findex comment-dwim + @findex indent-for-comment + Insert a comment at the end of the current line, if none is there + already. Then reindent the comment according to @code{comment-column} + @ifclear XEMACS + (@pxref{Options for Comments,,, emacs, GNU Emacs Manual}) + @end ifclear + @ifset XEMACS + (@pxref{Comments,,, xemacs, XEmacs User's Manual}) + @end ifset + and the variables below. Finally, position the point after the + comment starter. @kbd{C-u M-;} kills any comment on the current line, + together with any whitespace before it. This is a standard Emacs + command, but @ccmode{} enhances it a bit with two variables: + + @defopt c-indent-comment-alist + @vindex indent-comment-alist (c-) + @vindex comment-column + This style variable allows you to vary the column that @kbd{M-;} puts + the comment at, depending on what sort of code is on the line, and + possibly the indentation of any similar comment on the preceding line. + It is an association list that maps different types of lines to + actions describing how they should be handled. If a certain line type + isn't present on the list then the line is indented to the column + specified by @code{comment-column}. + + See the documentation string for a full description of this + variable (use @kbd{C-h v c-indent-comment-alist}). + @end defopt + + @defopt c-indent-comments-syntactically-p + @vindex indent-comments-syntactically-p (c-) + Normally, when this style variable is @code{nil}, @kbd{M-;} will + indent comment-only lines according to @code{c-indent-comment-alist}, + just as it does with lines where other code precede the comments. + However, if you want it to act just like @key{TAB} for comment-only + lines you can get that by setting + @code{c-indent-comments-syntactically-p} to non-@code{nil}. + + If @code{c-indent-comments-syntactically-p} is non-@code{nil} then + @code{c-indent-comment-alist} won't be consulted at all for comment-only + lines. + @end defopt + @end table + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Movement Commands, Filling and Breaking, Comment Commands, Commands + @comment node-name, next, previous, up + @section Movement Commands + @cindex movement + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @ccmode{} contains some useful commands for moving around in C code. + + @table @asis + @item @kbd{C-M-a} (@code{c-beginning-of-defun}) + @itemx @kbd{C-M-e} (@code{c-end-of-defun}) + @findex c-beginning-of-defun + @findex c-end-of-defun + + Move to the beginning or end of the current or next function. Other + constructs (such as a structs or classes) which have a brace block + also count as ``functions'' here. To move over several functions, you + can give these commands a repeat count. + + The start of a function is at its header. The end of the function is + after its closing brace, or after the semicolon of a construct (such + as a @code{struct}) which doesn't end at the brace. These two + commands try to leave point at the beginning of a line near the actual + start or end of the function. This occasionally causes point not to + move at all. + + These functions are analogous to the Emacs built-in commands + @code{beginning-of-defun} and @code{end-of-defun}, except they + eliminate the constraint that the top-level opening brace of the defun + must be in column zero. See @ref{Defuns,,,@emacsman{}, + @emacsmantitle{}}, for more information. + + @item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) + @itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) + @kindex C-M-a (AWK Mode) + @kindex C-M-e (AWK Mode) + @findex c-awk-beginning-of-defun + @findex awk-beginning-of-defun (c-) + @findex c-awk-end-of-defun + @findex awk-end-of-defun (c-) + Move to the beginning or end of the current or next AWK defun. These + commands can take prefix-arguments, their functionality being entirely + equivalent to @code{beginning-of-defun} and @code{end-of-defun}. + + AWK Mode @dfn{defuns} are either pattern/action pairs (either of which + might be implicit) or user defined functions. Having the @samp{@{} and + @samp{@}} (if there are any) in column zero, as is suggested for some + modes, is neither necessary nor helpful in AWK mode. + + @item @kbd{M-a} (@code{c-beginning-of-statement}) + @itemx @kbd{M-e} (@code{c-end-of-statement}) + @kindex M-a + @kindex M-e + @findex c-beginning-of-statement + @findex c-end-of-statement + @findex beginning-of-statement (c-) + @findex end-of-statement (c-) + Move to the beginning or end of the innermost C statement. If point + is already there, move to the next beginning or end of a statement, + even if that means moving into a block. (Use @kbd{C-M-b} or + @kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} + means move over @var{n} statements. + + If point is within or next to a comment or a string which spans more + than one line, these commands move by sentences instead of statements. + + When called from a program, these functions take three optional + arguments: the repetition count, a buffer position limit which is the + farthest back to search for the syntactic context, and a flag saying + whether to do sentence motion in or near comments and multiline + strings. + + @item @kbd{C-c C-u} (@code{c-up-conditional}) + @kindex C-c C-u + @findex c-up-conditional + @findex up-conditional (c-) + Move back to the containing preprocessor conditional, leaving the mark + behind. A prefix argument acts as a repeat count. With a negative + argument, move forward to the end of the containing preprocessor + conditional. + + @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the + function stops at them when going backward, but not when going + forward. + + This key sequence is not bound in AWK Mode, which doesn't have + preprocessor statements. + + @item @kbd{M-x c-up-conditional-with-else} + @findex c-up-conditional-with-else + @findex up-conditional-with-else (c-) + A variety of @code{c-up-conditional} that also stops at @samp{#else} + lines. Normally those lines are ignored. + + @item @kbd{M-x c-down-conditional} + @findex c-down-conditional + @findex down-conditional (c-) + Move forward into the next nested preprocessor conditional, leaving + the mark behind. A prefix argument acts as a repeat count. With a + negative argument, move backward into the previous nested preprocessor + conditional. + + @samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the + function stops at them when going forward, but not when going backward. + + @item @kbd{M-x c-down-conditional-with-else} + @findex c-down-conditional-with-else + @findex down-conditional-with-else (c-) + A variety of @code{c-down-conditional} that also stops at @samp{#else} + lines. Normally those lines are ignored. + + @item @kbd{C-c C-p} (@code{c-backward-conditional}) + @itemx @kbd{C-c C-n} (@code{c-forward-conditional}) + @kindex C-c C-p + @kindex C-c C-n + @findex c-backward-conditional + @findex c-forward-conditional + @findex backward-conditional (c-) + @findex forward-conditional (c-) + Move backward or forward across a preprocessor conditional, leaving + the mark behind. A prefix argument acts as a repeat count. With a + negative argument, move in the opposite direction. + + These key sequences are not bound in AWK Mode, which doesn't have + preprocessor statements. + + @item @kbd{M-x c-backward-into-nomenclature} + @itemx @kbd{M-x c-forward-into-nomenclature} + @findex c-backward-into-nomenclature + @findex c-forward-into-nomenclature + @findex backward-into-nomenclature (c-) + @findex forward-into-nomenclature (c-) + A popular programming style, especially for object-oriented languages + such as C++ is to write symbols in a mixed case format, where the + first letter of each word is capitalized, and not separated by + underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. + + These commands move backward or forward to the beginning of the next + capitalized word. With prefix argument @var{n}, move @var{n} times. + If @var{n} is negative, move in the opposite direction. + + Note that these two commands have been superseded by + @code{c-subword-mode}, which you should use instead. @xref{Subword + Movement}. They might be removed from a future release of @ccmode{}. + @end table + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Filling and Breaking, Minor Modes, Movement Commands, Commands + @comment node-name, next, previous, up + @section Filling and Line Breaking Commands + @cindex text filling + @cindex line breaking + @cindex comment handling + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Since there's a lot of normal text in comments and string literals, + @ccmode{} provides features to edit these like in text mode. The goal + is to do it seamlessly, i.e. you can use auto fill mode, sentence and + paragraph movement, paragraph filling, adaptive filling etc. wherever + there's a piece of normal text without having to think much about it. + @ccmode{} keeps the indentation, fixes suitable comment line prefixes, + and so on. + + You can configure the exact way comments get filled and broken, and + where Emacs does auto-filling (see @pxref{Custom Filling and + Breaking}). Typically, the style system (@pxref{Styles}) will have + set this up for you, so you probably won't have to bother. + + @findex auto-fill-mode + @cindex Auto Fill mode + @cindex paragraph filling + Line breaks are by default handled (almost) the same regardless of + whether they are made by auto fill mode (@pxref{Auto Fill,,, + @emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with + @kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In + string literals, the new line gets the same indentation as the + previous nonempty line.@footnote{You can change this default by + setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} + and @pxref{Customizing Indentation})}. + + @table @asis + @item @kbd{M-q} (@code{c-fill-paragraph}) + @kindex M-q + @findex c-fill-paragraph + @findex fill-paragraph (c-) + @cindex Javadoc markup + @cindex Pike autodoc markup + This command fills multiline string literals and both block + and line style comments. In Java buffers, the Javadoc markup words + are recognized as paragraph starters. The line oriented Pike autodoc + markup words are recognized in the same way in Pike mode. + + The formatting of the starters (@code{/*}) and enders (@code{*/}) of + block comments are kept as they were before the filling. I.e., if + either the starter or ender were on a line of its own, then it stays + on its own line; conversely, if the delimiter has comment text on its + line, it keeps at least one word of that text with it on the line. + + This command is the replacement for @code{fill-paragraph} in @ccmode{} + buffers. + + @item @kbd{M-j} (@code{c-indent-new-comment-line}) + @kindex M-j + @findex c-indent-new-comment-line + @findex indent-new-comment-line (c-) + This breaks the current line at point and indents the new line. If + point was in a comment, the new line gets the proper comment line + prefix. If point was inside a macro, a backslash is inserted before + the line break. It is the replacement for + @code{indent-new-comment-line}. + + @item @kbd{M-x c-context-line-break} + @findex c-context-line-break + @findex context-line-break (c-) + Insert a line break suitable to the context: If the point is inside a + comment, the new line gets the suitable indentation and comment line + prefix like @code{c-indent-new-comment-line}. In normal code it's + indented like @code{newline-and-indent} would do. In macros it acts + like @code{newline-and-indent} but additionally inserts and optionally + aligns the line ending backslash so that the macro remains unbroken. + @xref{Custom Macros}, for details about the backslash alignment. In a + string, a backslash is inserted only if the string is within a + macro@footnote{In GCC, unescaped line breaks within strings are + valid.}. + + This function is not bound to a key by default, but it's intended to be + used on the @kbd{RET} key. If you like the behavior of + @code{newline-and-indent} on @kbd{RET}, you should consider switching to + this function. @xref{Sample .emacs File}. + + @item @kbd{M-x c-context-open-line} + @findex c-context-open-line + @findex context-open-line (c-) + This is to @kbd{C-o} (@kbd{M-x open-line}) as + @code{c-context-line-break} is to @kbd{RET}. I.e. it works just like + @code{c-context-line-break} but leaves the point before the inserted + line break. + @end table + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Minor Modes, Electric Keys, Filling and Breaking, Commands + @comment node-name, next, previous, up + @section Minor Modes + @cindex Minor Modes + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @ccmode{} contains several minor-mode-like features that you might + find useful while writing new code or editing old code: + + @table @asis + @item electric mode + When this is enabled, certain visible characters cause reformatting as + they are typed. This is normally helpful, but can be a nuisance when + editing chaotically formatted code. It can also be disconcerting, + especially for users who are new to @ccmode{}. + @item auto-newline mode + This automatically inserts newlines where you'd probably want to type + them yourself, e.g. after typing @samp{@}}s. Its action is suppressed + when electric mode is disabled. + @item hungry-delete mode + This lets you delete a contiguous block of whitespace with a single + key - for example, the newline and indentation just inserted by + auto-newline when you want to back up and write a comment after the + last statement. + @item subword mode + This mode makes basic word movement commands like @kbd{M-f} + (@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the + parts of sillycapsed symbols as different words. + E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS}, + @samp{Graphics}, and @samp{Context}. + @item syntactic-indentation mode + When this is enabled (which it normally is), indentation commands such + as @kbd{C-j} indent lines of code according to their syntactic + structure. Otherwise, a line is simply indented to the same level as + the previous one and @kbd{@key{TAB}} adjusts the indentation in steps + of `c-basic-offset'. + @end table + + Full details on how these minor modes work are at @ref{Electric Keys}, + @ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, + and @ref{Indentation Engine Basics}. + + You can toggle each of these minor modes on and off, and you can + configure @ccmode{} so that it starts up with your favourite + combination of them (@pxref{Sample .emacs File}). By default, when + you initialize a buffer, electric mode and syntactic-indentation mode + are enabled but the other two modes are disabled. + + @ccmode{} displays the current state of the first four of these minor + modes on the modeline by appending letters to the major mode's name, + one letter for each enabled minor mode - @samp{l} for electric mode, + @samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and + @samp{w} for subword mode. If all these modes were enabled, you'd see + @samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of + the language in question for the other languages @ccmode{} supports.}. + + Here are the commands to toggle these modes: + + @table @asis + @item @kbd{C-c C-l} (@code{c-toggle-electric-state}) + @kindex C-c C-l + @findex c-toggle-electric-state + @findex toggle-electric-state (c-) + Toggle electric minor mode. When the command turns the mode off, it + also suppresses auto-newline mode. + + @item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) + @kindex C-c C-a + @findex c-toggle-auto-newline + @findex toggle-auto-newline (c-) + Toggle auto-newline minor mode. When the command turns the mode on, + it also enables electric minor mode. + + @item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.} + @findex c-toggle-hungry-state + @findex toggle-hungry-state (c-) + Toggle hungry-delete minor mode. + + @item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.} + @findex c-toggle-auto-hungry-state + @findex toggle-auto-hungry-state (c-) + Toggle both auto-newline and hungry delete minor modes. + + @item @kbd{C-c C-w} (@code{M-x c-subword-mode}) + @kindex C-c C-w + @findex c-subword-mode + @findex subword-mode (c-) + Toggle subword mode. + + @item @kbd{M-x c-toggle-syntactic-indentation} + @findex c-toggle-syntactic-indentation + @findex toggle-syntactic-indentation (c-) + Toggle syntactic-indentation mode. + @end table + + Common to all the toggle functions above is that if they are called + programmatically, they take an optional numerical argument. A + positive value will turn on the minor mode (or both of them in the + case of @code{c-toggle-auto-hungry-state}) and a negative value will + turn it (or them) off. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Electric Keys, Auto-newlines, Minor Modes, Commands + @comment node-name, next, previous, up + @section Electric Keys and Keywords + @cindex electric characters + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Most punctuation keys provide @dfn{electric} behavior - as well as + inserting themselves they perform some other action, such as + reindenting the line. This reindentation saves you from having to + reindent a line manually after typing, say, a @samp{@}}. A few + keywords, such as @code{else}, also trigger electric action. + + You can inhibit the electric behaviour described here by disabling + electric minor mode (@pxref{Minor Modes}). + + Common to all these keys is that they only behave electrically when + used in normal code (as contrasted with getting typed in a string + literal or comment). Those which cause re-indentation do so only when + @code{c-syntactic-indentation} has a non-@code{nil} value (which it + does by default). + + These keys and keywords are: + @c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more + @c like a bug in the code than a bug in this document. It'll get + @c fixed in the code sometime. + + @table @kbd + @item # + @kindex # + @findex c-electric-pound + @findex electric-pound (c-) + @vindex c-electric-pound-behavior + @vindex electric-pound-behavior (c-) + Pound (bound to @code{c-electric-pound}) is electric when typed as the + first non-whitespace character on a line and not within a macro + definition. In this case, the variable @code{c-electric-pound-behavior} + is consulted for the electric behavior. This variable takes a list + value, although the only element currently defined is @code{alignleft}, + which tells this command to force the @samp{#} character into column + zero. This is useful for entering preprocessor macro definitions. + + Pound is not electric in AWK buffers, where @samp{#} starts a comment, + and is bound to @code{self-insert-command} like any typical printable + character. + @c ACM, 2004/8/24: Change this (and the code) to do AWK comment + @c reindentation. + + @item * + @kindex * + @itemx / + @kindex / + @findex c-electric-star + @findex electric-star (c-) + @findex c-electric-slash + @findex electric-slash (c-) + A star (bound to @code{c-electric-star}) or a slash + (@code{c-electric-slash}) causes reindentation when you type it as the + second component of a C style block comment opener (@samp{/*}) or a + C++ line comment opener (@samp{//}) respectively, but only if the + comment opener is the first thing on the line (i.e. there's only + whitespace before it). + + Additionally, you can configure @ccmode{} so that typing a slash at + the start of a line within a block comment will terminate the + comment. You don't need to have electric minor mode enabled to get + this behaviour. @xref{Clean-ups}. + + In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not + electric. + + @item < + @kindex < + @itemx > + @kindex > + @findex c-electric-lt-gt + @findex electric-lt-gt (c-) + A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is + electric in two circumstances: when it is an angle bracket in a C++ + @samp{template} declaration (and similar constructs in other + languages) and when it is the second of two @kbd{<} or @kbd{>} + characters in a C++ style stream operator. In either case, the line + is reindented. Angle brackets in C @samp{#include} directives are not + electric. + + @item ( + @kindex ( + @itemx ) + @kindex ) + @findex c-electric-paren + @findex electric-paren (c-) + The normal parenthesis characters @samp{(} and @samp{)} (bound to + @code{c-electric-paren}) reindent the current line. This is useful + for getting the closing parenthesis of an argument list aligned + automatically. + + You can also configure @ccmode{} to insert a space automatically + between a function name and the @samp{(} you've just typed, and to + remove it automatically after typing @samp{)}, should the argument + list be empty. You don't need to have electric minor mode enabled to + get these actions. @xref{Clean-ups}. + + @item @{ + @kindex @{ + @itemx @} + @kindex @} + @findex c-electric-brace + @findex electric-brace (c-) + Typing a brace (bound to @code{c-electric-brace}) reindents the + current line. Also, one or more newlines might be inserted if + auto-newline minor mode is enabled. @xref{Auto-newlines}. + Additionally, you can configure @ccmode{} to compact excess whitespace + inserted by auto-newline mode in certain circumstances. + @xref{Clean-ups}. + + @item : + @kindex : + @findex c-electric-colon + @findex electric-colon (c-) + Typing a colon (bound to @code{c-electric-colon}) reindents the + current line. Additionally, one or more newlines might be inserted if + auto-newline minor mode is enabled. @xref{Auto-newlines}. If you + type a second colon immediately after such an auto-newline, by default + the whitespace between the two colons is removed, leaving a C++ scope + operator. @xref{Clean-ups}. + + If you prefer, you can insert @samp{::} in a single operation, + avoiding all these spurious reindentations, newlines, and clean-ups. + @xref{Other Commands}. + + @item ; + @kindex ; + @itemx , + @kindex , + @findex c-electric-semi&comma + @findex electric-semi&comma (c-) + Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) + reindents the current line. Also, a newline might be inserted if + auto-newline minor mode is enabled. @xref{Auto-newlines}. + Additionally, you can configure @ccmode{} so that when auto-newline + has inserted whitespace after a @samp{@}}, it will be removed again + when you type a semicolon or comma just after it. @xref{Clean-ups}. + + @end table + + @deffn Command c-electric-continued-statement + @findex electric-continued-statement (c-) + + Certain keywords are electric, causing reindentation when they are + preceded only by whitespace on the line. The keywords are those that + continue an earlier statement instead of starting a new one: + @code{else}, @code{while}, @code{catch} (only in C++ and Java) and + @code{finally} (only in Java). + + An example: + + @example + @group + for (i = 0; i < 17; i++) + if (a[i]) + res += a[i]->offset; + else + @end group + @end example + + Here, the @code{else} should be indented like the preceding @code{if}, + since it continues that statement. @ccmode{} will automatically + reindent it after the @code{else} has been typed in full, since only + then is it possible to decide whether it's a new statement or a + continuation of the preceding @code{if}. + + @vindex abbrev-mode + @findex abbrev-mode + @cindex Abbrev mode + @ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}}) + to accomplish this. It's therefore turned on by default in all language + modes except IDL mode, since CORBA IDL doesn't have any statements. + @end deffn + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands + @comment node-name, next, previous, up + @section Auto-newline Insertion + @cindex auto-newline + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor + Modes}), @ccmode{} inserts newlines for you automatically (in certain + syntactic contexts) when you type a left or right brace, a colon, a + semicolon, or a comma. Sometimes a newline appears before the + character you type, sometimes after it, sometimes both. + + Auto-newline only triggers when the following conditions hold: + + @itemize @bullet + @item + Auto-newline minor mode is enabled, as evidenced by the indicator + @samp{a} after the mode name on the modeline (e.g. @samp{C/a} or + @samp{C/la}). + + @item + The character was typed at the end of a line, or with only whitespace + after it, and possibly a @samp{\} escaping the newline. + + @item + The character is not on its own line already. (This applies only to + insertion of a newline @emph{before} the character.) + + @item + @cindex literal + @cindex syntactic whitespace + The character was not typed inside of a literal @footnote{A + @dfn{literal} is defined as any comment, string, or preprocessor macro + definition. These constructs are also known as @dfn{syntactic + whitespace} since they are usually ignored when scanning C code.}. + + @item + No numeric argument was supplied to the command (i.e. it was typed as + normal, with no @kbd{C-u} prefix). + @end itemize + + You can configure the precise circumstances in which newlines get + inserted (see @pxref{Custom Auto-newlines}). Typically, the style + system (@pxref{Styles}) will have set this up for you, so you probably + won't have to bother. + + Sometimes @ccmode{} inserts an auto-newline where you don't want one, + such as after a @samp{@}} when you're about to type a @samp{;}. + Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can + activate an appropriate @dfn{clean-up}, which will remove the excess + whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a + full description. See also @ref{Electric Keys} for a summary of + clean-ups listed by key. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands + @comment node-name, next, previous, up + @section Hungry Deletion of Whitespace + @cindex hungry-deletion + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + If you want to delete an entire block of whitespace at point, you can + use @dfn{hungry deletion}. This deletes all the contiguous whitespace + either before point or after point in a single operation. + ``Whitespace'' here includes tabs and newlines, but not comments or + preprocessor commands. Hungry deletion can markedly cut down on the + number of times you have to hit deletion keys when, for example, + you've made a mistake on the preceding line and have already pressed + @kbd{C-j}. + + Hungry deletion is a simple feature that some people find extremely + useful. In fact, you might find yourself wanting it in @strong{all} + your editing modes! + + Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the + backspace key'' and @dfn{@key{DELETE}} means ``the forward delete + key''. This is discussed in more detail below. + + There are two different ways you can use hungry deletion: + + @table @asis + @item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} + Here you toggle Hungry Delete minor mode with @kbd{M-x + c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command + was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding + for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This + makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry + deletion. + + @table @asis + @item @kbd{@key{DEL}} (@code{c-electric-backspace}) + @kindex DEL + @findex c-electric-backspace + @findex electric-backspace (c-) + This command is run by default when you hit the @kbd{DEL} key. When + hungry delete mode is enabled, it deletes any amount of whitespace in + the backwards direction. Otherwise, or when used with a prefix + argument or in a literal (@pxref{Auto-newlines}), the command just + deletes backwards in the usual way. (More precisely, it calls the + function contained in the variable @code{c-backspace-function}, + passing it the prefix argument, if any.) + + @item @code{c-backspace-function} + @vindex c-backspace-function + @vindex backspace-function (c-) + @findex backward-delete-char-untabify + Hook that gets called by @code{c-electric-backspace} when it doesn't + do an ``electric'' deletion of the preceding whitespace. The default + value is @code{backward-delete-char-untabify} + (@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which + deletes a single character. + + @item @kbd{C-d} (@code{c-electric-delete-forward}) + @kindex C-d + @findex c-electric-delete-forward + @findex electric-delete-forward (c-) + This function, which is bound to @kbd{C-d} by default, works just like + @code{c-electric-backspace} but in the forward direction. When it + doesn't do an ``electric'' deletion of the following whitespace, it + just does @code{delete-char}, more or less. (Strictly speaking, it + calls the function in @code{c-delete-function} with the prefix + argument.) + + @item @code{c-delete-function} + @vindex c-delete-function + @vindex delete-function (c-) + @findex delete-char + Hook that gets called by @code{c-electric-delete-forward} when it + doesn't do an ``electric'' deletion of the following whitespace. The + default value is @code{delete-char}. + @end table + + @item Using Distinct Bindings + The other (newer and recommended) way to use hungry deletion is to + perform @code{c-hungry-delete-backwards} and + @code{c-hungry-delete-forward} directly through their key sequences + rather than using the minor mode toggling. + + @table @asis + @item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} + @kindex C-c C- + @kindex C-c + @kindex C-c C-DEL + @kindex C-c DEL + @findex c-hungry-delete-backwards + @findex hungry-delete-backwards (c-) + Delete any amount of whitespace in the backwards direction (regardless + whether hungry-delete mode is enabled or not). This command is bound + to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more + natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at + a character terminal. + + @item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward}) + @kindex C-c C-d + @kindex C-c C- + @kindex C-c + @findex c-hungry-delete-forward + @findex hungry-delete-forward (c-) + Delete any amount of whitespace in the forward direction (regardless + whether hungry-delete mode is enabled or not). This command is bound + to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the + same reason as for @key{DEL} above. + @end table + @end table + + @kindex + @kindex + + When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we + actually do so without connecting them to the physical keys commonly + known as @key{Backspace} and @key{Delete}. The default bindings to + those two keys depends on the flavor of (X)Emacs you are using. + + @findex c-electric-delete + @findex electric-delete (c-) + @findex c-hungry-delete + @findex hungry-delete (c-) + @vindex delete-key-deletes-forward + In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to + @code{c-electric-backspace} and the @key{Delete} key is bound to + @code{c-electric-delete}. You control the direction it deletes in by + setting the variable @code{delete-key-deletes-forward}, a standard + XEmacs variable. + @c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). + When this variable is non-@code{nil}, @code{c-electric-delete} will do + forward deletion with @code{c-electric-delete-forward}, otherwise it + does backward deletion with @code{c-electric-backspace}. Similarly, + @kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to + @code{c-hungry-delete} which is controlled in the same way by + @code{delete-key-deletes-forward}. + + @findex normal-erase-is-backspace-mode + + Emacs 21 and later automatically binds @key{Backspace} and + @key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, + and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} + etc. If you need to change the bindings through + @code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt + its extended bindings accordingly. + + In earlier (X)Emacs versions, @ccmode{} doesn't bind either + @key{Backspace} or @key{Delete} directly. Only the key codes + @kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings + to map the physical keys to them. You might need to modify this + yourself if the defaults are unsuitable. + + Getting your @key{Backspace} and @key{Delete} keys properly set up can + sometimes be tricky. The information in @ref{DEL Does Not + Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having + trouble with this in GNU Emacs. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Subword Movement, Other Commands, Hungry WS Deletion, Commands + @comment node-name, next, previous, up + @section Subword Movement and Editing + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex nomenclature + @cindex subword + In spite of the GNU Coding Standards, it is popular to name a symbol + by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget}, + @samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call + these mixed case symbols @dfn{nomenclatures}. Also, each capitalized + (or completely uppercase) part of a nomenclature is called a + @dfn{subword}. Here are some examples: + + @multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} + @c This could be converted to @headitem when we require Texinfo 4.7 + @iftex + @item @b{Nomenclature} + @tab @b{Subwords} + @end iftex + @ifnottex + @item Nomenclature + @tab Subwords + @item --------------------------------------------------------- + @end ifnottex + @item @samp{GtkWindow} + @tab @samp{Gtk} and @samp{Window} + @item @samp{EmacsFrameClass} + @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} + @item @samp{NSGraphicsContext} + @tab @samp{NS}, @samp{Graphics}, and @samp{Context} + @end multitable + + The subword minor mode replaces the basic word oriented movement and + editing commands with variants that recognize subwords in a + nomenclature and treat them as separate words: + + @findex c-forward-subword + @findex forward-subword (c-) + @findex c-backward-subword + @findex backward-subword (c-) + @findex c-mark-subword + @findex mark-subword (c-) + @findex c-kill-subword + @findex kill-subword (c-) + @findex c-backward-kill-subword + @findex backward-kill-subword (c-) + @findex c-transpose-subwords + @findex transpose-subwords (c-) + @findex c-capitalize-subword + @findex capitalize-subword (c-) + @findex c-upcase-subword + @findex upcase-subword (c-) + @findex c-downcase-subword + @findex downcase-subword (c-) + @multitable @columnfractions .20 .40 .40 + @c This could be converted to @headitem when we require Texinfo 4.7 + @iftex + @item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} + @end iftex + @ifnottex + @item Key @tab Word oriented command @tab Subword oriented command + @item ---------------------------------------------------------------------------- + @end ifnottex + @item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} + @item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} + @item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} + @item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} + @item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} + @item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} + @item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} + @item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} + @item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} + @end multitable + + Note that if you have changed the key bindings for the word oriented + commands in your @file{.emacs} or a similar place, the keys you have + configured are also used for the corresponding subword oriented + commands. + + Type @kbd{C-c C-w} to toggle subword mode on and off. To make the + mode turn on automatically, put the following code in your + @file{.emacs}: + + @example + (add-hook 'c-mode-common-hook + (lambda () (c-subword-mode 1))) + @end example + + As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{} + buffers by typing @kbd{M-x c-subword-mode}. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Other Commands, , Subword Movement, Commands + @comment node-name, next, previous, up + @section Other Commands + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Here are the various other commands that didn't fit anywhere else: + + @table @asis + @item @kbd{C-c .} (@code{c-set-style}) + @kindex C-c . + @findex c-set-style + @findex set-style (c-) + Switch to the specified style in the current buffer. Use like this: + + @example + @kbd{C-c . @var{style-name} @key{RET}} + @end example + + You can use the @key{TAB} in the normal way to do completion on the + style name. Note that all style names are case insensitive, even the + ones you define yourself. + + Setting a style in this way does @emph{not} automatically reindent your + file. For commands that you can use to view the effect of your changes, + see @ref{Indentation Commands} and @ref{Filling and Breaking}. + + For details of the @ccmode{} style system, see @ref{Styles}. + @item @kbd{C-c :} (@code{c-scope-operator}) + @kindex C-c : + @findex c-scope-operator + @findex scope-operator (c-) + In C++, it is also sometimes desirable to insert the double-colon scope + operator without performing the electric behavior of colon insertion. + @kbd{C-c :} does just this. + + @item @kbd{C-c C-\} (@code{c-backslash-region}) + @kindex C-c C-\ + @findex c-backslash-region + @findex backslash-region (c-) + This function inserts and aligns or deletes end-of-line backslashes in + the current region. These are typically used in multi-line macros. + + With no prefix argument, it inserts any missing backslashes and aligns + them according to the @code{c-backslash-column} and + @code{c-backslash-max-column} variables. With a prefix argument, it + deletes any backslashes. + + The function does not modify blank lines at the start of the region. If + the region ends at the start of a line, it always deletes the backslash + (if any) at the end of the previous line. + + To customize the precise workings of this command, @ref{Custom Macros}. + @end table + + @noindent + The recommended line breaking function, @code{c-context-line-break} + (@pxref{Filling and Breaking}), is especially nice if you edit + multiline macros frequently. When used inside a macro, it + automatically inserts and adjusts the mandatory backslash at the end + of the line to keep the macro together, and it leaves the point at the + right indentation column for the code. Thus you can write code inside + macros almost exactly as you can elsewhere, without having to bother + with the trailing backslashes. + + @table @asis + @item @kbd{C-c C-e} (@code{c-macro-expand}) + @kindex C-c C-e + @findex c-macro-expand + @findex macro-expand (c-) + This command expands C, C++, Objective C or Pike macros in the region, + using an appropriate external preprocessor program. Normally it + displays its output in a temporary buffer, but if you give it a prefix + arg (with @kbd{C-u C-c C-e}) it will overwrite the original region + with the expansion. + + The command does not work in any of the other modes, and the key + sequence is not bound in these other modes. + + @code{c-macro-expand} isn't actually part of @ccmode{}, even though it + is bound to a @ccmode{} key sequence. If you need help setting it up + or have other problems with it, you can either read its source code or + ask for help in the standard (X)Emacs forums. + @end table + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Font Locking, Config Basics, Commands, Top + @comment node-name, next, previous, up + @chapter Font Locking + @cindex font locking + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex Font Lock mode + + @ccmode{} provides font locking for its supported languages by + supplying patterns for use with Font Lock mode. This means that you + get distinct faces on the various syntactic parts such as comments, + strings, keywords and types, which is very helpful in telling them + apart at a glance and discovering syntactic errors. @xref{Font + Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in + @ccmode{} buffers. + + @strong{Please note:} The font locking in AWK mode is currently not + integrated with the rest of @ccmode{}. Only the last section of this + chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other + sections apply to the other languages. + + @menu + * Font Locking Preliminaries:: + * Faces:: + * Doc Comments:: + * AWK Mode Font Locking:: + @end menu + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Font Locking Preliminaries, Faces, Font Locking, Font Locking + @comment node-name, next, previous, up + @section Font Locking Preliminaries + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The font locking for most of the @ccmode{} languages were provided + directly by the Font Lock package prior to version 5.30 of @ccmode{}. + In the transition to @ccmode{} the patterns have been reworked + completely and are applied uniformly across all the languages except AWK + mode, just like the indentation rules (although each language still has + some peculiarities of its own, of course). Since the languages + previously had completely separate font locking patterns, this means + that it's a bit different in most languages now. + + The main goal for the font locking in @ccmode{} is accuracy, to provide + a dependable aid in recognizing the various constructs. Some, like + strings and comments, are easy to recognize while others, like + declarations and types, can be very tricky. @ccmode{} can go to great + lengths to recognize declarations and casts correctly, especially when + the types aren't recognized by standard patterns. This is a fairly + demanding analysis which can be slow on older hardware, and it can + therefore be disabled by choosing a lower decoration level with the + variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, + emacs, GNU Emacs Manual}). + + @vindex font-lock-maximum-decoration + + The decoration levels are used as follows: + + @enumerate + @comment 1 + @item + Minimal font locking: Fontify only comments, strings and preprocessor + directives (in the languages that use cpp). + + @comment 2 + @item + Fast font locking: In addition to level 1, fontify keywords, simple + types and declarations that are easy to recognize. The variables + @code{*-font-lock-extra-types} (where @samp{*} is the name of the + language) are used to recognize types (see below). Documentation + comments like Javadoc are fontified according to + @code{c-doc-comment-style} (@pxref{Doc Comments}). + + Use this if you think the font locking is too slow. It's the closest + corresponding level to level 3 in the old font lock patterns. + + @comment 3 + @item + Accurate font locking: Like level 2 but uses a different approach that + can recognize types and declarations much more accurately. The + @code{*-font-lock-extra-types} variables are still used, but user + defined types are recognized correctly anyway in most cases. Therefore + those variables should be fairly restrictive and not contain patterns + that are uncertain. + + @cindex Lazy Lock mode + @cindex Just-in-time Lock mode + + This level is designed for fairly modern hardware and a font lock + support mode like Lazy Lock or Just-in-time Lock mode that only + fontifies the parts that are actually shown. Fontifying the whole + buffer at once can easily get bothersomely slow even on contemporary + hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}. + @end enumerate + + @cindex user defined types + @cindex types, user defined + + Since user defined types are hard to recognize you can provide + additional regexps to match those you use: + + @defopt c-font-lock-extra-types + @defoptx c++-font-lock-extra-types + @defoptx objc-font-lock-extra-types + @defoptx java-font-lock-extra-types + @defoptx idl-font-lock-extra-types + @defoptx pike-font-lock-extra-types + For each language there's a variable @code{*-font-lock-extra-types}, + where @samp{*} stands for the language in question. It contains a list + of regexps that matches identifiers that should be recognized as types, + e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} + as is customary in C code. Each regexp should not match more than a + single identifier. + + The default values contain regexps for many types in standard runtime + libraries that are otherwise difficult to recognize, and patterns for + standard type naming conventions like the @samp{_t} suffix in C and C++. + Java, Objective-C and Pike have as a convention to start class names + with capitals, so there are patterns for that in those languages. + + Despite the names of these variables, they are not only used for + fontification but in other places as well where @ccmode{} needs to + recognize types. + @end defopt + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Faces, Doc Comments, Font Locking Preliminaries, Font Locking + @comment node-name, next, previous, up + @section Faces + @cindex faces + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @ccmode{} attempts to use the standard faces for programming languages + in accordance with their intended purposes as far as possible. No extra + faces are currently provided, with the exception of a replacement face + @code{c-invalid-face} for emacsen that don't provide + @code{font-lock-warning-face}. + + @itemize @bullet + @item + @vindex font-lock-comment-face + Normal comments are fontified in @code{font-lock-comment-face}. + + @item + @vindex font-lock-doc-face + @vindex font-lock-doc-string-face + @vindex font-lock-comment-face + Comments that are recognized as documentation (@pxref{Doc Comments}) + get @code{font-lock-doc-face} (Emacs) or + @code{font-lock-doc-string-face} (XEmacs) if those faces exist. If + they don't then @code{font-lock-comment-face} is used. + + @item + @vindex font-lock-string-face + String and character literals are fontified in + @code{font-lock-string-face}. + + @item + @vindex font-lock-keyword-face + Keywords are fontified with @code{font-lock-keyword-face}. + + @item + @vindex font-lock-function-name-face + @code{font-lock-function-name-face} is used for function names in + declarations and definitions, and classes in those contexts. It's also + used for preprocessor defines with arguments. + + @item + @vindex font-lock-variable-name-face + Variables in declarations and definitions, and other identifiers in such + variable contexts, get @code{font-lock-variable-name-face}. It's also + used for preprocessor defines without arguments. + + @item + @vindex font-lock-constant-face + @vindex font-lock-reference-face + Builtin constants are fontified in @code{font-lock-constant-face} if it + exists, @code{font-lock-reference-face} otherwise. As opposed to the + preceding two faces, this is used on the names in expressions, and it's + not used in declarations, even if there happen to be a @samp{const} in + them somewhere. + + @item + @vindex font-lock-type-face + @code{font-lock-type-face} is put on types (both predefined and user + defined) and classes in type contexts. + + @item + @vindex font-lock-constant-face + @vindex font-lock-reference-face + Label identifiers get @code{font-lock-constant-face} if it exists, + @code{font-lock-reference-face} otherwise. + + @item + Name qualifiers and identifiers for scope constructs are fontified like + labels. + + @item + Special markup inside documentation comments are also fontified like + labels. + + @item + @vindex font-lock-preprocessor-face + @vindex font-lock-builtin-face + @vindex font-lock-reference-face + Preprocessor directives get @code{font-lock-preprocessor-face} if it + exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face} + or @code{font-lock-reference-face}, for lack of a closer equivalent. + + @item + @vindex font-lock-warning-face + @vindex c-invalid-face + @vindex invalid-face (c-) + Some kinds of syntactic errors are fontified with + @code{font-lock-warning-face} in Emacs. In older XEmacs versions + there's no corresponding standard face, so there a special + @code{c-invalid-face} is used, which is defined to stand out sharply by + default. + + Note that it's not used for @samp{#error} or @samp{#warning} directives, + since those aren't syntactic errors in themselves. + @end itemize + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Doc Comments, AWK Mode Font Locking, Faces, Font Locking + @comment node-name, next, previous, up + @section Documentation Comments + @cindex documentation comments + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + There are various tools to supply documentation in the source as + specially structured comments, e.g. the standard Javadoc tool in Java. + @ccmode{} provides an extensible mechanism to fontify such comments and + the special markup inside them. + + @defopt c-doc-comment-style + @vindex doc-comment-style (c-) + This is a style variable that specifies which documentation comment + style to recognize, e.g. @code{javadoc} for Javadoc comments. + + The value may also be a list of styles, in which case all of them are + recognized simultaneously (presumably with markup cues that don't + conflict). + + The value may also be an association list to specify different comment + styles for different languages. The symbol for the major mode is then + looked up in the alist, and the value of that element is interpreted as + above if found. If it isn't found then the symbol `other' is looked up + and its value is used instead. + + The default value for @code{c-doc-comment-style} is + @w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. + + Note that @ccmode{} uses this variable to set other variables that + handle fontification etc. That's done at mode initialization or when + you switch to a style which sets this variable. Thus, if you change it + in some other way, e.g. interactively in a CC Mode buffer, you will need + to do @kbd{M-x java-mode} (or whatever mode you're currently using) to + reinitialize. + + @findex c-setup-doc-comment-style + @findex setup-doc-comment-style (c-) + Note also that when @ccmode{} starts up, the other variables are + modified before the mode hooks are run. If you change this variable in + a mode hook, you'll have to call @code{c-setup-doc-comment-style} + afterwards to redo that work. + @end defopt + + @ccmode{} currently provides handing of the following doc comment + styles: + + @table @code + @item javadoc + @cindex Javadoc markup + Javadoc comments, the standard tool in Java. + + @item autodoc + @cindex Pike autodoc markup + For Pike autodoc markup, the standard in Pike. + + @item gtkdoc + @cindex GtkDoc markup + For GtkDoc markup, widely used in the Gnome community. + @end table + + The above is by no means complete. If you'd like to see support for + other doc comment styles, please let us know (@pxref{Mailing Lists and + Bug Reports}). + + You can also write your own doc comment fontification support to use + with @code{c-doc-comment-style}: Supply a variable or function + @code{*-font-lock-keywords} where @samp{*} is the name you want to use + in @code{c-doc-comment-style}. If it's a variable, it's prepended to + @code{font-lock-keywords}. If it's a function, it's called at mode + initialization and the result is prepended. For an example, see + @code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. + + If you add support for another doc comment style, please consider + contributing it - send a note to @email{bug-cc-mode@@gnu.org}. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node AWK Mode Font Locking, , Doc Comments, Font Locking + @comment node-name, next, previous, up + @section AWK Mode Font Locking + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The general appearance of font-locking in AWK mode is much like in any + other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs + Lisp Reference Manual}. + + The following faces are, however, used in a non-standard fashion in + AWK mode: + + @table @asis + @item @code{font-lock-variable-name-face} + This face was intended for variable declarations. Since variables are + not declared in AWK, this face is used instead for AWK system + variables (such as @code{NF}) and ``Special File Names'' (such as + @code{"/dev/stderr"}). + + @item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs) + This face is normally used for preprocessor directives in @ccmode{}. + There are no such things in AWK, so this face is used instead for + standard functions (such as @code{match}). + + @item @code{font-lock-string-face} + As well as being used for strings, including localizable strings, + (delimited by @samp{"} and @samp{_"}), this face is also used for AWK + regular expressions (delimited by @samp{/}). + + @item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) + This face highlights the following syntactically invalid AWK + constructs: + + @itemize @bullet + @item + An unterminated string or regular expression. Here the opening + delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in + @code{font-lock-warning-face}. This is most noticeable when typing in a + new string/regular expression into a buffer, when the warning-face + serves as a continual reminder to terminate the construct. + + AWK mode fontifies unterminated strings/regular expressions + differently from other modes: Only the text up to the end of the line + is fontified as a string (escaped newlines being handled correctly), + rather than the text up to the next string quote. + + @item + A space between the function name and opening parenthesis when calling + a user function. The last character of the function name and the + opening parenthesis are highlighted. This font-locking rule will + spuriously highlight a valid concatenation expression where an + identifier precedes a parenthesised expression. Unfortunately. + + @item + Whitespace following the @samp{\} in what otherwise looks like an + escaped newline. The @samp{\} is highlighted. + @end itemize + @end table + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Config Basics, Custom Filling and Breaking, Font Locking, Top + @comment node-name, next, previous, up + @chapter Configuration Basics + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex Emacs Initialization File + @cindex Configuration + You configure @ccmode{} by setting Lisp variables and calling (and + perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't + difficult.}, which is usually done by adding code to an Emacs + initialization file. This file might be @file{site-start.el} or + @file{.emacs} or @file{init.el} or @file{default.el} or perhaps some + other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For + the sake of conciseness, we just call this file ``your @file{.emacs}'' + throughout the rest of the manual. + + Several of these variables (currently 16), are known collectively as + @dfn{style variables}. @ccmode{} provides a special mechanism, known + as @dfn{styles} to make it easier to set these variables as a group, + to ``inherit'' settings from one style into another, and so on. Style + variables remain ordinary Lisp variables, whose values can be read and + changed independently of the style system. @xref{Style Variables}. + + There are several ways you can write the code, depending on the + precise effect you want---they are described further down on this page. + If you are new to @ccmode{}, we suggest you begin with the simplest + method, ``Top-level commands or the customization interface''. + + If you make conflicting settings in several of these ways, the way + that takes precedence is the one that appears latest in this list: + @itemize @asis + @item + @table @asis + @item Style + @itemx Top-level command or ``customization interface'' + @itemx Hook + @itemx File Style + @end table + @end itemize + + Here is a summary of the different ways of writing your configuration + settings: + + @table @asis + @item Top-level commands or the ``customization interface'' + Most simply, you can write @code{setq} and similar commands at the top + level of your @file{.emacs} file. When you load a @ccmode{} buffer, + it initializes its configuration from these global values (at least, + for those settings you have given values to), so it makes sense to + have these @code{setq} commands run @emph{before} @ccmode{} is first + initialized---in particular, before any call to @code{desktop-read} + (@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For + example, you might set c-basic-offset thus: + + @example + (setq c-basic-offset 4) + @end example + + You can use the more user friendly Customization interface instead, + but this manual does not cover in detail how that works. To do this, + start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. + @xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. + @c The following note really belongs in the Emacs manual. + Emacs normally writes the customizations at the end of your + @file{.emacs} file. If you use @code{desktop-read}, you should edit + your @file{.emacs} to place the call to @code{desktop-read} @emph{after} + the customizations. + + The first initialization of @ccmode{} puts a snapshot of the + configuration settings into the special style @code{user}. + @xref{Built-in Styles}. + + For basic use of Emacs, either of these ways of configuring is + adequate. However, the settings are then the same in all @ccmode{} + buffers and it can be clumsy to communicate them between programmers. + For more flexibility, you'll want to use one (or both) of @ccmode{}'s + more sophisticated facilities, hooks and styles. + + @item Hooks + An Emacs @dfn{hook} is a place to put Lisp functions that you want + Emacs to execute later in specific circumstances. + @xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main + hook and a language-specific hook for each language it supports - any + functions you put onto these hooks get executed as the last part of a + buffer's initialization. Typically you put most of your customization + within the main hook, and use the language-specific hooks to vary the + customization settings between language modes. For example, if you + wanted different (non-standard) values of @code{c-basic-offset} in C + Mode and Java Mode buffers, you could do it like this: + + @example + @group + (defun my-c-mode-hook () + (setq c-basic-offset 3)) + (add-hook 'c-mode-hook 'my-c-mode-hook) + + (defun my-java-mode-hook () + (setq c-basic-offset 6)) + (add-hook 'java-mode-hook 'my-java-mode-hook) + @end group + @end example + + See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. + + @item Styles + A @ccmode{} @dfn{style} is a coherent collection of customizations + with a name. At any time, exactly one style is active in each + @ccmode{} buffer, either the one you have selected or a default. + @ccmode{} is delivered with several existing styles. Additionally, + you can create your own styles, possibly based on these existing + styles. If you worked in a programming team called the ``Free + Group'', which had its own coding standards, you might well have this + in your @file{.emacs} file: + + @example + (setq c-default-style '((java-mode . "java") + (awk-mode . "awk") + (other . "free-group-style"))) + @end example + + See @ref{Styles} for fuller details on using @ccmode{} styles and how + to create them. + + @item File Styles + A @dfn{file style} is a rarely used variant of the ``style'' mechanism + described above, which applies to an individual source file. To use + it, you set certain Emacs local variables in a special block at the + end of the source file. @xref{File Styles}. + + @item Hooks with Styles + For ultimate flexibility, you can use hooks and styles together. For + example, if your team were developing a product which required a + Linux driver, you'd probably want to use the ``linux'' style for the + driver, and your own team's style for the rest of the code. You + could achieve this with code like this in your @file{.emacs}: + + @example + @group + (defun my-c-mode-hook () + (c-set-style + (if (and (buffer-file-name) + (string-match "/usr/src/linux" (buffer-file-name))) + "linux" + "free-group-style"))) + (add-hook 'c-mode-hook 'my-c-mode-hook) + @end group + @end example + + In a programming team, a hook is a also a good place for each member + to put his own personal preferences. For example, you might be the + only person in your team who likes Auto-newline minor mode. You could + have it enabled by default by placing the following in your + @file{.emacs}: + + @example + @group + (defun my-turn-on-auto-newline () + (c-toggle-auto-newline 1)) + (add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) + @end group + @end example + @end table + + @menu + * CC Hooks:: + * Style Variables:: + * Styles:: + @end menu + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node CC Hooks, Style Variables, Config Basics, Config Basics + @comment node-name, next, previous, up + @section Hooks + @cindex mode hooks + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @c The node name is "CC Hooks" rather than "Hooks" because of a bug in + @c some older versions of Info, e.g. the info.el in GNU Emacs 21.3. + @c If you go to "Config Basics" and hit on the xref to "CC + @c Hooks" the function Info-follow-reference searches for "*Note: CC + @c Hooks" from the beginning of the page. If this node were instead + @c named "Hooks", that search would spuriously find "*Note: + @c Hooks(elisp)" and go to the wrong node. + + @ccmode{} provides several hooks that you can use to customize the + mode for your coding style. The main hook is + @code{c-mode-common-hook}; typically, you'll put the bulk of your + customizations here. In addition, each language mode has its own + hook, allowing you to fine tune your settings individually for the + different @ccmode{} languages, and there is a package initialization + hook. Finally, there is @code{c-special-indent-hook}, which enables + you to solve anomalous indentation problems. It is described in + @ref{Other Indentation}, not here. All these hooks adhere to the + standard Emacs conventions. + + When you open a buffer, @ccmode{} first initializes it with the + currently active style (@pxref{Styles}). Then it calls + @code{c-mode-common-hook}, and finally it calls the language-specific + hook. Thus, any style settings done in these hooks will override + those set by @code{c-default-style}. + + @defvar c-initialization-hook + @vindex initialization-hook (c-) + Hook run only once per Emacs session, when @ccmode{} is initialized. + This is a good place to change key bindings (or add new ones) in any + of the @ccmode{} key maps. @xref{Sample .emacs File}. + @end defvar + + @defvar c-mode-common-hook + @vindex mode-common-hook (c-) + Common hook across all languages. It's run immediately before the + language specific hook. + @end defvar + + @defvar c-mode-hook + @defvarx c++-mode-hook + @defvarx objc-mode-hook + @defvarx java-mode-hook + @defvarx idl-mode-hook + @defvarx pike-mode-hook + @defvarx awk-mode-hook + The language specific mode hooks. The appropriate one is run as the + last thing when you enter that language mode. + @end defvar + + Although these hooks are variables defined in @ccmode{}, you can give + them values before @ccmode{}'s code is loaded---indeed, this is the + only way to use @code{c-initialization-hook}. Their values aren't + overwritten when @ccmode{} gets loaded. + + Here's a simplified example of what you can add to your @file{.emacs} + file to do things whenever any @ccmode{} language is edited. See the + Emacs manuals for more information on customizing Emacs via hooks. + @xref{Sample .emacs File}, for a more complete sample @file{.emacs} + file. + + @example + (defun my-c-mode-common-hook () + ;; my customizations for all of c-mode and related modes + (no-case-fold-search) + ) + (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) + @end example + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Style Variables, Styles, CC Hooks, Config Basics + @comment node-name, next, previous, up + @section Style Variables + @cindex styles + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex style variables + The variables that @ccmode{}'s style system control are called + @dfn{style variables}. Note that style variables are ordinary Lisp + variables, which the style system initializes; you can change their + values at any time (e.g. in a hook function). The style system can + also set other variables, to some extent. @xref{Styles}. + + @dfn{Style variables} are handled specially in several ways: + + @itemize @bullet + @item + Style variables are by default buffer-local variables. However, they + can instead be made global by setting + @code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is + initialized. + + @item + @vindex c-old-style-variable-behavior + @vindex old-style-variable-behavior (c-) + The default global binding of any style variable (with two exceptions + - see below) is the special symbol @code{set-from-style}. When the + style system initializes a buffer-local copy of a style variable for a + @ccmode{} buffer, if its global binding is still that symbol then it + will be set from the current style. Otherwise it will retain its + global default@footnote{This is a big change from versions of + @ccmode{} earlier than 5.26, where such settings would get overridden + by the style system unless special precautions were taken. That was + changed since it was counterintuitive and confusing, especially to + novice users. If your configuration depends on the old overriding + behavior, you can set the variable + @code{c-old-style-variable-behavior} to non-@code{nil}.}. This + ``otherwise'' happens, for example, when you've set the variable with + @code{setq} at the top level of your @file{.emacs} (@pxref{Config + Basics}). + + @item + The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is + an association list with an element for each syntactic symbol. It's + handled a little differently from the other style variables. It's + default global binding is the empty list @code{nil}, rather than + @code{set-from-style}. Before the style system is initialized, you + can add individual elements to @code{c-offsets-alist} by calling + @code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set + other style variables with @code{setq}. Those elements will then + prevail when the style system later initializes a buffer-local copy of + @code{c-offsets-alist}. + + @item + The style variable @code{c-special-indent-hook} is also handled in a + special way. Styles can only add functions to this hook, not remove + them, so any global settings you put on it are always + preserved@footnote{This did not change in version 5.26.}. The value + you give this variable in a style definition can be either a function + or a list of functions. + + @item + The global bindings of the style variables get captured in the special + @code{user} style when the style system is first initialized. + @xref{Built-in Styles}, for details. + @end itemize + + The style variables are:@* + @code{c-indent-comment-alist}, + @code{c-indent-comments-syntactically-p} (@pxref{Indentation + Commands});@* + @code{c-doc-comment-style} (@pxref{Doc Comments});@* + @code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} + (@pxref{Custom Filling and Breaking});@* + @code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* + @code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* + @code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and + Commas});@* + @code{c-cleanup-list} (@pxref{Clean-ups});@* + @code{c-basic-offset} (@pxref{Customizing Indentation});@* + @code{c-offsets-alist} (@pxref{c-offsets-alist});@* + @code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* + @code{c-special-indent-hook}, @code{c-label-minimum-indentation} + (@pxref{Other Indentation});@* + @code{c-backslash-column}, @code{c-backslash-max-column} + (@pxref{Custom Macros}). + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Styles, , Style Variables, Config Basics + @comment node-name, next, previous, up + @section Styles + @cindex styles + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + By @dfn{style} we mean the layout of the code---things like how many + columns to indent a block of code, whether an opening brace gets + indented to the level of the code it encloses, or of the construct + that introduces it, or ``hangs'' at the end of a line. + + Most people only need to edit code formatted in just a few well-defined + and consistent styles. For example, their organization might impose a + ``blessed'' style that all its programmers must conform to. Similarly, + people who work on GNU software will have to use the GNU coding style. + Some shops are more lenient, allowing a variety of coding styles, and as + programmers come and go, there could be a number of styles in use. For + this reason, @ccmode{} makes it convenient for you to set up logical + groupings of customizations called @dfn{styles}, associate a single name + for any particular style, and pretty easily start editing new or + existing code using these styles. + + @menu + * Built-in Styles:: + * Choosing a Style:: + * Adding Styles:: + * File Styles:: + @end menu + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Built-in Styles, Choosing a Style, Styles, Styles + @comment node-name, next, previous, up + @subsection Built-in Styles + @cindex styles, built-in + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + If you're lucky, one of @ccmode{}'s built-in styles might be just + what you're looking for. These are: + + @table @code + @item gnu + @cindex GNU style + Coding style blessed by the Free Software Foundation + for C code in GNU programs. + + @item k&r + @cindex K&R style + The classic Kernighan and Ritchie style for C code. + + @item bsd + @cindex BSD style + Also known as ``Allman style'' after Eric Allman. + + @item whitesmith + @cindex Whitesmith style + Popularized by the examples that came with Whitesmiths C, an early + commercial C compiler. + + @item stroustrup + @cindex Stroustrup style + The classic Stroustrup style for C++ code. + + @item ellemtel + @cindex Ellemtel style + Popular C++ coding standards as defined by ``Programming in C++, Rules + and Recommendations,'' Erik Nyquist and Mats Henricson, + Ellemtel@footnote{This document is available at + @uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other + places.}. + @c N.B. This URL was still valid at 2005/8/28 (ACM). + + @item linux + @cindex Linux style + C coding standard for Linux (the kernel). + + @item python + @cindex Python style + C coding standard for Python extension modules@footnote{Python is a + high level scripting language with a C/C++ foreign function interface. + For more information, see @uref{http://www.python.org/}.}. + + @item java + @cindex Java style + The style for editing Java code. Note that the default + value for @code{c-default-style} installs this style when you enter + @code{java-mode}. + + @item awk + @cindex AWK style + The style for editing AWK code. Note that the default value for + @code{c-default-style} installs this style when you enter + @code{awk-mode}. + + @item user + @cindex User style + This is a special style created by you. It consists of the factory + defaults for all the style variables as modified by the customizations + you do either with the Customization interface or by writing + @code{setq}s and @code{c-set-offset}s at the top level of your + @file{.emacs} file (@pxref{Config Basics}). The style system creates + this style as part of its initialization and doesn't modify it + afterwards. + @end table + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Choosing a Style, Adding Styles, Built-in Styles, Styles + @comment node-name, next, previous, up + @subsection Choosing a Style + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + When you create a new buffer, its style will be set from + @code{c-default-style}. The factory default is the style @code{gnu}, + except in Java and AWK modes where it's @code{java} and @code{awk}. + + Remember that if you set a style variable with the Customization + interface or at the top level of your @file{.emacs} file before the + style system is initialised (@pxref{Config Basics}), this setting will + override the one that the style system would have given the variable. + + To set a buffer's style interactively, use the command @kbd{C-c .} + (@pxref{Other Commands}). To set it from a file's local variable + list, @ref{File Styles}. + + @defopt c-default-style + @vindex default-style (c-) + This variable specifies which style to install by default in new + buffers. It takes either a style name string, or an association list + of major mode symbols to style names: + + @enumerate + @item + When @code{c-default-style} is a string, it must be an existing style + name. This style is then used for all modes. + + @item + When @code{c-default-style} is an association list, the mode language + is looked up to find a style name string. + + @item + If @code{c-default-style} is an association list where the mode + language mode isn't found then the special symbol @samp{other} is + looked up. If it's found then the associated style is used. + + @item + If @samp{other} is not found then the @samp{gnu} style is used. + @end enumerate + + In all cases, the style described in @code{c-default-style} is installed + @emph{before} the language hooks are run, so you can always override + this setting by including an explicit call to @code{c-set-style} in your + language mode hook, or in @code{c-mode-common-hook}. + + The standard value of @code{c-default-style} is @w{@code{((java-mode + . "java") (awk-mode . "awk") (other . "gnu"))}}. + @end defopt + + @defvar c-indentation-style + @vindex indentation-style (c-) + This variable always contains the buffer's current style name, as a + string. + @end defvar + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Adding Styles, File Styles, Choosing a Style, Styles + @comment node-name, next, previous, up + @subsection Adding and Amending Styles + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + If none of the built-in styles is appropriate, you'll probably want to + create a new @dfn{style definition}, possibly based on an existing + style. To do this, put the new style's settings into a list with the + following format - the list can then be passed as an argument to the + function @code{c-add-style}. You can see an example of a style + definition in @ref{Sample .emacs File}. + + @cindex style definition + @c @defvr {List} style definition + @table @asis + @item Structure of a Style Definition List + ([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) + + Optional @var{base-style}, if present, must be a string which is the + name of the @dfn{base style} from which this style inherits. At most + one @var{base-style} is allowed in a style definition. If + @var{base-style} is not specified, the style inherits from the table + of factory default values@footnote{This table is stored internally in + the variable c-fallback-style.} instead. All styles eventually + inherit from this internal table. Style loops generate errors. The + list of pre-existing styles can be seen in @ref{Built-in Styles}. + + The dotted pairs (@var{variable} . @var{value}) each consist of a + variable and the value it is to be set to when the style is later + activated.@footnote{Note that if the variable has been given a value + by the Customization interface or a @code{setq} at the top level of + your @file{.emacs}, this value will override the one the style system + tries to give it. @xref{Config Basics}.} The variable can be either a + @ccmode{} style variable or an arbitrary Emacs variable. In the + latter case, it is @emph{not} made buffer-local by the @ccmode{} style + system. + @c @end defvr + + Two variables are treated specially in the dotted pair list: + + @table @code + @item c-offsets-alist + The value is in turn a list of dotted pairs of the form + + @example + (@r{@var{syntactic-symbol}} . @r{@var{offset}}) + @end example + + as described in @ref{c-offsets-alist}. These are passed to + @code{c-set-offset} so there is no need to set every syntactic symbol + in your style, only those that are different from the inherited style. + + @item c-special-indent-hook + The value is added to @code{c-special-indent-hook} using + @code{add-hook}, so any functions already on it are kept. If the value + is a list, each element of the list is added with @code{add-hook}. + @end table + @end table + + Styles are kept in the @code{c-style-alist} variable, but you + should never modify this variable directly. Instead, @ccmode{} + provides the function @code{c-add-style} for this purpose. + + @defun c-add-style stylename description &optional set-p + @findex add-style (c-) + Add or update a style called @var{stylename}, a string. + @var{description} is the new style definition in the form described + above. If @var{stylename} already exists in @code{c-style-alist} then + it is replaced by @var{description}. (Note, this replacement is + total. The old style is @emph{not} merged into the new one.) + Otherwise, a new style is added. + + If the optional @var{set-p} is non-@code{nil} then the new style is + applied to the current buffer as well. The use of this facility is + deprecated and it might be removed from @ccmode{} in a future release. + You should use @code{c-set-style} instead. + + The sample @file{.emacs} file provides a concrete example of how a new + style can be added and automatically set. @xref{Sample .emacs File}. + @end defun + + @defvar c-style-alist + @vindex style-alist (c-) + This is the variable that holds the definitions for the styles. It + should not be changed directly; use @code{c-add-style} instead. + @end defvar + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node File Styles, , Adding Styles, Styles + @comment node-name, next, previous, up + @subsection File Styles + @cindex styles, file local + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex file local variables + + The Emacs manual describes how you can customize certain variables on a + per-file basis by including a @dfn{file local variable} block at the end + of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{}, + @emacsmantitle{}}). + + So far, you've only seen a functional interface for setting styles in + @ccmode{}, and this can't be used here. @ccmode{} fills the gap by + providing two variables for use in a file's local variable list. + Don't use them anywhere else! These allow you to customize the style + on a per-file basis: + + @defvar c-file-style + @vindex file-style (c-) + Set this variable to a style name string in the Local Variables list. + From now on, when you visit the file, @ccmode{} will automatically set + the file's style to this one using @code{c-set-style}. + @end defvar + + @defvar c-file-offsets + @vindex file-offsets (c-) + Set this variable (in the Local Variables list) to an association list + of the same format as @code{c-offsets-alist}. From now on, when you + visit the file, @ccmode{} will automatically institute these offsets + using @code{c-set-offset}. + @end defvar + + Note that file style settings (i.e. @code{c-file-style}) are applied + before file offset settings + (i.e. @code{c-file-offsets})@footnote{Also, if either of these are set + in a file's local variable section, all the style variable values are + made local to that buffer, even if + @code{c-style-variables-are-local-p} is @code{nil}. Since this + variable is virtually always non-@code{nil} anyhow, you're unlikely to + notice this effect.}. + + If you set any variables, including style variables, by the file local + variables mechanism, these settings take priority over all other + settings, even those in your mode hooks (@pxref{CC Hooks}). If you + use @code{c-file-style} or @code{c-file-offsets} and also explicitly + set a style variable in a local variable block, the explicit setting + will take priority. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top + @comment node-name, next, previous, up + @chapter Customizing Filling and Line Breaking + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Since there's a lot of normal text in comments and string literals, + @ccmode{} provides features to edit these like in text mode. It does + this by hooking in on the different line breaking functions and tuning + relevant variables as necessary. + + @vindex c-comment-prefix-regexp + @vindex comment-prefix-regexp (c-) + @cindex comment line prefix + @vindex comment-start + @vindex comment-end + @vindex comment-start-skip + @vindex paragraph-start + @vindex paragraph-separate + @vindex paragraph-ignore-fill-prefix + @vindex adaptive-fill-mode + @vindex adaptive-fill-regexp + @vindex adaptive-fill-first-line-regexp + To make Emacs recognize comments and treat text in them as normal + paragraphs, @ccmode{} makes several standard + variables@footnote{@code{comment-start}, @code{comment-end}, + @code{comment-start-skip}, @code{paragraph-start}, + @code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, + @code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and + @code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them + according to the language syntax and the comment line prefix. + + @defopt c-comment-prefix-regexp + @vindex comment-prefix-regexp (c-) + This style variable contains the regexp used to recognize the + @dfn{comment line prefix}, which is the line decoration that starts + every line in a comment. The variable is either the comment line + prefix itself, or (more usually) an association list with different + values for different languages. The symbol for the major mode is + looked up in the alist to get the regexp for the language, and if it + isn't found then the special symbol @samp{other} is looked up instead. + + When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} + inserts the comment line prefix from a neighbouring line at the start + of the new line. The default value of c-comment-prefix-regexp is + @samp{//+\\|\\**}, which matches C++ style line comments like + + @example + // blah blah + @end example + + @noindent + with two or more slashes in front of them, and the second and + subsequent lines of C style block comments like + + @example + @group + /* + * blah blah + */ + @end group + @end example + + @noindent + with zero or more stars at the beginning of every line. If you change + this variable, please make sure it still matches the comment starter + (i.e. @code{//}) of line comments @emph{and} the line prefix inside + block comments. + + @findex c-setup-paragraph-variables + @findex setup-paragraph-variables (c-) + Also note that since @ccmode{} uses the value of + @code{c-comment-prefix-regexp} to set up several other variables at + mode initialization, there won't be any effect if you just change it + inside a @ccmode{} buffer. You need to call the command + @code{c-setup-paragraph-variables} too, to update those other + variables. That's also the case if you modify + @code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will + already have set up these variables before calling the hook. + @end defopt + + In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt + the line prefix from the other lines in the comment. + + @vindex adaptive-fill-mode + @cindex Adaptive Fill mode + @ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU + Emacs Manual}) to make Emacs correctly keep the line prefix when + filling paragraphs. That also makes Emacs preserve the text + indentation @emph{inside} the comment line prefix. E.g. in the + following comment, both paragraphs will be filled with the left + margins of the texts kept intact: + + @example + @group + /* Make a balanced b-tree of the nodes in the incoming + * stream. But, to quote the famous words of Donald E. + * Knuth, + * + * Beware of bugs in the above code; I have only + * proved it correct, not tried it. + */ + @end group + @end example + + @findex c-setup-filladapt + @findex setup-filladapt (c-) + @findex filladapt-mode + @vindex filladapt-mode + @cindex Filladapt mode + It's also possible to use other adaptive filling packages, notably Kyle + E. Jones' Filladapt package@footnote{It's available from + @uref{http://www.wonderworks.com/}. As of version 2.12, it does however + lack a feature that makes it work suboptimally when + @code{c-comment-prefix-regexp} matches the empty string (which it does + by default). A patch for that is available from + @uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.}, + @c 2005/11/22: The above is still believed to be the case. + which handles things like bulleted lists nicely. There's a convenience + function @code{c-setup-filladapt} that tunes the relevant variables in + Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with + something like this in your @file{.emacs}: + + @example + (defun my-c-mode-common-hook () + (c-setup-filladapt) + (filladapt-mode 1)) + (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) + @end example + + @defopt c-block-comment-prefix + @vindex block-comment-prefix (c-) + @vindex c-comment-continuation-stars + @vindex comment-continuation-stars (c-) + Normally the comment line prefix inserted for a new line inside a + comment is deduced from other lines in it. However there's one + situation when there's no hint about what the prefix should look like, + namely when a block comment is broken for the first time. This style + variable@footnote{In versions before 5.26, this variable was called + @code{c-comment-continuation-stars}. As a compatibility measure, + @ccmode{} still uses the value on that variable if it's set.} is used + then as the comment prefix. It defaults to @samp{* + }@footnote{Actually, this default setting of + @code{c-block-comment-prefix} typically gets overridden by the default + style @code{gnu}, which sets it to blank. You can see the line + splitting effect described here by setting a different style, + e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment + + @example + /* Got O(n^2) here, which is a Bad Thing. */ + @end example + + @noindent + break into + + @example + @group + /* Got O(n^2) here, which + * is a Bad Thing. */ + @end group + @end example + + Note that it won't work to adjust the indentation by putting leading + spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the + normal indentation engine to indent the line. Thus, the right way to + fix the indentation is by customizing the @code{c} syntactic symbol. It + defaults to @code{c-lineup-C-comments}, which handles the indentation of + most common comment styles, see @ref{Line-Up Functions}. + @end defopt + + @defopt c-ignore-auto-fill + @vindex ignore-auto-fill (c-) + When auto fill mode is enabled, @ccmode{} can selectively ignore it + depending on the context the line break would occur in, e.g. to never + break a line automatically inside a string literal. This variable + takes a list of symbols for the different contexts where auto-filling + never should occur: + + @table @code + @item string + Inside a string or character literal. + @item c + Inside a C style block comment. + @item c++ + Inside a C++ style line comment. + @item cpp + Inside a preprocessor directive. + @item code + Anywhere else, i.e. in normal code. + @end table + + By default, @code{c-ignore-auto-fill} is set to @code{(string cpp + code)}, which means that when auto-fill mode is activated, + auto-filling only occurs in comments. In literals, it's often + desirable to have explicit control over newlines. In preprocessor + directives, the necessary @samp{\} escape character before the newline + is not automatically inserted, so an automatic line break would + produce invalid code. In normal code, line breaks are normally + dictated by some logical structure in the code rather than the last + whitespace character, so automatic line breaks there will produce poor + results in the current implementation. + @end defopt + + @vindex comment-multi-line + If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,, + @emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and + line prefix are preserved. If inside a comment and + @code{comment-multi-line} is @code{nil}, a new comment of the same + type is started on the next line and indented as appropriate for + comments. + + Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at + startup. The reason is that @kbd{M-j} could otherwise produce sequences + of single line block comments for texts that should logically be treated + as one comment, and the rest of the paragraph handling code + (e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to + inconsistent behavior. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top + @comment node-name, next, previous, up + @chapter Customizing Auto-newlines + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @ccmode{} determines whether to insert auto-newlines in two basically + different ways, depending on the character just typed: + + @table @asis + @item Braces and Colons + @ccmode{} first determines the syntactic context of the brace or colon + (@pxref{Syntactic Symbols}), then looks for a corresponding element in + an alist. This element specifies where to put newlines - this is any + combination of before and after the brace or colon. If no alist + element is found, newlines are inserted both before and after a brace, + but none are inserted around a colon. See @ref{Hanging Braces} and + @ref{Hanging Colons}. + + @item Semicolons and Commas + The variable @code{c-hanging-semi&comma-criteria} contains a list of + functions which determine whether to insert a newline after a newly + typed semicolon or comma. @xref{Hanging Semicolons and Commas}. + @end table + + The names of these configuration variables contain @samp{hanging} + because they let you @dfn{hang} the pertinent characters. A character + which introduces a C construct is said to @dfn{hang on the right} when + it appears at the end of a line after other code, being separated by a + line break from the construct it introduces, like the opening brace in: + + @example + @group + while (i < MAX) @{ + total += entry[i]; + entry [i++] = 0; + @} + @end group + @end example + + @noindent + A character @dfn{hangs on the left} when it appears at the start of + the line after the construct it closes off, like the above closing + brace. + + The next chapter, ``Clean-ups'', describes how to configure @ccmode{} + to remove these automatically added newlines in certain specific + circumstances. @xref{Clean-ups}. + + @menu + * Hanging Braces:: + * Hanging Colons:: + * Hanging Semicolons and Commas:: + @end menu + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines + @comment node-name, next, previous, up + @section Hanging Braces + @cindex hanging braces + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + To specify which kinds of braces you want auto-newlines put around, + you set the style variable @code{c-hanging-braces-alist}. Its + structure and semantics are described in this section. Details of how + to set it up, and its relationship to CC Mode's style system are given + in @ref{Style Variables}. + + Say you wanted an auto-newline after (but not before) the following + @samp{@{}: + + @example + if (foo < 17) @{ + @end example + + @noindent + First you need to find the @dfn{syntactic context} of the brace---type + a @key{RET} before the brace to get it on a line of its + own@footnote{Also insert a @samp{\} at the end of the previous line if + you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you + something like: + + @example + ((substatement-open 1061)) + @end example + + @noindent + So here you need to put the entry @code{(substatement-open . (after))} + into @code{c-hanging-braces-alist}. + + If you don't want any auto-newlines for a particular syntactic symbol, + put this into @code{c-hanging-braces-alist}: + + @example + (brace-entry-open) + @end example + + If some brace syntactic symbol is not in @code{c-hanging-brace-alist}, + its entry is taken by default as @code{(before after)}---insert a + newline both before and after the brace. In place of a + ``before/after'' list you can specify a function in this alist---this + is useful when the auto newlines depend on the code around the brace. + + @defopt c-hanging-braces-alist + @vindex hanging-braces-alist (c-) + + This variable is an association list which maps syntactic symbols to + lists of places to insert a newline. @xref{Association + Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the + syntactic symbol, the associated value is either @code{nil}, a list, + or a function. + + @table @asis + @item The Key - the syntactic symbol + The syntactic symbols that are useful as keys in this list are + @code{brace-list-intro}, @code{statement-cont}, + @code{inexpr-class-open}, @code{inexpr-class-close}, and all the + @code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols}, + for a more detailed description of these syntactic symbols, except for + @code{inexpr-class-open} and @code{inexpr-class-close}, which aren't + actual syntactic symbols. Elements with any other value as a key get + ignored. + + The braces of anonymous inner classes in Java are given the special + symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that + they can be distinguished from the braces of normal classes@footnote{The + braces of anonymous classes produce a combination of + @code{inexpr-class}, and @code{class-open} or @code{class-close} in + normal indentation analysis.}. + + Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, + @samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace + lists in this regard, even though they do for normal indentation + purposes. It's currently not possible to set automatic newlines on + these constructs. + + @item The associated value - the ``ACTION'' list or function + The value associated with each syntactic symbol in this association + list is called an @var{action}, which can be either a list or a + function which returns a list. @xref{Custom Braces}, for how to use + a function as a brace hanging @var{action}. + + The list @var{action} (or the list returned by @var{action} when it's + a function) contains some combination of the symbols @code{before} and + @code{after}, directing @ccmode{} where to put newlines in + relationship to the brace being inserted. Thus, if the list contains + only the symbol @code{after}, then the brace hangs on the right side + of the line, as in: + + @example + // here, open braces always `hang' + void spam( int i ) @{ + if( i == 7 ) @{ + dosomething(i); + @} + @} + @end example + + When the list contains both @code{after} and @code{before}, the braces + will appear on a line by themselves, as shown by the close braces in + the above example. The list can also be empty, in which case newlines + are added neither before nor after the brace. + @end table + + If a syntactic symbol is missing entirely from + @code{c-hanging-braces-alist}, it's treated in the same way as an + @var{action} with a list containing @code{before} and @code{after}, so + that braces by default end up on their own line. + + For example, the default value of @code{c-hanging-braces-alist} is: + + @example + ((brace-list-open) + (brace-entry-open) + (statement-cont) + (substatement-open after) + (block-close . c-snug-do-while) + (extern-lang-open after) + (namespace-open after) + (module-open after) + (composition-open after) + (inexpr-class-open after) + (inexpr-class-close before)) + @end example + + @noindent which says that @code{brace-list-open}, + @code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists + inside statements, such as initializers for static array variables + inside functions in C, are recognized as @code{statement-cont}. All + normal substatement blocks are recognized with other symbols.} braces + should both hang on the right side and allow subsequent text to follow + on the same line as the brace. Also, @code{substatement-open}, + @code{extern-lang-open}, and @code{inexpr-class-open} braces should hang + on the right side, but subsequent text should follow on the next line. + The opposite holds for @code{inexpr-class-close} braces; they won't + hang, but the following text continues on the same line. Here, in the + @code{block-close} entry, you also see an example of using a function as + an @var{action}. In all other cases, braces are put on a line by + themselves. + @end defopt + + @menu + * Custom Braces:: + @end menu + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Custom Braces, , Hanging Braces, Hanging Braces + @comment node-name, next, previous, up + @subsection Custom Brace Hanging + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @vindex c-hanging-braces-alist + @vindex hanging-braces-alist (c-) + @cindex action functions + Syntactic symbols aren't the only place where you can customize + @ccmode{} with the lisp equivalent of callback functions. Remember + that @var{action}s are usually a list containing some combination of + the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). + For more flexibility, you can instead specify brace ``hanginess'' by + giving a syntactic symbol an @dfn{action function} in + @code{c-hanging-braces-alist}; this function determines the + ``hanginess'' of a brace, usually by looking at the code near it. + + @cindex customization, brace hanging + An action function is called with two arguments: the syntactic symbol + for the brace (e.g. @code{substatement-open}), and the buffer position + where the brace has been inserted. Point is undefined on entry to an + action function, but the function must preserve it (e.g. by using + @code{save-excursion}). The return value should be a list containing + some combination of @code{before} and @code{after}, including neither + of them (i.e. @code{nil}). + + @defvar c-syntactic-context + @vindex syntactic-context (c-) + During the call to the indentation or brace hanging @var{action} + function, this variable is bound to the full syntactic analysis list. + This might be, for example, @samp{((block-close 73))}. Don't ever + give @code{c-syntactic-context} a value yourself---this would disrupt + the proper functioning of @ccmode{}. + + This variable is also bound in three other circumstances: + (i)@w{ }when calling a c-hanging-semi&comma-criteria function + (@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a + line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a + c-special-indent-hook function (@pxref{Other Indentation}). + @end defvar + + As an example, @ccmode{} itself uses this feature to dynamically + determine the hanginess of braces which close ``do-while'' + constructs: + + @example + void do_list( int count, char** atleast_one_string ) + @{ + int i=0; + do @{ + handle_string( atleast_one_string[i] ); + i++; + @} while( i < count ); + @} + @end example + + @ccmode{} assigns the @code{block-close} syntactic symbol to the + brace that closes the @code{do} construct, and normally we'd like the + line that follows a @code{block-close} brace to begin on a separate + line. However, with ``do-while'' constructs, we want the + @code{while} clause to follow the closing brace. To do this, we + associate the @code{block-close} symbol with the @var{action} function + @code{c-snug-do-while}: + + @example + (defun c-snug-do-while (syntax pos) + "Dynamically calculate brace hanginess for do-while statements." + (save-excursion + (let (langelem) + (if (and (eq syntax 'block-close) + (setq langelem (assq 'block-close c-syntactic-context)) + (progn (goto-char (cdr langelem)) + (if (= (following-char) ?@{) + (forward-sexp -1)) + (looking-at "\\[^_]"))) + '(before) + '(before after))))) + @end example + + @findex c-snug-do-while + @findex snug-do-while (c-) + This function simply looks to see if the brace closes a ``do-while'' + clause and if so, returns the list @samp{(before)} indicating + that a newline should be inserted before the brace, but not after it. + In all other cases, it returns the list @samp{(before after)} so + that the brace appears on a line by itself. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines + @comment node-name, next, previous, up + @section Hanging Colons + @cindex hanging colons + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex customization, colon hanging + @vindex c-hanging-colons-alist + @vindex hanging-colons-alist (c-) + + Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), + colons can also be made to hang using the style variable + @code{c-hanging-colons-alist} - When a colon is typed, @ccmode + determines its syntactic context, looks this up in the alist + @code{c-changing-colons-alist} and inserts up to two newlines + accordingly. Here, however, If @ccmode fails to find an entry for a + syntactic symbol in the alist, no newlines are inserted around the + newly typed colon. + + @defopt c-hanging-colons-alist + @vindex hanging-colons-alist (c-) + + @table @asis + @item The Key - the syntactic symbol + The syntactic symbols appropriate as keys in this association list + are: @code{case-label}, @code{label}, @code{access-label}, + @code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic + Symbols}. Elements with any other value as a key get ignored. + + @item The associate value - the ``ACTION'' list + The @var{action} here is simply a list containing a combination of the + symbols @code{before} and @code{after}. Unlike in + @code{c-hanging-braces-alist}, functions as @var{actions} are not + supported - there doesn't seem to be any need for them. + @end table + @end defopt + + In C++, double-colons are used as a scope operator but because these + colons always appear right next to each other, newlines before and after + them are controlled by a different mechanism, called @dfn{clean-ups} in + @ccmode{}. @xref{Clean-ups}, for details. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines + @comment node-name, next, previous, up + @section Hanging Semicolons and Commas + @cindex hanging semicolons + @cindex hanging commas + @cindex customization, semicolon newlines + @cindex customization, comma newlines + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @defopt c-hanging-semi&comma-criteria + @vindex hanging-semi&comma-criteria (c-) + This style variable takes a list of functions; these get called when + you type a semicolon or comma. The functions are called in order + without arguments. When these functions are entered, point is just + after the newly inserted @samp{;} or @samp{,} and they must preserve + point (e.g., by using @code{save-excursion}). During the call, the + variable @code{c-syntactic-context} is bound to the syntactic context + of the current line@footnote{This was first introduced in @ccmode{} + 5.31.} @pxref{Custom Braces}. These functions don't insert newlines + themselves, rather they direct @ccmode{} whether or not to do so. + They should return one of the following values: + + @table @code + @item t + A newline is to be inserted after the @samp{;} or @samp{,}, and no + more functions from the list are to be called. + @item stop + No more functions from the list are to be called, and no newline is to + be inserted. + @item nil + No determination has been made, and the next function in the list is + to be called. + @end table + + Note that auto-newlines are never inserted @emph{before} a semicolon + or comma. If every function in the list is called without a + determination being made, then no newline is added. + + In AWK mode, this variable is set by default to @code{nil}. In the + other modes, the default value is a list containing a single function, + @code{c-semi&comma-inside-parenlist}. This inserts newlines after all + semicolons, apart from those separating @code{for}-clause statements. + @end defopt + + @defun c-semi&comma-no-newlines-before-nonblanks + @findex semi&comma-no-newlines-before-nonblanks (c-) + This is an example of a criteria function, provided by @ccmode{}. It + prevents newlines from being inserted after semicolons when there is a + non-blank following line. Otherwise, it makes no determination. To + use, add this function to the front of the + @code{c-hanging-semi&comma-criteria} list. + + @example + (defun c-semi&comma-no-newlines-before-nonblanks () + (save-excursion + (if (and (eq last-command-char ?\;) + (zerop (forward-line 1)) + (not (looking-at "^[ \t]*$"))) + 'stop + nil))) + @end example + @end defun + + @defun c-semi&comma-inside-parenlist + @findex semi&comma-inside-parenlist (c-) + @defunx c-semi&comma-no-newlines-for-oneline-inliners + @findex semi&comma-no-newlines-for-oneline-inliners (c-) + The function @code{c-semi&comma-inside-parenlist} is what prevents + newlines from being inserted inside the parenthesis list of @code{for} + statements. In addition to + @code{c-semi&comma-no-newlines-before-nonblanks} described above, + @ccmode{} also comes with the criteria function + @code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses + newlines after semicolons inside one-line inline method definitions + (e.g. in C++ or Java). + @end defun + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top + @comment node-name, next, previous, up + @chapter Clean-ups + @cindex clean-ups + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) + whitespace in specific circumstances and are complementary to colon + and brace hanging. You enable a clean-up by adding its symbol into + @code{c-cleanup-list}, e.g. like this: + + @example + (add-to-list 'c-cleanup-list 'space-before-funcall) + @end example + + On the surface, it would seem that clean-ups overlap the functionality + provided by the @code{c-hanging-*-alist} variables. Clean-ups, + however, are used to adjust code ``after-the-fact'', i.e. to adjust + the whitespace in constructs later than when they were typed. + + Most of the clean-ups remove automatically inserted newlines, and are + only active when auto-newline minor mode is turned on. Others will + work all the time. Note that clean-ups are only performed when there + is nothing but whitespace appearing between the individual components + of the construct, and (apart from @code{comment-close-slash}) when the + construct does not occur within a literal (@pxref{Auto-newlines}). + + @defopt c-cleanup-list + @vindex cleanup-list (c-) + @cindex literal + + You configure @ccmode{}'s clean-ups by setting the style variable + @code{c-cleanup-list}, which is a list of clean-up symbols. By + default, @ccmode{} cleans up only the @code{scope-operator} construct, + which is necessary for proper C++ support. + @end defopt + + These are the clean-ups that are only active when electric and + auto-newline minor modes are enabled: + + @c TBD: Would like to use some sort of @deffoo here; @table indents a + @c bit too much in dvi output. + @table @code + @item brace-else-brace + Clean up @samp{@} else @{} constructs by placing the entire construct on + a single line. Clean up occurs when the open brace after the + @samp{else} is typed. So for example, this: + + @example + @group + void spam(int i) + @{ + if( i==7 ) @{ + dosomething(); + @} + else + @{ + @end group + @end example + + @noindent + appears like this after the last open brace is typed: + + @example + @group + void spam(int i) + @{ + if( i==7 ) @{ + dosomething(); + @} else @{ + @end group + @end example + + @item brace-elseif-brace + Similar to the @code{brace-else-brace} clean-up, but this cleans up + @samp{@} else if (...) @{} constructs. For example: + + @example + @group + void spam(int i) + @{ + if( i==7 ) @{ + dosomething(); + @} + else if( i==3 ) + @{ + @end group + @end example + + @noindent + appears like this after the last open parenthesis is typed: + + @example + @group + void spam(int i) + @{ + if( i==7 ) @{ + dosomething(); + @} else if( + @end group + @end example + + @noindent + and like this after the last open brace is typed: + + @example + @group + void spam(int i) + @{ + if( i==7 ) @{ + dosomething(); + @} else if( i==3 ) @{ + @end group + @end example + + @item brace-catch-brace + Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch + (...) @{} in C++ and Java mode. + + @item empty-defun-braces + Clean up braces following a top-level function or class definition that + contains no body. Clean up occurs when the closing brace is typed. + Thus the following: + + @example + @group + class Spam + @{ + @} + @end group + @end example + + @noindent + is transformed into this when the close brace is typed: + + @example + @group + class Spam + @{@} + @end group + @end example + + @item defun-close-semi + Clean up the terminating semicolon on top-level function or class + definitions when they follow a close brace. Clean up occurs when the + semicolon is typed. So for example, the following: + + @example + @group + class Spam + @{ + ... + @} + ; + @end group + @end example + + @noindent + is transformed into this when the semicolon is typed: + + @example + @group + class Spam + @{ + ... + @}; + @end group + @end example + + @item list-close-comma + Clean up commas following braces in array and aggregate initializers. + Clean up occurs when the comma is typed. The space before the comma + is zapped just like the space before the semicolon in + @code{defun-close-semi}. + + @item scope-operator + Clean up double colons which might designate a C++ scope operator split + across multiple lines@footnote{Certain C++ constructs introduce + ambiguous situations, so @code{scope-operator} clean-ups might not + always be correct. This usually only occurs when scoped identifiers + appear in switch label tags.}. Clean up occurs when the second colon is + typed. You will always want @code{scope-operator} in the + @code{c-cleanup-list} when you are editing C++ code. + + @item one-liner-defun + Clean up a single line of code enclosed by defun braces by removing + the whitespace before and after the code. The clean-up happens when + the closing brace is typed. If the variable + @code{c-max-one-liner-length} is set, the cleanup is only done if the + resulting line would be no longer than the value of that variable. + + For example, consider this AWK code: + + @example + @group + BEGIN @{ + FS = "\t" # use as a field separator + @} + @end group + @end example + + @noindent + It gets compacted to the following when the closing brace is typed: + + @example + @group + BEGIN @{FS = "\t"@} # use as a field separator + @end group + @end example + + @defopt c-max-one-liner-length + @vindex max-one-liner-length (c-) + The maximum length of the resulting line for which the clean-up + @code{one-liner-defun} will be triggered. This length is that of the entire + line, including any leading whitespace and any trailing comment. Its + default value is 80. If the value is zero or @code{nil}, no limit + applies. + @end defopt + @end table + + The following clean-ups are always active when they occur on + @code{c-cleanup-list}, regardless of whether Electric minor mode or + Auto-newline minor mode are enabled: + + @table @code + @item space-before-funcall + Insert a space between the function name and the opening parenthesis + of a function call. This produces function calls in the style + mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT, + SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening + parenthesis is typed. This clean-up should never be active in AWK + Mode, since such a space is syntactically invalid for user defined + functions. + + @item compact-empty-funcall + Clean up any space between the function name and the opening parenthesis + of a function call that has no arguments. This is typically used + together with @code{space-before-funcall} if you prefer the GNU function + call style for functions with arguments but think it looks ugly when + it's only an empty parenthesis pair. I.e. you will get @samp{signal + (SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the + closing parenthesis is typed. + + @item comment-close-slash + When inside a block comment, terminate the comment when you type a slash + at the beginning of a line (i.e. immediately after the comment prefix). + This clean-up removes whitespace preceding the slash and if needed, + inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this + situation if you just want a literal @samp{/} inserted. + @end table + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top + @comment node-name, next, previous, up + @chapter Indentation Engine Basics + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + This chapter will briefly cover how @ccmode{} indents lines of code. + It is helpful to understand the indentation model being used so that + you will know how to customize @ccmode{} for your personal coding + style. All the details are in @ref{Customizing Indentation}. + + @ccmode{} has an indentation engine that provides a flexible and + general mechanism for customizing indentation. When @ccmode{} indents + a line of code, it separates its calculations into two steps: + + @enumerate + @item + @cindex syntactic symbol + @cindex anchor position + It analyzes the line to determine its @dfn{syntactic symbol(s)} (the + kind of language construct it's looking at) and its @dfn{anchor + position} (the position earlier in the file that @ccmode{} will indent + the line relative to). The anchor position might be the location of + an opening brace in the previous line, for example. @xref{Syntactic + Analysis}. + @item + @cindex offsets + @cindex indentation offset specifications + It looks up the syntactic symbol(s) in the configuration to get the + corresponding @dfn{offset(s)}. The symbol @code{+}, which means + ``indent this line one more level'' is a typical offset. @ccmode{} + then applies these offset(s) to the anchor position, giving the + indentation for the line. The different sorts of offsets are + described in @ref{c-offsets-alist}. + @end enumerate + + In exceptional circumstances, the syntax directed indentation + described here may be a nuisance rather than a help. You can disable + it by setting @code{c-syntactic-indentation} to @code{nil}. (To set + the variable interactively, @ref{Minor Modes}). + + @defopt c-syntactic-indentation + @vindex syntactic-indentation (c-) + When this is non-@code{nil} (which it is by default), the indentation + of code is done according to its syntactic structure. When it's + @code{nil}, every line is just indented to the same level as the + previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the + indentation in steps of @code{c-basic-offset}. The current style + (@pxref{Config Basics}) then has no effect on indentation, nor do any + of the variables associated with indentation, not even + @code{c-special-indent-hook}. + @end defopt + + @menu + * Syntactic Analysis:: + * Syntactic Symbols:: + * Indentation Calculation:: + @end menu + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics + @comment node-name, next, previous, up + @section Syntactic Analysis + @cindex syntactic analysis + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex syntactic element + @cindex syntactic context + The first thing @ccmode{} does when indenting a line of code, is to + analyze the line, determining the @dfn{syntactic context} of the + (first) construct on that line. It's a list of @dfn{syntactic + elements}, where each syntactic element in turn is a list@footnote{In + @ccmode 5.28 and earlier, a syntactic element was a dotted pair; the + cons was the syntactic symbol and the cdr was the anchor position. + For compatibility's sake, the parameter passed to a line-up function + still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a + brief and typical example: + + @example + ((defun-block-intro 1959)) + @end example + + @cindex syntactic symbol + @noindent + The first thing inside each syntactic element is always a + @dfn{syntactic symbol}. It describes the kind of construct that was + recognized, e.g. @code{statement}, @code{substatement}, + @code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, + for a complete list of currently recognized syntactic symbols and + their semantics. The remaining entries are various data associated + with the recognized construct - there might be zero or more. + + @cindex anchor position + Conceptually, a line of code is always indented relative to some + position higher up in the buffer (typically the indentation of the + previous line). That position is the @dfn{anchor position} in the + syntactic element. If there is an entry after the syntactic symbol in + the syntactic element list then it's either nil or that anchor position. + + Here is an example. Suppose we had the following code as the only thing + in a C++ buffer @footnote{The line numbers in this and future examples + don't actually appear in the buffer, of course!}: + + @example + 1: void swap( int& a, int& b ) + 2: @{ + 3: int tmp = a; + 4: a = b; + 5: b = tmp; + 6: @} + @end example + + @noindent + We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to + report what the syntactic analysis is for the current line: + + @table @asis + @item @kbd{C-c C-s} (@code{c-show-syntactic-information}) + @kindex C-c C-s + @findex c-show-syntactic-information + @findex show-syntactic-information (c-) + This command calculates the syntactic analysis of the current line and + displays it in the minibuffer. The command also highlights the anchor + position(s). + @end table + + Running this command on line 4 of this example, we'd see in the echo + area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the + analysis is inserted into the buffer as a comment on the current + line.}: + + @example + ((statement 35)) + @end example + + @noindent + and the @samp{i} of @code{int} on line 3 would be highlighted. This + tells us that the line is a statement and it is indented relative to + buffer position 35, the highlighted position. If you were to move + point to line 3 and hit @kbd{C-c C-s}, you would see: + + @example + ((defun-block-intro 29)) + @end example + + @noindent + This indicates that the @samp{int} line is the first statement in a top + level function block, and is indented relative to buffer position 29, + which is the brace just after the function header. + + Here's another example: + + @example + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} + @end example + + @noindent + Hitting @kbd{C-c C-s} on line 4 gives us: + + @example + ((substatement-open 46)) + @end example + + @cindex substatement + @cindex substatement block + @noindent + which tells us that this is a brace that @emph{opens} a substatement + block. @footnote{A @dfn{substatement} is the line after a + conditional statement, such as @code{if}, @code{else}, @code{while}, + @code{do}, @code{switch}, etc. A @dfn{substatement + block} is a brace block following one of these conditional statements.} + + @cindex comment-only line + Syntactic contexts can contain more than one element, and syntactic + elements need not have anchor positions. The most common example of + this is a @dfn{comment-only line}: + + @example + 1: void draw_list( List& drawables ) + 2: @{ + 3: // call the virtual draw() method on each element in list + 4: for( int i=0; i < drawables.count(), ++i ) + 5: @{ + 6: drawables[i].draw(); + 7: @} + 8: @} + @end example + + @noindent + Hitting @kbd{C-c C-s} on line 3 of this example gives: + + @example + ((comment-intro) (defun-block-intro 46)) + @end example + + @noindent + and you can see that the syntactic context contains two syntactic + elements. Notice that the first element, @samp{(comment-intro)}, has no + anchor position. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics + @comment node-name, next, previous, up + @section Syntactic Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex syntactic symbols, brief list + @vindex c-offsets-alist + @vindex offsets-alist (c-) + This section is a complete list of the syntactic symbols which appear + in the @code{c-offsets-alist} style variable, along with brief + descriptions. The previous section (@pxref{Syntactic Analysis}) + states what syntactic symbols are and how the indentation engine uses + them. + + More detailed descriptions of these symbols, together with snippets of + source code to which they apply, appear in the examples in the + subsections below. Note that, in the interests of brevity, the anchor + position associated with most syntactic symbols is @emph{not} + specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent + line---this highlights the anchor position. + + @ssindex -open symbols + @ssindex -close symbols + @ssindex -block-intro symbols + The syntactic symbols which indicate brace constructs follow a general + naming convention. When a line begins with an open or close brace, + its syntactic symbol will contain the suffix @code{-open} or + @code{-close} respectively. The first line within the brace block + construct will contain the suffix @code{-block-intro}. + + @ssindex -intro symbols + @ssindex -cont symbols + In constructs which can span several lines, a distinction is usually + made between the first line that introduces the construct and the + lines that continue it. The syntactic symbols that indicate these + lines will contain the suffixes @code{-intro} or @code{-cont} + respectively. + + The best way to understand how all this works is by looking at some + examples. Remember that you can see the syntax of any source code + line by using @kbd{C-c C-s}. + + @table @code + @item string + Inside a multiline string. @ref{Literal Symbols}. + @item c + Inside a multiline C style block comment. @ref{Literal Symbols}. + @item defun-open + Brace that opens a top-level function definition. @ref{Function + Symbols}. + @item defun-close + Brace that closes a top-level function definition. @ref{Function + Symbols}. + @item defun-block-intro + The first line in a top-level defun. @ref{Function Symbols}. + @item class-open + Brace that opens a class definition. @ref{Class Symbols}. + @item class-close + Brace that closes a class definition. @ref{Class Symbols}. + @item inline-open + Brace that opens an in-class inline method. @ref{Class Symbols}. + @item inline-close + Brace that closes an in-class inline method. @ref{Class Symbols}. + @item func-decl-cont + The region between a function definition's argument list and the + function opening brace (excluding K&R argument declarations). In C, + you cannot put anything but whitespace and comments in this region, + however in C++ and Java, @code{throws} declarations and other things + can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not + @c go somewhere better?} + @item knr-argdecl-intro + First line of a K&R C argument declaration. @ref{K&R Symbols}. + @item knr-argdecl + Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. + @item topmost-intro + The first line in a ``topmost'' definition. @ref{Function Symbols}. + @item topmost-intro-cont + Topmost definition continuation lines. This is only used in the parts + that aren't covered by other symbols such as @code{func-decl-cont} and + @code{knr-argdecl}. @ref{Function Symbols}. + @item member-init-intro + First line in a member initialization list. @ref{Class Symbols}. + @item member-init-cont + Subsequent member initialization list lines. @ref{Class Symbols}. + @item inher-intro + First line of a multiple inheritance list. @ref{Class Symbols}. + @item inher-cont + Subsequent multiple inheritance lines. @ref{Class Symbols}. + @item block-open + Statement block open brace. @ref{Literal Symbols}. + @item block-close + Statement block close brace. @ref{Conditional Construct Symbols}. + @item brace-list-open + Open brace of an enum or static array list. @ref{Brace List Symbols}. + @item brace-list-close + Close brace of an enum or static array list. @ref{Brace List Symbols}. + @item brace-list-intro + First line in an enum or static array list. @ref{Brace List Symbols}. + @item brace-list-entry + Subsequent lines in an enum or static array list. @ref{Brace List + Symbols}. + @item brace-entry-open + Subsequent lines in an enum or static array list where the line begins + with an open brace. @ref{Brace List Symbols}. + @item statement + A statement. @ref{Function Symbols}. + @item statement-cont + A continuation of a statement. @ref{Function Symbols}. + @item statement-block-intro + The first line in a new statement block. @ref{Conditional Construct + Symbols}. + @item statement-case-intro + The first line in a case block. @ref{Switch Statement Symbols}. + @item statement-case-open + The first line in a case block that starts with a brace. @ref{Switch + Statement Symbols}. + @item substatement + The first line after a conditional or loop construct. + @ref{Conditional Construct Symbols}. + @item substatement-open + The brace that opens a substatement block. @ref{Conditional Construct + Symbols}. + @item substatement-label + The first line after a conditional or loop construct if it's a label. + @ref{Conditional Construct Symbols}. + @item case-label + A label in a @code{switch} block. @ref{Switch Statement Symbols}. + @item access-label + C++ access control label. @ref{Class Symbols}. + @item label + Any other label. @ref{Literal Symbols}. + @item do-while-closure + The @code{while} line that ends a @code{do}-@code{while} construct. + @ref{Conditional Construct Symbols}. + @item else-clause + The @code{else} line of an @code{if}-@code{else} construct. + @ref{Conditional Construct Symbols}. + @item catch-clause + The @code{catch} or @code{finally} (in Java) line of a + @code{try}-@code{catch} construct. @ref{Conditional Construct + Symbols}. + @item comment-intro + A line containing only a comment introduction. @ref{Literal Symbols}. + @item arglist-intro + The first line in an argument list. @ref{Paren List Symbols}. + @item arglist-cont + Subsequent argument list lines when no arguments follow on the same + line as the arglist opening paren. @ref{Paren List Symbols}. + @item arglist-cont-nonempty + Subsequent argument list lines when at least one argument follows on + the same line as the arglist opening paren. @ref{Paren List Symbols}. + @item arglist-close + The solo close paren of an argument list. @ref{Paren List Symbols}. + @item stream-op + Lines continuing a stream operator (C++ only). @ref{Literal + Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} + @item inclass + The line is nested inside a class definition. @ref{Class Symbols}. + @item cpp-macro + The start of a preprocessor macro definition. @ref{Literal Symbols}. + @item cpp-define-intro + The first line inside a multiline preprocessor macro if + @code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro + Symbols}. + @item cpp-macro-cont + All lines inside multiline preprocessor macros if + @code{c-syntactic-indentation-in-macros} is @code{nil}. + @ref{Multiline Macro Symbols}. + @item friend + A C++ friend declaration. @ref{Class Symbols}. + @item objc-method-intro + The first line of an Objective-C method definition. @ref{Objective-C + Method Symbols}. + @item objc-method-args-cont + Lines continuing an Objective-C method definition. @ref{Objective-C + Method Symbols}. + @item objc-method-call-cont + Lines continuing an Objective-C method call. @ref{Objective-C Method + Symbols}. + @item extern-lang-open + Brace that opens an @code{extern} block (e.g. @code{extern "C" + @{...@}}). @ref{External Scope Symbols}. + @item extern-lang-close + Brace that closes an @code{extern} block. @ref{External Scope + Symbols}. + @item inextern-lang + Analogous to @code{inclass} syntactic symbol, but used inside + @code{extern} blocks. @ref{External Scope Symbols}. + @item namespace-open + @itemx namespace-close + @itemx innamespace + These are analogous to the three @code{extern-lang} symbols above, but + are returned for C++ namespace blocks. @ref{External Scope Symbols}. + @item module-open + @itemx module-close + @itemx inmodule + Analogous to the above, but for CORBA IDL @code{module} blocks. + @ref{External Scope Symbols}. + @item composition-open + @itemx composition-close + @itemx incomposition + Analogous to the above, but for CORBA CIDL @code{composition} blocks. + @ref{External Scope Symbols}. + @item template-args-cont + C++ template argument list continuations. @ref{Class Symbols}. + @item inlambda + Analogous to @code{inclass} syntactic symbol, but used inside lambda + (i.e. anonymous) functions. Only used in Pike mode. @ref{Statement + Block Symbols}. + @item lambda-intro-cont + Lines continuing the header of a lambda function, i.e. between the + @code{lambda} keyword and the function body. Only used in Pike mode. + @ref{Statement Block Symbols}. + @item inexpr-statement + A statement block inside an expression. The gcc C and C++ extension + for this is recognized. It's also used for the special functions that + take a statement block as an argument in Pike. @ref{Statement Block + Symbols}. + @item inexpr-class + A class definition inside an expression. This is used for anonymous + classes in Java. It's also used for anonymous array initializers in + Java. @ref{Anonymous Class Symbol}. + @end table + + @menu + * Function Symbols:: + * Class Symbols:: + * Conditional Construct Symbols:: + * Switch Statement Symbols:: + * Brace List Symbols:: + * External Scope Symbols:: + * Paren List Symbols:: + * Literal Symbols:: + * Multiline Macro Symbols:: + * Objective-C Method Symbols:: + * Anonymous Class Symbol:: + * Statement Block Symbols:: + * K&R Symbols:: + @end menu + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Function Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + This example shows a typical function declaration. + + @example + 1: void + 2: swap( int& a, int& b ) + 3: @{ + 4: int tmp = a; + 5: a = b; + 6: b = tmp; + 7: int ignored = + 8: a + b; + 9: @} + @end example + + @ssindex topmost-intro + @ssindex topmost-intro-cont + @ssindex defun-open + @ssindex defun-close + @ssindex defun-block-intro + Line 1 shows a @code{topmost-intro} since it is the first line that + introduces a top-level construct. Line 2 is a continuation of the + top-level construct introduction so it has the syntax + @code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is + the brace that opens a top-level function definition. Line 9 is the + corresponding + @code{defun-close} since it contains the brace that closes the top-level + function definition. Line 4 is a @code{defun-block-intro}, i.e. it is + the first line of a brace-block, enclosed in a + top-level function definition. + + @ssindex statement + @ssindex statement-cont + Lines 5, 6, and 7 are all given @code{statement} syntax since there + isn't much special about them. Note however that line 8 is given + @code{statement-cont} syntax since it continues the statement begun + on the previous line. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Class related Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Here's an example which illustrates some C++ class syntactic symbols: + + @example + 1: class Bass + 2: : public Guitar, + 3: public Amplifiable + 4: @{ + 5: public: + 6: Bass() + 7: : eString( new BassString( 0.105 )), + 8: aString( new BassString( 0.085 )), + 9: dString( new BassString( 0.065 )), + 10: gString( new BassString( 0.045 )) + 11: @{ + 12: eString.tune( 'E' ); + 13: aString.tune( 'A' ); + 14: dString.tune( 'D' ); + 15: gString.tune( 'G' ); + 16: @} + 17: friend class Luthier; + 18: @}; + @end example + + @ssindex class-open + @ssindex class-close + As in the previous example, line 1 has the @code{topmost-intro} syntax. + Here however, the brace that opens a C++ class definition on line 4 is + assigned the @code{class-open} syntax. Note that in C++, classes, + structs, and unions are essentially equivalent syntactically (and are + very similar semantically), so replacing the @code{class} keyword in the + example above with @code{struct} or @code{union} would still result in a + syntax of @code{class-open} for line 4 @footnote{This is the case even + for C and Objective-C. For consistency, structs in all supported + languages are syntactically equivalent to classes. Note however that + the keyword @code{class} is meaningless in C and Objective-C.}. + Similarly, line 18 is assigned @code{class-close} syntax. + + @ssindex inher-intro + @ssindex inher-cont + Line 2 introduces the inheritance list for the class so it is assigned + the @code{inher-intro} syntax, and line 3, which continues the + inheritance list is given @code{inher-cont} syntax. + + @ssindex access-label + @ssindex inclass + Hitting @kbd{C-c C-s} on line 5 shows the following analysis: + + @example + ((inclass 58) (access-label 58)) + @end example + + @noindent + The primary syntactic symbol for this line is @code{access-label} as + this a label keyword that specifies access protection in C++. However, + because this line is also a top-level construct inside a class + definition, the analysis actually shows two syntactic symbols. The + other syntactic symbol assigned to this line is @code{inclass}. + Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} + syntax: + + @example + ((inclass 58) (topmost-intro 60)) + @end example + + @ssindex member-init-intro + @ssindex member-init-cont + Line 7 introduces a C++ member initialization list and as such is given + @code{member-init-intro} syntax. Note that in this case it is + @emph{not} assigned @code{inclass} since this is not considered a + top-level construct. Lines 8 through 10 are all assigned + @code{member-init-cont} since they continue the member initialization + list started on line 7. + + @cindex in-class inline methods + @ssindex inline-open + @ssindex inline-close + Line 11's analysis is a bit more complicated: + + @example + ((inclass 58) (inline-open)) + @end example + + This line is assigned a syntax of both @code{inline-open} and + @code{inclass} because it opens an @dfn{in-class} C++ inline method + definition. This is distinct from, but related to, the C++ notion of an + inline function in that its definition occurs inside an enclosing class + definition, which in C++ implies that the function should be inlined. + However, if the definition of the @code{Bass} constructor appeared + outside the class definition, the construct would be given the + @code{defun-open} syntax, even if the keyword @code{inline} appeared + before the method name, as in: + + @example + 1: class Bass + 2: : public Guitar, + 3: public Amplifiable + 4: @{ + 5: public: + 6: Bass(); + 7: @}; + 8: + 9: inline + 10: Bass::Bass() + 11: : eString( new BassString( 0.105 )), + 12: aString( new BassString( 0.085 )), + 13: dString( new BassString( 0.065 )), + 14: gString( new BassString( 0.045 )) + 15: @{ + 16: eString.tune( 'E' ); + 17: aString.tune( 'A' ); + 18: dString.tune( 'D' ); + 19: gString.tune( 'G' ); + 20: @} + @end example + + @ssindex friend + Returning to the previous example, line 16 is given @code{inline-close} + syntax, while line 12 is given @code{defun-block-open} syntax, and lines + 13 through 15 are all given @code{statement} syntax. Line 17 is + interesting in that its syntactic analysis list contains three + elements: + + @example + ((inclass 58) (topmost-intro 380) (friend)) + @end example + + The @code{friend} and @code{inline-open} syntactic symbols are + modifiers that do not have anchor positions. + + @ssindex template-args-cont + Template definitions introduce yet another syntactic symbol: + + @example + 1: ThingManager framework_callbacks; + @end example + + Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 + are both analyzed as @code{template-args-cont} lines. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Conditional Construct Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Here is a (totally contrived) example which illustrates how syntax is + assigned to various conditional constructs: + + @example + 1: void spam( int index ) + 2: @{ + 3: for( int i=0; i 0 ); + 15: @} + @end example + + Only the lines that illustrate new syntactic symbols will be discussed. + + @ssindex substatement-open + @ssindex statement-block-intro + @ssindex block-close + Line 4 has a brace which opens a conditional's substatement block. It + is thus assigned @code{substatement-open} syntax, and since line 5 is + the first line in the substatement block, it is assigned + @code{statement-block-intro} syntax. Line 10 contains the brace + that closes the inner substatement block, and is therefore given the + syntax @code{block-close}@footnote{@code{block-open} is used only for + ``free-standing'' blocks, and is somewhat rare (@pxref{Literal + Symbols} for an example.)}. Line 13 is treated the same way. + + @ssindex substatement + Lines 6 and 9 are also substatements of conditionals, but since they + don't start blocks they are given @code{substatement} syntax + instead of @code{substatement-open}. + + @ssindex substatement-label + Line 8 contains a label, which is normally given @code{label} syntax. + This one is however a bit special since it's between a conditional and + its substatement. It's analyzed as @code{substatement-label} to let you + handle this rather odd case differently from normal labels. + + @ssindex else-clause + @ssindex catch-clause + Line 7 start with an @code{else} that matches the @code{if} statement on + line 5. It is therefore given the @code{else-clause} syntax and is + anchored on the matching @code{if}. The @code{try}-@code{catch} + constructs in C++ and Java are treated this way too, except that + @code{catch} and (in Java) @code{finally}, are marked with + @code{catch-clause}. + + @ssindex do-while-closure + The @code{while} construct on line 14 that closes a @code{do} + conditional is given the special syntax @code{do-while-closure} if it + appears on a line by itself. Note that if the @code{while} appeared on + the same line as the preceding close brace, that line would still have + @code{block-close} syntax. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Switch Statement Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Switch statements have their own set of syntactic symbols. Here's an + example: + + @example + 1: void spam( enum Ingredient i ) + 2: @{ + 3: switch( i ) @{ + 4: case Ham: + 5: be_a_pig(); + 6: break; + 7: case Salt: + 8: drink_some_water(); + 9: break; + 10: default: + 11: @{ + 12: what_is_it(); + 13: break; + 14: @} + 15: @} + 14: @} + @end example + + @ssindex case-label + @ssindex statement-case-intro + @ssindex statement-case-open + Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, + while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 + is treated slightly differently since it contains a brace that opens a + block --- it is given @code{statement-case-open} syntax. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Brace List Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex brace lists + There are a set of syntactic symbols that are used to recognize + constructs inside of brace lists. A brace list is defined as an + @code{enum} or aggregate initializer list, such as might statically + initialize an array of structs. The three special aggregate constructs + in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as + brace lists too. An example: + + @example + 1: static char* ingredients[] = + 2: @{ + 3: "Ham", + 4: "Salt", + 5: NULL + 6: @}; + @end example + + @ssindex brace-list-open + @ssindex brace-list-intro + @ssindex brace-list-close + @ssindex brace-list-entry + Following convention, line 2 in this example is assigned + @code{brace-list-open} syntax, and line 3 is assigned + @code{brace-list-intro} syntax. Likewise, line 6 is assigned + @code{brace-list-close} syntax. Lines 4 and 5 however, are assigned + @code{brace-list-entry} syntax, as would all subsequent lines in this + initializer list. + + @ssindex brace-entry-open + Your static initializer might be initializing nested structures, for + example: + + @example + 1: struct intpairs[] = + 2: @{ + 3: @{ 1, 2 @}, + 4: @{ + 5: 3, + 6: 4 + 7: @} + 8: @{ 1, + 9: 2 @}, + 10: @{ 3, 4 @} + 11: @}; + @end example + + Here, you've already seen the analysis of lines 1, 2, 3, and 11. On + line 4, things get interesting; this line is assigned + @code{brace-entry-open} syntactic symbol because it's a bracelist entry + line that starts with an open brace. Lines 5 and 6 (and line 9) are + pretty standard, and line 7 is a @code{brace-list-close} as you'd + expect. Once again, line 8 is assigned as @code{brace-entry-open} as is + line 10. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection External Scope Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + External language definition blocks also have their own syntactic + symbols. In this example: + + @example + 1: extern "C" + 2: @{ + 3: int thing_one( int ); + 4: int thing_two( double ); + 5: @} + @end example + + @ssindex extern-lang-open + @ssindex extern-lang-close + @ssindex inextern-lang + @ssindex inclass + @noindent + line 2 is given the @code{extern-lang-open} syntax, while line 5 is given + the @code{extern-lang-close} syntax. The analysis for line 3 yields: + + @example + ((inextern-lang) (topmost-intro 14)) + @end example + + @noindent + where @code{inextern-lang} is a modifier similar in purpose to + @code{inclass}. + + There are various other top level blocks like @code{extern}, and they + are all treated in the same way except that the symbols are named after + the keyword that introduces the block. E.g. C++ namespace blocks get + the three symbols @code{namespace-open}, @code{namespace-close} and + @code{innamespace}. The currently recognized top level blocks are: + + @table @asis + @item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} + @code{extern} blocks in C and C++.@footnote{These should logically be + named @code{extern-open}, @code{extern-close} and @code{inextern}, but + that isn't the case for historical reasons.} + + @item @code{namespace-open}, @code{namespace-close}, @code{innamespace} + @ssindex namespace-open + @ssindex namespace-close + @ssindex innamespace + @code{namespace} blocks in C++. + + @item @code{module-open}, @code{module-close}, @code{inmodule} + @ssindex module-open + @ssindex module-close + @ssindex inmodule + @code{module} blocks in CORBA IDL. + + @item @code{composition-open}, @code{composition-close}, @code{incomposition} + @ssindex composition-open + @ssindex composition-close + @ssindex incomposition + @code{composition} blocks in CORBA CIDL. + @end table + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Parenthesis (Argument) List Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + A number of syntactic symbols are associated with parenthesis lists, + a.k.a argument lists, as found in function declarations and function + calls. This example illustrates these: + + @example + 1: void a_function( int line1, + 2: int line2 ); + 3: + 4: void a_longer_function( + 5: int line1, + 6: int line2 + 7: ); + 8: + 9: void call_them( int line1, int line2 ) + 10: @{ + 11: a_function( + 12: line1, + 13: line2 + 14: ); + 15: + 16: a_longer_function( line1, + 17: line2 ); + 18: @} + @end example + + @ssindex arglist-intro + @ssindex arglist-close + Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are + the first line following the open parenthesis, and lines 7 and 14 are + assigned @code{arglist-close} syntax since they contain the parenthesis + that closes the argument list. + + @ssindex arglist-cont-nonempty + @ssindex arglist-cont + Lines that continue argument lists can be assigned one of two syntactic + symbols. For example, Lines 2 and 17 + are assigned @code{arglist-cont-nonempty} syntax. What this means + is that they continue an argument list, but that the line containing the + parenthesis that opens the list is @emph{not empty} following the open + parenthesis. Contrast this against lines 6 and 13 which are assigned + @code{arglist-cont} syntax. This is because the parenthesis that opens + their argument lists is the last character on that line. + + Syntactic elements with @code{arglist-intro}, + @code{arglist-cont-nonempty}, and @code{arglist-close} contain two + buffer positions: the anchor position (the beginning of the + declaration or statement) and the position of the open parenthesis. + The latter position can be used in a line-up function (@pxref{Line-Up + Functions}). + + Note that there is no @code{arglist-open} syntax. This is because any + parenthesis that opens an argument list, appearing on a separate line, + is assigned the @code{statement-cont} syntax instead. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Comment String Label and Macro Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + A few miscellaneous syntactic symbols that haven't been previously + covered are illustrated by this C++ example: + + @example + 1: void Bass::play( int volume ) + 2: const + 3: @{ + 4: /* this line starts a multiline + 5: * comment. This line should get `c' syntax */ + 6: + 7: char* a_multiline_string = "This line starts a multiline \ + 8: string. This line should get `string' syntax."; + 9: + 10: note: + 11: @{ + 12: #ifdef LOCK + 13: Lock acquire(); + 14: #endif // LOCK + 15: slap_pop(); + 16: cout << "I played " + 17: << "a note\n"; + 18: @} + 19: @} + @end example + + The lines to note in this example include: + + @itemize @bullet + @item + @ssindex func-decl-cont + Line 2 is assigned the @code{func-decl-cont} syntax. + + @item + @ssindex comment-intro + Line 4 is assigned both @code{defun-block-intro} @emph{and} + @code{comment-intro} syntax. A syntactic element with + @code{comment-intro} has no anchor point --- It is always accompanied + by another syntactic element which does have one. + + @item + @ssindex c + Line 5 is assigned @code{c} syntax. + + @item + @cindex syntactic whitespace + Line 6 which, even though it contains nothing but whitespace, is + assigned @code{defun-block-intro}. Note that the appearance of the + comment on lines 4 and 5 do not cause line 6 to be assigned + @code{statement} syntax because comments are considered to be + @dfn{syntactic whitespace}, which are ignored when analyzing + code. + + @item + @ssindex string + Line 8 is assigned @code{string} syntax. + + @item + @ssindex label + Line 10 is assigned @code{label} syntax. + + @item + @ssindex block-open + Line 11 is assigned @code{block-open} as well as @code{statement} + syntax. A @code{block-open} syntactic element doesn't have an anchor + position, since it always appears with another syntactic element which + does have one. + + @item + @ssindex cpp-macro + Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the + normal syntactic symbols (@code{statement-block-intro} and + @code{statement}, respectively). Normally @code{cpp-macro} is + configured to cancel out the normal syntactic context to make all + preprocessor directives stick to the first column, but that's easily + changed if you want preprocessor directives to be indented like the rest + of the code. Like @code{comment-intro}, a syntactic element with + @code{cpp-macro} doesn't contain an anchor position. + + @item + @ssindex stream-op + Line 17 is assigned @code{stream-op} syntax. + @end itemize + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Multiline Macro Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex multiline macros + @cindex syntactic whitespace + @ssindex cpp-define-intro + @ssindex cpp-macro-cont + Multiline preprocessor macro definitions are normally handled just like + other code, i.e. the lines inside them are indented according to the + syntactic analysis of the preceding lines inside the macro. The first + line inside a macro definition (i.e. the line after the starting line of + the cpp directive itself) gets @code{cpp-define-intro}. In this example: + + @example + 1: #define LIST_LOOP(cons, listp) \ + 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ + 3: if (!CONSP (cons)) \ + 4: signal_error ("Invalid list format", listp); \ + 5: else + @end example + + @noindent + line 1 is given the syntactic symbol @code{cpp-macro}. The first line + of a cpp directive is always given that symbol. Line 2 is given + @code{cpp-define-intro}, so that you can give the macro body as a whole + some extra indentation. Lines 3 through 5 are then analyzed as normal + code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause} + on line 5. + + The syntactic analysis inside macros can be turned off with + @code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In + that case, lines 2 through 5 would all be given @code{cpp-macro-cont} + with an anchor position pointing to the @code{#} which starts the cpp + directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed + macros.}. + + @xref{Custom Macros}, for more info about the treatment of macros. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Objective-C Method Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + In Objective-C buffers, there are three additional syntactic symbols + assigned to various message calling constructs. Here's an example + illustrating these: + + @example + 1: - (void)setDelegate:anObject + 2: withStuff:stuff + 3: @{ + 4: [delegate masterWillRebind:self + 5: toDelegate:anObject + 6: withExtraStuff:stuff]; + 7: @} + @end example + + @ssindex objc-method-intro + @ssindex objc-method-args-cont + @ssindex objc-method-call-cont + Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is + assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both + assigned @code{objc-method-call-cont} syntax. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Anonymous Class Symbol (Java) + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Java has a concept of anonymous classes which can look something like + this: + + @example + 1: public void watch(Observable o) @{ + 2: o.addObserver(new Observer() @{ + 3: public void update(Observable o, Object arg) @{ + 4: history.addElement(arg); + 5: @} + 6: @}); + 7: @} + @end example + + @ssindex inexpr-class + The brace following the @code{new} operator opens the anonymous class. + Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the + @code{inclass} symbol used in normal classes. Thus, the class will be + indented just like a normal class, with the added indentation given to + @code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't + have an anchor position. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols + @comment node-name, next, previous, up + @subsection Statement Block Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + There are a few occasions where a statement block might be used inside + an expression. One is in C or C++ code using the gcc extension for + this, e.g: + + @example + 1: int res = (@{ + 2: int y = foo (); int z; + 3: if (y > 0) z = y; else z = - y; + 4: z; + 5: @}); + @end example + + @ssindex inexpr-statement + Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the + symbols they'd get in a normal block. Therefore, the indentation put on + @code{inexpr-statement} is added to the normal statement block + indentation. An @code{inexpr-statement} syntactic element doesn't + contain an anchor position. + + In Pike code, there are a few other situations where blocks occur inside + statements, as illustrated here: + + @example + 1: array itgob() + 2: @{ + 3: string s = map (backtrace()[-2][3..], + 4: lambda + 5: (mixed arg) + 6: @{ + 7: return sprintf ("%t", arg); + 8: @}) * ", " + "\n"; + 9: return catch @{ + 10: write (s + "\n"); + 11: @}; + 12: @} + @end example + + @ssindex inlambda + @ssindex lambda-intro-cont + Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes + by the @code{lambda} keyword. If the function argument list is put + on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} + syntax. The function body is handled as an inline method body, with the + addition of the @code{inlambda} syntactic symbol. This means that line + 6 gets @code{inlambda} and @code{inline-open}, and line 8 gets + @code{inline-close}@footnote{You might wonder why it doesn't get + @code{inlambda} too. It's because the closing brace is relative to the + opening brace, which stands on its own line in this example. If the + opening brace was hanging on the previous line, then the closing brace + would get the @code{inlambda} syntax too to be indented correctly.}. + + @ssindex inexpr-statement + On line 9, @code{catch} is a special function taking a statement block + as its argument. The block is handled as an in-expression statement + with the @code{inexpr-statement} syntax, just like the gcc extended C + example above. The other similar special function, @code{gauge}, is + handled like this too. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node K&R Symbols, , Statement Block Symbols, Syntactic Symbols + @comment node-name, next, previous, up + @subsection K&R Symbols + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @ssindex knr-argdecl-intro + @ssindex knr-argdecl + Two other syntactic symbols can appear in old style, non-prototyped C + code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: + + @example + 1: int add_three_integers(a, b, c) + 2: int a; + 3: int b; + 4: int c; + 5: @{ + 6: return a + b + c; + 7: @} + @end example + + Here, line 2 is the first line in an argument declaration list and so is + given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines + (i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} + syntax. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics + @comment node-name, next, previous, up + @section Indentation Calculation + @cindex indentation + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Indentation for a line is calculated from the syntactic context + (@pxref{Syntactic Analysis}). + + First, a buffer position is found whose column will be the base for the + indentation calculation. It's the anchor position in the first + syntactic element that provides one that is used. If no syntactic + element has an anchor position then column zero is used. + + Second, the syntactic symbols in each syntactic element are looked up + in the @code{c-offsets-alist} style variable + (@pxref{c-offsets-alist}), which is an association list of syntactic + symbols and the offsets to apply for those symbols. These offsets are + added together with the base column to produce the new indentation + column. + + Let's use our two code examples above to see how this works. Here is + our first example again: + + @example + 1: void swap( int& a, int& b ) + 2: @{ + 3: int tmp = a; + 4: a = b; + 5: b = tmp; + 6: @} + @end example + + Let's say point is on line 3 and we hit the @key{TAB} key to reindent + the line. The syntactic context for that line is: + + @example + ((defun-block-intro 29)) + @end example + + @noindent + Since buffer position 29 is the first and only anchor position in the + list, @ccmode{} goes there and asks for the current column. This brace + is in column zero, so @ccmode{} uses @samp{0} as the base column. + + Next, @ccmode{} looks up @code{defun-block-intro} in the + @code{c-offsets-alist} style variable. Let's say it finds the value + @samp{4}; it adds this to the base column @samp{0}, yielding a running + total indentation of 4 spaces. + + Since there is only one syntactic element on the list for this line, + indentation calculation is complete, and the total indentation for the + line is 4 spaces. + + Here's another example: + + @example + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} + @end example + + If we were to hit @kbd{TAB} on line 4 in the above example, the same + basic process is performed, despite the differences in the syntactic + context. The context for this line is: + + @example + ((substatement-open 46)) + @end example + + Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in + @code{if} on line 3. This character is in the fourth column on that + line so the base column is @samp{4}. Then @ccmode{} looks up the + @code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it + finds the value @samp{4}. It's added with the base column and yields an + indentation for the line of 8 spaces. + + Simple, huh? + + Actually, it's a bit more complicated than that since the entries on + @code{c-offsets-alist} can be much more than plain offsets. + @xref{c-offsets-alist}, for the full story. + + Anyway, the mode usually just does The Right Thing without you having to + think about it in this much detail. But when customizing indentation, + it's helpful to understand the general indentation model being used. + + As you configure @ccmode{}, you might want to set the variable + @code{c-echo-syntactic-information-p} to non-@code{nil} so that the + syntactic context and calculated offset always is echoed in the + minibuffer when you hit @kbd{TAB}. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top + @comment node-name, next, previous, up + @chapter Customizing Indentation + @cindex customization, indentation + @cindex indentation + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The principal variable for customizing indentation is the style + variable @code{c-offsets-alist}, which gives an @dfn{offset} (an + indentation rule) for each syntactic symbol. Its structure and + semantics are completely described in @ref{c-offsets-alist}. The + various ways you can set the variable, including the use of the + @ccmode{} style system, are described in @ref{Config Basics} and its + sections, in particular @ref{Style Variables}. + + The simplest and most used kind of ``offset'' setting in + @code{c-offsets-alist} is in terms of multiples of + @code{c-basic-offset}: + + @defopt c-basic-offset + @vindex basic-offset (c-) + This style variable holds the basic offset between indentation levels. + It's factory default is 4, but all the built-in styles set it + themselves, to some value between 2 (for @code{gnu} style) and 8 (for + @code{bsd}, @code{linux}, and @code{python} styles). + @end defopt + + The most flexible ``offset'' setting you can make in + @code{c-offsets-alist} is a line-up function (or even a list of them), + either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one + you write yourself (@pxref{Custom Line-Up}). + + Finally, in @ref{Other Indentation} you'll find the tool of last + resort: a hook which is called after a line has been indented. You + can install functions here to make ad-hoc adjustments to any line's + indentation. + + @menu + * c-offsets-alist:: + * Interactive Customization:: + * Line-Up Functions:: + * Custom Line-Up:: + * Other Indentation:: + @end menu + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation + @comment node-name, next, previous, up + @section c-offsets-alist + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + This section explains the structure and semantics of the style + variable @code{c-offset-alist}, the principal variable for configuring + indentation. Details of how to set it up, and its relationship to + @ccmode{}'s style system are given in @ref{Style Variables}. + + @defopt c-offsets-alist + @vindex offsets-alist (c-) + This is an alist which associates an offset with each syntactic + symbol. This @dfn{offset} is a rule specifying how to indent a line + whose syntactic context matches the symbol. @xref{Syntactic + Analysis}. + + Note that the buffer-local binding of this alist in a @ccmode{} buffer + contains an entry for @emph{every} syntactic symbol. Its global + binding and its settings within style specifications usually contain + only a few entries. @xref{Style Variables}. + + The offset specification associated with any particular syntactic + symbol can be an integer, a variable name, a vector, a function or + lambda expression, a list, or one of the following special symbols: + @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The + meanings of these values are described in detail below. + + Here is an example fragment of a @code{c-offsets-alist}, showing some + of these kinds of offsets: + + @example + ((statement . 0) + (substatement . +) + (cpp-macro . [0]) + (topmost-intro-cont . c-lineup-topmost-intro-cont) + (statement-block-intro . (add c-lineup-whitesmith-in-block + c-indent-multi-line-block)) + @dots{} + @*) + @end example + @end defopt + + @deffn Command c-set-offset (@kbd{C-c C-o}) + @findex set-offset (c-) + @kindex C-c C-o + This command changes the entry for a syntactic symbol in the current + binding of @code{c-offsets-alist}, or it inserts a new entry if there + isn't already one for that syntactic symbol. + + You can use @code{c-set-offsets} interactively within a @ccmode{} + buffer to make experimental changes to your indentation settings. + @kbd{C-c C-o} prompts you for the syntactic symbol to change + (defaulting to that of the current line) and the new offset + (defaulting to the current offset). + + @code{c-set-offsets} takes two arguments when used programmatically: + @var{symbol}, the syntactic element symbol to change and @var{offset}, + the new offset for that syntactic element. You can call the command + in your @file{.emacs} to change the global binding of + @code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a + hook function to make changes from the current style. @ccmode{} + itself uses this function when initializing styles. + @end deffn + + @cindex offset specification + The ``offset specifications'' in @code{c-offsets-alist} can be any of + the following: + + @table @asis + @item An integer + The integer specifies a relative offset. All relative + offsets@footnote{The syntactic context @code{@w{((defun-block-intro + 2724) (comment-intro))}} would likely have two relative offsets.} will + be added together and used to calculate the indentation relative to an + anchor position earlier in the buffer. @xref{Indentation + Calculation}, for details. Most of the time, it's probably better to + use one of the special symbols like @code{+} than an integer (apart + from zero). + + @item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} + These special symbols describe a relative offset in multiples of + @code{c-basic-offset}: + + By defining a style's indentation in terms of @code{c-basic-offset}, + you can change the amount of whitespace given to an indentation level + while maintaining the same basic shape of your code. Here are the + values that the special symbols correspond to: + + @table @code + @item + + @code{c-basic-offset} times 1 + @item - + @code{c-basic-offset} times -1 + @item ++ + @code{c-basic-offset} times 2 + @item -- + @code{c-basic-offset} times -2 + @item * + @code{c-basic-offset} times 0.5 + @item / + @code{c-basic-offset} times -0.5 + @end table + + @item A vector + The first element of the vector, an integer, sets the absolute + indentation column. This will override any previously calculated + indentation, but won't override relative indentation calculated from + syntactic elements later on in the syntactic context of the line being + indented. @xref{Indentation Calculation}. Any elements in the vector + beyond the first will be ignored. + + @item A function or lambda expression + The function will be called and its return value will in turn be + evaluated as an offset specification. Functions are useful when more + context than just the syntactic symbol is needed to get the desired + indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for + details about them. + + @item A symbol with a variable binding + If the symbol also has a function binding, the function takes + precedence over the variable. Otherwise the value of the variable is + used. It must be an integer (which is used as relative offset) or a + vector (an absolute offset). + + @item A list + The offset can also be a list containing several offset + specifications; these are evaluated recursively and combined. A list + is typically only useful when some of the offsets are line-up + functions. A common strategy is calling a sequence of functions in + turn until one of them recognizes that it is appropriate for the + source line and returns a non-@code{nil} value. + + @code{nil} values are always ignored when the offsets are combined. + The first element of the list specifies the method of combining the + non-@code{nil} offsets from the remaining elements: + + @table @code + @item first + Use the first offset that doesn't evaluate to @code{nil}. Subsequent + elements of the list don't get evaluated. + @item min + Use the minimum of all the offsets. All must be either relative or + absolute - they can't be mixed. + @item max + Use the maximum of all the offsets. All must be either relative or + absolute - they can't be mixed. + @item add + Add all the evaluated offsets together. Exactly one of them may be + absolute, in which case the result is absolute. Any relative offsets + that preceded the absolute one in the list will be ignored in that case. + @end table + + As a compatibility measure, if the first element is none of the above + then it too will be taken as an offset specification and the whole list + will be combined according to the method @code{first}. + @end table + + @vindex c-strict-syntax-p + @vindex strict-syntax-p (c-) + If an offset specification evaluates to @code{nil}, then a relative + offset of 0 (zero) is used@footnote{There is however a variable + @code{c-strict-syntax-p} that when set to non-@code{nil} will cause an + error to be signaled in that case. It's now considered obsolete since + it doesn't work well with some of the alignment functions that return + @code{nil} instead of zero. You should therefore leave + @code{c-strict-syntax-p} set to @code{nil}.}. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation + @comment node-name, next, previous, up + @section Interactive Customization + @cindex customization, interactive + @cindex interactive customization + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + As an example of how to customize indentation, let's change the + style of this example@footnote{In this and subsequent examples, the + original code is formatted using the @samp{gnu} style unless otherwise + indicated. @xref{Styles}.}: + + @example + @group + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} + @end group + @end example + + @noindent + to: + + @example + @group + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} + @end group + @end example + + In other words, we want to change the indentation of braces that open a + block following a condition so that the braces line up under the + conditional, instead of being indented. Notice that the construct we + want to change starts on line 4. To change the indentation of a line, + we need to see which syntactic symbols affect the offset calculations + for that line. Hitting @kbd{C-c C-s} on line 4 yields: + + @example + ((substatement-open 44)) + @end example + + @noindent + so we know that to change the offset of the open brace, we need to + change the indentation for the @code{substatement-open} syntactic + symbol. + + To do this interactively, just hit @kbd{C-c C-o}. This prompts + you for the syntactic symbol to change, providing a reasonable default. + In this case, the default is @code{substatement-open}, which is just the + syntactic symbol we want to change! + + After you hit return, @ccmode{} will then prompt you for the new + offset value, with the old value as the default. The default in this + case is @samp{+}, but we want no extra indentation so enter + @samp{0} and @kbd{RET}. This will associate the offset 0 with the + syntactic symbol @code{substatement-open}. + + To check your changes quickly, just hit @kbd{C-c C-q} + (@code{c-indent-defun}) to reindent the entire function. The example + should now look like: + + @example + @group + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} + @end group + @end example + + Notice how just changing the open brace offset on line 4 is all we + needed to do. Since the other affected lines are indented relative to + line 4, they are automatically indented the way you'd expect. For more + complicated examples, this might not always work. The general approach + to take is to always start adjusting offsets for lines higher up in the + file, then reindent and see if any following lines need further + adjustments. + + @c Move this bit to "Styles" (2005/10/7) + @deffn Command c-set-offset symbol offset + @findex set-offset (c-) + @kindex C-c C-o + This is the command bound to @kbd{C-c C-o}. It provides a convenient + way to set offsets on @code{c-offsets-alist} both interactively (see + the example above) and from your mode hook. + + It takes two arguments when used programmatically: @var{symbol} is the + syntactic element symbol to change and @var{offset} is the new offset + for that syntactic element. + @end deffn + @c End of MOVE THIS BIT. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation + @comment node-name, next, previous, up + @section Line-Up Functions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @cindex line-up function + @cindex indentation function + Often there are cases when a simple offset setting on a syntactic + symbol isn't enough to get the desired indentation---for example, you + might want to line up a closing parenthesis with the matching opening + one rather than indenting relative to its ``anchor point''. @ccmode{} + provides this flexibility with @dfn{line-up functions}. + + The way you associate a line-up function with a syntactic symbol is + described in @ref{c-offsets-alist}. @ccmode{} comes with many + predefined line-up functions for common situations. If none of these + does what you want, you can write your own. @xref{Custom Line-Up}. + Sometimes, it is easier to tweak the standard indentation by adding a + function to @code{c-special-indent-hook} (@pxref{Other Indentation}). + + The line-up functions haven't been adapted for AWK buffers or tested + with them. Some of them might work serendipitously. There shouldn't be + any problems writing custom line-up functions for AWK mode. + + The calling convention for line-up functions is described fully in + @ref{Custom Line-Up}. Roughly speaking, the return value is either an + offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, + meaning ``this function is inappropriate in this case - try a + different one''. @xref{c-offsets-alist}. + + The subsections below describe all the standard line-up functions, + categorized by the sort of token the lining-up centers around. For + each of these functions there is a ``works with'' list that indicates + which syntactic symbols the function is intended to be used with. + + @macro workswith + @emph{Works with:@ } + @end macro + @ifinfo + @unmacro workswith + @macro workswith + Works with: + @end macro + @end ifinfo + + @macro sssTBasicOffset + <--> @i{c-basic-offset}@c + @end macro + + @macro sssTsssTBasicOffset + <--><--> @i{c-basic-offset}@c + @end macro + + @macro hereFn{func} + <- @i{\func\}@c + @end macro + + @c The TeX backend seems to insert extra spaces around the argument. :P + @iftex + @unmacro hereFn + @macro hereFn{func} + <-@i{\func\}@c + @end macro + @end iftex + + @menu + * Brace/Paren Line-Up:: + * List Line-Up:: + * Operator Line-Up:: + * Comment Line-Up:: + * Misc Line-Up:: + @end menu + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions + @comment node-name, next, previous, up + @subsection Brace and Parenthesis Line-Up Functions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The line-up functions here calculate the indentation for braces, + parentheses and statements within brace blocks. + + @defun c-lineup-close-paren + @findex lineup-close-paren (c-) + Line up the closing paren under its corresponding open paren if the + open paren is followed by code. If the open paren ends its line, no + indentation is added. E.g: + + @example + @group + main (int, + char ** + ) @hereFn{c-lineup-close-paren} + @end group + @end example + + @noindent + and + + @example + @group + main ( + int, char ** + ) @hereFn{c-lineup-close-paren} + @end group + @end example + + As a special case, if a brace block is opened at the same line as the + open parenthesis of the argument list, the indentation is + @code{c-basic-offset} instead of the open paren column. See + @code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. + + @workswith All @code{*-close} symbols. + @end defun + + @comment ------------------------------------------------------------ + + @anchor{c-lineup-arglist-close-under-paren} + @defun c-lineup-arglist-close-under-paren + @findex lineup-arglist-close-under-paren (c-) + Set your @code{arglist-close} syntactic symbol to this line-up function + so that parentheses that close argument lists will line up under the + parenthesis that opened the argument list. It can also be used with + @code{arglist-cont} and @code{arglist-cont-nonempty} to line up all + lines inside a parenthesis under the open paren. + + As a special case, if a brace block is opened at the same line as the + open parenthesis of the argument list, the indentation is + @code{c-basic-offset} only. See @code{c-lineup-arglist} for further + discussion of this ``DWIM'' measure. + + @workswith Almost all symbols, but are typically most useful on + @code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and + @code{arglist-cont-nonempty}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-indent-one-line-block + @findex indent-one-line-block (c-) + Indent a one line block @code{c-basic-offset} extra. E.g: + + @example + @group + if (n > 0) + @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} + @sssTBasicOffset{} + @end group + @end example + + @noindent + and + + @example + @group + if (n > 0) + @{ @hereFn{c-indent-one-line-block} + m+=n; n=0; + @} + @end group + @end example + + The block may be surrounded by any kind of parenthesis characters. + @code{nil} is returned if the line doesn't start with a one line block, + which makes the function usable in list expressions. + + @workswith Almost all syntactic symbols, but most useful on the + @code{-open} symbols. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-indent-multi-line-block + @findex indent-multi-line-block (c-) + Indent a multiline block @code{c-basic-offset} extra. E.g: + + @example + @group + int *foo[] = @{ + NULL, + @{17@}, @hereFn{c-indent-multi-line-block} + @end group + @end example + + @noindent + and + + @example + @group + int *foo[] = @{ + NULL, + @{ @hereFn{c-indent-multi-line-block} + 17 + @}, + @sssTBasicOffset{} + @end group + @end example + + The block may be surrounded by any kind of parenthesis characters. + @code{nil} is returned if the line doesn't start with a multiline + block, which makes the function usable in list expressions. + + @workswith Almost all syntactic symbols, but most useful on the + @code{-open} symbols. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-runin-statements + @findex lineup-runin-statements (c-) + Line up statements for coding standards which place the first statement + in a block on the same line as the block opening brace@footnote{Run-in + style doesn't really work too well. You might need to write your own + custom line-up functions to better support this style.}. E.g: + + @example + @group + int main() + @{ puts ("Hello!"); + return 0; @hereFn{c-lineup-runin-statements} + @} + @end group + @end example + + If there is no statement after the opening brace to align with, + @code{nil} is returned. This makes the function usable in list + expressions. + + @workswith The @code{statement} syntactic symbol. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-inexpr-block + @findex lineup-inexpr-block (c-) + This can be used with the in-expression block symbols to indent the + whole block to the column where the construct is started. E.g. for Java + anonymous classes, this lines up the class under the @samp{new} keyword, + and in Pike it lines up the lambda function body under the @samp{lambda} + keyword. Returns @code{nil} if the block isn't part of such a + construct. + + @workswith @code{inlambda}, @code{inexpr-statement}, + @code{inexpr-class}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-after-whitesmith-blocks + @findex lineup-after-whitesmith-blocks (c-) + Compensate for Whitesmith style indentation of blocks. Due to the way + @ccmode{} calculates anchor positions for normal lines inside blocks, + this function is necessary for those lines to get correct Whitesmith + style indentation. Consider the following examples: + + @example + @group + int foo() + @{ + a; + x; @hereFn{c-lineup-after-whitesmith-blocks} + @end group + @end example + + @example + @group + int foo() + @{ + @{ + a; + @} + x; @hereFn{c-lineup-after-whitesmith-blocks} + @end group + @end example + + The fact that the line with @code{x} is preceded by a Whitesmith style + indented block in the latter case and not the first should not affect + its indentation. But since CC Mode in cases like this uses the + indentation of the preceding statement as anchor position, the @code{x} + would in the second case be indented too much if the offset for + @code{statement} was set simply to zero. + + This lineup function corrects for this situation by detecting if the + anchor position is at an open paren character. In that case, it instead + indents relative to the surrounding block just like + @code{c-lineup-whitesmith-in-block}. + + @workswith @code{brace-list-entry}, @code{brace-entry-open}, + @code{statement}, @code{arglist-cont}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-whitesmith-in-block + @findex lineup-whitesmith-in-block (c-) + Line up lines inside a block in Whitesmith style. It's done in a way + that works both when the opening brace hangs and when it doesn't. E.g: + + @example + @group + something + @{ + foo; @hereFn{c-lineup-whitesmith-in-block} + @} + @end group + @end example + + @noindent + and + + @example + @group + something @{ + foo; @hereFn{c-lineup-whitesmith-in-block} + @} + @sssTBasicOffset{} + @end group + @end example + + In the first case the indentation is kept unchanged, in the second + @code{c-basic-offset} is added. + + @workswith @code{defun-close}, @code{defun-block-intro}, + @code{inline-close}, @code{block-close}, @code{brace-list-close}, + @code{brace-list-intro}, @code{statement-block-intro}, + @code{arglist-intro}, @code{arglist-cont-nonempty}, + @code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass} + and @code{inextern-lang}. + @end defun + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions + @comment node-name, next, previous, up + @subsection List Line-Up Functions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The line-up functions here calculate the indentation for lines which + form lists of items, usually separated by commas. + + The function @ref{c-lineup-arglist-close-under-paren}, which is mainly + for indenting a close parenthesis, is also useful for the lines + contained within parentheses. + + @defun c-lineup-arglist + @findex lineup-arglist (c-) + Line up the current argument line under the first argument. + + As a special case, if an argument on the same line as the open + parenthesis starts with a brace block opener, the indentation is + @code{c-basic-offset} only. This is intended as a ``DWIM'' measure in + cases like macros that contain statement blocks, e.g: + + @example + @group + A_VERY_LONG_MACRO_NAME (@{ + some (code, with + long, lines * in[it]); + @}); + @sssTBasicOffset{} + @end group + @end example + + This is motivated partly because it's more in line with how code + blocks are handled, and partly since it approximates the behavior of + earlier CC Mode versions, which due to inaccurate analysis tended to + indent such cases this way. + + @workswith @code{arglist-cont-nonempty}, @code{arglist-close}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-arglist-intro-after-paren + @findex lineup-arglist-intro-after-paren (c-) + Line up a line to just after the open paren of the surrounding paren or + brace block. + + @workswith @code{defun-block-intro}, @code{brace-list-intro}, + @code{statement-block-intro}, @code{statement-case-intro}, + @code{arglist-intro}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-multi-inher + @findex lineup-multi-inher (c-) + Line up the classes in C++ multiple inheritance clauses and member + initializers under each other. E.g: + + @example + @group + Foo::Foo (int a, int b): + Cyphr (a), + Bar (b) @hereFn{c-lineup-multi-inher} + @end group + @end example + + @noindent + and + + @example + @group + class Foo + : public Cyphr, + public Bar @hereFn{c-lineup-multi-inher} + @end group + @end example + + @noindent + and + + @example + @group + Foo::Foo (int a, int b) + : Cyphr (a) + , Bar (b) @hereFn{c-lineup-multi-inher} + @end group + @end example + + @workswith @code{inher-cont}, @code{member-init-cont}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-java-inher + @findex lineup-java-inher (c-) + Line up Java implements and extends declarations. If class names + follow on the same line as the @samp{implements}/@samp{extends} + keyword, they are lined up under each other. Otherwise, they are + indented by adding @code{c-basic-offset} to the column of the keyword. + E.g: + + @example + @group + class Foo + extends + Bar @hereFn{c-lineup-java-inher} + @sssTBasicOffset{} + @end group + @end example + + @noindent + and + + @example + @group + class Foo + extends Cyphr, + Bar @hereFn{c-lineup-java-inher} + @end group + @end example + + @workswith @code{inher-cont}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-java-throws + @findex lineup-java-throws (c-) + Line up Java throws declarations. If exception names follow on the + same line as the throws keyword, they are lined up under each other. + Otherwise, they are indented by adding @code{c-basic-offset} to the + column of the @samp{throws} keyword. The @samp{throws} keyword itself + is also indented by @code{c-basic-offset} from the function declaration + start if it doesn't hang. E.g: + + @example + @group + int foo() + throws @hereFn{c-lineup-java-throws} + Bar @hereFn{c-lineup-java-throws} + @sssTsssTBasicOffset{} + @end group + @end example + + @noindent + and + + @example + @group + int foo() throws Cyphr, + Bar, @hereFn{c-lineup-java-throws} + Vlod @hereFn{c-lineup-java-throws} + @end group + @end example + + @workswith @code{func-decl-cont}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-template-args + @findex lineup-template-args (c-) + Line up the arguments of a template argument list under each other, but + only in the case where the first argument is on the same line as the + opening @samp{<}. + + To allow this function to be used in a list expression, @code{nil} is + returned if there's no template argument on the first line. + + @workswith @code{template-args-cont}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-ObjC-method-call + @findex lineup-ObjC-method-call (c-) + For Objective-C code, line up selector args as Emacs Lisp mode does + with function args: go to the position right after the message receiver, + and if you are at the end of the line, indent the current line + c-basic-offset columns from the opening bracket; otherwise you are + looking at the first character of the first method call argument, so + lineup the current line with it. + + @workswith @code{objc-method-call-cont}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-ObjC-method-args + @findex lineup-ObjC-method-args (c-) + For Objective-C code, line up the colons that separate args. The colon + on the current line is aligned with the one on the first line. + + @workswith @code{objc-method-args-cont}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-ObjC-method-args-2 + @findex lineup-ObjC-method-args-2 (c-) + Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on + the current line with the colon on the previous line. + + @workswith @code{objc-method-args-cont}. + @end defun + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions + @comment node-name, next, previous, up + @subsection Operator Line-Up Functions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The line-up functions here calculate the indentation for lines which + start with an operator, by lining it up with something on the previous + line. + + @defun c-lineup-argcont + @findex lineup-argcont (c-) + Line up a continued argument. E.g: + + @example + @group + foo (xyz, aaa + bbb + ccc + + ddd + eee + fff); @hereFn{c-lineup-argcont} + @end group + @end example + + Only continuation lines like this are touched, @code{nil} is returned on + lines which are the start of an argument. + + Within a gcc @code{asm} block, @code{:} is recognised as an argument + separator, but of course only between operand specifications, not in the + expressions for the operands. + + @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-arglist-operators + @findex lineup-arglist-operators (c-) + Line up lines starting with an infix operator under the open paren. + Return @code{nil} on lines that don't start with an operator, to leave + those cases to other line-up functions. Example: + + @example + @group + if ( x < 10 + || at_limit (x, @hereFn{c-lineup-arglist-operators} + list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} + ) + @end group + @end example + + Since this function doesn't do anything for lines without an infix + operator you typically want to use it together with some other lineup + settings, e.g. as follows (the @code{arglist-close} setting is just a + suggestion to get a consistent style): + + @example + (c-set-offset 'arglist-cont + '(c-lineup-arglist-operators 0)) + (c-set-offset 'arglist-cont-nonempty + '(c-lineup-arglist-operators c-lineup-arglist)) + (c-set-offset 'arglist-close + '(c-lineup-arglist-close-under-paren)) + @end example + + @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-assignments + @findex lineup-assignments (c-) + Line up the current line after the assignment operator on the first line + in the statement. If there isn't any, return nil to allow stacking with + other line-up functions. If the current line contains an assignment + operator too, try to align it with the first one. + + @workswith @code{topmost-intro-cont}, @code{statement-cont}, + @code{arglist-cont}, @code{arglist-cont-nonempty}. + + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-math + @findex lineup-math (c-) + Like @code{c-lineup-assignments} but indent with @code{c-basic-offset} + if no assignment operator was found on the first line. I.e. this + function is the same as specifying a list @code{(c-lineup-assignments + +)}. It's provided for compatibility with old configurations. + + @workswith @code{topmost-intro-cont}, @code{statement-cont}, + @code{arglist-cont}, @code{arglist-cont-nonempty}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-cascaded-calls + @findex lineup-cascaded-calls (c-) + Line up ``cascaded calls'' under each other. If the line begins with + @code{->} or @code{.} and the preceding line ends with one or more + function calls preceded by the same token, then the arrow is lined up + with the first of those tokens. E.g: + + @example + @group + r = proc->add(17)->add(18) + ->add(19) + @hereFn{c-lineup-cascaded-calls} + offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}} + @end group + @end example + + In any other situation @code{nil} is returned to allow use in list + expressions. + + @workswith @code{topmost-intro-cont}, @code{statement-cont}, + @code{arglist-cont}, @code{arglist-cont-nonempty}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-streamop + @findex lineup-streamop (c-) + Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). + + @workswith @code{stream-op}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-string-cont + @findex lineup-string-cont (c-) + Line up a continued string under the one it continues. A continued + string in this sense is where a string literal follows directly after + another one. E.g: + + @example + @group + result = prefix + "A message " + "string."; @hereFn{c-lineup-string-cont} + @end group + @end example + + @code{nil} is returned in other situations, to allow stacking with other + lineup functions. + + @workswith @code{topmost-intro-cont}, @code{statement-cont}, + @code{arglist-cont}, @code{arglist-cont-nonempty}. + @end defun + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions + @comment node-name, next, previous, up + @subsection Comment Line-Up Functions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The lineup functions here calculate the indentation for several types + of comment structure. + + @defun c-lineup-C-comments + @findex lineup-C-comments (c-) + Line up C block comment continuation lines. Various heuristics are used + to handle most of the common comment styles. Some examples: + + @example + @group + /* /** /* + * text * text text + */ */ */ + @end group + @end example + + @example + @group + /* text /* /** + text ** text ** text + */ */ */ + @end group + @end example + + @example + @group + /************************************************** + * text + *************************************************/ + @end group + @end example + + @vindex comment-start-skip + @example + @group + /************************************************** + Free form text comments: + In comments with a long delimiter line at the + start, the indentation is kept unchanged for lines + that start with an empty comment line prefix. The + delimiter line is whatever matches the + @code{comment-start-skip} regexp. + **************************************************/ + @end group + @end example + + The style variable @code{c-comment-prefix-regexp} is used to recognize + the comment line prefix, e.g. the @samp{*} that usually starts every + line inside a comment. + + @workswith The @code{c} syntactic symbol. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-comment + @findex lineup-comment (c-) + Line up a comment-only line according to the style variable + @code{c-comment-only-line-offset}. If the comment is lined up with a + comment starter on the previous line, that alignment is preserved. + + @defopt c-comment-only-line-offset + @vindex comment-only-line-offset (c-) + This style variable specifies the extra offset for the line. It can + contain an integer or a cons cell of the form + + @example + (@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) + @end example + + @noindent + where @var{non-anchored-offset} is the amount of offset given to + non-column-zero anchored lines, and @var{anchored-offset} is the amount + of offset to give column-zero anchored lines. Just an integer as value + is equivalent to @code{(@r{@var{value}} . -1000)}. + @end defopt + + @workswith @code{comment-intro}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-knr-region-comment + @findex lineup-knr-region-comment (c-) + Line up a comment in the ``K&R region'' with the declaration. That is + the region between the function or class header and the beginning of the + block. E.g: + + @example + @group + int main() + /* Called at startup. */ @hereFn{c-lineup-knr-region-comment} + @{ + return 0; + @} + @end group + @end example + + Return @code{nil} if called in any other situation, to be useful in list + expressions. + + @workswith @code{comment-intro}. + @end defun + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Misc Line-Up, , Comment Line-Up, Line-Up Functions + @comment node-name, next, previous, up + @subsection Miscellaneous Line-Up Functions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The line-up functions here are the odds and ends which didn't fit into + any earlier category. + + @defun c-lineup-dont-change + @findex lineup-dont-change (c-) + This lineup function makes the line stay at whatever indentation it + already has; think of it as an identity function for lineups. + + @workswith Any syntactic symbol. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-cpp-define + @findex lineup-cpp-define (c-) + Line up macro continuation lines according to the indentation of the + construct preceding the macro. E.g: + + @example + @group + const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} + \"Some text.\"; + + #define X(A, B) \ + do @{ \ @hereFn{c-lineup-cpp-define} + printf (A, B); \ + @} while (0) + @end group + @end example + + @noindent + and: + + @example + @group + int dribble() @{ + if (!running) @hereFn{@r{The beginning of the preceding construct.}} + error(\"Not running!\"); + + #define X(A, B) \ + do @{ \ @hereFn{c-lineup-cpp-define} + printf (A, B); \ + @} while (0) + @end group + @end example + + If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the + function returns the relative indentation to the macro start line to + allow accumulation with other offsets. E.g. in the following cases, + @code{cpp-define-intro} is combined with the + @code{statement-block-intro} that comes from the @samp{do @{} that hangs + on the @samp{#define} line: + + @example + @group + const char msg[] = + \"Some text.\"; + + #define X(A, B) do @{ \ + printf (A, B); \ @hereFn{c-lineup-cpp-define} + this->refs++; \ + @} while (0) @hereFn{c-lineup-cpp-define} + @end group + @end example + + @noindent + and: + + @example + @group + int dribble() @{ + if (!running) + error(\"Not running!\"); + + #define X(A, B) do @{ \ + printf (A, B); \ @hereFn{c-lineup-cpp-define} + this->refs++; \ + @} while (0) @hereFn{c-lineup-cpp-define} + @end group + @end example + + The relative indentation returned by @code{c-lineup-cpp-define} is zero + and two, respectively, on the two lines in each of these examples. They + are then added to the two column indentation that + @code{statement-block-intro} gives in both cases here. + + If the relative indentation is zero, then @code{nil} is returned + instead. That is useful in a list expression to specify the default + indentation on the top level. + + If @code{c-syntactic-indentation-in-macros} is @code{nil} then this + function keeps the current indentation, except for empty lines (ignoring + the ending backslash) where it takes the indentation from the closest + preceding nonempty line in the macro. If there's no such line in the + macro then the indentation is taken from the construct preceding it, as + described above. + + @workswith @code{cpp-define-intro}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-gcc-asm-reg + @findex lineup-gcc-asm-reg (c-) + Line up a gcc asm register under one on a previous line. + + @example + @group + asm ("foo %1, %0\n" + "bar %0, %1" + : "=r" (w), + "=r" (x) + : "0" (y), + "1" (z)); + @end group + @end example + + The @samp{x} line is aligned to the text after the @samp{:} on the + @samp{w} line, and similarly @samp{z} under @samp{y}. + + This is done only in an @samp{asm} or @samp{__asm__} block, and only to + those lines mentioned. Anywhere else @code{nil} is returned. The usual + arrangement is to have this routine as an extra feature at the start of + arglist lineups, e.g. + + @example + (c-lineup-gcc-asm-reg c-lineup-arglist) + @end example + + @workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. + @end defun + + @comment ------------------------------------------------------------ + + @defun c-lineup-topmost-intro-cont + @findex lineup-topmost-intro-cont (c-) + Line up declaration continuation lines zero or one indentation + step@footnote{This function is mainly provided to mimic the behavior of + CC Mode 5.28 and earlier where this case wasn't handled consistently so + that those lines could be analyzed as either topmost-intro-cont or + statement-cont. It's used for @code{topmost-intro-cont} by default, but + you might consider using @code{+} instead.}. For lines preceding a + definition, zero is used. For other lines, @code{c-basic-offset} is + added to the indentation. E.g: + + @example + @group + int + neg (int i) @hereFn{c-lineup-topmost-intro-cont} + @{ + return -i; + @} + @end group + @end example + + @noindent + and + + @example + @group + struct + larch @hereFn{c-lineup-topmost-intro-cont} + @{ + double height; + @} + the_larch, @hereFn{c-lineup-topmost-intro-cont} + another_larch; @hereFn{c-lineup-topmost-intro-cont} + @sssTBasicOffset{} + @end group + @end example + + @noindent + and + + @example + @group + struct larch + the_larch, @hereFn{c-lineup-topmost-intro-cont} + another_larch; @hereFn{c-lineup-topmost-intro-cont} + @end group + @end example + + @workswith @code{topmost-intro-cont}. + @end defun + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation + @comment node-name, next, previous, up + @section Custom Line-Up Functions + @cindex customization, indentation functions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The most flexible way to customize indentation is by writing custom + line-up functions, and associating them with specific syntactic + symbols (@pxref{c-offsets-alist}). Depending on the effect you want, + it might be better to write a @code{c-special-indent-hook} function + rather than a line-up function (@pxref{Other Indentation}). + + @ccmode{} comes with an extensive set of predefined line-up functions, + not all of which are used by the default styles. So there's a good + chance the function you want already exists. @xref{Line-Up + Functions}, for a list of them. If you write your own line-up + function, it's probably a good idea to start working from one of these + predefined functions, which can be found in the file + @file{cc-align.el}. If you have written a line-up function that you + think is generally useful, you're very welcome to contribute it; + please contact @email{bug-cc-mode@@gnu.org}. + + Line-up functions are passed a single argument, the syntactic + element (see below). The return value is a @code{c-offsets-alist} + offset specification: for example, an integer, a symbol such as + @code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful + when the offset specification for a syntactic element is a list + containing the line-up function (@pxref{c-offsets-alist}).}, or even + another line-up function. Full details of these are in + @ref{c-offsets-alist}. + + Line-up functions must not move point or change the content of the + buffer (except temporarily). They are however allowed to do + @dfn{hidden buffer changes}, i.e. setting text properties for caching + purposes etc. Buffer undo recording is disabled while they run. + + The syntactic element passed as the parameter to a line-up function is + a cons cell of the form + + @example + (@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) + @end example + + @noindent + @c FIXME!!! The following sentence might be better omitted, since the + @c information is in the cross reference "Syntactic Analysis". 2005/10/2. + where @var{syntactic-symbol} is the symbol that the function was + called for, and @var{anchor-position} is the anchor position (if any) + for the construct that triggered the syntactic symbol + (@pxref{Syntactic Analysis}). This cons cell is how the syntactic + element of a line used to be represented in @ccmode{} 5.28 and + earlier. Line-up functions are still passed this cons cell, so as to + preserve compatibility with older configurations. In the future, we + may decide to convert to using the full list format---you can prepare + your setup for this by using the access functions + (@code{c-langelem-sym}, etc.) described below. + + @vindex c-syntactic-element + @vindex syntactic-element (c-) + @vindex c-syntactic-context + @vindex syntactic-context (c-) + Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more + info in the syntactic element - typically other positions that can be + interesting besides the anchor position. That info can't be accessed + through the passed argument, which is a cons cell. Instead, you can + get this information from the variable @code{c-syntactic-element}, + which is dynamically bound to the complete syntactic element. The + variable @code{c-syntactic-context} might also be useful - it gets + dynamically bound to the complete syntactic context. @xref{Custom + Braces}. + + @ccmode{} provides a few functions to access parts of syntactic + elements in a more abstract way. Besides making the code easier to + read, they also hide the difference between the old cons cell form + used in the line-up function argument and the new list form used in + @code{c-syntactic-element} and everywhere else. The functions are: + + @defun c-langelem-sym langelem + @findex langelem-sym (c-) + Return the syntactic symbol in @var{langelem}. + @end defun + + @defun c-langelem-pos langelem + @findex langelem-pos (c-) + Return the anchor position in @var{langelem}, or nil if there is none. + @end defun + + @defun c-langelem-col langelem &optional preserve-point + @findex langelem-col (c-) + Return the column of the anchor position in @var{langelem}. Also move + the point to that position unless @var{preserve-point} is + non-@code{nil}. + @end defun + + @defun c-langelem-2nd-pos langelem + @findex langelem-2nd-pos (c-) + Return the secondary position in @var{langelem}, or @code{nil} if there + is none. + + Note that the return value of this function is always @code{nil} if + @var{langelem} is in the old cons cell form. Thus this function is + only meaningful when used on syntactic elements taken from + @code{c-syntactic-element} or @code{c-syntactic-context}. + @end defun + + Custom line-up functions can be as simple or as complex as you like, and + any syntactic symbol that appears in @code{c-offsets-alist} can have a + custom line-up function associated with it. + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Other Indentation, , Custom Line-Up, Customizing Indentation + @comment node-name, next, previous, up + @section Other Special Indentations + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Here are the remaining odds and ends regarding indentation: + + @defopt c-label-minimum-indentation + @vindex label-minimum-indentation (c-) + In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is + imposed on lines inside code blocks. This minimum indentation is + controlled by this style variable. The default value is 1. + + @findex c-gnu-impose-minimum + @findex gnu-impose-minimum (c-) + It's the function @code{c-gnu-impose-minimum} that enforces this minimum + indentation. It must be present on @code{c-special-indent-hook} to + work. + @end defopt + + @defopt c-special-indent-hook + @vindex special-indent-hook (c-) + This style variable is a standard hook variable that is called after + every line is indented by @ccmode{}. It is called only if + @code{c-syntactic-indentation} is non-@code{nil} (which it is by + default (@pxref{Indentation Engine Basics})). You can put a function + on this hook to do any special indentation or ad hoc line adjustments + your style dictates, such as adding extra indentation to constructors + or destructor declarations in a class definition, etc. Sometimes it + is better to write a custom Line-up Function instead (@pxref{Custom + Line-Up}). + + When the indentation engine calls this hook, the variable + @code{c-syntactic-context} is bound to the current syntactic context + (i.e. what you would get by typing @kbd{C-c C-s} on the source line. + @xref{Custom Braces}.). Note that you should not change point or mark + inside a @code{c-special-indent-hook} function, i.e. you'll probably + want to wrap your function in a @code{save-excursion}@footnote{The + numerical value returned by @code{point} will change if you change the + indentation of the line within a @code{save-excursion} form, but point + itself will still be over the same piece of text.}. + + Setting @code{c-special-indent-hook} in style definitions is handled + slightly differently from other variables---A style can only add + functions to this hook, not remove them. @xref{Style Variables}. + @end defopt + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Custom Macros, Odds and Ends, Customizing Indentation, Top + @comment node-name, next, previous, up + @chapter Customizing Macros + @cindex macros + @cindex preprocessor directives + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Normally, the lines in a multi-line macro are indented relative to + each other as though they were code. You can suppress this behaviour + by setting the following user option: + + @defopt c-syntactic-indentation-in-macros + @vindex syntactic-indentation-in-macros (c-) + Enable syntactic analysis inside macros, which is the default. If this + is @code{nil}, all lines inside macro definitions are analyzed as + @code{cpp-macro-cont}. + @end defopt + + @ccmode{} provides some tools to help keep the line continuation + backslashes in macros neat and tidy. Their precise action is + customized with these variables: + + @defopt c-backslash-column + @vindex backslash-column (c-) + @defoptx c-backslash-max-column + @vindex backslash-max-column (c-) + These variables control the alignment columns for line continuation + backslashes in multiline macros. They are used by the functions that + automatically insert or align such backslashes, + e.g. @code{c-backslash-region} and @code{c-context-line-break}. + + @code{c-backslash-column} specifies the minimum column for the + backslashes. If any line in the macro goes past this column, then the + next tab stop (i.e. next multiple of @code{tab-width}) in that line is + used as the alignment column for all the backslashes, so that they + remain in a single column. However, if any lines go past + @code{c-backslash-max-column} then the backslashes in the rest of the + macro will be kept at that column, so that the lines which are too + long ``stick out'' instead. + + Don't ever set these variables to @code{nil}. If you want to disable + the automatic alignment of backslashes, use + @code{c-auto-align-backslashes}. + @end defopt + + @defopt c-auto-align-backslashes + @vindex auto-align-backslashes (c-) + Align automatically inserted line continuation backslashes if + non-@code{nil}. When line continuation backslashes are inserted + automatically for line breaks in multiline macros, e.g. by + @code{c-context-line-break}, they are aligned with the other + backslashes in the same macro if this flag is set. + + If @code{c-auto-align-backslashes} is @code{nil}, automatically + inserted backslashes are preceded by a single space, and backslashes + get aligned only when you explicitly invoke the command + @code{c-backslash-region} (@kbd{C-c C-\}). + @end defopt + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Odds and Ends, Sample .emacs File, Custom Macros, Top + @comment node-name, next, previous, up + @chapter Odds and Ends + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + The stuff that didn't fit in anywhere else is documented here. + + @defopt c-require-final-newline + @vindex require-final-newline (c-) + Controls whether a final newline is enforced when the file is saved. + The value is an association list that for each language mode specifies + the value to give to @code{require-final-newline} (@pxref{Saving + Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a + language isn't present on the association list, CC Mode won't touch + @code{require-final-newline} in buffers for that language. + + The default is to set @code{require-final-newline} to @code{t} in the + languages that mandate that source files should end with newlines. + These are C, C++ and Objective-C. + @end defopt + + @defopt c-echo-syntactic-information-p + @vindex echo-syntactic-information-p (c-) + If non-@code{nil}, the syntactic analysis for the current line is shown + in the echo area when it's indented (unless + @code{c-syntactic-indentation} is @code{nil}). That's useful when + finding out which syntactic symbols to modify to get the indentation you + want. + @end defopt + + @defopt c-report-syntactic-errors + @vindex report-syntactic-errors (c-) + If non-@code{nil}, certain syntactic errors are reported with a ding and + a message, for example when an @code{else} is indented for which there + is no corresponding @code{if}. + + Note however that @ccmode{} doesn't make any special effort to check for + syntactic errors; that's the job of the compiler. The reason it can + report cases like the one above is that it can't find the correct + anchoring position to indent the line in that case. + @end defopt + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Sample .emacs File, Performance Issues, Odds and Ends, Top + @comment node-name, next, previous, up + @appendix Sample .emacs File + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Here's a sample .emacs file fragment that might help you along the way. + Just copy this region and paste it into your .emacs file. You might want + to change some of the actual values. + + @verbatim + ;; Make a non-standard key binding. We can put this in + ;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, + ;; inherit from it. + (defun my-c-initialization-hook () + (define-key c-mode-base-map "\C-m" 'c-context-line-break)) + (add-hook 'c-initialization-hook 'my-c-initialization-hook) + + ;; offset customizations not in my-c-style + ;; This will take precedence over any setting of the syntactic symbol + ;; made by a style. + (setq c-offsets-alist '((member-init-intro . ++))) + + ;; Create my personal style. + (defconst my-c-style + '((c-tab-always-indent . t) + (c-comment-only-line-offset . 4) + (c-hanging-braces-alist . ((substatement-open after) + (brace-list-open))) + (c-hanging-colons-alist . ((member-init-intro before) + (inher-intro) + (case-label after) + (label after) + (access-label after))) + (c-cleanup-list . (scope-operator + empty-defun-braces + defun-close-semi)) + (c-offsets-alist . ((arglist-close . c-lineup-arglist) + (substatement-open . 0) + (case-label . 4) + (block-open . 0) + (knr-argdecl-intro . -))) + (c-echo-syntactic-information-p . t)) + "My C Programming Style") + (c-add-style "PERSONAL" my-c-style) + + ;; Customizations for all modes in CC Mode. + (defun my-c-mode-common-hook () + ;; set my personal style for the current buffer + (c-set-style "PERSONAL") + ;; other customizations + (setq tab-width 8 + ;; this will make sure spaces are used instead of tabs + indent-tabs-mode nil) + ;; we like auto-newline, but not hungry-delete + (c-toggle-auto-newline 1)) + (add-hook 'c-mode-common-hook 'my-c-mode-common-hook) + @end verbatim + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top + @comment node-name, next, previous, up + @chapter Performance Issues + @cindex performance + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. + + C and its derivative languages are highly complex creatures. Often, + ambiguous code situations arise that require @ccmode{} to scan large + portions of the buffer to determine syntactic context. Such + pathological code can cause @ccmode{} to perform fairly badly. This + section gives some insight in how @ccmode{} operates, how that interacts + with some coding styles, and what you can use to improve performance. + + The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take + more than a fraction of a second) in any interactive operation. + I.e. it's tuned to limit the maximum response time in single operations, + which is sometimes at the expense of batch-like operations like + reindenting whole blocks. If you find that @ccmode{} gradually gets + slower and slower in certain situations, perhaps as the file grows in + size or as the macro or comment you're editing gets bigger, then chances + are that something isn't working right. You should consider reporting + it, unless it's something that's mentioned in this section. + + Because @ccmode{} has to scan the buffer backwards from the current + insertion point, and because C's syntax is fairly difficult to parse in + the backwards direction, @ccmode{} often tries to find the nearest + position higher up in the buffer from which to begin a forward scan + (it's typically an opening or closing parenthesis of some kind). The + farther this position is from the current insertion point, the slower it + gets. + + @findex beginning-of-defun + In earlier versions of @ccmode{}, we used to recommend putting the + opening brace of a top-level construct@footnote{E.g. a function in C, + or outermost class definition in C++ or Java.} into the leftmost + column. Earlier still, this used to be a rigid Emacs constraint, as + embodied in the @code{beginning-of-defun} function. @ccmode now + caches syntactic information much better, so that the delay caused by + searching for such a brace when it's not in column 0 is minimal, + except perhaps when you've just moved a long way inside the file. + + @findex defun-prompt-regexp + @vindex c-Java-defun-prompt-regexp + @vindex Java-defun-prompt-regexp (c-) + A special note about @code{defun-prompt-regexp} in Java mode: The common + style is to hang the opening braces of functions and classes on the + right side of the line, and that doesn't work well with the Emacs + approach. @ccmode{} comes with a constant + @code{c-Java-defun-prompt-regexp} which tries to define a regular + expression usable for this style, but there are problems with it. In + some cases it can cause @code{beginning-of-defun} to hang@footnote{This + has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, + it is not used by default, but if you feel adventurous, you can set + @code{defun-prompt-regexp} to it in your mode hook. In any event, + setting and relying on @code{defun-prompt-regexp} will definitely slow + things down because (X)Emacs will be doing regular expression searches a + lot, so you'll probably be taking a hit either way! + + @ccmode{} maintains a cache of the opening parentheses of the blocks + surrounding the point, and it adapts that cache as the point is moved + around. That means that in bad cases it can take noticeable time to + indent a line in a new surrounding, but after that it gets fast as long + as the point isn't moved far off. The farther the point is moved, the + less useful is the cache. Since editing typically is done in ``chunks'' + rather than on single lines far apart from each other, the cache + typically gives good performance even when the code doesn't fit the + Emacs approach to finding the defun starts. + + @vindex c-enable-xemacs-performance-kludge-p + @vindex enable-xemacs-performance-kludge-p (c-) + XEmacs users can set the variable + @code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This + tells @ccmode{} to use XEmacs-specific built-in functions which, in some + circumstances, can locate the top-most opening brace much more quickly than + @code{beginning-of-defun}. Preliminary testing has shown that for + styles where these braces are hung (e.g. most JDK-derived Java styles), + this hack can improve performance of the core syntax parsing routines + from 3 to 60 times. However, for styles which @emph{do} conform to + Emacs' recommended style of putting top-level braces in column zero, + this hack can degrade performance by about as much. Thus this variable + is set to @code{nil} by default, since the Emacs-friendly styles should + be more common (and encouraged!). Note that this variable has no effect + in Emacs since the necessary built-in functions don't exist (in Emacs + 22.1 as of this writing in February 2007). + + Text properties are used to speed up skipping over syntactic whitespace, + i.e. comments and preprocessor directives. Indenting a line after a + huge macro definition can be slow the first time, but after that the + text properties are in place and it should be fast (even after you've + edited other parts of the file and then moved back). + + Font locking can be a CPU hog, especially the font locking done on + decoration level 3 which tries to be very accurate. Note that that + level is designed to be used with a font lock support mode that only + fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time + Lock mode, so make sure you use one of them. Fontification of a whole + buffer with some thousand lines can often take over a minute. That is + a known weakness; the idea is that it never should happen. + + The most effective way to speed up font locking is to reduce the + decoration level to 2 by setting @code{font-lock-maximum-decoration} + appropriately. That level is designed to be as pretty as possible + without sacrificing performance. @xref{Font Locking Preliminaries}, for + more info. + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Limitations and Known Bugs, FAQ, Performance Issues, Top + @comment node-name, next, previous, up + @chapter Limitations and Known Bugs + @cindex limitations + @cindex bugs + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @itemize @bullet + @item + @ccmode{} doesn't support trigraphs. (These are character sequences + such as @samp{??(}, which represents @samp{[}. They date from a time + when some character sets didn't have all the characters that C needs, + and are now utterly obsolete.) + + @item + There is no way to apply auto newline settings (@pxref{Auto-newlines}) + on already typed lines. That's only a feature to ease interactive + editing. + + To generalize this issue a bit: @ccmode{} is not intended to be used as + a reformatter for old code in some more or less batch-like way. With + the exception of some functions like @code{c-indent-region}, it's only + geared to be used interactively to edit new code. There's currently no + intention to change this goal. + + If you want to reformat old code, you're probably better off using some + other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent' + Manual}, which has more powerful reformatting capabilities than + @ccmode{}. + + @item + The support for C++ templates (in angle brackets) is not yet complete. + When a non-nested template is used in a declaration, @ccmode{} indents + it and font-locks it OK. Templates used in expressions, and nested + templates do not fare so well. Sometimes a workaround is to refontify + the expression after typing the closing @samp{>}. + + @item + On loading @ccmode{}, sometimes this error message appears: + + @example + File mode specification error: (void-variable c-font-lock-keywords-3) + @end example + + This is due to a bug in the function @code{eval-after-load} in some + versions of (X)Emacs. It can manifest itself when there is a symbolic + link in the path of the directory which contains (X)Emacs. As a + workaround, put the following into your @file{.emacs} file, fairly + early on: + + @example + (defun my-load-cc-fonts () + (require "cc-fonts")) + (add-hook 'c-initialization-hook 'my-load-cc-fonts) + @end example + @end itemize + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node FAQ, Updating CC Mode, Limitations and Known Bugs, Top + @comment node-name, next, previous, up + @appendix Frequently Asked Questions + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @itemize @bullet + @item + @emph{How can I change the indent level from 4 spaces to 2 spaces?} + + Set the variable @code{c-basic-offset}. @xref{Getting Started}. + + @item + @kindex RET + @kindex C-j + @emph{Why doesn't the @kbd{RET} key indent the new line?} + + Emacs' convention is that @kbd{RET} just adds a newline, and that + @kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this + too by adding this to your @code{c-initialization-hook}: + + @example + (define-key c-mode-base-map "\C-m" 'c-context-line-break) + @end example + + @xref{Getting Started}. This is a very common question. If you want + this to be the default behavior, don't lobby us, lobby RMS! @t{:-)} + + @item + @emph{How do I stop my code jumping all over the place when I type?} + + Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting + Started}. + + @item + @kindex C-x h + @kindex C-M-\ + @emph{How do I reindent the whole file?} + + Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit + @kbd{C-M-\}. @xref{Indentation Commands}. + + @item + @kindex C-M-q + @kindex C-M-u + @emph{How do I reindent the current block?} + + First move to the brace which opens the block with @kbd{C-M-u}, then + reindent that expression with @kbd{C-M-q}. @xref{Indentation + Commands}. + + @item + @emph{I put @code{(c-set-offset 'substatement-open 0)} in my + @file{.emacs} file but I get an error saying that @code{c-set-offset}'s + function definition is void. What's wrong?} + + This means that @ccmode{} hasn't yet been loaded into your Emacs + session by the time the @code{c-set-offset} call is reached, most + likely because @ccmode{} is being autoloaded. Instead of putting the + @code{c-set-offset} line in your top-level @file{.emacs} file, put it + in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply + modify @code{c-offsets-alist} directly: + + @example + (setq c-offsets-alist '((substatement-open . 0))) + @end example + + @item + @cindex open paren in column zero + @emph{I have an open paren character at column zero inside a comment or + multiline string literal, and it causes the fontification and/or + indentation to go haywire. What gives?} + + It's due to the ad-hoc rule in (X)Emacs that such open parens always + start defuns (which translates to functions, classes, namespaces or any + other top-level block constructs in the @ccmode{} languages). + @ifset XEMACS + @xref{Defuns,,, xemacs, XEmacs User's Manual}, for details. + @end ifset + @ifclear XEMACS + @xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details + (@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual). + @end ifclear + + This heuristic is built into the core syntax analysis routines in + (X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs + 21.1 it became possible to turn it off@footnote{Using the variable + @code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so + there since it's got its own system to keep track of blocks. + + @end itemize + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top + @comment node-name, next, previous, up + @appendix Getting the Latest CC Mode Release + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @ccmode{} has been standard with all versions of Emacs since 19.34 and + of XEmacs since 19.16. + + @cindex web site + Due to release schedule skew, it is likely that all of these Emacsen + have old versions of @ccmode{} and so should be upgraded. Access to the + @ccmode{} source code, as well as more detailed information on Emacsen + compatibility, etc. are all available on the web site: + + @quotation + @uref{http://cc-mode.sourceforge.net/} + @end quotation + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top + @comment node-name, next, previous, up + @appendix Mailing Lists and Submitting Bug Reports + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @kindex C-c C-b + @findex c-submit-bug-report + @findex submit-bug-report (c-) + To report bugs, use the @kbd{C-c C-b} (bound to + @code{c-submit-bug-report}) command. This provides vital information + we need to reproduce your problem. Make sure you include a concise, + but complete code example. Please try to boil your example down to + just the essential code needed to reproduce the problem, and include + an exact recipe of steps needed to expose the bug. Be especially sure + to include any code that appears @emph{before} your bug example, if + you think it might affect our ability to reproduce it. + + Please try to produce the problem in an Emacs instance without any + customizations loaded (i.e. start it with the @samp{-q --no-site-file} + arguments). If it works correctly there, the problem might be caused + by faulty customizations in either your own or your site + configuration. In that case, we'd appreciate it if you isolate the + Emacs Lisp code that triggers the bug and include it in your report. + + @cindex bug report mailing list + Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can + also send other questions and suggestions (kudos? @t{;-)} to that + address. It's a mailing list which you can join or browse an archive + of; see the web site at @uref{http://cc-mode.sourceforge.net/} for + further details. + + @cindex announcement mailing list + If you want to get announcements of new @ccmode{} releases, send the + word @emph{subscribe} in the body of a message to + @email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible + to subscribe from the web site too. Announcements will also be posted + to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, + @code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++}, + @code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools}, + @code{comp.lang.idl}, and @code{comp.lang.awk}. + @c There is no newsgroup for Pike. :-( + + + @node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top + @appendix GNU Free Documentation License + @include doclicense.texi + + + @c Removed the tentative node "Mode Initialization" from here, 2005/8/27. + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Command and Function Index, Variable Index, GNU Free Documentation License, Top + @comment node-name, next, previous, up + @unnumbered Command and Function Index + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Since most @ccmode{} commands are prepended with the string + @samp{c-}, each appears under its @code{c-@var{thing}} name and its + @code{@var{thing} (c-)} name. + @iftex + @sp 2 + @end iftex + @printindex fn + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Variable Index, Concept and Key Index, Command and Function Index, Top + @comment node-name, next, previous, up + @unnumbered Variable Index + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + Since most @ccmode{} variables are prepended with the string + @samp{c-}, each appears under its @code{c-@var{thing}} name and its + @code{@var{thing} (c-)} name. + @iftex + @sp 2 + @end iftex + @printindex vr + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @node Concept and Key Index, , Variable Index, Top + @comment node-name, next, previous, up + @unnumbered Concept and Key Index + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @printindex cp + + + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @comment Epilogue. + @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + @iftex + @page + @summarycontents + @contents + @end iftex + + @bye + + @ignore + arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0 + @end ignore diff --cc lisp/ChangeLog index 9a5b277201a,0161024abb5..9524be4cdee --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@@ -1,16 -1,2241 +1,2254 @@@ + 2007-10-09 Juanma Barranquero + + * follow.el: Require easymenu. + (follow-mode-hook, follow-mode): Doc fixes. + (follow-mode-off-hook): Mark as obsolete. + + 2007-10-08 Martin Rudalics + + * window.el (mouse-autoselect-window-cancel): Don't cancel for + select-window or select-frame events. + (handle-select-window): When autoselecting window set input + focus. Restructure. + + * frame.el (focus-follows-mouse): Moved to frame.c. + * cus-start.el (all): Add focus-follows-mouse. + + 2007-10-08 Juanma Barranquero + + * bs.el (bs-mode): Make sure global-font-lock-mode doesn't + activate font-locking in the *buffer-selection* buffer. + (bs-show-sorted): Doc fix. + + * bs.el (bs--get-marked-string, bs--get-modified-string) + (bs--get-readonly-string, bs--get-size-string, bs--get-name) + (bs--get-mode-name, bs-mode): Fix typos in docstrings. + (bs--format-aux): Doc fix. + + 2007-10-08 Micha,Ak(Bl Cadilhac + + * progmodes/gud.el (gud-gud-gdb-command-name): Fix typo in docstring. + + 2007-10-08 Nick Roberts + + * progmodes/gud.el (gud-gud-gdb-command-name): New option. + (gud-gdb): New function for old M-x gdb (text command mode). + (gud-gdb-command-name, gdb): Move to... + + * progmodes/gdb-ui.el: ...here and adapt doc string. + (gud-gdba-command-name, gdba): Delete. + + 2007-10-08 Juanma Barranquero + + * bs.el: Don't defvar `font-lock-verbose'. + (bs-config-clear, bs-kill, bs-string-show-normally, bs-sort-functions) + (bs--get-file-name): Fix typos in docstrings. + (bs--show-header): Use `dolist' instead of `mapcar'. + (bs-mode): Set `show-trailing-whitespace' to nil. + (bs-buffer-sort-function, bs-mouse-select-other-frame) + (bs-visits-non-file, bs-sort-buffer-interns-are-last, bs-show): + Doc fixes. + + 2007-10-08 Adam Hupp (tiny change) + + * progmodes/gdb-ui.el (pdb): Specify file for gud-break. + + 2007-10-08 Nick Roberts + + * progmodes/gud.el (gdb): Make graphical mode the default and + switch to text command mode if appropriate, i.e., reverse previous + arrangement. + (gud-gdb-marker-filter): Adapt for above change. + + * progmodes/gdb-ui.el (gdb-init-1): Don't set the values + gud-minor-mode and gud-marker-filter. + (gdb-fullname-regexp): New variable. + (gud-gdba-marker-filter): Use it to switch to text command + mode if appropriate. + + 2007-10-08 Nick Roberts + + * progmodes/gud.el (gud-display-line): Find source buffer even when + GUD buffer has its own frame. + + 2007-10-08 Jan Dj,Ad(Brv + + * term/x-win.el (icon-map-list): Set to nil for 22.1 compatibility. + + 2007-10-08 Jan Dj,Ad(Brv + + * term/x-win.el (x-gtk-stock-map): Version is 22.2. + + 2007-10-08 Martin Rudalics + + * allout.el (allout-before-change-handler): Replace got-char by + goto-char. + + 2007-10-08 Stefan Monnier + + * vc-svn.el (vc-svn-resolve-when-done, vc-svn-find-file-hook): New funs. + Used to try and automatically enabled smerge-mode in the presence of + conflicts and to call `svn resolved' when the conflicts are gone. + (vc-svn-parse-status): Remember the svn-specific status. + + 2007-10-08 Eli Zaretskii + + * menu-bar.el (menu-bar-search-documentation-menu): Rename from + menu-bar-apropos-menu. All users changed. + (menu-bar-help-menu): Change menu symbols to better match the text + displayed by the menu. + + 2007-10-08 Dan Nicolaescu + + * files.el (file-name-sans-versions): Use [:alnum:] and also allow + #, @, : and ^. + + 2007-10-08 Dan Nicolaescu + + * pcvs-defs.el (cvs-mode-map): Bind TAB and backtab. + + * log-view.el (log-view-mode-map): Likewise. + + * diff-mode.el (diff-mode-shared-map): Likewise. + + 2007-10-08 Dan Nicolaescu + + * files.el (file-name-sans-versions): Also allow `A-Z'. + + * vc.el: Mention all supported VC backends. + + 2007-10-08 Richard Stallman + + * wid-edit.el (widget-specify-button): Don't merge mouse-face with + neighbouring buttons. + + 2007-10-08 Andreas Schwab + + * files.el (file-name-sans-versions): Also allow `_'. + + 2007-10-08 Dan Nicolaescu + + * files.el (file-name-sans-versions): Allow - and a-z in version names. + + * log-view.el (log-view-mode-map, log-view-mode-menu): + Bind log-view-annotate-version. + (log-view-beginning-of-defun, log-view-end-of-defun) + (log-view-annotate-version): New functions. + (log-view-mode): Use log-view-beginning-of-defun and + log-view-end-of-defun. + + 2007-10-08 Stefan Monnier + + * emacs-lisp/easy-mmode.el (define-minor-mode): Fix staging. + + 2007-10-08 Stefan Monnier + + * wid-edit.el (widget-image-insert): Don't merge mouse-face with + neighbouring buttons. + + * progmodes/compile.el (compilation-error-regexp-alist-alist): + Recognize gcc's use of "note" for informational messages. + + 2007-10-08 Stefan Monnier + + * textmodes/css-mode.el (css-electric-keys): electrick->electric. + (css-mode): Update correspondingly. + + 2007-10-08 Dan Nicolaescu + + * vc-git.el (vc-git-log-view-mode): Add font-lock patterns for + Signed-off-by, Acked-by and Merge. + + 2007-10-08 Stefan Monnier + + * ediff-init.el (ediff-verbose-p): This var is not a constant. + + 2007-10-08 Stefan Monnier + + * vc-mtn.el: New file. + + * vc-hooks.el (vc-handled-backends): Add Mtn. + + 2007-10-08 Eli Zaretskii + + * files.el (find-file, find-file-other-window) + (find-file-other-frame, find-file-existing, find-file-read-only) + (find-file-read-only-other-window) + (find-file-read-only-other-frame) + (find-alternate-file-other-window, find-alternate-file): Doc fixes. + + 2007-10-08 Nick Roberts + + * progmodes/gud.el (gdb-ready): New variable. + (gdb): Set it to nil. Set gud-running to nil here... + (gud-common-init): ...instead of here. + + * progmodes/gdb-ui.el (gdba, gdb-send, gdb-source-info): + Use gdb-ready. Discard input until GDB is ready to accept it. + + 2007-10-08 Martin Rudalics + + * dired.el (dired-warning): Inherit from font-lock-warning-face to + make it show up with eight colors. + + 2007-10-08 Stefan Monnier + + * diff-mode.el (diff-sanity-check-hunk): Fix up the case when unified + diffs are concatenated with no intervening line. + + 2007-10-08 Dave Love + + * progmodes/python.el: Merge changes from Dave Love's v2007-Sep-10. + (python-font-lock-keywords): Update to the 2.5 version of the language. + (python-quote-syntax): Let-bind font-lock-syntactic-keywords to nil. + (python-backspace): Only behave funny in code. + (python-compilation-regexp-alist): Add PDB stack trace regexp. + (inferior-python-mode): Add PDB prompt regexp. + (python-fill-paragraph): Refine the fenced-string regexp. + (python-find-imports): Handle imports spanning several lines. + (python-mode): Add `class' to hideshow support. + + 2007-10-08 Stefan Monnier + + * pcvs.el (cvs-mode-add-change-log-entry-other-window): Use + add-log-buffer-file-name-function rather than bind buffer-file-name, + so we dont end up calling change-log-mode in *cvs* when `fi' is the + ChangeLog file itself. + + * outline.el (outline-flag-region): Use front-advance. + + 2007-10-08 Ilya Zakharevich + + * progmodes/cperl-mode.el: Merge upstream 5.23. + (cperl-where-am-i): Remove function. + (cperl-backward-to-noncomment): Don't go too far when skipping POD/HEREs + (cperl-sniff-for-indent): De-invert [string] and [comment]. + When looking for label, skip s:m:y:tr. + (cperl-indent-line): Likewise. + (cperl-mode): Don't assume `font-lock-multiline' is auto-local. + (cperl-windowed-init): Wrong `ps-print' handling. + Both thanks to Chong Yidong. + (cperl-look-at-leading-count): Could fail with unfinished RExen. + (cperl-find-pods-heres): If the second part of s()[] is missing, + don't try to highlight delimiters... + + 2007-10-08 Stefan Monnier + + * progmodes/compile.el (compilation-get-file-structure): Complete last + change by also using spec-directory in the puthash. + + 2007-10-08 Riccardo Murri + + * vc-bzr.el (vc-bzr-file-name-relative): Use 'when' instead of 'and'. + (vc-bzr-status): Fix shadowing of variable 'status'. + (vc-bzr-workfile-version): Use correct path to 'last-revision' file. + Use `expand-file-name' instead of `concat'. + (vc-bzr-annotate-command): Use option name '--long' instead of '-l'. + Update annotation line regexp. Fixes launchpad.net [Bug 137435]. + + 2007-10-08 Jason Rumney + + * frame.el (focus-follows-mouse): Doc-fix. Change default on w32. + + 2007-10-08 Richard Stallman + + * emacs-lisp/lisp-mode.el (lisp-indent-offset): Make defcustom. + Add `safe-local-variable' property. + (lisp-body-indent): Likewise. + + 2007-10-08 Richard Stallman + + * files.el (hack-local-variables-confirm): Rename arg VARS to ALL-VARS. + Add doc string. + + 2007-10-08 Martin Rudalics + + * files.el (backup-buffer-copy): Try to overwrite old backup first. + + 2007-10-08 Martin Rudalics + + * repeat.el (repeat): Use last-repeatable-command instead of + real-last-command. Run pre- and post-command hooks for + self-insertion. Update doc-string. + + 2007-10-08 Alexandre Julliard + + * vc-git.el (vc-git-state): Call git-add --refresh to update the + state of the file. + (vc-git-workfile-unchanged-p): Delegate implementation to vc-git-state. + (vc-git-create-repo): Fix invalid command. + + 2007-10-08 Richard Stallman + + * textmodes/flyspell.el (flyspell-mode): + Catch errors in flyspell-mode-on. + + 2007-10-09 Juanma Barranquero + + * term/x-win.el (x-alternatives-map): Remove spurious parenthesis. + + 2007-10-09 Stefan Monnier + + * international/encoded-kb.el (encoded-kbd-setup-display): + Use input-decode-map rather than local-key-translation-map. + + * term/rxvt.el (rxvt-alternatives-map): New map. + (terminal-init-rxvt): Use it. + Bind rxvt-function-map in input-decode-map. + + * term/xterm.el (xterm-alternatives-map): New map. + (terminal-init-xterm): Use it. + Bind xterm-function-map in input-decode-map. + + * term/x-win.el (x-alternatives-map): New var. + (x-setup-function-keys): Use it. + + * help-fns.el (describe-variable): Slightly change the layout of + meta-info to separate it better from the docstring. + Standardize insertion of extra empty lines in various circumstances. + + * diff-mode.el (diff-hunk-style): New fun. + (diff-end-of-hunk): Use it. + (diff-context->unified): Use the new `apply' undo element, + if applicable, so as to save undo-log space. + (diff-fine-change): New face. + (diff-fine-highlight-preproc): New function. + (diff-fine-highlight): New command. + (diff-mode-map, diff-mode-menu): Add diff-fine-highlight. + + * smerge-mode.el (smerge-refine-chopup-region): Add `preproc' argument. + (smerge-refine-highlight-change): Add `props' argument. + (smerge-refine-subst): New function holding most of smerge-refine. + (smerge-refine): Use it. + + 2007-10-08 Eric S. Raymond + + * vc.el (vc-default-wash-log): Remove unused code, the + log washers all live in the backends now. + (vc-default-comment-history): Correct for the fact + that wash-log is argumentless in the new API. + + 2007-10-08 Michael Albinus + + * net/tramp.el (tramp-find-foreign-file-name-handler): Check also host. + (tramp-maybe-send-script): Apply `member' but `memq'. + (tramp-advice-file-expand-wildcards): Simplify implementation. + + 2007-10-08 Juanma Barranquero + + * follow.el (follow-mode): Don't run hooks twice. Use `when'. + + * mb-depth.el (minibuf-depth-indicator-function): New variable. + (minibuf-depth-setup-minibuffer): Use it. + + 2007-10-07 Glenn Morris + + * simple.el (bad-packages-alist): Clarify Semantic and CEDET + version numbers. + + 2007-10-06 Juri Linkov + + * textmodes/fill.el (fill-paragraph-or-region): New function. + + * bindings.el (esc-map): Bind M-q to fill-paragraph-or-region + instead of fill-paragraph. + + * tutorial.el (tutorial--default-keys): Replace fill-paragraph + with fill-paragraph-or-region. Suspend command is now the same + `suspend-frame' on window systems and on tty. + + * image.el (image-type): Check if image-types is bound to not fail + on tty. + + * delsel.el (delete-selection-pre-hook): + * emulation/cua-base.el (cua-paste): Check if mouse-region-match + is fbound to not fail on mouseless tty. + + 2007-10-06 Michael Albinus + + * net/tramp.el (top): Move loading of tramp-util.el and + tramp-vc.el to tramp-compat.el. + (tramp-make-tramp-temp-file): Complete rewrite. Create remote + temporary file if possible, in order to avoid a security hole. + (tramp-do-copy-or-rename-file-out-of-band) + (tramp-maybe-open-connection): Call `tramp-make-tramp-temp-file' + with DONT-CREATE, because the connection is not setup yet. + (tramp-handle-process-file): Rewrite temporary file handling. + (tramp-completion-mode): New defvar. + (tramp-completion-mode-p): Use it. + + * net/tramp-compat.el (top): Load tramp-util.el and tramp-vc.el. + + * net/tramp-fish.el (tramp-fish-handle-process-file): + Rewrite temporary file handling. + + 2007-10-06 Eric S. Raymond + + * vc.el: Workfile version -> focus version change. Port various + comments from new VC to reduce the noise in the diff. + Patch in the new vc-create-repo function to go with the + header comment about it already present. + There are no changes to existing logic in this patch. + (vc-revert-buffer1): Rename to vc-revert-buffer-internal. + + 2007-10-06 Aaron Hawley + + * autoinsert.el (auto-insert-alist): Add a Texinfo entry. + + 2007-10-05 Chris Moore + + * server.el (server-kill-new-buffers): Doc fix. + + 2007-10-05 John W. Eaton + + * progmodes/octave-mod.el (octave-abbrev-table): Add "until". + (octave-begin-keywords): Add "do". + (octave-end-keywords): Remove "end". + (octave-reserved-words): Add "end". Remove "all_va_args", + "gplot", and 'gsplot". + (octave-text-functions): Remove "gset", "gshow", "set", and "show". + (octave-variables): Remove "IMAGEPATH", "INFO_FILE", + "INFO_PROGRAM", "LOADPATH", "__error_text__", "automatic_replot", + "default_return_value", "define_all_return_values", + "do_fortran_indexing", "empty_list_elements_ok", + "gnuplot_has_multiplot", "implicit_str_to_num_ok", + "ok_to_lose_imaginary_part", "prefer_column_vectors", + "prefer_zero_one_indexing", "propagate_empty_matrices", + "resize_on_range_error", "treat_neg_dim_as_zero", + "warn_assign_as_truth_value", "warn_comma_in_global_decl", + "warn_divide_by_zero", "warn_function_name_clash", + "warn_missing_semicolon", "whitespace_in_literal_matrix". + Add "DEFAULT_EXEC_PATH", "DEFAULT_LOADPATH", "IMAGE_PATH", + "crash_dumps_octave_core", "sighup_dumps_octave_core", + "sigterm_dumps_octave_core". + (octave-block-match-alist): Remove "end" from block-end keywords. + (octave-mode): Update ftp site address. + + 2007-10-05 Dan Nicolaescu + + * vc.el: Reorder functions, no code changes. + + 2007-10-04 Michael Albinus + + * net/tramp.el (tramp-make-temp-file): Move to tramp-compat.el. + (tramp-do-copy-or-rename-file-directly): Handle tmpfile only in + the cond clauses where needed. + (tramp-handle-write-region): Rearrange code for proper handling of + tmpfile. + + * net/tramp-compat.el (tramp-compat-make-temp-file): New defsubst. + + * net/tramp.el: + * net/tramp-fish.el: + * net/tramp-ftp.el: + * net/tramp-smb.el: Rename `tramp-make-temp-file' to + `tramp-compat-make-temp-file'. + + 2007-10-04 Juanma Barranquero + + * image-dired.el (image-dired-image-at-point-p): Fix typo in docstring. + + 2007-10-03 Stefan Monnier + + * emacs-lisp/copyright.el (copyright-update): Don't update if the file + already uses a more recent copyright version than the "current" one. + + 2007-10-03 Micha,Ak(Bl Cadilhac + + * doc-view.el (doc-view-dvi->pdf-sentinel, doc-view-reset-slice) + (doc-view-insert-image): Minor aesthetical docstring changes. + + 2007-10-03 Tassilo Horn + + * doc-view.el (doc-view): Don't ignore pdf and dvi files when + completing filename. + (doc-view-search-internal): Docstring change. + + 2007-10-03 Michael Albinus + + * net/tramp.el (top): Add tramp-compat to `tramp-unload-hook'. + (tramp-file-name-handler-alist): + Add `tramp-handle-insert-file-contents-literally'. Needed for XEmacs. + (tramp-make-temp-file): Use `make-temp-name'. `make-temp-file', + used before, creates the file already, which is not desired. + (tramp-do-copy-or-rename-file-directly): Simplify handling of + temporary file. + (tramp-handle-insert-file-contents): Assign the result in the + short track case. + (tramp-handle-insert-file-contents-literally): New defun. + (tramp-completion-mode-p): Revert change from 2007-09-24. + Checking for `return' etc as last character is not sufficient, for + example in dired-mode when entering (revert-buffer) or + (dired-sort). + + * net/tramp-compat.el (top): Add also compatibility code for loading + appropriate timer package. + (tramp-compat-copy-tree): Check for `subrp' and `symbol-file' in + order to avoid autoloading problems. + + * net/tramp-fish.el: + * net/tramp-smb.el: Move further compatibility code to tramp-compat.el. + + * net/tramp-ftp.el (tramp-ftp-file-name-handler): Handle the case + where the second parameter of `copy-file' or `rename-file' is a + remote file but not via ftp. + + 2007-10-02 Richard Stallman + + * frame.el (cursor-in-non-selected-windows): Doc fix. + + 2007-10-01 Thien-Thi Nguyen + + * play/zone.el (zone): Let-bind show-trailing-whitespace to nil. + Suggested by Chris Moore . + + 2007-10-01 Jay Belanger + + * calc/calc-math.el (math-largest-emacs-expt): Handle the cases + when `expt' doesn't give range errors. + + 2007-10-01 Markus Triska + + * calc/calc-math.el (math-smallest-emacs-expt): + Make the computation more robust. + + 2007-09-30 David Kastrup + + * startup.el (argv): Alias for `command-line-args-left' to use as + `(pop argv)' inside of --eval command sequences. Allows for + passing shell commands into Emacs verbatim without need for Lisp + quoting. + + * autorevert.el (auto-revert-handler): In `auto-revert-tail-mode', + check only for changed size. + (auto-revert-tail-handler): Get size from caller. If the file has + shrunk, tail the whole file again (the file presumably has been + rewritten). + + * woman.el (woman-topic-all-completions, woman-mini-help): + Fix fallout from 2007-09-07 introduction of `dolist' when the list + actually was being manipulated in the loop. + (woman-Cyg-to-Win, woman-pre-process-region) + (woman-horizontal-escapes, woman-if-body, woman-unescape) + (woman-strings, woman-special-characters, woman1-hc) + (woman-change-fonts, woman-find-next-control-line): + Use `match-beginning' rather than `match-string' when the result is + just used as a flag. + + 2007-09-30 Michael Albinus + + * net/tramp-compat.el: New file. + + * net/tramp.el: + * net/tramp-fish.el: + * net/tramp-smb.el: + * net/tramp-uu.el: + * net/trampver.el: Move compatibility code to tramp-compat.el. + Apply `mapc' instead of `mapcar' when the code needs side effects + only. Move utf-8 coding cookie to the second line. + + 2007-09-30 Reiner Steib + + * term/x-win.el (x-gtk-stock-map): Add Gnus and MH-E icons. + Improve custom type. + (icon-map-list): Make it customizable. Document how to disable + stock icons. + + 2007-09-30 Richard Stallman + + * play/zone.el (zone-hiding-modeline): Use mode-line-format. + + 2007-09-29 Jan Dj,Ad(Brv + + * term/x-win.el (x-gtk-stock-map): Version is 22.2. + + 2007-09-28 Stefan Monnier + + * t-mouse.el (gpm-mouse-mode): Rename from t-mouse-mode. Rewrite. + (t-mouse-mode): New compatibility alias. + + 2007-09-28 Dan Nicolaescu + + * server.el (server-delete-client): Only delete the terminal if it + is non-nil. + + 2007-09-28 Michael Albinus + + * net/tramp.el (with-file-property, with-connection-property): + Highlight as keyword. + (tramp-rfn-eshadow-setup-minibuffer) + (tramp-rfn-eshadow-update-overlay, tramp-handle-set-file-times) + (tramp-set-file-uid-gid, tramp-do-copy-or-rename-file-via-buffer) + (tramp-do-copy-or-rename-file-directly) + (tramp-do-copy-or-rename-file-out-of-band) + (tramp-handle-shell-command, tramp-get-debug-buffer) + (tramp-send-command-and-read, tramp-equal-remote) + (tramp-get-local-gid): Pacify byte-compiler. + (tramp-handle-file-name-directory): Result shall not be expanded. + (tramp-find-foreign-file-name-handler): Rewrite. + (tramp-dissect-file-name): Add optional parameter NODEFAULT. + + * net/tramp-cache.el (tramp-cache-print): Pacify byte-compiler. + + * net/tramp-fish.el (tramp-fish-handle-expand-file-name): + Apply `tramp-completion-mode-p'. + (tramp-fish-handle-set-file-times) + (tramp-fish-handle-executable-find) + (tramp-fish-handle-process-file, tramp-fish-get-file-entries) + (tramp-fish-retrieve-data): Pacify byte-compiler. + + * net/tramp-gw.el (tramp-gw-basic-authentication): + Call `tramp-read-passwd' with first parameter `nil'. + + 2007-09-28 Glenn Morris + + * mail/supercite.el (sc-attribs-filter-namelist): Use mapc rather + than mapcar. + + * textmodes/tex-mode.el (tex-suscript-height-ratio) + (tex-suscript-height-minimum): New customizable variables. + (tex-suscript-height): New function. + (superscript, subscript): Set height using tex-suscript-height + rather than fixing at 0.8. + (tex-fontify-script, tex-font-script-display): Add :version tag. + + 2007-09-27 Juanma Barranquero + + * progmodes/python.el (python-eldoc-function): Doc fix. + + 2007-09-27 Glenn Morris + + * image.el (image-type-auto-detected-p): Doc fix. Don't detect an + image if it is not in image-type-auto-detectable, or is there with + a nil value. + + 2007-09-27 Michael Albinus + + * net/tramp.el (tramp-maybe-open-connection): Make test for alive + connection more robust. + + 2007-09-26 Juanma Barranquero + + * emacs-lisp/eldoc.el (eldoc-function-argstring-format): + Deal with the case that special &keywords are at the beginning or + end of the argument list. Also add some (incomplete) support for + non-standard arglists. + + 2007-09-26 Juanma Barranquero + + * emacs-lisp/eldoc.el (eldoc-message-commands-table-size) + (eldoc-message-commands, eldoc-current-idle-delay) + (eldoc-function-argstring-format): Fix typos in docstrings. + + 2007-09-26 Jay Belanger + + * calc/calc-units.el (calc-convert-units) + (calc-convert-temperature): Remove unnecessary colons. + + 2007-09-26 Bastien Guerry + + * org-export-latex.el (org-export-latex-tables-verbatim): New function. + (org-export-latex-remove-from-headlines): Name changed because of typo. + (org-export-latex-quotation-marks-convention): Option removed. + (org-export-latex-make-preamble): Handle the DATE option. + (org-export-latex-cleaned-string): Now the only cleaning function, + synched up with org.el. + (org-export-latex-lists, org-export-latex-parse-list) + (org-export-list-to-latex): New functions. + + 2007-09-26 Carsten Dominik + + * org.el (org-kill-is-subtree-p): Use `org-outline-regexp'. + (org-outline-regexp): New constant. + (org-remember-handler): Throw error when the target file is not in + org-mode. + (org-cleaned-string-for-export): No longer call + `org-export-latex-cleaned-string' with an argument. + (org-get-tags): Returns now a list, not a string. + (org-get-tags-string): New function. + (org-archive-subtree): No need to split return of `org-get-tags'. + (org-set-tags, org-entry-properties): Call `org-get-tags-string' + instead of `org-get-tags'. + (org-agenda-format-date): Rename from `org-agenda-date-format'. + (org-time-from-absolute, org-agenda-format-date-aligned): New funs. + (org-compatible-face): New argument INHERITS. Inherit from this + face if possible. + (org-level-1, org-level-2, org-level-3, org-level-4) + (org-level-5, org-level-6, org-level-7, org-level-8) + (org-special-keyword, org-drawer, org-column, org-warning) + (org-archived, org-todo, org-done, org-headline-done, org-table) + (org-formula, org-code, org-agenda-structure) + (org-scheduled-today, org-scheduled-previously) + (org-upcoming-deadline, org-time-grid): Call `org-compatible-face' + in the new way. + (org-get-heading): New argument NO-TAGS. + (org-fast-tag-selection-include-todo): Made defvar instead of + defcustom, feature is not deprecated. + (org-remember-store-without-prompt): New default value t. + (org-todo-log-states): New variable. + (org-set-regexps-and-options): #+TODO is an alias for SEQ_TODO. + Compute the log states. + (org-goto-map): More commands copied from global map. Also bind + `org-occur'. + (org-goto): Made into a general lookup command. + (org-get-location): Complete rewrite. + (org-goto-exit-command): New variable. + (org-goto-selected-point): New variable. + (org-goto-ret, org-goto-left, org-goto-right, org-goto-quit): + Set the new variables. + (org-paste-subtree): Whitespace insertion strategy revised. + (org-remember-apply-template): Protect v-A from the possibility + that v-a might be nil. + (org-remember-handler): Insertion rules revised. + (org-todo): Respect org-todo-log-states. + (org-up-heading-safe): New function. + (org-entry-get-with-inheritance): Use `org-up-heading-safe'. + + 2007-09-26 Dan Nicolaescu + + * progmodes/cc-cmds.el (c-indent-line-or-region): Only indent the + region if in transient-mark-mode. + + 2007-09-26 Juanma Barranquero + + * calc/calc-ext.el (calc-init-extensions, calc-reset): + * calc/calc-help.el (calc-full-help): + * calc/calc-misc.el (another-calc): + * calc/calc-store.el (calc-var-name-map): + * calc/calc-stuff.el (calc-flush-caches): + * calc/calc-units.el (math-build-units-table): + * calc/calc.el (calc-digit-map, calc-dispatch-map, calc-mode) + (calc-quit): + * calendar/icalendar.el (icalendar--format-ical-event) + (icalendar--convert-ical-to-diary): + * emacs-lisp/authors.el (authors): + * emacs-lisp/cust-print.el (custom-print-install) + (custom-print-uninstall): + * emacs-lisp/disass.el (disassemble-1): + * emacs-lisp/easy-mmode.el (easy-mmode-define-syntax): + * emacs-lisp/edebug.el (byte-compile-resolve-functions): + * emacs-lisp/elint.el (elint-current-buffer, elint-check-defun-form) + (elint-check-let-form, elint-check-condition-case-form) + (elint-initialize): + * emacs-lisp/elp.el (elp-results): + * emacs-lisp/generic.el (generic-mode-internal): + * emacs-lisp/re-builder.el (reb-delete-overlays): + * emacs-lisp/regi.el (regi-interpret): + * emacs-lisp/sregex.el (sregex--char-aux): + * emulation/cua-rect.el (cua--deactivate-rectangle) + (cua--highlight-rectangle, cua--rectangle-post-command): + * emulation/viper-keym.el (viper-toggle-key, viper-ESC-key): + * emulation/viper-macs.el (viper-describe-kbd-macros) + (viper-describe-one-macro): + * emulation/viper-util.el (viper-setup-master-buffer): + * emulation/viper.el (set-viper-state-in-major-mode): + * international/mule-diag.el (describe-current-coding-system): + * language/ethio-util.el (ethio-fidel-to-sera-buffer): + * mail/emacsbug.el (report-emacs-bug): + * net/ange-ftp.el (ange-ftp-call-chmod, ange-ftp-parse-bs2000-listing): + * obsolete/hilit19.el (hilit-unhighlight-region) + (hilit-set-mode-patterns): + * play/solitaire.el (solitaire-check, solitaire-solve): + * play/zone.el (zone-pgm-rotate): + * progmodes/ada-mode.el (ada-save-exceptions-to-file): + * progmodes/ada-prj.el (ada-prj-display-page): + * progmodes/delphi.el (delphi-search-directory, delphi-find-unit-file) + (delphi-debug-mode-map, delphi-mode-map, delphi-mode): + * progmodes/ebrowse.el (ebrowse-tree-mode, ebrowse-view-exit-fn) + (ebrowse-member-mode, ebrowse-save-tree-as, ebrowse-save-class): + * progmodes/sh-script.el (sh-make-vars-local) + (sh-reset-indent-vars-to-global-values): + * progmodes/sql.el (top): + * progmodes/vhdl-mode.el (vhdl-set-style, vhdl-regress-line): + * progmodes/xscheme.el (top): + * textmodes/artist.el (artist-mt-get-symbol-from-keyword-sub) + (artist-go-retrieve-from-symbol-sub, artist-go-get-symbol-shift-sub) + (artist-fc-retrieve-from-symbol-sub, artist-vaporize-line) + (artist-vaporize-lines, artist-ellipse-compute-fill-info) + (artist-submit-bug-report): + * textmodes/flyspell.el (flyspell-delay-commands) + (flyspell-deplacement-commands): + * textmodes/table.el (table--generate-source-epilogue, table-insert) + (table--generate-source-cells-in-a-row, table--make-cell-map) + (*table--cell-describe-bindings): Use `mapc' rather than `mapcar'. + + 2007-09-25 Juanma Barranquero + + * allout.el (produce-allout-mode-map, allout-process-exposed): + * ansi-color.el (ansi-color-make-color-map): + * autoinsert.el (auto-insert): + * bookmark.el (bookmark-bmenu-list, bookmark-show-all-annotations): + * dired-aux.el (dired-create-files): + * dired.el (dired-restore-desktop-buffer): + * ediff-diff.el (ediff-setup-fine-diff-regions): + * ediff-mult.el (ediff-intersect-directories) + (ediff-redraw-directory-group-buffer, ediff-dir-diff-copy-file) + (ediff-redraw-registry-buffer): + * ediff-ptch.el (ediff-fixup-patch-map): + * ediff-util.el (ediff-toggle-multiframe, ediff-toggle-use-toolbar) + (ediff-really-quit, ediff-clear-diff-vector): + * emerge.el (emerge-really-quit): + * ffap.el (ffap-replace-file-component): + * filecache.el (file-cache-add-directory) + (file-cache-add-directory-recursively) + (file-cache-add-from-file-cache-buffer, file-cache-delete-file-regexp) + (file-cache-delete-directory, file-cache-files-matching-internal) + (file-cache-display): + * files.el (cd): + * find-lisp.el (find-lisp-insert-directory): + * finder.el (finder-compile-keywords): + * help.el (view-emacs-news): + * hi-lock.el (hi-lock-write-interactive-patterns): + * ido.el (ido-to-end, ido-set-matches-1): + * image-dired.el (image-dired-display-thumbs, image-dired-remove-tag) + (image-dired-mark-tagged-files): + * jka-cmpr-hook.el (jka-compr-get-compression-info): + * printing.el (pr-eval-local-alist, pr-eval-setting-alist): + * ps-print.el (ps-background, ps-begin-file) + (ps-build-reference-face-lists): + * simple.el (clone-buffer): + * startup.el (command-line): + * tempo.el (tempo-insert-template, tempo-is-user-element) + (tempo-forward-mark, tempo-backward-mark): + * woman.el (woman-dired-define-keys): Use `mapc' rather than `mapcar'. + + 2007-09-25 Glenn Morris + + * textmodes/tex-mode.el (tex-font-script-display): Doc fix. + + * view.el (view-search-no-match-lines): Add a doc string. + Rewrite to simplify and work better. + + 2007-09-24 Dan Nicolaescu + + * progmodes/cc-mode.el (c-mode-base-map): + Use c-indent-line-or-region instead of c-indent-line. + + * indent.el (indent-for-tab-command): First check if the region is + active. + + 2007-09-24 Micha,Ak(Bl Cadilhac + + * whitespace.el (whitespace-tickle-timer): Don't install the timer if + whitespace-rescan-timer-time is 0. + + 2007-09-24 Karl Berry + + * international/mule.el (coding-system-base): Fix doc string grammar. + + 2007-09-24 Michael Albinus + + * net/tramp.el (tramp-completion-mode-p): Rename from + `tramp-completion-mode'. Revert logic, check `return', `newline' + and such alike. Packages like Icicles tend to use other completion + characters but `tab' and `space' only. + + 2007-09-24 Adam Hupp + + * progmodes/python.el (run-python): Import emacs module without + waiting; prevents lockup on error. + + 2007-09-23 Richard Stallman + + * mail/sendmail.el (mail-bury): Delete the frame + if this frame looks like it was made for this message. + + * completion.el (completion-separator-self-insert-command) + (completion-separator-self-insert-autofilling): + If `self-insert-command' has been remapped, use the substitute. + + * simple.el (copy-region-as-kill): Doc fix. + + * textmodes/org.el (org-confirm-shell-link-function) + (org-confirm-elisp-link-function): Doc fixes. + + 2007-09-23 Glenn Morris + + * ses.el (ses-calculate-cell): Don't evaluate unsafe formulae. + + 2007-09-23 Dan Nicolaescu + + * term/w32-win.el (w32-drag-n-drop): Use mapc instead of mapcar. + + * term/tvi970.el (terminal-init-tvi970): Likewise. + + * term/sun-mouse.el (print-mouse-format): Likewise. + + * term/sun.el (scroll-down-in-place, scroll-up-in-place): + Use forward-line instead of previous-line and next-line. + + 2007-09-22 Juri Linkov + + * textmodes/org.el (org-confirm-shell-link-function): Doc fix. + + * tutorial.el (tutorial--default-keys): Update standard bindings: + rename `iconify-or-deiconify-frame' to `suspend-frame', + and `save-buffers-kill-emacs' to `save-buffers-kill-terminal'. + + 2007-09-22 Juri Linkov + + * startup.el (fancy-startup-text, fancy-about-text, fancy-startup-tail): + Add help-echo to external links and to links without description. + (fancy-splash-insert): Use help-echo from the 3rd element of the + link specification list, or "Follow this link" if it's nil. Doc fix. + + 2007-09-22 Juri Linkov + + * startup.el (command-line): Rename `inhibit-startup-message' to + `inhibit-startup-screen'. + (fancy-about-text): Use shorter label for "Ordering Manuals". + (fancy-startup-tail): Add optional arg `concise'. When `concise' + is nil, display a line with "To start..." and 3 links to useful + tasks. Display the "Dismiss" button and "Don't show this message + again" only when concise is non-nil. + (fancy-startup-screen): Call `fancy-startup-tail' with optional + arg `concise'. If CONCISE is non-nil, display a concise version + of the splash screen in another window. Otherwise, switch to the + startup buffer in the same window. + (startup-echo-area-message): Change displayed binding from + C-h C-p (describe-project) to C-h C-a (about-emacs), and change + text "about the GNU system and GNU/Linux" to "about GNU Emacs and + the GNU system". + (display-startup-screen): Fix buffer name from "*About GNU Emacs*" + to "*GNU Emacs*". + (display-about-screen): Don't check the existence of the buffer + "*About GNU Emacs*". + (display-splash-screen): Make alias to `display-startup-screen'. + (command-line-1): Rename `inhibit-startup-message' to + `inhibit-startup-screen'. Inhibit startup screen when Emacs is + started with command line options "-f", "-funcall", "-e", "-eval", + "-execute", "-insert", "-find-file", "-file", "-visit". + Inhibit startup screen when Emacs is started with a file name only + on tty (i.e. don't inhibit it when started with a file name like + "emacs FILE..." on a window system). + (command-line-1): Simplify logic of displaying the startup screen: + if file-count > 0, then display the concise version in another + window, otherwise display full version in the same window. + + * help.el (help-map): Bind C-h C-a to about-emacs. + (help-for-help-internal): Add C-a description to C-h help text. + + 2007-09-22 Dan Nicolaescu + + * emacs-lisp/checkdoc.el (checkdoc-force-docstrings-flag) + (checkdoc-permit-comma-termination-flag): Autoload the + safe-local-variable setting. + + * bookmark.el (bookmark-xemacsp): Remove. + (bookmark-make): Don't use bookmark-xemacsp, + use (featurep 'xemacs) instead. + + * speedbar.el (speedbar-frame-mode) + (speedbar-frame-reposition-smartly) + (speedbar-set-mode-line-format, speedbar-reconfigure-keymaps) + (speedbar-check-vc): Remove use of non-existent variable + dframe-xemacsp, use (featurep 'xemacs) instead. + + * indent.el (indent-for-tab-command): Indent the region if + transient-mark-mode and the region is active. + + 2007-09-21 Francesco Potort,Al(B + + * progmodes/octave-inf.el (inferior-octave-mode): Use add-hook to + add inferior-octave-directory-tracker to the buffer-local value + of comint-input-filter-functions. + + 2007-09-21 Dan Nicolaescu + + * xt-mouse.el (xterm-mouse-mode): Re-enable suspend-tty-functions. + + 2007-09-21 Juanma Barranquero + + * frame.el (suspend-frame): Call `iconify-or-deiconify-frame' also + on w32 frames. + + 2007-09-21 Stefan Monnier + + * startup.el (normal-top-level): Remove DISPLAY from + process-environment to let it be computed dynamically in callproc.c. + + * frame.el (frame-initialize, make-frame): + * faces.el (tty-set-up-initial-frame-faces): + * env.el (setenv): Don't set display-environment-variable. + + * server.el (server-getenv-from): Remove. Use getenv-internal instead. + (server-create-tty-frame): Don't set unused `tty' property. + Set `display' instead of display-environment-variable. + (server-create-window-system-frame): No display-environment-variable. + + 2007-09-21 Michael Albinus + + * rfn-eshadow.el (rfn-eshadow-setup-minibuffer-hook) + (rfn-eshadow-update-overlay-hook): New defvars. + (rfn-eshadow-setup-minibuffer, rfn-eshadow-update-overlay): + Run the hooks. + + * net/tramp.el (tramp-rfn-eshadow-overlay): New defvar. + (tramp-rfn-eshadow-setup-minibuffer) + (tramp-rfn-eshadow-update-overlay): New defuns. Hook into + rfn-eshadow.el. + + * net/tramp-smb.el (tramp-smb-errors): Add error message for call + timeout. + + 2007-09-21 Glenn Morris + + * obsolete/sun-fns.el (emacs-quit-menu): Remove emacstool-related code. + * term/sun-mouse.el (suspend-emacstool): Remove. + * term/sun.el: Remove emacstool-related code. + + * emacs-lisp/bytecomp.el (byte-compile-warnings) + (byte-compile-warnings-safe-p): Add `mapcar'. + (byte-compile-warning-types): Add mapcar and make-local. + (byte-compile-normal-call): Add option to suppress mapcar warning. + (top-level): Use mapc rather than mapcar in eval-when-compile. + + * textmodes/tex-mode.el (tex-validate-region): Handle escaped parens. + (tex-next-unmatched-eparen, tex-last-unended-eparen): New functions. + (latex-forward-sexp-1, latex-backward-sexp-1): Doc fix. + Handle escaped parens. + (latex-forward-sexp): Doc fix. + + * eshell/esh-mode.el (eshell-output-filter-functions): Add + eshell-postoutput-scroll-to-bottom. + + * loadup.el: Remove termdev. + + * progmodes/fortran.el (fortran-mode-abbrev-table, fortran-line-length): + * progmodes/f90.el (f90-mode-abbrev-table): Use mapc rather than mapcar. + + 2007-09-21 Markus Triska + + * emacs-lisp/bytecomp.el (byte-compile-normal-call): Warn when + `mapcar' is called for effect. + + 2007-09-21 Kevin Ryde + + * international/mule.el (sgml-html-meta-auto-coding-function): + Bind `case-fold-search' to t. + + 2007-09-20 Stefan Monnier + + * termdev.el: Remove. + + * frame.el (get-device-terminal): New function. Moved from termdev.el. + (frames-on-display-list): Use it. + + * bindings.el: Bind C-z to suspend-frame instead of suspend-emacs. + + * termdev.el (terminal-id): Ask terminal-live-p before giving up. + + 2007-09-20 Richard Stallman + + * newcomment.el (comment-add): If EXTRA, double `comment-add' value. + + 2007-09-20 Stefan Monnier + + * add-log.el (add-log-current-defun): Fix thinko w.r.t derived-mode-p. + + 2007-09-20 Glenn Morris + + * textmodes/tex-mode.el (tex-validate-buffer): Use paragraph + motion functions, rather than hard-coding "\n\n". + (tex-validate-region): Check for eobp, to speed up. + (tex-next-unmatched-end): Doc fix. + + 2007-09-19 Stefan Monnier + + * files.el (auto-mode-alist): Use archive-mode for .rar files. + + * international/mule.el (auto-coding-alist): Rar archives are binary. + + * arc-mode.el: Add basic support for Rar. + (archive-find-type): Recognize Rar's signature. + (archive-desummarize): New fun. + (archive-summarize): Use it to restore the buffer's data in case + someone wants to switch to some other major mode. + (archive-resummarize): Use it as well. + (archive-rar-summarize, archive-rar-extract): New functions. + + * filesets.el: Remove spurious * in docstrings. + (filesets-running-xemacs): Remove. Use (featurep 'xemacs) instead. + (filesets-conditional-sort): Remove unused arg `simply-do-it'. + (filesets-ingroup-collect): Remove unused arg `depth'. + (filesets-update): Remove unused arg `version'. + + * finder.el (finder-compile-keywords): Fix up comment style. + (finder-mouse-face-on-line): previous-line -> forward-line. + + * recentf.el: Remove spurious * in docstrings. + (recentf-save-list): Fix up comment style. + + * progmodes/octave-mod.el: Remove spurious * in docstrings. + (octave-mode-map): Move init into declaration and remove \t binding. + (octave-mode-startup-message): Remove unused var. + (octave-scan-blocks): Remove unused arg `from'. + (octave-forward-block, octave-down-block, octave-up-block): + Update callers. + + * progmodes/meta-mode.el (meta-mode-syntax-table): Move init into decl. + (meta-mode-map): Likewise and remove \t binding. + + * net/snmp-mode.el: Remove spurious * in docstrings. + (snmp-rfc1155-types, snmp-rfc1213-types, snmp-rfc1902-types) + (snmp-rfc1903-types, snmp-rfc1155-access, snmp-rfc1902-access) + (snmp-rfc1212-status, snmp-rfc1902-status): Remove list wrappers now + that completion accepts lists of strings. + (snmp-mode-syntax-table): Move initialization into declaration. + (snmp-mode-map): Likewise and remove \t binding. + (snmp-common-mode): Set tab-always-indent according to snmp-t-a-i. + (snmp-indent-line, snmp-mode-imenu-create-index): Remove unused var. + (snmp-indent-command): Remove. + + * emacs-lisp/lisp-mode.el (lisp-mode-shared-map): Use the default TAB + binding, so tab-always-indent works right. + + 2007-09-19 Johannes Weiner + + * net/browse-url.el (browse-url-elinks-new-window): New function. + (browse-url-elinks): Use browse-url-elinks-new-window. + Accept optional second argument `new-window'. Fix typo in doc-string. + (browse-url-elinks-sentinel): Use browse-url-elinks-new-window. + Improve error message. + + 2007-09-19 Micha,Ak(Bl Cadilhac + + * net/browse-url.el (browse-url-url-encode-chars): Use the right + parameter name in the function body. + Reported by Johannes Weiner. + + 2007-09-19 Glenn Morris + + * net/socks.el (socks-open-network-stream): Signal an explicit + error if the port associated with a service string can't be found. + + * textmodes/tex-mode.el (tex-terminate-paragraph): + Use backward-paragraph. + + 2007-09-19 Stefan Monnier + + * server.el (server-running-p): New function. + + 2007-09-18 Jason Rumney + + * term/w32-win.el (w32-focus-frame): Make obsolete alias for + x-focus-frame. + + * frame.el (select-frame-set-input-focus, select-frame-by-name): + Use x-focus-frame for w32. + + 2007-09-17 David Kastrup + + * textmodes/tex-mode.el (tex-verbatim-environments): + Eliminate CL dependency. + + 2007-09-17 Richard Stallman + + * newcomment.el (comment-add): New arg EXTRA. + (comment-region-default): Pass EXTRA if not indenting lines. + + 2007-09-17 Micha,Ak(Bl Cadilhac + + * net/browse-url.el (browse-url-url-encode-chars): New function. + URL-encode some chars in a string. + (browse-url-encode-url): Rewrite using the previous function. + (browse-url-file-url): Use `browse-url-url-encode-chars'. + (browse-url-elinks-sentinel): Fix typo. + (browse-url-new-window-flag): Doc change. + + 2007-09-17 Glenn Morris + + * textmodes/tex-mode.el (tex-compilation-parse-errors): Prefer the + filename from `--file-line-error', if it is available. + + 2007-09-17 Joe Wells (tiny change) + + * textmodes/tex-mode.el (tex-compilation-parse-errors): Also match + TeX `--file-line-error' format. + + 2007-09-17 Dan Nicolaescu + + * xt-mouse.el: Delete add-hook calls that were moved to + xterm-mouse-mode. + (xterm-mouse-mode): Disable resume-tty-functions, explain why it + does not work. + + 2007-09-17 Richard Stallman + + * cus-face.el (custom-theme-set-faces): Undo previous change. + + * faces.el (face-spec-set): When FRAME nil, look up each frame in SPEC. + + 2007-09-17 Glenn Morris + + * textmodes/tex-mode.el (tex-region): Simplify previous change, + handling the case where the region is not in `tex-main-file'. + (tex-region-1): Delete. + (tex-region-header): New function, doing the header part of the + old tex-region-1. + + 2007-09-16 Stefan Monnier + + * simple.el (newline): Simplify use of prefix-numeric-value. + (line-move-partial): Remove unused var `ppos'. + (line-move-1): Replace 9999 with most-positive-fixnum. + (move-end-of-line): Use more efficient single-property search. + (move-beginning-of-line): Remove unused var `start'. + (blink-matching-open): Restructure in a more functional style. + + 2007-09-16 Micha,Ak(Bl Cadilhac + + * calendar/holidays.el (list-holidays): Remove the cyclic alias. + + 2007-09-16 Stefan Monnier + + * server.el (server-clients): Only keep procs, no properties any more. + (server-client): Remove. + (server-client-get, server-client-set): Remove, replace all callers by + process-get and process-put resp. + (server-clients-with, server-add-client, server-delete-client) + (server-create-tty-frame, server-create-window-system-frame) + (server-process-filter, server-execute, server-visit-files) + (server-buffer-done, server-kill-buffer-query-function) + (server-kill-emacs-query-function, server-switch-buffer) + (server-save-buffers-kill-terminal): Update accordingly. + + * server.el (server-with-environment): Simplify. + (server-select-display, server-unselect-display): Re-add functions that + seem to have been lost in the multi-tty merge. + (server-eval-and-print, server-create-tty-frame) + (server-create-window-system-frame, server-goto-toplevel) + (server-execute, server-return-error): New functions extracted from + server-process-filter. + (server-execute-continuation): New functions. + (server-process-filter): Restructure so that all arguments are analysed + first and then acted upon in a subsequent stage. This way + server-goto-toplevel can be executed later, when we know if + it's necessary. + Remove the "-version" and "-version-good" support. + + 2007-09-16 Drew Adams + + * cus-edit (custom-face-edit-activate): Doc fix. + + 2007-09-16 Glenn Morris + + * calendar/cal-menu.el, calendar/calendar.el, calendar/diary-lib.el: + Following cal-bahai renaming, update all instances of + list-bahai-diary-entries to diary-bahai-list-entries, + mark-bahai-diary-entries to diary-bahai-mark-entries, + calendar-goto-bahai-date to calendar-bahai-goto-date, + insert-bahai-diary-entry to diary-bahai-insert-entry, + insert-monthly-bahai-diary-entry to diary-bahai-insert-monthly-entry, + insert-yearly-bahai-diary-entry to diary-bahai-insert-yearly-entry, and + calendar-print-bahai-date to calendar-bahai-print-date. + + * textmodes/tex-mode.el (tex-region): Handle the case where the + region is not in `tex-main-file'. Move the old code that applies + to both cases... + (tex-region-1): ...to this new function. + + 2007-09-15 Stefan Monnier + + * vc.el (vc-process-sentinel): New function. + (vc-exec-after): Use it instead of using ugly hackish analysis and + construction of Elisp code. + (vc-sentinel-movepoint): New dynamically scoped var. + (vc-print-log, vc-annotate): Set it to move the user's point. + + * vc-cvs.el (vc-cvs-annotate-time): Use inhibit-read-only and + inhibit-modification-hooks. + + * calendar/cal-bahai.el (mark-bahai-diary-entries): Fix up typo. + (calendar-bahai-print-date, calendar-bahai-goto-date) + (diary-bahai-list-entries, diary-bahai-insert-entry): + New names to clean up the namespace a bit more. + (calendar-goto-bahai-date, calendar-print-bahai-date): Compat aliases. + + 2007-09-15 Glenn Morris + + * calendar/holidays.el (holiday-list): Rename it back to + `list-holidays', but leave `holiday-list' as an alias. + + * textmodes/bibtex-style.el (bibtex-style-indent-basic): Specify a + custom group. + + * textmodes/css-mode.el (css): New custom group. + (css-electrick-keys, css-selector, css-property) + (css-indent-offset): Specify custom group. + + 2007-09-15 Stefan Monnier + + * pcvs.el (cvs-tags-list, cvs-retrieve-revision, cvs-find-modif) + (cvs-execute-single-file): Use process-file. + (cvs-run-process): Use start-file-process. + + 2007-09-15 Dan Nicolaescu + + * xt-mouse.el (xterm-mouse-mode): Add hooks here not at the top + level. Remove the hooks when turning off the mode. + + * term/xterm.el: Require xt-mouse at compile time. + (terminal-init-xterm): Turn on xterm mouse tracking for this + terminal if xterm-mouse-mode is enabled. + + 2007-09-14 Dan Nicolaescu + + * term/xterm.el (xterm-function-map): Replace bindings that were + deleted by the merge. + + 2007-09-14 Ulf Jasper + + * play/bubbles.el (bubbles-version): Bump value to "0.5". + (bubbles-mode-map): Move define-key statements here. + (bubbles-game-theme-menu): Ditto. + (bubbles-graphics-theme-menu): Ditto. + (bubbles-menu): Ditto. + (bubbles-mode): Initialize buffer-undo-list, redisplay. + (bubbles--initialize): Reset buffer-undo-list, redisplay. + (bubbles-plop): Set buffer-undo-list, redisplay. + (bubbles-undo): Reset buffer-undo-list, redisplay. + (bubbles--show-images): Take care of missing text properties. + + 2007-09-14 Glenn Morris + + * startup.el (fancy-startup-text, fancy-about-text): Fix face + quoting. + + * calendar/cal-hebrew.el, calendar/cal-menu.el + * calendar/calendar.el, calendar/diary-lib.el + * calendar/holidays.el: Rename all instances of + list-calendar-holidays callers to calendar-list-holidays, + list-holidays to holiday-list, check-calendar-holidays to + calendar-check-holidays, mark-calendar-holidays to + calendar-mark-holidays, and filter-visible-calendar-holidays to + holiday-filter-visible-calendar. + + 2007-09-14 Dan Nicolaescu + + * term/xterm.el (xterm-function-map): Add C-M- bindings. + + 2007-09-13 Sascha Wilde (tiny change) + + * play/bubbles.el (bubbles--initialize-images): Fix bug: + Use transparent background for empty cells in graphics mode. + + 2007-09-13 Jari Aalto + + * man.el (Man-default-man-entry): At end of line, continue looking + to the next line for possible end of hyphenated command. + + 2007-09-13 Chris Moore + + * shell.el (shell-resync-dirs): Don't move the cursor relative to + the command being edited. + + 2007-09-12 Jim Meyering (tiny change) + + * emacs-lisp/copyright.el (copyright-names-regexp): Doc fix: typo. + + 2007-09-12 Dan Nicolaescu + + * term/xterm.el (xterm-function-map): Add bindings for M-S- and + C-M-S- keys. + + * term/rxvt.el (rxvt-function-map): Initialize in the declaration. + + 2007-09-12 Micha,Ak(Bl Cadilhac + + * net/browse-url.el (browse-url-encode-url): Fix an infinite loop. + New argument `filename-p' to use one set of confusing chars or another. + (browse-url-file-url): Use the argument. + Suggested by Johannes Weiner. + + 2007-09-12 Romain Francoise + + * cus-start.el (all): Revert 2007-09-08 change. + + 2007-09-12 Aaron Hawley + + * jka-cmpr-hook.el (jka-compr-compression-info-list): Use gzip to + extract .Z files, since it is more common than uncompress. + + 2007-09-12 Glenn Morris + + * textmodes/org-publish.el (org-publish-org-to-html): Remove + duplicate function definition. + + 2007-09-10 Chris Moore + + * diff-mode.el (diff-sanity-check-hunk): + Also accept single-line hunks. + + 2007-09-10 Chong Yidong + + * startup.el (startup-screen-inhibit-startup-screen) + (pure-space-overflow-message): New vars. + (fancy-splash-insert): Allow functions for face and link specs. + (fancy-splash-head): Remove unused arg. Move splash text... + (fancy-startup-text, fancy-about-text): ...here. + (fancy-startup-tail): Rename from fancy-splash-tail. + (fancy-startup-screen, fancy-about-screen): Split off from + fancy-splash-screens. + (display-startup-screen): New function. + (display-about-screen): Rename from display-splash-screen. + (command-line-1): Use concise startup screen if necessary. + + 2007-09-10 Thien-Thi Nguyen + + * net/browse-url.el (browse-url-encode-url): Use copy-sequence. + Reported by Jan Dj,Ad(Brv . + + 2007-09-10 Stefan Monnier + + * progmodes/python.el: Merge changes from Dave Love's v2007-Sep-10. + (python-font-lock-keywords): Update to the 2.5 version of the language. + (python-quote-syntax): Let-bind font-lock-syntactic-keywords to nil. + (python-backspace): Only behave funny in code. + (python-compilation-regexp-alist): Add PDB stack trace regexp. + (inferior-python-mode): Add PDB prompt regexp. + (python-fill-paragraph): Refine the fenced-string regexp. + (python-find-imports): Handle imports spanning several lines. + (python-mode): Add `class' to hideshow support. + + 2007-09-10 Dave Love + + * outline.el (outline-4, outline-5, outline-7): + Move font-lock-builtin-face down from 4 to 7 to better keep the + progression of color brightness, and to better match Org-mode's faces. + + 2007-09-10 Micha,Ak(Bl Cadilhac + + * progmodes/meta-mode.el (meta-font-lock-keywords) + (font-lock-match-meta-declaration-item-and-skip-to-next) + (meta-comment-indent, meta-indent-previous-line) + (meta-indent-unfinished-line, meta-beginning-of-defun) + (meta-end-of-defun, meta-common-initialization): Handle \f. + (meta-indent-unfinished-line): Do not handle a `%' in a string as + a comment-start. + + * files.el (file-modes-char-to-who, file-modes-char-to-right) + (file-modes-rights-to-number): Auxiliary functions for symbolic to + numeric notation of file modes. + (file-modes-symbolic-to-number): New. Convert symbolic modes to its + numeric value. + (read-file-modes): New. Read either an octal value of a file mode or a + symbolic value, and return its numeric value. + + * dired-aux.el (dired-do-chmod): Change to use the built-in + `set-file-modes' and the previous symbolic mode parsing functions. + + 2007-09-10 Stefan Monnier + + * textmodes/texinfo.el: Remove spurious * in docstrings. + (texinfo-mode-syntax-table, texinfo-mode-map): + Initialize in the declaration. + + * tmm.el: Remove spurious * in docstrings. + (tmm-prompt): Use with-current-buffer. + + * vcursor.el: Remove spurious * in docstrings. + (vcursor-map): Initialize in the declaration. + (vcursor-use-vcursor-map): Use define-minor-mode. + (vcursor-toggle-vcursor-map): Keep as an obsolete alias. + + * wid-browse.el (widget-browse-mode-map, widget-minor-mode-map): + Initialize in the declaration. + (widget-minor-mode): Use define-minor-mode. + + * woman.el (woman-mode-map, woman-syntax-table): + Initialize in the declaration. + + 2007-09-09 Tassilo Horn + + * doc-view.el: New file. + + 2007-09-09 Juri Linkov + + * Makefile.in (update-authors): Add etc/ to AUTHORS. + + * makefile.w32-in (update-authors): Add etc/ to AUTHORS. + + * startup.el (initial-buffer-choice): Rename choice "Splash screen" + to "Startup screen". Fix docstring. + (inhibit-startup-screen): Rename from `inhibit-splash-screen'. + (inhibit-splash-screen): Make alias to `inhibit-startup-screen'. + (inhibit-startup-message): Change alias to `inhibit-startup-screen'. + (initial-scratch-message): Fix docstring. + (fancy-startup-text): Move link to Emacs Manual below Emacs Guided + Tour (which is a kind of tutorial and will be next to Emacs Tutorial). + Add link to "Customize Startup" and set interval between links to + 5 spaces. + (fancy-about-text): Add links "Authors" and "Contributing". + (fancy-splash-head): Add text "Welcome to " on the startup screen, + and "This is " on the about screen. Add link to + "http://www.gnu.org/software/emacs/" for "GNU Emacs". + For the about screen move emacs version to the header from + `fancy-splash-tail' (as it's done already for normal about screen). + (fancy-splash-tail): Insert emacs version only for startup screen. + (normal-splash-screen): Remove duplicate empty lines. + (normal-about-screen): Add links "Authors" and "Contributing". + + * menu-bar.el (menu-bar-help-menu): + Move "About Emacs" and "About GNU" to the end of the Help menu. + Move "Emacs Psychotherapist" after "Send Bug Report...". + Move "External Packages" after "Find Emacs Packages". + + 2007-09-09 Michael Albinus + + * net/tramp.el (top): Remove declarations of `tramp-gw-*' symbols, + they are useless with the byte compiler. + (tramp-make-temp-file, tramp-make-tramp-temp-file): Move up. + (tramp-do-copy-or-rename-file-directly): Rearrange let-bindings. + (tramp-compute-multi-hops): Mask `tramp-gw-*' symbols. + (tramp-file-name-real-host, tramp-file-name-port) + (tramp-find-method, tramp-find-user, tramp-find-host): Make them + defuns. + + * net/tramp-cache.el (top): Improve error message when + `tramp-persistency-file-name' is corrupted. + + 2007-09-09 Carsten Dominik + + * textmodes/org.el (org-re): Also replace the :alpha: class. + (org-todo-tag-alist): Variable removed. + (org-todo-key-alist, org-todo-key-trigger) New variables. + (org-use-fast-todo-selection): New option. + (org-log-done): Docstring fixed. + (org-deadline-warning-days): New default value 14. + (org-edit-timestamp-down-means-later) New option. + (org-tag-alist): Docstring fixed. + (org-fast-tag-selection-include-todo): New option. + (org-export-language-setup): New languages added. + (org-set-regexps-and-options): Compute the new variables. + (org-paste-subtree): Cleaning up. + (org-remember-apply-template): New escape %A. + (org-todo): Call fast TODO selection. + (org-fast-todo-selection): New function. + (org-add-log-note): Allow prefix for abort exit. + (org-at-property-p, org-entry-properties) + (org-columns-get-autowidth-alist): Use :alpha: class. + (org-get-wdays): New function. + (org-agenda-remove-date): New variable. + (org-agenda-get-deadlines): Use `org-get-wdays'. + (org-agenda-get-deadlines): Reverse ee before returning. + (org-format-agenda-item): New argument REMOVE-RE. + (org-agenda-convert-date): Baha'i calendar added. + (org-infile-export-plist): Also find DATE line. + (org-get-min-level): New function. + (org-export-as-html, org-export-as-ascii): Use the date format. + (org-shiftup, org-shiftdown): Use. + `org-edit-timestamp-down-means-later'. + (org-assign-fast-keys): New function. + + 2007-09-08 Fredrik Axelsson + + * cus-start.el (all): Add prefer-window-split-horizontally from + window.c. + + 2007-09-08 Eli Zaretskii + + * net/browse-url.el (browse-url-galeon): Fix last change. + (top-level): Require cl when compiling. + + 2007-09-08 Carsten Dominik + + * textmodes/org-export-latex.el: arch-tag restored. + + * textmodes/org-publish.el: arch-tag restored. + + 2007-09-08 Masatake YAMATO + + * progmodes/which-func.el (which-func-modes): Add diff-mode. + + * progmodes/cc-langs.el: Support new keywords added to + objective-c frontend of gcc. + (c-simple-stmt-kwds): Add @throw. + (c-block-stmt-2-kwds): Add @synchronized. + (c-block-stmt-1-kwds): Add @finally and @try. + + 2007-09-07 Carsten Dominik + + * textmodes/org.el (org-edit-timestamp-down-means-later): New option. + (org-agenda-after-show-hook): New variable. + (org-columns-compile-format) + (org-columns-get-autowidth-alist, org-buffer-property-keys) + (org-entry-properties, org-at-property-p): Allow [:alnum:] in + property names. + (org-get-wdays): New function. + + 2007-09-07 Stefan Monnier + + * simple.el (normal-erase-is-backspace-setup-frame): Massage. + + * term/xterm.el (xterm-function-map): Initialize in the declaration. + + * vc-arch.el (vc-arch-checkin): Fix typo. + + 2007-09-07 Johan Bockg,Ae(Brd + + * cus-face.el (custom-theme-set-faces): Set face attributes + locally for each frame. + + 2007-09-07 Stefan Monnier + + * progmodes/fortran.el (fortran-mode): Set font-lock-syntactic-keywords + via font-lock-defaults. + + * emacs-lisp/bytecomp.el (byte-compile-log-file): Check major-mode via + derived-mode-p. + + 2007-09-07 Thien-Thi Nguyen + + * progmodes/autoconf.el (autoconf-definition-regexp): + Handle optional square brackets around definition name. + + 2007-09-07 Johannes Weiner + + * net/browse-url.el (browse-url-browser-function): Add elinks. + (browse-url-elinks-wrapper): New option. + (browse-url-encode-url, browse-url-elinks) + (browse-url-elinks-sentinel): New functions. + (browse-url-file-url, browse-url-netscape, browse-url-mozilla) + (browse-url-firefox, browse-url-galeon, browse-url-epiphany): + Use new function browse-url-encode-url. + + 2007-09-07 Glenn Morris + + * version.el (emacs-version): Revert 2007-08-29 change: no need to + say if multi-tty is present. + + 2007-09-07 Stefan Monnier + + * cus-start.el (split-window-preferred-function): Add custom info. + + * calendar/holidays.el (holiday-list, calendar-check-holidays) + (calendar-mark-holidays, calendar-list-holidays) + (holiday-filter-visible-calendar): New names to clean up namespace. + (filter-visible-calendar-holidays, list-calendar-holidays) + (mark-calendar-holidays, check-calendar-holidays, list-holidays): + Add compatibility aliases. + (calendar-check-holidays, calendar-mark-holidays) + (calendar-holiday-list, holiday-filter-visible-calendar): Use dolist. + (holiday-sexp): Replace append with list. + (holiday-filter-visible-calendar): Replace append with push. + + * woman.el: Remove spurious * in docstrings. + (woman-mini-help, woman-non-underline-faces, woman0-rename) + (woman-topic-all-completions-merge, woman-file-name-all-completions) + (woman-select-symbol-fonts, woman-expand-directory-path): Use dolist. + (woman-write-directory-cache, woman-display-extended-fonts) + (WoMan-log-begin, WoMan-log-1): Use with-current-buffer. + (woman-really-find-file): Use pop-to-buffer if switch-to-buffer fails. + (woman-mode): Use inhibit-read-only. + (woman-negative-vertical-space): Use dotimes. + (woman2-tagged-paragraph, woman-tab-to-tab-stop): Use insert-char. + + 2007-09-06 Romain Francoise + + * vc-bzr.el (vc-bzr-admin-lastrev): New defconst. + (vc-bzr-workfile-version): Use it. + + 2007-09-06 Sean O'Rourke + + * complete.el (PC-do-completion): Don't try to treat + empty string as an abbreviation. + + 2007-09-06 Johan Bockg,Ae(Brd + + * help-fns.el (describe-variable): Keep doc's text properties. + + 2007-09-06 Dan Nicolaescu + + * vc.el (vc-default-diff-tree): Pass a list to the diff vc command + instead of a file. + + 2007-09-06 Glenn Morris + + * emacs-lisp/checkdoc.el (checkdoc-minor-mode-string): New. + (checkdoc-minor-mode): Allow user to specify lighter via + checkdoc-minor-mode-string. + + 2007-09-05 Richard Stallman + + * startup.el (fancy-startup-text): Rename from fancy-splash-text. + Several items removed, simplified, or put on one line. + (fancy-about-text): Add substantial contents, part of startup text. + (fancy-splash-head): Make "GNU" or "GNU/Linux" a link. + (normal-splash-screen): Call normal-mouse-startup-screen, + normal-no-mouse-startup-screen, or normal-about-screen. + (normal-mouse-startup-screen): New fn, broken out, shortened. + (normal-no-mouse-startup-screen): New fn, broken out. + (normal-about-screen): New function, contents all new. + + 2007-09-05 Micha,Ak(Bl Cadilhac + + * emacs-lisp/rx.el (rx): Fix typo in docstring. + + 2007-09-05 Glenn Morris + + * cus-edit.el (custom-buffer-create-internal): Check tool-bar-mode + is bound. + + 2007-09-05 Johan Bockg,Ae(Brd + + * emacs-lisp/advice.el (ad-make-advised-docstring): Highlight note + in doc string. + + 2007-09-04 Dan Nicolaescu + + * server.el (server-start, server-unload-hook): Undo previous change. + + * xt-mouse.el: Undo previous change. + + 2007-09-04 Juri Linkov + + * startup.el (fancy-about-text): New variable. + (fancy-splash-delay, fancy-splash-max-time): Remove user options. + (fancy-current-text, fancy-splash-stop-time) + (fancy-splash-outer-buffer): Remove variables. + (fancy-splash-head, fancy-splash-tail): Add new optional argument + `startup' and use it to conditionally display different texts for + Startup and About screens. Don't display Help commands on the About + screen. + (fancy-splash-screens-1): Remove function and move its content to + `fancy-splash-screens' to the part that dislpays the About screen. + (exit-splash-screen): Don't treat specially exiting from + alternating screens. + (fancy-splash-screens): Rename argument `static' to `startup'. + Fix docstring. Remove code for displaying alternating screens. + Use arg `startup' in calls to `fancy-splash-head', `fancy-splash-tail'. + Remove let-bind for `fancy-splash-outer-buffer' and add let-bind + for `inhibit-read-only'. + (normal-splash-screen): Rename argument `static' to `startup'. + Fix docstring. Use argument `startup' to conditionally display + different texts for Startup and About screens. Don't display Help + commands on the About screen. Remove `unwind-protect' `sit-for' + delay and `kill-buffer' after it. + (display-startup-echo-area-message): Remove call to + `use-fancy-splash-screens-p' because image.el is preloaded and + doesn't display "Loading image... done". + (display-splash-screen): Rename argument `static' to `startup'. + Fix docstring. + + 2007-09-04 Dan Nicolaescu + + * server.el (server-start, server-unload-hook): + suspend-tty-functions has been renamed to suspend-tty-hook. + + * xt-mouse.el: Likewise. resume-tty-functions has been renamed to + resume-tty-hook. + + 2007-09-03 Emanuele Giaquinta (tiny change) + + * loadup.el: Fix merge problem, only load "button" once. + + 2007-09-03 Glenn Morris + + * vc-svn.el (vc-svn-print-log): If there is only one file, use + "Working file:" as the prefix, for the sake of + log-view-current-file. + + 2007-09-02 Dan Nicolaescu + + * term/xterm.el (xterm-modify-other-keys-terminal-list): New variable. + (xterm-turn-on-modify-other-keys): Only turn on modify-other-keys + if the selected frames is in + xterm-modify-other-keys-terminal-list. + (xterm-turn-off-modify-other-keys): Add an optional frame + parameter. Only turn off modify-other-keys if FRAME is in + xterm-modify-other-keys-terminal-list. + (xterm-remove-modify-other-keys): New function. + (terminal-init-xterm): Use it. Deal with delete-frame hook. + Add the selected frame to xterm-modify-other-keys-terminal-list. + + 2007-09-02 Jan Dj,Ad(Brv + + * term/x-win.el (x-gtk-stock-map): Map diropen to system-file-manager. + (icon-map-list): New variable. + (x-gtk-map-stock): Use icon-map-list. + + 2007-09-02 Romain Francoise + + * log-view.el (log-view-current-file): Balance parens. + + 2007-09-02 Glenn Morris + + * comint.el (comint-mode): Don't set scroll-conservatively. + + * eshell/em-unix.el (eshell/time): Stringify and flatten the + non-command arguments. + + * log-view.el (log-view-current-file): Give a more explicit error + if log-view-file-re fails to find a match. + + 2007-09-01 Thien-Thi Nguyen + + * emacs-lisp/bytecomp.el (byte-recompile-directory): + Fix bug: Don't expand top-level file name more than once. + Reported by Dmitry Antipov . + + 2007-09-01 Stefan Monnier + + * server.el (server-process-filter): Don't display the splash screen. + It's annoying enough on the initial screen and becomes positively + obnoxious here. + + 2007-08-31 Stefan Monnier + + * emacs-lisp/avl-tree.el: Use defstruct rather than macros. + Change naming to use "avl-tree--" for internal functions. + + 2007-08-31 Dan Nicolaescu + + * term/x-win.el (x-menu-bar-open): Delete duplicated function from + the merge. + (global-set-key): Delete f10 mapping, now done in menu-bar.el. + (provide): Move to the end of file. + + * vc-svn.el (vc-svn-diff-tree): Pass a list to vc-svn-diff. + + 2007-08-31 Micha,Ak(Bl Cadilhac + + * textmodes/flyspell.el (flyspell-mark-duplications-exceptions): + New variable. List of exceptions for the duplicated word rule. + (flyspell-mark-duplications-flag): Mention it. + (flyspell-word): Treat it. + + * files.el (create-file-buffer): If the filename sans directory starts + with spaces, remove them. + + 2007-08-31 Jan Dj,Ad(Brv + + * term/x-win.el (x-gtk-stock-map): Add etc/images to keys. + (x-gtk-map-stock): Use two directory elements when matching + file name. + + 2007-08-31 James Wright + + * eshell/em-unix.el (eshell/info): New function. + + 2007-08-31 Stefan Monnier + + * frame.el (frame-initialize, make-frame): + * server.el (server-process-filter): + * faces.el (tty-set-up-initial-frame-faces): Don't set + term-environment-variable since it's not used any more. + + * env.el (setenv): Don't treat $TERM specially. + + * startup.el (normal-top-level): Set $TERM to `dumb' so that unless + stated otherwise, subprocesses do not send back escape sequences + corresponding to the terminal from which Emacs was started. + + 2007-08-31 Thien-Thi Nguyen + + * calculator.el: Require cl for compilation. + + 2007-08-30 Daniel Pfeiffer + + * outline.el (outline-font-lock-levels): Comment out unused var. + (outline-font-lock-face): Wrap around face list to handle any + nesting depth gracefully. + + 2007-08-30 Michael Albinus + + * net/ange-ftp.el: Add ange-ftp property to `set-file-modes' and + `set-file-times'. + + 2007-08-30 Carsten Dominik + + * textmodes/org.el (org-export-visible): Fix drawers before export. + (org-do-sort): Allow sorting by priority. + (org-agenda-files): Ignore non-existing files. + (org-agenda-skip-unavailable-files): New variable. + (org-ellipsis): All a face as value. + (org-mode): Interprete the face value of `org-ellipsis'. + (org-archive-save-context-info): New option. + (org-archive-subtree): Store context info in archived entry. + (org-fast-tag-selection-can-set-todo-state): New variable. + (org-fast-tag-selection): Allow setting TODO states through this + interface. + (org-cycle): Docstring updated. + (org-todo-keyword-faces): New option. + (org-get-todo-face): New function. + (org-set-font-lock-defaults, org-agenda-highlight-todo): + Use `org-get-todo-face'. + (org-switch-to-buffer-other-window): New function. + (org-table-edit-field, org-table-show-reference) + (org-table-edit-formulas, org-add-log-note) + (org-fast-tag-selection, org-agenda, org-prepare-agenda) + (org-timeline): Use `org-switch-to-buffer-other-window' instead of + `switch-to-buffer-other-window' to make sure that the temporary + windows show up on the current frame. + (org-mhe-get-message-real-folder, org-batch-store-agenda-views) + (org-get-entries-from-diary, org-replace-region-by-html): + Don't allow pop-up frames. + (org-agenda-get-deadlines, org-agenda-get-scheduled): + Fix problems with time-of-day. + (org-export-get-title-from-subtree): New function. + (org-agenda-get-scheduled, org-agenda-get-deadlines): Fix problems + with listing items that are DONE. + (org-change-tag-in-region): New command. + (org-agenda-skip-scheduled-if-done) + (org-agenda-skip-deadline-if-done): Docstring clarified. + (org-mode): Hide drawers on startup. + (org-get-todo-face): New function. + (org-todo-keyword-faces): New option. + (org-set-regexps-and-options): Use `org-remove-keyword-keys'. + (org-remove-keyword-keys): New function. + + 2007-08-30 Jari Aalto (tiny change) + + * progmodes/grep.el (grep-find-ignored-directories): + Add monotone _MTN bookkeeping directory in workspaces. + Add RCS control directory. List items in alphabetical order. + + * progmodes/grep.el (grep-files-aliases): Add cc alias. + Sort items in alphabetical order. Fix parens. + + 2007-08-29 Dan Nicolaescu + + * vc-hg.el (vc-hg-extra-menu-map): New variable. + (vc-hg-extra-menu, vc-hg-outgoing, vc-hg-incoming, vc-hg-push) + (vc-hg-pull): New functions. + (vc-hg-outgoing-mode, vc-hg-incoming-mode): New derived modes. + + * term/mac-win.el: Don't require url, only autoloaded url + functions are used in this file. + + 2007-08-29 Andreas Schwab + + * shell.el (shell): Return correct value from interactive spec. + + 2007-08-29 Glenn Morris + + * version.el (emacs-version): Increase to 23.0.50. + + 2007-08-29 Jan Dj,Ad(Brv + + * term/x-win.el (x-gtk-stock-map): :version changed to 23.1. + + 2007-08-29 Juri Linkov + + * loadup.el: Add "button" loading after "faces" and move "startup" + to load after "button". + + 2007-08-29 Dan Nicolaescu + + * loadup.el: Load term/mac-win on a Mac using Carbon. + + * term/mac-win.el: Provide mac-win. + (mac-initialized): New variable. + (mac-initialize-window-system): New function. Move global setup here. + (handle-args-function-alist, frame-creation-function-alist): + (window-system-initialization-alist): Add mac entries. + (x-setup-function-keys): New function containing all the + top level function key definitions. + + * term/x-win.el (x-menu-bar-open): Use accelerate-menu. + + * env.el (read-envvar-name): Don't consider the environment frame param. + + * env.el (setenv): + * frame.el (frame-initialize, make-frame): + * faces.el (tty-set-up-initial-frame-faces): + * server.el (server-process-filter): Set + display-environment-variable and term-environment-variable. + + * server.el (server-process-filter): Set COLORFGBG and COLORTERM. + + 2007-08-29 Jason Rumney + + * loadup.el: Only load term/x-win when X is compiled in. + Load term/w32-win and dependencies on windows-nt. + + * term/w32-win.el: Reorder to match x-win.el more closely. + Provide w32-win. Don't throw error when global window-system not w32. + (internal-face-interactive): Remove obsolete function. + (x-setup-function-keys): Use local-function-key-map. + (w32-initialized): New variable. + (w32-initialize-window-system): Set it. + Move more global setup here. + (x-setup-function-keys): New function. + (w32-initialize-window-system): Move non function key global setup here. + (x-cut-buffer-max): Remove. + (w32-initialize-window-system): New function. + (handle-args-function-alist, frame-creation-function-alist): + (window-system-initialization-alist): Add w32 entries. + + 2007-08-29 David Kastrup + + * env.el (getenv): Pass frame to getenv-internal. + + 2007-08-29 Karoly Lorentey + + * version.el (emacs-version): Show if multi-tty is present. + + * loadup.el: Delay loading env; mule-conf gets confused by cl + during bootstrap. Also load termdev and term/x-win. + + * bindings.el (mode-line-client): New variable. + (help-echo): Add it to the default mode-line format. + + * cus-start.el: Remove bogus window-system reference from GTK test. + + * ebrowse.el (ebrowse-electric-list-mode-map) + (ebrowse-electric-position-mode-map): + * ebuff-menu.el (electric-buffer-menu-mode-map): + * echistory.el (electric-history-map): Bind C-z to `suspend-frame', + not `suspend-emacs'. + + * ediff-wind.el (ediff-setup-windows-automatic): New function. + (ediff-window-setup-function): Use it as default. + + * files.el (save-buffers-kill-terminal): New function. + (ctl-x-map): Change binding of C-x C-c to save-buffers-kill-terminal. + + * font-lock.el (lisp-font-lock-keywords-2): Add `let-environment' + and `with-selected-frame'. + + * help-fns.el (describe-variable): Describe frame-local variables + correctly. + + * simple.el (normal-erase-is-backspace-mode): Rewrite for multiple + display support. + (normal-erase-is-backspace-setup-frame): New function. + + * subr.el (with-selected-frame): New function. + (read-quoted-char): Use terminal-local binding of + local-function-key-map instead of function-key-map. + + * talk.el (talk): New function. + (talk-handle-delete-frame): New function. + (talk-add-display): Open a new frame only if FRAME was not a frame. + + * termdev.el: New file. + + * menu-bar.el (menu-bar-open): New function. Bind it to f10. + * term/x-win.el: Don't bind f10. + * tmm.el: Remove autoload binding for f10. + + * international/encoded-kb.el (encoded-kbd-setup-display): Use + `set-input-meta-mode'. Fix broken condition before set-input-mode. + Store the saved input method as a terminal parameter. Add keymap + parameter. Use it instead of changing key-translation-map directly. + (saved-key-translation-map, encoded-kbd-mode, saved-input-mode): + Remove. + (encoded-kbd-setup-display): New function. + + * international/mule-cmds.el (set-locale-environment): Fix getenv + call. Use save-buffers-kill-terminal. Ignore window-system; always + set the keyboard coding system. Add DISPLAY parameter. + (set-display-table-and-terminal-coding-system): Add DISPLAY + parameter. Pass it to set-terminal-coding-system. + + * international/mule.el (keyboard-coding-system): Test for + encoded-kbd-setup-display, not encoded-kbd-mode. + (set-terminal-coding-system, set-keyboard-coding-system): Add + DISPLAY parameter. + (set-keyboard-coding-system): Use encoded-kbd-setup-display. + + * term/README: Update. + + * term/linux.el (terminal-init-linux): Use `set-input-meta-mode'. + + * term/x-win.el (x-setup-function-keys): New function. Move + function-key-map tweaks here. Protect against multiple calls on + the same terminal. Use terminal-local binding of + local-function-key-map instead of function-key-map. + (x-initialize-window-system): Make a copy of pure list. Pass a + frame getenv. + + * term/vt200.el, term/vt201.el, term/vt220.el, term/vt240.el: + * term/vt300.el, term/vt320.el, term/vt400.el, term/vt420.el: + * term/AT386.el, term/internal.el, term/iris-ansi.el, term/lk201.el: + * term/mac-win.el, term/news.el, term/rxvt.el, term/sun.el: + * term/tvi970.el, term/wyse50.el: Use terminal-local binding of + local-function-key-map instead of function-key-map. + + * term/rxvt.el, term/xterm.el: Speed up load time by protecting + `substitute-key-definition' and `define-key' calls against + multiple execution. Use terminal-local binding of + local-function-key-map instead of function-key-map. Pass a frame + to getenv. + + * edmacro.el (edmacro-format-keys): + * emulation/cua-base.el (cua--pre-command-handler): + * isearch.el (isearch-other-meta-char): + * xt-mouse.el: Use terminal-local binding of + local-function-key-map instead of function-key-map. + + * fringe.el (set-fringe-mode): Simplify and fix using + `modify-all-frames-parameters'. + * scroll-bar.el (set-scroll-bar-mode): Ditto. + * tool-bar.el (tool-bar-mode): Ditto. Remove 'tool-bar-map length + check before calling `tool-bar-setup'. + (tool-bar-setup): New variable. + (tool-bar-setup): Use it to guard against multiple calls. Add + optional frame parameter, and select that frame before adding items. + (toggle-tool-bar-mode-from-frame): New function. + + * menu-bar.el (toggle-menu-bar-mode-from-frame): New function. + (menu-bar-showhide-menu): Use toggle-menu-bar-mode-from-frame and + toggle-tool-bar-mode-from-frame to change "Menu-bar" and + "Tool-bar" toggles to reflect the state of the current frame. + (menu-bar-mode): Simplify and fix using `modify-all-frames-parameters'. + + * env.el: Require cl for byte compilation (for `block' and `return'). + (environment, setenv-internal): New functions. + (let-environment): New macro. + (setenv, getenv): Add optional terminal parameter. Update docs. + (setenv): Use setenv-internal. Always set process-environment. + Handle `local-environment-variables'. + (read-envvar-name, setenv, getenv): Use frame parameters + to store the local environment, not terminal parameters. Include + `process-environment' as well. + + * faces.el (tty-run-terminal-initialization): New function. + (tty-create-frame-with-faces): Use it. Set up faces and + background mode only after the terminal has been initialized. + Call terminal-init-*. Don't load the initialization file more + than once. Call set-locale-environment. + (frame-set-background-mode): Handle the 'background-mode terminal + parameter. + (tty-find-type): New function. + (x-create-frame-with-faces): Remove bogus check for + first frame. Call `tool-bar-setup'. Don't make frame visible + until we are done setting up all its parameters. Call + x-setup-function-keys. + + * frame.el (make-frame): Always inherit 'environment and 'client + parameters. Set up the 'environment frame parameter, when needed. + Also inherit 'client parameter. Don't override explicitly + specified values with inherited ones. Add 'terminal frame + parameter. Append window-system-default-frame-alist to parameters + before calling frame-creation-function. + (frame-initialize): Copy the environment from the initial frame. + (window-system-default-frame-alist): Enhance doc string. + (frame-notice-user-settings): Don't put 'tool-bar-lines in + `default-frame-alist' when initial frame is on a tty. + (modify-all-frames-parameters): Simplify using `assq-delete-all'. + Remove specified parameters from `window-system-default-frame-alist'. + (make-frame-on-tty, framep-on-display, suspend-frame): + Extend doc string, update parameter names. + (frames-on-display-list): Use terminal-id to get the display id. + (frame-notice-user-settings): Extend to apply + settings in `window-system-default-frame-alist' as well. + (terminal-id, terminal-parameters, terminal-parameter) + (set-terminal-parameter, terminal-handle-delete-frame): New functions. + (delete-frame-functions): Add to `delete-frame-functions' hook. + (blink-cursor-mode): Adapt blink-cursor-mode default + value from startup.el. + (make-frame-on-display): Protect condition on x-initialized when + x-win.el is not loaded. Update doc. + (suspend-frame): Use display-controlling-tty-p to decide between + suspend-emacs and suspend-tty. + (frames-on-display-list): Update for display ids. + (framep-on-display): Ditto. + (suspend-frame): Use display-name, not frame-tty-name. + (selected-terminal): New function. + + * server.el: Use `device' instead of `display' or `display-id' in + variable and client parameter names. + (server-select-display): Remove (unused). + (server-tty-live-p, server-handle-delete-tty): Remove. + (server-unquote-arg, server-quote-arg, server-buffer-clients): + Update docs. + (server-getenv-from, server-with-environment, server-send-string) + (server-save-buffers-kill-terminal): New functions. + (server-delete-client): Handle quits in kill-buffer. Don't kill + modified buffers. Add extra logging. Delete frames after + deleting the tty. Clear 'client parameter before deleting a frame. + Use delete-display, not delete-tty. + (server-visit-files): Don't set `server-existing-buffer' if the + buffer already has other clients. Return list of buffers + created. Update doc. Don't set client-record when nowait. + (server-handle-delete-frame): Delete the client if this was its + last frame. Check that the frame is alive. Remove bogus comment. + Add note on possible race condition. Delete tty clients, if needed. + (server-handle-suspend-tty): Use server-send-string. Kill the + client in case of errors from process-send-string. Use the display + parameter. + (server-unload-hook): Remove obsolete delete-tty hook. + (server-start): Ask before restarting if the old server still has + clients. Add feedback messages. Remove obsolete delete-tty hook. + (server-process-filter): Use server-send-string. Accept `-dir' + command. Switch to *scratch* immediately after creating the frame, + before evaluating any -evals. Protect `display-splash-screen' + call in a condition-case. Explain why. Call + `display-startup-echo-area-message' before + `display-splash-screen'. Don't display the splash screen when no + frame was created. Show the Emacs splash screen and startup echo + area message. Display the *scratch* buffer by default. Store the + local environment in a frame (not terminal) parameter. Do not try + to decode environment strings. Fix reference to the 'display + frame parameter. Change syntax of environment variables. Put + environment into terminal parameters, not client parameters. Use + a dummy client with --no-wait's X frames. In `-position LINE' + handler, don't ruin the request string until the line number is + extracted. Log opened files. Handle -current-frame command. + Don't create frames when it is given. Don't bind X frames to the + client when we are in -no-wait mode. Set locale environment + variables from client while creating tty frames. Disable call to + configure-display-for-locale. When processing -position command, + don't change the request string until the parameters are + extracted. Don't try to create an X frame when Emacs does not + support it. Improve logging. Temporarily set ncurses-related + environment variables to those of the client while creating a new + tty frame. Select buffers opened by nowait clients, don't leave + them buried under others. Set the display parameter, and use it + when appropriate. + + * startup.el (display-startup-echo-area-message): Handle + `inhibit-startup-echo-area-message' here. + (command-line-1): Moved from here. + (fancy-splash-screens): Use `overriding-local-map' instead of + `overriding-terminal-local-map' for now; the latter doesn't work + right, it looses keypresses to another terminal. Use + `overriding-terminal-local-map' to set up keymap. Install a + `delete-frame-functions' hook to catch `delete-frame' events. + Ignore `select-window' events to cope better with + `focus-follows-mouse'. Don't switch back to the original buffer + if the splash frame has been killed. Restore previous buffer, even + if it's *scratch*. + (normal-splash-screen): Don't let-bind `mode-line-format'; it + changes the global binding - setq it instead. Use + `save-buffers-kill-terminal'. + (display-splash-screen): Don't do anything if the splash screen is + already displayed elsewhere. + (fancy-splash-exit, fancy-splash-delete-frame): New functions. + (command-line): Replace duplicated code with a call to + tty-run-terminal-initialization. Don't load the terminal + initialization file more than once. Remove call to nonexistent + function `set-locale-translation-file-name'. + + * xt-mouse.el (xterm-mouse-x, xterm-mouse-y): Convert to terminal + parameters. + (xterm-mouse-position-function, xterm-mouse-event): Update. + (xterm-mouse-mode): Don't depend on current value of window-system. + (turn-on-xterm-mouse-tracking, turn-off-xterm-mouse-tracking): + Update for multi-tty. + (turn-on-xterm-mouse-tracking-on-terminal) + (turn-off-xterm-mouse-tracking-on-terminal) + (xterm-mouse-handle-delete-frame): New functions. + (delete-frame-functions, after-make-frame-functions) + (suspend-tty-functions, resume-tty-functions): Install extra hooks + for multi-tty. + +2007-10-10 Vinicius Jose Latorre + + * ps-print.el: Fix the usage of :foreground and :background face + attributes. Reported by Nikolaj Schumacher . + (ps-print-version): New version 7.2.5. + (ps-face-attributes, ps-face-attribute-list, ps-face-background): Fix + code. + (ps-face-foreground-color-p, ps-face-background-color-p) + (ps-face-color-p): New inline funs. + (ps-background, ps-begin-file, ps-build-reference-face-lists): Use + `mapc' rather than `mapcar'. + + 2007-08-29 Stefan Monnier * simple.el (invisible-p): Remove: implemented in C now. diff --cc lisp/arc-mode.el index 20757586aea,404e4543e0b..421283da9e0 --- a/lisp/arc-mode.el +++ b/lisp/arc-mode.el @@@ -463,20 -459,8 +463,20 @@@ Each descriptor is a vector of the for (make-variable-buffer-local 'archive-files) ;; ------------------------------------------------------------------------- - ;; Section: Support functions. + ;;; Section: Support functions. +(eval-when-compile + (defsubst byte-after (pos) + "Like char-after but an eight-bit char is converted to unibyte." + (multibyte-char-to-unibyte (char-after pos))) + (defsubst insert-unibyte (&rest args) + "Like insert but don't make unibyte string and eight-bit char multibyte." + (dolist (elt args) + (if (integerp elt) + (insert (if (< elt 128) elt (decode-char 'eight-bit elt))) + (insert (string-to-multibyte elt))))) + ) + (defsubst archive-name (suffix) (intern (concat "archive-" (symbol-name archive-subtype) "-" suffix))) @@@ -737,7 -724,10 +747,9 @@@ is visible (and the real data of the bu Optional argument SHUT-UP, if non-nil, means don't print messages when parsing the archive." (widen) - (set-buffer-multibyte nil) (let ((inhibit-read-only t)) + (setq archive-proper-file-start (copy-marker (point-min) t)) + (set (make-local-variable 'change-major-mode-hook) 'archive-desummarize) (or shut-up (message "Parsing archive file...")) (buffer-disable-undo (current-buffer)) @@@ -1419,11 -1403,12 +1427,11 @@@ This doesn't recover lost files, it jus (save-restriction (save-excursion (widen) - (set-buffer-multibyte nil) (goto-char (+ archive-proper-file-start (aref descr 4) 2)) (delete-char 13) - (insert name))))) + (insert-unibyte name))))) ;; ------------------------------------------------------------------------- - ;; Section: Lzh Archives + ;;; Section: Lzh Archives (defun archive-lzh-summarize (&optional start) (let ((p (or start 1)) ;; 1 for .lzh, something further on for .exe diff --cc lisp/startup.el index 3dcf65cc461,ef0e750d7dc..947fc0da57a --- a/lisp/startup.el +++ b/lisp/startup.el @@@ -808,15 -844,16 +844,17 @@@ opening the first frame (e.g. open a co (custom-reevaluate-setting 'file-name-shadow-mode) (custom-reevaluate-setting 'send-mail-function) (custom-reevaluate-setting 'focus-follows-mouse) + (custom-reevaluate-setting 'global-auto-composition-mode) + (normal-erase-is-backspace-setup-frame) + ;; Register default TTY colors for the case the terminal hasn't a - ;; terminal init file. - (unless (memq window-system '(x w32 mac)) - ;; We do this regardles of whether the terminal supports colors - ;; or not, since they can switch that support on or off in - ;; mid-session by setting the tty-color-mode frame parameter. - (tty-register-default-colors)) + ;; terminal init file. We do this regardles of whether the terminal + ;; supports colors or not and regardless the current display type, + ;; since users can connect to color-capable terminals and also + ;; switch color support on or off in mid-session by setting the + ;; tty-color-mode frame parameter. + (tty-register-default-colors) ;; Record whether the tool-bar is present before the user and site ;; init files are processed. frame-notice-user-settings uses this diff --cc make-dist index 99f2d791101,cce67987d0c..a2b00018d67 --- a/make-dist +++ b/make-dist @@@ -570,10 -572,9 +572,9 @@@ echo "Making links to \`lwlib' echo "Making links to \`etc'" ### Don't distribute = files, TAGS, DOC files, backups, autosaves, or ### tex litter. - ### Don't distribute gfdl.1, since no man page references it. (cd etc files=`ls -d * | grep -v CVS | grep -v RCS | grep -v 'Old' | grep -v '^e$' \ - | grep -v '^images$' | grep -v '^refcards$' | grep -v '^tutorials$'` + | grep -v '^charsets$' | grep -v '^images$' | grep -v '^refcards$' | grep -v '^tutorials$'` ln $files ../${tempdir}/etc ## If we ended up with a symlink, or if we did not get anything ## due to a cross-device symlink, copy the file.