X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9b8b3b6779d2b572e4d00995bdfff68e09f47473..b23ef7a531da10cd87990fa903b3417e0eba3944:/man/programs.texi diff --git a/man/programs.texi b/man/programs.texi index bd44386036..63b694f270 100644 --- a/man/programs.texi +++ b/man/programs.texi @@ -1,5 +1,6 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985,86,87,93,94,95,97,99,2000 Free Software Foundation, Inc. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, +@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Programs, Building, Text, Top @chapter Editing Programs @@ -7,84 +8,66 @@ @cindex C editing @cindex program editing - Emacs has many commands designed to understand the syntax of programming -languages such as Lisp and C. These commands can + Emacs provides many features to facilitate editing programs. Some +of these features can @itemize @bullet @item -Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}). +Find or move over top-level definitions (@pxref{Defuns}). @item -Move over or mark top-level expressions---@dfn{defuns}, in Lisp; -functions, in C (@pxref{Defuns}). +Apply the usual indentation conventions of the language +(@pxref{Program Indent}). @item -Show how parentheses balance (@pxref{Matching}). +Balance parentheses (@pxref{Parentheses}). @item Insert, kill or align comments (@pxref{Comments}). @item -Follow the usual indentation conventions of the language -(@pxref{Program Indent}). +Highlight program syntax (@pxref{Font Lock}). @end itemize - The commands for words, sentences and paragraphs are very useful in -editing code even though their canonical application is for editing -human language text. Most symbols contain words (@pxref{Words}); -sentences can be found in strings and comments (@pxref{Sentences}). -Paragraphs per se don't exist in code, but the paragraph commands are -useful anyway, because programming language major modes define -paragraphs to begin and end at blank lines (@pxref{Paragraphs}). -Judicious use of blank lines to make the program clearer will also -provide useful chunks of text for the paragraph commands to work -on. - -@cindex selective display -@cindex outline -@cindex folding -@findex outline-minor-mode -@cindex outlines - The selective display feature is useful for looking at the overall -structure of a function (@pxref{Selective Display}). This feature -causes only the lines that are indented less than a specified amount to -appear on the screen. Programming modes often support Outline minor -mode (@pxref{Outline Mode}). The Foldout package provides -folding-editor features (@pxref{Foldout}). - - The `automatic typing' features may be useful when writing programs. -@xref{,Autotyping,, autotype, Autotyping}. + This chapter describes these features and many more. @menu * Program Modes:: Major modes for editing programs. -* Lists:: Expressions with balanced parentheses. -* List Commands:: The commands for working with list and sexps. -* Defuns:: Each program is made up of separate functions. - There are editing commands to operate on them. +* Defuns:: Commands to operate on major top-level parts + of a program. * Program Indent:: Adjusting indentation to show the nesting. -* Matching:: Insertion of a close-delimiter flashes matching open. +* Parentheses:: Commands that operate on parentheses. * Comments:: Inserting, killing, and aligning comments. -* Balanced Editing:: Inserting two matching parentheses at once, etc. -* Symbol Completion:: Completion on symbol names of your program or language. -* Which Function:: Which Function mode shows which function you are in. +* Documentation:: Getting documentation of functions you plan to call. * Hideshow:: Displaying blocks selectively. +* Symbol Completion:: Completion on symbol names of your program or language. * Glasses:: Making identifiersLikeThis more readable. -* Documentation:: Getting documentation of functions you plan to call. -* Change Log:: Maintaining a change history for your program. -* Authors:: Maintaining an @file{AUTHORS} file. -* Tags:: Go direct to any function in your program in one - command. Tags remembers which file it is in. -* Imenu:: Making buffer indexes as menus. -* Emerge:: A convenient way of merging two versions of a program. +* Misc for Programs:: Other Emacs features useful for editing programs. * C Modes:: Special commands of C, C++, Objective-C, Java, and Pike modes. -* Fortran:: Fortran mode and its special features. * Asm Mode:: Asm mode and its special features. +@ifnottex +* Fortran:: Fortran mode and its special features. +@end ifnottex @end menu @node Program Modes @section Major Modes for Programming Languages - @cindex modes for programming languages + + Emacs has specialized major modes for various programming languages. +@xref{Major Modes}. A programming language major mode typically +specifies the syntax of expressions, the customary rules for +indentation, how to do syntax highlighting for the language, and how +to find the beginning of a function definition. It often customizes +or provides facilities for compiling and debugging programs as well. + + Ideally, Emacs should provide a major mode for each programming +language that you might want to edit; if it doesn't have a mode for +your favorite language, you can contribute one. But often the mode +for one language can serve for other syntactically similar languages. +The major mode for language @var{l} is called @code{@var{l}-mode}, +and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. +@xref{Choosing Modes}. + @cindex Perl mode @cindex Icon mode -@cindex Awk mode @cindex Makefile mode @cindex Tcl mode @cindex CPerl mode @@ -93,61 +76,50 @@ folding-editor features (@pxref{Foldout}). @cindex Metafont mode @cindex Modula2 mode @cindex Prolog mode +@cindex Python mode @cindex Simula mode @cindex VHDL mode @cindex M4 mode @cindex Shell-script mode @cindex Delphi mode @cindex PostScript mode - Emacs also has major modes for the programming languages Lisp, Scheme -(a variant of Lisp) and the Scheme-based DSSSL expression language, Ada, -Awk, C, C++, Delphi (Object Pascal), Fortran (free and fixed format), -Icon, IDLWAVE, -Java, Metafont (@TeX{}'s companion for font creation), Modula2, -Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Simula, -VHDL, CORBA IDL, and Tcl. -There is also a major mode for makefiles, called Makefile -mode. An alternative mode for Perl is called CPerl mode. Modes -are available for scripts for the common Unix shells, VMS DCL and -MS-DOS/MS-Windows `BAT' files. In a similar fashion to programming -languages, modes are provided for editing various sorts of configuration +@cindex Conf mode +@cindex DNS mode + The existing programming language major modes include Lisp, Scheme (a +variant of Lisp) and the Scheme-based DSSSL expression language, Ada, +ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed +format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s +companion for font creation), Modula2, Objective-C, Octave, Pascal, +Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An +alternative mode for Perl is called CPerl mode. Modes are available for +the scripting languages of the common GNU and Unix shells, VMS DCL, and +MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for +editing makefiles, DNS master files, and various sorts of configuration files. -Separate manuals are available for the modes for Ada (@pxref{Top, , Ada -Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL +@kindex DEL @r{(programming modes)} +@findex c-electric-backspace + In most programming languages, indentation should vary from line to +line to illustrate the structure of the program. So the major modes +for programming languages arrange for @key{TAB} to update the +indentation of the current line. They also rebind @key{DEL} to treat +a tab as if it were the equivalent number of spaces; this lets you +delete one column of indentation without worrying whether the +whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a +tab character before point, in these modes. + + Separate manuals are available for the modes for Ada (@pxref{Top, , Ada +Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes -(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). - - Ideally, a major mode should be implemented for each programming -language that you might want to edit with Emacs; but often the mode for -one language can serve for other syntactically similar languages. The -language modes that exist are those that someone decided to take the -trouble to write. - - There are several forms of Lisp mode, which differ in the way they -interface to Lisp execution. @xref{Executing Lisp}. - - Each of the programming language major modes defines the @key{TAB} key -to run an indentation function that knows the indentation conventions of -that language and updates the current line's indentation accordingly. -For example, in C mode @key{TAB} is bound to @code{c-indent-line}. -@kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB}; -thus, it too indents in a mode-specific fashion. +(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran +mode, see +@iftex +@ref{Fortran,,, emacs-xtra}. +@end iftex +@ifnottex +@ref{Fortran}. +@end ifnottex -@kindex DEL @r{(programming modes)} -@findex backward-delete-char-untabify - In most programming languages, indentation is likely to vary from line to -line. So the major modes for those languages rebind @key{DEL} to treat a -tab as if it were the equivalent number of spaces (using the command -@code{backward-delete-char-untabify}). This makes it possible to rub out -indentation one column at a time without worrying whether it is made up of -spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point, -in these modes. - - Programming language modes define paragraphs to be separated only by -blank lines, so that the paragraph commands remain useful. Auto Fill mode, -if enabled in a programming language major mode, indents the new lines -which it creates. @cindex mode hook @vindex c-mode-hook @@ -155,179 +127,94 @@ which it creates. @vindex emacs-lisp-mode-hook @vindex lisp-interaction-mode-hook @vindex scheme-mode-hook - Turning on a major mode runs a normal hook called the @dfn{mode hook}, -which is the value of a Lisp variable. Each major mode has a mode hook, -and the hook's name is always made from the mode command's name by -adding @samp{-hook}. For example, turning on C mode runs the hook -@code{c-mode-hook}, while turning on Lisp mode runs the hook -@code{lisp-mode-hook}. @xref{Hooks}. - -@node Lists -@section Lists and Sexps - -@cindex Control-Meta - By convention, Emacs keys for dealing with balanced expressions are -usually Control-Meta characters. They tend to be analogous in -function to their Control and Meta equivalents. These commands are -usually thought of as pertaining to expressions in programming -languages, but can be useful with any language in which some sort of -parentheses exist (including human languages). - -@cindex list -@cindex sexp -@cindex expression - These commands fall into two classes. Some deal only with @dfn{lists} -(parenthetical groupings). They see nothing except parentheses, brackets, -braces (whichever ones must balance in the language you are working with), -and escape characters that might be used to quote those. - - The other commands deal with expressions or @dfn{sexps}. The word `sexp' -is derived from @dfn{s-expression}, the ancient term for an expression in -Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It -refers to an expression in whatever language your program is written in. -Each programming language has its own major mode, which customizes the -syntax tables so that expressions in that language count as sexps. - - Sexps typically include symbols, numbers, and string constants, as well -as anything contained in parentheses, brackets or braces. - - In languages that use prefix and infix operators, such as C, it is not -possible for all expressions to be sexps. For example, C mode does not -recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression; -it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the -@samp{+} as punctuation between them. This is a fundamental ambiguity: -both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to -move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a -single sexp in C mode. - - Some languages have obscure forms of expression syntax that nobody -has bothered to make Emacs understand properly. - -@node List Commands -@section List And Sexp Commands - -@c doublewidecommands -@table @kbd -@item C-M-f -Move forward over a sexp (@code{forward-sexp}). -@item C-M-b -Move backward over a sexp (@code{backward-sexp}). -@item C-M-k -Kill sexp forward (@code{kill-sexp}). -@item C-M-@key{DEL} -Kill sexp backward (@code{backward-kill-sexp}). -@item C-M-u -Move up and backward in list structure (@code{backward-up-list}). -@item C-M-d -Move down and forward in list structure (@code{down-list}). -@item C-M-n -Move forward over a list (@code{forward-list}). -@item C-M-p -Move backward over a list (@code{backward-list}). -@item C-M-t -Transpose expressions (@code{transpose-sexps}). -@item C-M-@@ -Put mark after following expression (@code{mark-sexp}). -@end table - -@cindex parentheses, moving across -@cindex matching parenthesis and braces, moving to -@cindex braces, moving across -@kindex C-M-f -@kindex C-M-b -@findex forward-sexp -@findex backward-sexp - To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If -the first significant character after point is an opening delimiter -(@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f} -moves past the matching closing delimiter. If the character begins a -symbol, string, or number, @kbd{C-M-f} moves over that. + Turning on a major mode runs a normal hook called the @dfn{mode +hook}, which is the value of a Lisp variable. Each major mode has a +mode hook, and the hook's name is always made from the mode command's +name by adding @samp{-hook}. For example, turning on C mode runs the +hook @code{c-mode-hook}, while turning on Lisp mode runs the hook +@code{lisp-mode-hook}. The purpose of the mode hook is to give you a +place to set up customizations for that major mode. @xref{Hooks}. - The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a -sexp. The detailed rules are like those above for @kbd{C-M-f}, but with -directions reversed. If there are any prefix characters (single-quote, -backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back -over them as well. The sexp commands move across comments as if they -were whitespace in most modes. +@node Defuns +@section Top-Level Definitions, or Defuns - @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the -specified number of times; with a negative argument, it moves in the -opposite direction. + In Emacs, a major definition at the top level in the buffer, +something like a function, is called a @dfn{defun}. The name comes +from Lisp, but in Emacs we use it for all languages. -@cindex deleting parenthesized expressions -@kindex C-M-k -@findex kill-sexp -@kindex C-M-DEL -@findex backward-kill-sexp - Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp}) -or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills -the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}} -kills the characters that @kbd{C-M-b} would move over. +@menu +* Left Margin Paren:: An open-paren or similar opening delimiter + starts a defun if it is at the left margin. +* Moving by Defuns:: Commands to move over or mark a major definition. +* Imenu:: Making buffer indexes as menus. +* Which Function:: Which Function mode shows which function you are in. +@end menu -@kindex C-M-n -@kindex C-M-p -@findex forward-list -@findex backward-list - The @dfn{list commands} move over lists, as the sexp commands do, but skip -blithely over any number of other kinds of sexps (symbols, strings, etc.). -They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p} -(@code{backward-list}). The main reason they are useful is that they -usually ignore comments (since the comments usually do not contain any -lists).@refill +@node Left Margin Paren +@subsection Left Margin Convention -@kindex C-M-u -@kindex C-M-d -@findex backward-up-list -@findex down-list - @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when -that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u} -(@code{backward-up-list}). -@kbd{C-M-u} moves backward up past one unmatched opening delimiter. A -positive argument serves as a repeat count; a negative argument reverses -direction of motion and also requests repetition, so it moves forward and -up one or more levels.@refill - - To move @emph{down} in list structure, use @kbd{C-M-d} -(@code{down-list}). In Lisp mode, where @samp{(} is the only opening -delimiter, this is nearly the same as searching for a @samp{(}. An -argument specifies the number of levels of parentheses to go down. +@cindex open-parenthesis in leftmost column +@cindex ( in leftmost column + Emacs assumes by default that any opening delimiter found at the +left margin is the start of a top-level definition, or defun. You can +override this default by setting this user option: + +@defvar open-paren-in-column-0-is-defun-start +If this user option is set to @code{t} (the default), opening +parentheses or braces at column zero always start defuns. When it's +@code{nil}, defuns are found by searching for parens or braces at the +outermost level. Some major modes, including C and related modes, set +@code{open-paren-in-column-0-is-defun-start} buffer-locally to +@code{nil} +@end defvar + + In modes where @code{open-paren-in-column-0-is-defun-start} is +@code{t}, @strong{don't put an opening delimiter at the left margin +unless it is a defun start}. For instance, never put an +open-parenthesis at the left margin in a Lisp file unless it is the +start of a top-level list. -@cindex transposition of parenthesized expressions -@kindex C-M-t -@findex transpose-sexps - A somewhat random-sounding command which is nevertheless handy is -@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp -across the next one. An argument serves as a repeat count, and a -negative argument drags backwards (thus canceling out the effect of -@kbd{C-M-t} with a positive argument). An argument of zero, rather than -doing nothing, transposes the sexps ending after point and the mark. + If you don't follow this convention, not only will you have trouble +when you explicitly use the commands for motion by defuns; other +features that use them will also give you trouble. This includes +the indentation commands (@pxref{Program Indent}) and Font Lock +mode (@pxref{Font Lock}). -@kindex C-M-@@ -@findex mark-sexp - To set the region around the next sexp in the buffer, use @kbd{C-M-@@} -(@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f} -would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In -particular, a negative argument is useful for putting the mark at the -beginning of the previous sexp. + The most likely problem case is when you want an opening delimiter +at the start of a line inside a string. To avoid trouble, put an +escape character (@samp{\}, in Emacs Lisp, @samp{/} in some other Lisp +dialects) before the opening delimiter. This will not affect the +contents of the string, but will prevent that opening delimiter from +starting a defun. Here's an example: - The list and sexp commands' understanding of syntax is completely -controlled by the syntax table. Any character can, for example, be -declared to be an opening delimiter and act like an open parenthesis. -@xref{Syntax}. +@example + (insert "Foo: +\(bar) +") +@end example -@node Defuns -@section Defuns + To help you catch violations of this convention, Font Lock mode +highlights confusing opening delimiters (those that ought to be +quoted) in bold red. + + In the earliest days, the original Emacs found defuns by moving +upward a level of parentheses or braces until there were no more +levels to go up. This always required scanning all the way back to +the beginning of the buffer, even for a small function. To speed up +the operation, we changed Emacs to assume that any opening delimiter +at the left margin is the start of a defun. This heuristic is nearly +always right, and avoids the need to scan back to the beginning of the +buffer. However, now that modern computers are so powerful, this +scanning is rarely slow enough to annoy, so we've provided a way to +disable the heuristic. + +@node Moving by Defuns +@subsection Moving by Defuns @cindex defuns - In Emacs, a parenthetical grouping at the top level in the buffer is -called a @dfn{defun}. The name derives from the fact that most top-level -lists in a Lisp file are instances of the special form @code{defun}, but -any top-level parenthetical grouping counts as a defun in Emacs parlance -regardless of what its contents are, and regardless of the programming -language in use. For example, in C, the body of a function definition is a -defun. + These commands move point or set up the region based on top-level +major definitions, also called @dfn{defuns}. -@c doublewidecommands @table @kbd @item C-M-a Move to beginning of current or preceding defun @@ -346,40 +233,111 @@ Put region around whole current or following defun (@code{mark-defun}). @findex beginning-of-defun @findex end-of-defun @findex mark-defun - The commands to move to the beginning and end of the current defun are -@kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}). + The commands to move to the beginning and end of the current defun +are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} +(@code{end-of-defun}). If you repeat one of these commands, or use a +positive numeric argument, each repetition moves to the next defun in +the direction of motion. + + @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward +@var{n} times to the next beginning of a defun. This is not exactly +the same place that @kbd{C-M-e} with argument @var{n} would move to; +the end of this defun is not usually exactly the same place as the +beginning of the following defun. (Whitespace, comments, and perhaps +declarations can separate them.) Likewise, @kbd{C-M-e} with a +negative argument moves back to an end of a defun, which is not quite +the same as @kbd{C-M-a} with a positive argument. +@kindex C-M-h @r{(C mode)} @findex c-mark-function - If you wish to operate on the current defun, use @kbd{C-M-h} -(@code{mark-defun}) which puts point at the beginning and mark at the end -of the current or next defun. For example, this is the easiest way to get -ready to move the defun to a different place in the text. In C mode, -@kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the -same as @code{mark-defun}; the difference is that it backs up over the -argument declarations, function name and returned data type so that the -entire C function is inside the region. @xref{Marking Objects}. + To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun}) +which puts point at the beginning and mark at the end of the current +defun. This is the easiest way to get ready to kill the defun in +order to move it to a different place in the file. If you use the +command while point is between defuns, it uses the following defun. +Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode +when the mark is active, extends the end of the region to include one +more defun each time. + + In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, +which is almost the same as @code{mark-defun}; the difference is that +it backs up over the argument declarations, function name and returned +data type so that the entire C function is inside the region. This is +an example of how major modes adjust the standard key bindings so that +they do their standard jobs in a way better fitting a particular +language. Other major modes may replace any or all of these key +bindings for that purpose. -@cindex open-parenthesis in leftmost column -@cindex ( in leftmost column - Emacs assumes that any open-parenthesis found in the leftmost column -is the start of a defun. Therefore, @strong{never put an -open-parenthesis at the left margin in a Lisp file unless it is the -start of a top-level list. Never put an open-brace or other opening -delimiter at the beginning of a line of C code unless it starts the body -of a function.} The most likely problem case is when you want an -opening delimiter at the start of a line inside a string. To avoid -trouble, put an escape character (@samp{\}, in C and Emacs Lisp, -@samp{/} in some other Lisp dialects) before the opening delimiter. It -will not affect the contents of the string. - - In the remotest past, the original Emacs found defuns by moving upward a -level of parentheses until there were no more levels to go up. This always -required scanning all the way back to the beginning of the buffer, even for -a small function. To speed up the operation, Emacs was changed to assume -that any @samp{(} (or other character assigned the syntactic class of -opening-delimiter) at the left margin is the start of a defun. This -heuristic is nearly always right and avoids the costly scan; however, -it mandates the convention described above. +@node Imenu +@subsection Imenu +@cindex index of buffer definitions +@cindex buffer definitions index +@cindex tags + + The Imenu facility offers a way to find the major definitions in +a file by name. It is also useful in text formatter major modes, +where it treats each chapter, section, etc., as a definition. +(@xref{Tags}, for a more powerful feature that handles multiple files +together.) + +@findex imenu + If you type @kbd{M-x imenu}, it reads the name of a definition using +the minibuffer, then moves point to that definition. You can use +completion to specify the name; the command always displays the whole +list of valid names. + +@findex imenu-add-menubar-index + Alternatively, you can bind the command @code{imenu} to a mouse +click. Then it displays mouse menus for you to select a definition +name. You can also add the buffer's index to the menu bar by calling +@code{imenu-add-menubar-index}. If you want to have this menu bar +item available for all buffers in a certain major mode, you can do +this by adding @code{imenu-add-menubar-index} to its mode hook. But +if you have done that, you will have to wait a little while each time +you visit a file in that mode, while Emacs finds all the definitions +in that buffer. + +@vindex imenu-auto-rescan + When you change the contents of a buffer, if you add or delete +definitions, you can update the buffer's index based on the +new contents by invoking the @samp{*Rescan*} item in the menu. +Rescanning happens automatically if you set @code{imenu-auto-rescan} to +a non-@code{nil} value. There is no need to rescan because of small +changes in the text. + +@vindex imenu-sort-function + You can customize the way the menus are sorted by setting the +variable @code{imenu-sort-function}. By default, names are ordered as +they occur in the buffer; if you want alphabetic sorting, use the +symbol @code{imenu--sort-by-name} as the value. You can also +define your own comparison function by writing Lisp code. + + Imenu provides the information to guide Which Function mode +@ifnottex +(@pxref{Which Function}). +@end ifnottex +@iftex +(see below). +@end iftex +The Speedbar can also use it (@pxref{Speedbar}). + +@node Which Function +@subsection Which Function Mode +@cindex current function name in mode line + + Which Function mode is a minor mode that displays the current +function name in the mode line, updating it as you move around in a +buffer. + +@findex which-function-mode +@vindex which-func-modes + To enable (or disable) Which Function mode, use the command @kbd{M-x +which-function-mode}. This command is global; it applies to all +buffers, both existing ones and those yet to be created. However, it +takes effect only in certain major modes, those listed in the value of +@code{which-func-modes}. If the value is @code{t}, then Which Function +mode applies to all major modes that know how to support it---in other +words, all the major modes that support Imenu. @node Program Indent @section Indentation for Programs @@ -398,98 +356,126 @@ inside a single parenthetical grouping. * Custom C Indent:: Controlling indentation style for C and related modes. @end menu +@cindex pretty-printer Emacs also provides a Lisp pretty-printer in the library @code{pp}. This program reformats a Lisp object with indentation chosen to look nice. @node Basic Indent @subsection Basic Program Indentation Commands -@c WideCommands + The basic indentation commands indent a single line according to the +usual conventions of the language you are editing. + @table @kbd @item @key{TAB} Adjust indentation of current line. @item C-j -Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}). +Insert a newline, then adjust indentation of following line +(@code{newline-and-indent}). @end table @kindex TAB @r{(programming modes)} -@findex c-indent-line -@findex lisp-indent-line +@findex c-indent-command +@findex indent-line-function +@findex indent-for-tab-command The basic indentation command is @key{TAB}, which gives the current line the correct indentation as determined from the previous lines. The -function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line} -in Lisp mode, @code{c-indent-line} in C mode, etc. These functions -understand different syntaxes for different languages, but they all do -about the same thing. @key{TAB} in any programming-language major mode +function that @key{TAB} runs depends on the major mode; it is +@code{lisp-indent-line} +in Lisp mode, @code{c-indent-command} in C mode, etc. These functions +understand the syntax and conventions of different languages, but they all do +conceptually the same job: @key{TAB} in any programming-language major mode inserts or deletes whitespace at the beginning of the current line, -independent of where point is in the line. If point is inside the -whitespace at the beginning of the line, @key{TAB} leaves it at the end of -that whitespace; otherwise, @key{TAB} leaves point fixed with respect to +independent of where point is in the line. If point was inside the +whitespace at the beginning of the line, @key{TAB} puts it at the end of +that whitespace; otherwise, @key{TAB} keeps point fixed with respect to the characters around it. - Use @kbd{C-q @key{TAB}} to insert a tab at point. + Use @kbd{C-q @key{TAB}} to insert a tab character at point. @kindex C-j @findex newline-and-indent - When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}), -which is equivalent to a @key{RET} followed by a @key{TAB}. @kbd{C-j} creates -a blank line and then gives it the appropriate indentation. - - @key{TAB} indents the second and following lines of the body of a -parenthetical grouping each under the preceding one; therefore, if you -alter one line's indentation to be nonstandard, the lines below will -tend to follow it. This behavior is convenient in cases where you have -overridden the standard result of @key{TAB} because you find it -unaesthetic for a particular line. - - Remember that an open-parenthesis, open-brace or other opening delimiter -at the left margin is assumed by Emacs (including the indentation routines) -to be the start of a function. Therefore, you must never have an opening -delimiter in column zero that is not the beginning of a function, not even -inside a string. This restriction is vital for making the indentation -commands fast; you must simply accept it. @xref{Defuns}, for more -information on this. + When entering lines of new code, use @kbd{C-j} +(@code{newline-and-indent}), which inserts a newline and then adjusts +indentation after it. (It also deletes any trailing whitespace which +remains before the new newline.) Thus, @kbd{C-j} at the end of a line +creates a blank line with appropriate indentation. In programming +language modes, it is equivalent to @key{RET} @key{TAB}. + + @key{TAB} indents a line that starts within a parenthetical grouping +under the preceding line within the grouping, or the text after the +parenthesis. Therefore, if you manually give one of these lines a +nonstandard indentation, the lines below will tend to follow it. This +behavior is convenient in cases where you have overridden the standard +result of @key{TAB} because you find it unaesthetic for a particular +line. + + In some modes, an open-parenthesis, open-brace or other opening +delimiter at the left margin is assumed by Emacs (including the +indentation routines) to be the start of a function. This speeds up +indentation commands. If you will be editing text which contains +opening delimiters in column zero that aren't the beginning of a +functions, even inside strings or comments, you must set +@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin +Paren}, for more information on this. + + Normally, lines are indented with tabs and spaces. If you want Emacs +to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}). @node Multi-line Indent @subsection Indenting Several Lines - When you wish to reindent several lines of code which have been altered -or moved to a different level in the list structure, you have several -commands available. + When you wish to reindent several lines of code which have been +altered or moved to a different level in the parenthesis structure, +you have several commands available. @table @kbd @item C-M-q -Reindent all the lines within one list (@code{indent-sexp}). -@item C-u @key{TAB} -Shift an entire list rigidly sideways so that its first line -is properly indented. +Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}). @item C-M-\ Reindent all lines in the region (@code{indent-region}). +@item C-u @key{TAB} +Shift an entire parenthetical grouping rigidly sideways so that its +first line is properly indented. +@item M-x indent-code-rigidly +Shift all the lines in the region rigidly sideways, but do not alter +lines that start inside comments and strings. @end table @kindex C-M-q -@findex indent-sexp - You can reindent the contents of a single list by positioning point -before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in -Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable -commands in other modes). The indentation of the line the sexp starts on -is not changed; therefore, only the relative indentation within the list, -and not its position, is changed. To correct the position as well, type a -@key{TAB} before the @kbd{C-M-q}. +@findex indent-pp-sexp + You can reindent the contents of a single parenthetical grouping by +positioning point before the beginning of it and typing @kbd{C-M-q} +(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also +bound to other suitable commands in other modes). The indentation of +the line where the grouping starts is not changed; therefore this +changes only the relative indentation within the grouping, not its +overall indentation. To correct that as well, type @key{TAB} first. + + Another way to specify the range to be reindented is with the +region. The command @kbd{C-M-\} (@code{indent-region}) applies +@key{TAB} to every line whose first character is between point and +mark. @kindex C-u TAB - If the relative indentation within a list is correct but the -indentation of its first line is not, go to that line and type @kbd{C-u -@key{TAB}}. @key{TAB} with a numeric argument reindents the current -line as usual, then reindents by the same amount all the lines in the -grouping starting on the current line. In other words, it reindents the -whole grouping rigidly as a unit. It is clever, though, and does not -alter lines that start inside strings, or C preprocessor lines when in C -mode. - - Another way to specify the range to be reindented is with the region. -The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to -every line whose first character is between point and mark. + If you like the relative indentation within a grouping, but not the +indentation of its first line, you can type @kbd{C-u @key{TAB}} to +reindent the whole grouping as a rigid unit. (This works in Lisp +modes and C and related modes.) @key{TAB} with a numeric argument +reindents the current line as usual, then reindents by the same amount +all the lines in the parenthetical grouping starting on the current +line. It is clever, though, and does not alter lines that start +inside strings. Neither does it alter C preprocessor lines when in C +mode, but it does reindent any continuation lines that may be attached +to them. + +@findex indent-code-rigidly + You can also perform this operation on the region, using the command +@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the +region sideways, like @code{indent-rigidly} does (@pxref{Indentation +Commands}). It doesn't alter the indentation of lines that start +inside a string, unless the region also starts inside that string. +The prefix arg specifies the number of columns to indent. @node Lisp Indent @subsection Customizing Lisp Indentation @@ -513,60 +499,23 @@ such lines are always indented @code{lisp-indent-offset} more columns than the containing list. @vindex lisp-body-indent - The standard pattern is overridden for certain functions. Functions -whose names start with @code{def} always indent the second line by -@code{lisp-body-indent} extra columns beyond the open-parenthesis -starting the expression. - - The standard pattern can be overridden in various ways for individual -functions, according to the @code{lisp-indent-function} property of the -function name. There are four possibilities for this property: - -@table @asis -@item @code{nil} -This is the same as no property; the standard indentation pattern is used. -@item @code{defun} -The pattern used for function names that start with @code{def} is used for -this function also. -@item a number, @var{number} -The first @var{number} arguments of the function are -@dfn{distinguished} arguments; the rest are considered the @dfn{body} -of the expression. A line in the expression is indented according to -whether the first argument on it is distinguished or not. If the -argument is part of the body, the line is indented @code{lisp-body-indent} -more columns than the open-parenthesis starting the containing -expression. If the argument is distinguished and is either the first -or second argument, it is indented @emph{twice} that many extra columns. -If the argument is distinguished and not the first or second argument, -the standard pattern is followed for that line. -@item a symbol, @var{symbol} -@var{symbol} should be a function name; that function is called to -calculate the indentation of a line within this expression. The -function receives two arguments: -@table @asis -@item @var{state} -The value returned by @code{parse-partial-sexp} (a Lisp primitive for -indentation and nesting computation) when it parses up to the -beginning of this line. -@item @var{pos} -The position at which the line being indented begins. -@end table -@noindent -It should return either a number, which is the number of columns of -indentation for that line, or a list whose car is such a number. The -difference between returning a number and returning a list is that a -number says that all following lines at the same nesting level should -be indented just like this one; a list says that following lines might -call for different indentations. This makes a difference when the -indentation is being computed by @kbd{C-M-q}; if the value is a -number, @kbd{C-M-q} need not recalculate indentation for the following -lines until the end of the list. -@end table + Certain functions override the standard pattern. Functions whose +names start with @code{def} treat the second lines as the start of +a @dfn{body}, by indenting the second line @code{lisp-body-indent} +additional columns beyond the open-parenthesis that starts the +expression. + +@cindex @code{lisp-indent-function} property + You can override the standard pattern in various ways for individual +functions, according to the @code{lisp-indent-function} property of +the function name. Normally you would use this for macro definitions +and specify it using the @code{declare} construct (@pxref{Defining +Macros,,, elisp, the Emacs Lisp Reference Manual}). @node C Indent @subsection Commands for C Indentation - Here are the commands for indentation in C mode and related modes: + Here are special features for indentation in C mode and related modes: @table @code @item C-c C-q @@ -579,14 +528,15 @@ declaration (@code{c-indent-defun}). @kindex C-M-q @r{(C mode)} @findex c-indent-exp Reindent each line in the balanced expression that follows point -(@code{c-indent-exp}). A prefix argument inhibits error checking and -warning messages about invalid syntax. +(@code{c-indent-exp}). A prefix argument inhibits warning messages +about invalid syntax. @item @key{TAB} @findex c-indent-command Reindent the current line, and/or in some cases insert a tab character (@code{c-indent-command}). +@vindex c-tab-always-indent If @code{c-tab-always-indent} is @code{t}, this command always reindents the current line and does nothing else. This is the default. @@ -596,13 +546,7 @@ otherwise, it inserts a tab (or the equivalent number of spaces, if @code{indent-tabs-mode} is @code{nil}). Any other value (not @code{nil} or @code{t}) means always reindent the -line, and also insert a tab if within a comment, a string, or a -preprocessor directive. - -@item C-u @key{TAB} -Reindent the current line according to its syntax; also rigidly reindent -any other lines of the expression that starts on the current line. -@xref{Multi-line Indent}. +line, and also insert a tab if within a comment or a string. @end table To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This @@ -614,758 +558,470 @@ to the front of the block and then reindents it all. @node Custom C Indent @subsection Customizing C Indentation +@cindex style (for indentation) - C mode and related modes use a simple yet flexible mechanism for -customizing indentation. The mechanism works in two steps: first it -classifies the line syntactically according to its contents and context; -second, it associates each kind of syntactic construct with an -indentation offset which you can customize. - -@menu -* Syntactic Analysis:: -* Indentation Calculation:: -* Changing Indent Style:: -* Syntactic Symbols:: -* Variables for C Indent:: -* C Indent Styles:: -@end menu - -@node Syntactic Analysis -@subsubsection Step 1---Syntactic Analysis -@cindex syntactic analysis - - In the first step, the C indentation mechanism looks at the line -before the one you are currently indenting and determines the syntactic -components of the construct on that line. It builds a list of these -syntactic components, each of which contains a @dfn{syntactic symbol} -and sometimes also a buffer position. Some syntactic symbols describe -grammatical elements, for example @code{statement} and -@code{substatement}; others describe locations amidst grammatical -elements, for example @code{class-open} and @code{knr-argdecl}. + C mode and related modes use a flexible mechanism for customizing +indentation. C mode indents a source line in two steps: first it +classifies the line syntactically according to its contents and +context; second, it determines the indentation offset associated by +your selected @dfn{style} with the syntactic construct and adds this +onto the indentation of the @dfn{anchor statement}. - Conceptually, a line of C code is always indented relative to the -indentation of some line higher up in the buffer. This is represented -by the buffer positions in the syntactic component list. - - Here is an example. Suppose we have the following code in a C++ mode -buffer (the line numbers don't actually appear in the buffer): +@table @kbd +@item C-c . @key{RET} @var{style} @key{RET} +Select a predefined style @var{style} (@code{c-set-style}). +@end table -@example -1: void swap (int& a, int& b) -2: @{ -3: int tmp = a; -4: a = b; -5: b = tmp; -6: @} -@end example + A @dfn{style} is a named collection of customizations that can be +used in C mode and the related modes. @ref{Styles,,, ccmode, The CC +Mode Manual}, for a complete description. Emacs comes with several +predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, +@code{stroustrup}, @code{linux}, @code{python}, @code{java}, +@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these +styles are primarily intended for one language, but any of them can be +used with any of the languages supported by these modes. To find out +what a style looks like, select it and reindent some code, e.g., by +typing @key{C-M-q} at the start of a function definition. + +@kindex C-c . @r{(C mode)} +@findex c-set-style + To choose a style for the current buffer, use the command @w{@kbd{C-c +.}}. Specify a style name as an argument (case is not significant). +This command affects the current buffer only, and it affects only +future invocations of the indentation commands; it does not reindent +the code already in the buffer. To reindent the whole buffer in the +new style, you can type @kbd{C-x h C-M-\}. - If you type @kbd{C-c C-s} (which runs the command -@code{c-show-syntactic-information}) on line 4, it shows the result of -the indentation mechanism for that line: +@vindex c-default-style + You can also set the variable @code{c-default-style} to specify the +default style for various major modes. Its value should be either the +style's name (a string) or an alist, in which each element specifies +one major mode and which indentation style to use for it. For +example, @example -((statement . 32)) +(setq c-default-style + '((java-mode . "java") (awk-mode . "awk") (other . "gnu"))) @end example - This indicates that the line is a statement and it is indented -relative to buffer position 32, which happens to be the @samp{i} in -@code{int} on line 3. If you move the cursor to line 3 and type -@kbd{C-c C-s}, it displays this: - -@example -((defun-block-intro . 28)) -@end example +@noindent +specifies explicit choices for Java and AWK modes, and the default +@samp{gnu} style for the other C-like modes. (These settings are +actually the defaults.) This variable takes effect when you select +one of the C-like major modes; thus, if you specify a new default +style for Java mode, you can make it take effect in an existing Java +mode buffer by typing @kbd{M-x java-mode} there. + + The @code{gnu} style specifies the formatting recommended by the GNU +Project for C; it is the default, so as to encourage use of our +recommended style. + + @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and +@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more +information on customizing indentation for C and related modes, +including how to override parts of an existing style and how to define +your own styles. + +@node Parentheses +@section Commands for Editing with Parentheses - This indicates that the @code{int} line is the first statement in a -block, and is indented relative to buffer position 28, which is the -brace just after the function header. +@findex check-parens +@cindex unbalanced parentheses and quotes + This section describes the commands and features that take advantage +of the parenthesis structure in a program, or help you keep it +balanced. -@noindent -Here is another example: + When talking about these facilities, the term ``parenthesis'' also +includes braces, brackets, or whatever delimiters are defined to match +in pairs. The major mode controls which delimiters are significant, +through the syntax table (@pxref{Syntax}). In Lisp, only parentheses +count; in C, these commands apply to braces and brackets too. -@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 + You can use @kbd{M-x check-parens} to find any unbalanced +parentheses and unbalanced string quotes in the buffer. -@noindent -Typing @kbd{C-c C-s} on line 4 displays this: +@menu +* Expressions:: Expressions with balanced parentheses. +* Moving by Parens:: Commands for moving up, down and across + in the structure of parentheses. +* Matching:: Insertion of a close-delimiter flashes matching open. +@end menu -@example -((substatement-open . 43)) -@end example +@node Expressions +@subsection Expressions with Balanced Parentheses - This says that the brace @emph{opens} a substatement block. By the -way, a @dfn{substatement} indicates the line after an @code{if}, -@code{else}, @code{while}, @code{do}, @code{switch}, @code{for}, -@code{try}, @code{catch}, @code{finally}, or @code{synchronized} -statement. - -@cindex syntactic component -@cindex syntactic symbol -@vindex c-syntactic-context - Within the C indentation commands, after a line has been analyzed -syntactically for indentation, the variable @code{c-syntactic-context} -contains a list that describes the results. Each element in this list -is a @dfn{syntactic component}: a cons cell containing a syntactic -symbol and (optionally) its corresponding buffer position. There may be -several elements in a component list; typically only one element has a -buffer position. - -@node Indentation Calculation -@subsubsection Step 2---Indentation Calculation -@cindex Indentation Calculation - - The C indentation mechanism calculates the indentation for the current -line using the list of syntactic components, @code{c-syntactic-context}, -derived from syntactic analysis. Each component is a cons cell that -contains a syntactic symbol and may also contain a buffer position. - - Each component contributes to the final total indentation of the line -in two ways. First, the syntactic symbol identifies an element of -@code{c-offsets-alist}, which is an association list mapping syntactic -symbols into indentation offsets. Each syntactic symbol's offset adds -to the total indentation. Second, if the component includes a buffer -position, the column number of that position adds to the indentation. -All these offsets and column numbers, added together, give the total -indentation. - - The following examples demonstrate the workings of the C indentation -mechanism: +@cindex sexp +@cindex expression +@cindex balanced expression + These commands deal with balanced expressions, also called +@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an +expression in Lisp.}. -@example -1: void swap (int& a, int& b) -2: @{ -3: int tmp = a; -4: a = b; -5: b = tmp; -6: @} -@end example +@table @kbd +@item C-M-f +Move forward over a balanced expression (@code{forward-sexp}). +@item C-M-b +Move backward over a balanced expression (@code{backward-sexp}). +@item C-M-k +Kill balanced expression forward (@code{kill-sexp}). +@item C-M-t +Transpose expressions (@code{transpose-sexps}). +@item C-M-@@ +@itemx C-M-@key{SPC} +Put mark after following expression (@code{mark-sexp}). +@end table - Suppose that point is on line 3 and you type @key{TAB} to reindent the -line. As explained above (@pxref{Syntactic Analysis}), the syntactic -component list for that line is: + Each programming language major mode customizes the definition of +balanced expressions to suit that language. Balanced expressions +typically include symbols, numbers, and string constants, as well as +any pair of matching delimiters and their contents. Some languages +have obscure forms of expression syntax that nobody has bothered to +implement in Emacs. -@example -((defun-block-intro . 28)) -@end example +@cindex Control-Meta + By convention, the keys for these commands are all Control-Meta +characters. They usually act on expressions just as the corresponding +Meta characters act on words. For instance, the command @kbd{C-M-b} +moves backward over a balanced expression, just as @kbd{M-b} moves +back over a word. - In this case, the indentation calculation first looks up -@code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose -that it finds the integer 2; it adds this to the running total -(initialized to zero), yielding a updated total indentation of 2 spaces. +@kindex C-M-f +@kindex C-M-b +@findex forward-sexp +@findex backward-sexp + To move forward over a balanced expression, use @kbd{C-M-f} +(@code{forward-sexp}). If the first significant character after point +is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or +@samp{@{} in C), @kbd{C-M-f} moves past the matching closing +delimiter. If the character begins a symbol, string, or number, +@kbd{C-M-f} moves over that. - The next step is to find the column number of buffer position 28. -Since the brace at buffer position 28 is in column zero, this adds 0 to -the running total. Since this line has only one syntactic component, -the total indentation for the line is 2 spaces. + The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a +balanced expression. The detailed rules are like those above for +@kbd{C-M-f}, but with directions reversed. If there are prefix +characters (single-quote, backquote and comma, in Lisp) preceding the +expression, @kbd{C-M-b} moves back over them as well. The balanced +expression commands move across comments as if they were whitespace, +in most modes. -@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 + @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the +specified number of times; with a negative argument, it moves in the +opposite direction. - If you type @key{TAB} on line 4, the same process is performed, but -with different data. The syntactic component list for this line is: +@cindex killing expressions +@kindex C-M-k +@findex kill-sexp + Killing a whole balanced expression can be done with @kbd{C-M-k} +(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} +would move over. -@example -((substatement-open . 43)) -@end example +@cindex transposition of expressions +@kindex C-M-t +@findex transpose-sexps + A somewhat random-sounding command which is nevertheless handy is +@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous +balanced expression across the next one. An argument serves as a +repeat count, moving the previous expression over that many following +ones. A negative argument drags the previous balanced expression +backwards across those before it (thus canceling out the effect of +@kbd{C-M-t} with a positive argument). An argument of zero, rather +than doing nothing, transposes the balanced expressions ending at or +after point and the mark. - Here, the indentation calculation's first job is to look up the -symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume -that the offset for this symbol is 2. At this point the running total -is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43, -which is the @samp{i} in @code{if} on line 3. This character is in -column 2 on that line. Adding this yields a total indentation of 4 -spaces. - -@vindex c-strict-syntax-p - If a syntactic symbol in the analysis of a line does not appear in -@code{c-offsets-alist}, it is ignored; if in addition the variable -@code{c-strict-syntax-p} is non-@code{nil}, it is an error. - -@node Changing Indent Style -@subsubsection Changing Indentation Style - - There are two ways to customize the indentation style for the C-like -modes. First, you can select one of several predefined styles, each of -which specifies offsets for all the syntactic symbols. For more -flexibility, you can customize the handling of individual syntactic -symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic -symbols. +@kindex C-M-@@ +@kindex C-M-@key{SPC} +@findex mark-sexp + To set the region around the next balanced expression in the buffer, +use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place +that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like +@kbd{C-M-f}. In particular, a negative argument is useful for putting +the mark at the beginning of the previous balanced expression. The +alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you +repeat this command, or use it in Transient Mark mode when the mark is +active, it extends the end of the region by one sexp each time. + + In languages that use infix operators, such as C, it is not possible +to recognize all balanced expressions as such because there can be +multiple possibilities at a given position. For example, C mode does +not treat @samp{foo + bar} as a single expression, even though it +@emph{is} one C expression; instead, it recognizes @samp{foo} as one +expression and @samp{bar} as another, with the @samp{+} as punctuation +between them. Both @samp{foo + bar} and @samp{foo} are legitimate +choices for ``the expression following point'' when point is at the +@samp{f}, so the expression commands must perforce choose one or the +other to operate on. Note that @samp{(foo + bar)} is recognized as a +single expression in C mode, because of the parentheses. + +@node Moving by Parens +@subsection Moving in the Parenthesis Structure + +@cindex parenthetical groupings +@cindex parentheses, moving across +@cindex matching parenthesis and braces, moving to +@cindex braces, moving across +@cindex list commands + The Emacs commands for handling parenthetical groupings see nothing +except parentheses (or whatever characters must balance in the +language you are working with), and the escape characters that might +be used to quote those. They are mainly intended for editing +programs, but can be useful for editing any text that has parentheses. +They are sometimes called ``list'' commands because in Lisp these +groupings are lists. @table @kbd -@item M-x c-set-style @key{RET} @var{style} @key{RET} -Select predefined indentation style @var{style}. Type @kbd{?} when -entering @var{style} to see a list of supported styles; to find out what -a style looks like, select it and reindent some C code. - -@item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET} -Set the indentation offset for syntactic symbol @var{symbol} -(@code{c-set-offset}). The second argument @var{offset} specifies the -new indentation offset. +@item C-M-n +Move forward over a parenthetical group (@code{forward-list}). +@item C-M-p +Move backward over a parenthetical group (@code{backward-list}). +@item C-M-u +Move up in parenthesis structure (@code{backward-up-list}). +@item C-M-d +Move down in parenthesis structure (@code{down-list}). @end table - The @code{c-offsets-alist} variable controls the amount of -indentation to give to each syntactic symbol. Its value is an -association list, and each element of the list has the form -@code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets -for various syntactic symbols, you can customize indentation in fine -detail. To change this alist, use @code{c-set-offset} (see below). - - Each offset value in @code{c-offsets-alist} can be an integer, a -function or variable name, a list, or one of the following symbols: @code{+}, -@code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative -multiples of the variable @code{c-basic-offset}. Thus, if you want to -change the levels of indentation to be 3 spaces instead of 2 spaces, set -@code{c-basic-offset} to 3. - - Using a function as the offset value provides the ultimate flexibility -in customizing indentation. The function is called with a single -argument containing the @code{cons} of the syntactic symbol and -the buffer position, if any. The function should return an integer -offset. - - If the offset value is a list, its elements are processed according -to the rules above until a non-@code{nil} value is found. That value is -then added to the total indentation in the normal manner. The primary -use for this is to combine the results of several functions. - -@kindex C-c C-o @r{(C mode)} -@findex c-set-offset - The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to -set offsets, both interactively or in your @file{~/.emacs} file. First -specify the syntactic symbol, then the offset you want. @xref{Syntactic -Symbols}, for a list of valid syntactic symbols and their meanings. - -@node Syntactic Symbols -@subsubsection Syntactic Symbols - - Here is a table of valid syntactic symbols for indentation in C and -related modes, with their syntactic meanings. Normally, most of these -symbols are assigned offsets in @code{c-offsets-alist}. - -@table @code -@item string -Inside a multi-line string. +@kindex C-M-n +@kindex C-M-p +@findex forward-list +@findex backward-list + The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and +@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n}) +parenthetical groupings, skipping blithely over any amount of text +that doesn't include meaningful parentheses (symbols, strings, etc.). -@item c -Inside a multi-line C style block comment. +@kindex C-M-u +@findex backward-up-list + @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the +parenthesis structure. To move @emph{up} one (or @var{n}) levels, use +@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up +past one unmatched opening delimiter. A positive argument serves as a +repeat count; a negative argument reverses the direction of motion, so +that the command moves forward and up one or more levels. -@item defun-open -On a brace that opens a function definition. +@kindex C-M-d +@findex down-list + To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} +(@code{down-list}). In Lisp mode, where @samp{(} is the only opening +delimiter, this is nearly the same as searching for a @samp{(}. An +argument specifies the number of levels to go down. -@item defun-close -On a brace that closes a function definition. +@node Matching +@subsection Automatic Display Of Matching Parentheses +@cindex matching parentheses +@cindex parentheses, displaying matches -@item defun-block-intro -In the first line in a top-level defun. + The Emacs parenthesis-matching feature is designed to show +automatically how parentheses (and other matching delimiters) match in +the text. Whenever you type a self-inserting character that is a +closing delimiter, the cursor moves momentarily to the location of the +matching opening delimiter, provided that is on the screen. If it is +not on the screen, Emacs displays some of the text near it in the echo +area. Either way, you can tell which grouping you are closing off. -@item class-open -On a brace that opens a class definition. + If the opening delimiter and closing delimiter are mismatched---such +as in @samp{[x)}---a warning message is displayed in the echo area. -@item class-close -On a brace that closes a class definition. +@vindex blink-matching-paren +@vindex blink-matching-paren-distance +@vindex blink-matching-delay + Three variables control parenthesis match display: -@item inline-open -On a brace that opens an in-class inline method. + @code{blink-matching-paren} turns the feature on or off: @code{nil} +disables it, but the default is @code{t} to enable match display. -@item inline-close -On a brace that closes an in-class inline method. + @code{blink-matching-delay} says how many seconds to leave the +cursor on the matching opening delimiter, before bringing it back to +the real location of point; the default is 1, but on some systems it +is useful to specify a fraction of a second. -@item extern-lang-open -On a brace that opens an external language block. + @code{blink-matching-paren-distance} specifies how many characters +back to search to find the matching opening delimiter. If the match +is not found in that distance, scanning stops, and nothing is displayed. +This is to prevent the scan for the matching delimiter from wasting +lots of time when there is no match. The default is 25600. -@item extern-lang-close -On a brace that closes an external language block. +@cindex Show Paren mode +@cindex highlighting matching parentheses +@findex show-paren-mode + Show Paren mode provides a more powerful kind of automatic matching. +Whenever point is after a closing delimiter, that delimiter and its +matching opening delimiter are both highlighted; otherwise, if point +is before an opening delimiter, the matching closing delimiter is +highlighted. (There is no need to highlight the opening delimiter in +that case, because the cursor appears on top of that character.) Use +the command @kbd{M-x show-paren-mode} to enable or disable this mode. + + Show Paren mode uses the faces @code{show-paren-match} and +@code{show-paren-mismatch} to highlight parentheses; you can customize +them to control how highlighting looks. @xref{Face Customization}. -@item func-decl-cont -The region between a function definition's argument list and the defun -opening brace (excluding K&R function definitions). In C, you cannot -put anything but whitespace and comments between them; in C++ and Java, -@code{throws} declarations and other things can appear in this context. +@node Comments +@section Manipulating Comments +@cindex comments -@item knr-argdecl-intro -On the first line of a K&R C argument declaration. + Because comments are such an important part of programming, Emacs +provides special commands for editing and inserting comments. It can +also do spell checking on comments with Flyspell Prog mode +(@pxref{Spelling}). -@item knr-argdecl -In one of the subsequent lines in a K&R C argument declaration. +@menu +* Comment Commands:: Inserting, killing, and aligning comments. +* Multi-Line Comments:: Commands for adding and editing multi-line comments. +* Options for Comments::Customizing the comment features. +@end menu -@item topmost-intro -On the first line in a topmost construct definition. +@node Comment Commands +@subsection Comment Commands +@cindex indentation for comments +@cindex alignment for comments -@item topmost-intro-cont -On the topmost definition continuation lines. + The comment commands in this table insert, kill and align comments. +They are described in this section and following sections. -@item member-init-intro -On the first line in a member initialization list. +@table @asis +@item @kbd{M-;} +Insert or realign comment on current line; alternatively, comment or +uncomment the region (@code{comment-dwim}). +@item @kbd{C-u M-;} +Kill comment on current line (@code{comment-kill}). +@item @kbd{C-x ;} +Set comment column (@code{comment-set-column}). +@item @kbd{C-M-j} +@itemx @kbd{M-j} +Like @key{RET} followed by inserting and aligning a comment +(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. +@item @kbd{M-x comment-region} +@itemx @kbd{C-c C-c} (in C-like modes) +Add or remove comment delimiters on all the lines in the region. +@end table -@item member-init-cont -On one of the subsequent member initialization list lines. +@kindex M-; +@findex comment-dwim + The command to create or align a comment is @kbd{M-;} +(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What +I Mean''; it indicates that this command can be used for many +different jobs relating to comments, depending on the situation where +you use it. + + If there is no comment already on the line, @kbd{M-;} inserts a new +comment, aligned at a specific column called the @dfn{comment column}. +The new comment begins with the string Emacs thinks comments should +start with (the value of @code{comment-start}; see below). Point is +after that string, so you can insert the text of the comment right +away. If the major mode has specified a string to terminate comments, +@kbd{M-;} inserts that after point, to keep the syntax valid. + + If the text of the line extends past the comment column, this +command aligns the comment start string to a suitable boundary +(usually, at least one space is inserted). + + You can also use @kbd{M-;} to align an existing comment. If a line +already contains the comment-start string, @kbd{M-;} realigns it to +the conventional alignment and moves point after it. (Exception: +comments starting in column 0 are not moved.) Even when an existing +comment is properly aligned, @kbd{M-;} is still useful for moving +directly to the start of the text inside the comment. -@item inher-intro -On the first line of a multiple inheritance list. +@findex comment-kill +@kindex C-u M-; + @kbd{C-u M-;} kills any comment on the current line, along with the +whitespace before it. To reinsert the comment on another line, move +to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to +realign it. + + Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} +(@code{comment-dwim}) with a prefix argument. That command is +programmed so that when it receives a prefix argument it calls +@code{comment-kill}. However, @code{comment-kill} is a valid command +in its own right, and you can bind it directly to a key if you wish. + + @kbd{M-;} does two other jobs when used with an active region in +Transient Mark mode (@pxref{Transient Mark}). Then it either adds or +removes comment delimiters on each line of the region. (If every line +is a comment, it removes comment delimiters from each; otherwise, it +adds comment delimiters to each.) If you are not using Transient Mark +mode, then you should use the commands @code{comment-region} and +@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}), +or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}). +A prefix argument used in these circumstances specifies how many +comment delimiters to add or how many to delete. + + Some major modes have special rules for aligning certain kinds of +comments in certain contexts. For example, in Lisp code, comments which +start with two semicolons are indented as if they were lines of code, +instead of at the comment column. Comments which start with three +semicolons are supposed to start at the left margin. Emacs understands +these conventions by indenting a double-semicolon comment using @key{TAB}, +and by not changing the indentation of a triple-semicolon comment at all. -@item inher-cont -On one of the subsequent multiple inheritance lines. +@example +;; This function is just an example +;;; Here either two or three semicolons are appropriate. +(defun foo (x) +;;; And now, the first part of the function: + ;; The following line adds one. + (1+ x)) ; This line adds one. +@end example -@item block-open -On a statement block open brace. + For C-like modes, you can configure the exact effect of @kbd{M-;} +more flexibly than for most buffers by setting the variables +@code{c-indent-comment-alist} and +@code{c-indent-comments-syntactically-p}. For example, on a line +ending in a closing brace, @kbd{M-;} puts the comment one space after +the brace rather than at @code{comment-column}. For full details see +@ref{Comment Commands,,, ccmode, The CC Mode Manual}. -@item block-close -On a statement block close brace. +@node Multi-Line Comments +@subsection Multiple Lines of Comments -@item brace-list-open -On the opening brace of an @code{enum} or @code{static} array list. +@kindex C-M-j +@kindex M-j +@cindex blank lines in programs +@findex comment-indent-new-line -@item brace-list-close -On the closing brace of an @code{enum} or @code{static} array list. + If you are typing a comment and wish to continue it on another line, +you can use the command @kbd{C-M-j} or @kbd{M-j} +(@code{comment-indent-new-line}). If @code{comment-multi-line} +(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new +line within the comment. Otherwise it closes the comment and starts a +new comment on a new line. When Auto Fill mode is on, going past the +fill column while typing a comment causes the comment to be continued +in just this fashion. + +@kindex C-c C-c (C mode) +@findex comment-region + To turn existing lines into comment lines, use the @kbd{M-x +comment-region} command (or type @kbd{C-c C-c} in C-like modes). It +adds comment delimiters to the lines that start in the region, thus +commenting them out. With a negative argument, it does the +opposite---it deletes comment delimiters from the lines in the region. -@item brace-list-intro -On the first line in an @code{enum} or @code{static} array list. + With a positive argument, @code{comment-region} duplicates the last +character of the comment start sequence it adds; the argument +specifies how many copies of the character to insert. Thus, in Lisp +mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. +Duplicating the comment delimiter is a way of calling attention to the +comment. It can also affect how the comment is aligned or indented. +In Lisp, for proper indentation, you should use an argument of two or +three, if between defuns; if within a defun, it must be three. + + You can configure C Mode such that when you type a @samp{/} at the +start of a line in a multi-line block comment, this closes the +comment. Enable the @code{comment-close-slash} clean-up for this. +@xref{Clean-ups,,, ccmode, The CC Mode Manual}. -@item brace-list-entry -On one of the subsequent lines in an @code{enum} or @code{static} array -list. +@node Options for Comments +@subsection Options Controlling Comments -@item brace-entry-open -On one of the subsequent lines in an @code{enum} or @code{static} array -list, when the line begins with an open brace. - -@item statement -On an ordinary statement. - -@item statement-cont -On a continuation line of a statement. - -@item statement-block-intro -On the first line in a new statement block. - -@item statement-case-intro -On the first line in a @code{case} ``block.'' - -@item statement-case-open -On the first line in a @code{case} block starting with brace. - -@item inexpr-statement -On a statement block inside an expression. This is used for a GNU -extension to the C language, and for Pike special functions that take a -statement block as an argument. - -@item inexpr-class -On a class definition inside an expression. This is used for anonymous -classes and anonymous array initializers in Java. - -@item substatement -On the first line after an @code{if}, @code{while}, @code{for}, -@code{do}, or @code{else}. - -@item substatement-open -On the brace that opens a substatement block. - -@item case-label -On a @code{case} or @code{default} label. - -@item access-label -On a C++ @code{private}, @code{protected}, or @code{public} access label. - -@item label -On any ordinary label. - -@item do-while-closure -On the @code{while} that ends a @code{do}-@code{while} construct. - -@item else-clause -On the @code{else} of an @code{if}-@code{else} construct. - -@item catch-clause -On the @code{catch} and @code{finally} lines in -@code{try}@dots{}@code{catch} constructs in C++ and Java. - -@item comment-intro -On a line containing only a comment introduction. - -@item arglist-intro -On the first line in an argument list. - -@item arglist-cont -On one of the subsequent argument list lines when no arguments follow on -the same line as the arglist opening parenthesis. - -@item arglist-cont-nonempty -On one of the subsequent argument list lines when at least one argument -follows on the same line as the arglist opening parenthesis. - -@item arglist-close -On the closing parenthesis of an argument list. - -@item stream-op -On one of the lines continuing a stream operator construct. - -@item inclass -On a construct that is nested inside a class definition. The -indentation is relative to the open brace of the class definition. - -@item inextern-lang -On a construct that is nested inside an external language block. - -@item inexpr-statement -On the first line of statement block inside an expression. This is used -for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}. -It is also used for the special functions that takes a statement block -as an argument in Pike. - -@item inexpr-class -On the first line of a class definition inside an expression. This is -used for anonymous classes and anonymous array initializers in Java. - -@item cpp-macro -On the start of a cpp macro. - -@item friend -On a C++ @code{friend} declaration. - -@item objc-method-intro -On the first line of an Objective-C method definition. - -@item objc-method-args-cont -On one of the lines continuing an Objective-C method definition. - -@item objc-method-call-cont -On one of the lines continuing an Objective-C method call. - -@item inlambda -Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only -used in Pike. - -@item lambda-intro-cont -On a line continuing the header of a lambda function, between the -@code{lambda} keyword and the function body. Only used in Pike. -@end table - -@node Variables for C Indent -@subsubsection Variables for C Indentation - - This section describes additional variables which control the -indentation behavior of C mode and related mode. - -@table @code -@item c-offsets-alist -@vindex c-offsets-alist -Association list of syntactic symbols and their indentation offsets. -You should not set this directly, only with @code{c-set-offset}. -@xref{Changing Indent Style}, for details. - -@item c-style-alist -@vindex c-style-alist -Variable for defining indentation styles; see below. - -@item c-basic-offset -@vindex c-basic-offset -Amount of basic offset used by @code{+} and @code{-} symbols in -@code{c-offsets-alist}.@refill - -@item c-special-indent-hook -@vindex c-special-indent-hook -Hook for user-defined special indentation adjustments. This hook is -called after a line is indented by C mode and related modes. -@end table - - The variable @code{c-style-alist} specifies the predefined indentation -styles. Each element has form @code{(@var{name} -@var{variable-setting}@dots{})}, where @var{name} is the name of the -style. Each @var{variable-setting} has the form @code{(@var{variable} -. @var{value})}; @var{variable} is one of the customization variables -used by C mode, and @var{value} is the value for that variable when -using the selected style. - - When @var{variable} is @code{c-offsets-alist}, that is a special case: -@var{value} is appended to the front of the value of @code{c-offsets-alist} -instead of replacing that value outright. Therefore, it is not necessary -for @var{value} to specify each and every syntactic symbol---only those -for which the style differs from the default. - - The indentation of lines containing only comments is also affected by -the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}). - -@node C Indent Styles -@subsubsection C Indentation Styles -@cindex c indentation styles - - A @dfn{C style} is a collection of indentation style customizations. -Emacs comes with several predefined indentation styles for C and related -modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup}, -@code{linux}, @code{python}, @code{java}, @code{whitesmith}, -@code{ellemtel}, @code{cc-mode}, and @code{user}. - -@findex c-set-style -@vindex c-default-style - To choose the style you want, use the command @kbd{M-x c-set-style}. -Specify a style name as an argument (case is not significant in C style -names). The chosen style only affects newly visited buffers, not those -you are already editing. You can also set the variable -@code{c-default-style} to specify the style for various major modes. -Its value should be an alist, in which each element specifies one major -mode and which indentation style to use for it. For example, - -@example -(setq c-default-style - '((java-mode . "java") (other . "gnu"))) -@end example - -@noindent -specifies an explicit choice for Java mode, and the default @samp{gnu} -style for the other C-like modes. - - The style @code{gnu} defines the formatting recommend by the GNU -Project; it is the default, so as to encourage the indentation we -recommend. If you make changes in variables such as -@code{c-basic-offset} and @code{c-offsets-alist} in your @file{~/.emacs} -file, they will however take precedence. - -@findex c-add-style - To define a new C indentation style, call the function -@code{c-add-style}: - -@example -(c-add-style @var{name} @var{values} @var{use-now}) -@end example - -@noindent -Here @var{name} is the name of the new style (a string), and -@var{values} is an alist whose elements have the form -@code{(@var{variable} . @var{value})}. The variables you specify should -be among those documented in @ref{Variables for C Indent}. - - If @var{use-now} is non-@code{nil}, @code{c-add-style} selects the new -style after defining it. - -@node Matching -@section Automatic Display Of Matching Parentheses -@cindex matching parentheses -@cindex parentheses, displaying matches - - The Emacs parenthesis-matching feature is designed to show -automatically how parentheses match in the text. Whenever you type a -self-inserting character that is a closing delimiter, the cursor moves -momentarily to the location of the matching opening delimiter, provided -that is on the screen. If it is not on the screen, some text near it is -displayed in the echo area. Either way, you can tell what grouping is -being closed off. - - In Lisp, automatic matching applies only to parentheses. In C, it -applies to braces and brackets too. Emacs knows which characters to regard -as matching delimiters based on the syntax table, which is set by the major -mode. @xref{Syntax}. - - If the opening delimiter and closing delimiter are mismatched---such as -in @samp{[x)}---a warning message is displayed in the echo area. The -correct matches are specified in the syntax table. - -@vindex blink-matching-paren -@vindex blink-matching-paren-distance -@vindex blink-matching-delay - Three variables control parenthesis match display. -@code{blink-matching-paren} turns the feature on or off; @code{nil} -turns it off, but the default is @code{t} to turn match display on. -@code{blink-matching-delay} says how many seconds to wait; the default -is 1, but on some systems it is useful to specify a fraction of a -second. @code{blink-matching-paren-distance} specifies how many -characters back to search to find the matching opening delimiter. If -the match is not found in that far, scanning stops, and nothing is -displayed. This is to prevent scanning for the matching delimiter from -wasting lots of time when there is no match. The default is 12,000. - -@cindex Show Paren mode -@cindex highlighting matching parentheses -@findex show-paren-mode - You can also request a more powerful alternative kind of automatic -parenthesis matching by enabling Show Paren mode. This mode turns off -the usual kind of matching parenthesis display and instead uses -highlighting to show what matches. Whenever point is after a close -parenthesis, the close parenthesis and its matching open parenthesis are -both highlighted; otherwise, if point is before an open parenthesis, the -matching close parenthesis is highlighted. (There is no need to -highlight the open parenthesis after point because the cursor appears on -top of that character.) Use the command @kbd{M-x show-paren-mode} to -enable or disable this mode. - - By default, @code{show-paren-mode} uses colors to highlight the -parentheses. However, if your display doesn't support colors, you can -customize the faces @code{show-paren-match-face} and -@code{show-paren-mismatch-face} to use other attributes, such as bold or -underline. @xref{Face Customization}. - -@node Comments -@section Manipulating Comments -@cindex comments - - Because comments are such an important part of programming, Emacs -provides special commands for editing and inserting comments. - -@menu -* Comment Commands:: -* Multi-Line Comments:: -* Options for Comments:: -@end menu - -@node Comment Commands -@subsection Comment Commands - -@kindex M-; -@cindex indentation for comments -@findex indent-for-comment -@findex comment-dwim - - The comment commands insert, kill and align comments. - -@c WideCommands -@table @kbd -@item M-; -Call the comment command that is appropriate for the context -(@code{comment-dwim}). -@item M-x indent-for-comment -Insert or align comment. -@item C-x ; -Set comment column (@code{set-comment-column}). -@item C-u - C-x ; -Kill comment on current line (@code{comment-kill}). -@item C-M-j -Like @key{RET} followed by inserting and aligning a comment -(@code{indent-new-comment-line}). -@item M-x comment-region -Add or remove comment delimiters on all the lines in the region. -@end table - - The command that creates a comment is @kbd{M-x indent-for-comment}. -If there is no comment already on the line, a new comment is created, -aligned at a specific column called the @dfn{comment column}. The comment -is created by inserting the string Emacs thinks comments should start with -(the value of @code{comment-start}; see below). Point is left after that -string. If the text of the line extends past the comment column, then the -indentation is done to a suitable boundary (usually, at least one space is -inserted). If the major mode has specified a string to terminate comments, -that is inserted after point, to keep the syntax valid. - - @kbd{M-x indent-for-comment} can also be used to align an existing -comment. If a line already contains the string that starts comments, -then @kbd{M-x indent-for-comment} just moves point after it and -reindents it to the conventional place. Exception: comments starting in -column 0 are not moved. - - @kbd{M-;} (@code{comment-dwim}) conveniently combines -@code{indent-for-comment} with @code{comment-region} and -@code{uncomment-region}, described below in @ref{Multi-Line Comments}, -as appropriate for the current context. If the region is active and the -Transient Mark mode is on (@pxref{Transient Mark}), @kbd{M-;} invokes -@code{comment-region}, unless the region consists only of comments, in -which case it invokes @code{uncomment-region}. Otherwise, if the -current line is empty, @kbd{M-;} inserts a comment and indents it. If -the current line is not empty, @kbd{M-;} invokes @code{comment-kill} if -a numeric argument was given, else it reindents the comment on the -current line. (The @dfn{dwim} in @code{comment-dwim} is an acronym for -``Do What I Mean''.) - - Some major modes have special rules for indenting certain kinds of -comments in certain contexts. For example, in Lisp code, comments which -start with two semicolons are indented as if they were lines of code, -instead of at the comment column. Comments which start with three -semicolons are supposed to start at the left margin. Emacs understands -these conventions by indenting a double-semicolon comment using @key{TAB}, -and by not changing the indentation of a triple-semicolon comment at all. - -@example -;; This function is just an example -;;; Here either two or three semicolons are appropriate. -(defun foo (x) -;;; And now, the first part of the function: - ;; The following line adds one. - (1+ x)) ; This line adds one. -@end example - - In C code, a comment preceded on its line by nothing but whitespace -is indented like a line of code. - - Even when an existing comment is properly aligned, @kbd{M-;} is still -useful for moving directly to the start of the comment. - -@kindex C-u - C-x ; -@findex kill-comment -@findex comment-kill - @kbd{C-u - C-x ;} (@code{comment-kill}) kills the comment on the current line, -if there is one. The indentation before the start of the comment is killed -as well. If there does not appear to be a comment in the line, nothing is -done. To reinsert the comment on another line, move to the end of that -line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that -@kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column}) -with a negative argument. That command is programmed so that when it -receives a negative argument it calls @code{comment-kill}. However, -@code{comment-kill} is a valid command which you could bind directly to a -key if you wanted to. (For compatibility with previous versions, -@code{kill-comment} is provided as an alias to @code{comment-kill}.) - -@node Multi-Line Comments -@subsection Multiple Lines of Comments - -@kindex C-M-j -@cindex blank lines in programs -@findex indent-new-comment-line - If you are typing a comment and wish to continue it on another line, -you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}). -This terminates the comment you are typing, creates a new blank line -afterward, and begins a new comment indented under the old one. When -Auto Fill mode is on, going past the fill column while typing a comment -causes the comment to be continued in just this fashion. If point is -not at the end of the line when @kbd{C-M-j} is typed, the text on -the rest of the line becomes part of the new comment line. - -@findex comment-region - To turn existing lines into comment lines, use the @kbd{M-x -comment-region} command. It adds comment delimiters to the lines that start -in the region, thus commenting them out. With a negative argument, it -does the opposite---it deletes comment delimiters from the lines in the -region. - - With a positive argument, @code{comment-region} duplicates the last -character of the comment start sequence it adds; the argument specifies -how many copies of the character to insert. Thus, in Lisp mode, -@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating -the comment delimiter is a way of calling attention to the comment. It -can also affect how the comment is indented. In Lisp, for proper -indentation, you should use an argument of two, if between defuns, and -three, if within a defun. - -@vindex comment-padding - The variable @code{comment-padding} specifies how many spaces -@code{comment-region} should insert on each line between the -comment delimiter and the line's original text. The default is 1. - -@node Options for Comments -@subsection Options Controlling Comments - -@vindex comment-column -@kindex C-x ; -@findex set-comment-column - The comment column is stored in the variable @code{comment-column}. You -can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} -(@code{set-comment-column}) sets the comment column to the column point is -at. @kbd{C-u C-x ;} sets the comment column to match the last comment -before point in the buffer, and then does a @kbd{M-;} to align the -current line's comment under the previous one. Note that @kbd{C-u - C-x ;} -runs the function @code{comment-kill} as described above. +@vindex comment-column +@kindex C-x ; +@findex comment-set-column + The @dfn{comment column}, the column at which Emacs tries to place +comments, is stored in the variable @code{comment-column}. You can +set it to a number explicitly. Alternatively, the command @kbd{C-x ;} +(@code{comment-set-column}) sets the comment column to the column +point is at. @kbd{C-u C-x ;} sets the comment column to match the +last comment before point in the buffer, and then does a @kbd{M-;} to +align the current line's comment under the previous one. The variable @code{comment-column} is per-buffer: setting the variable in the normal fashion affects only the current buffer, but there is a @@ -1375,1591 +1031,377 @@ current buffer. @vindex comment-start-skip The comment commands recognize comments based on the regular -expression that is the value of the variable @code{comment-start-skip}. -Make sure this regexp does not match the null string. It may match more -than the comment starting delimiter in the strictest sense of the word; -for example, in C mode the value of the variable is @code{@t{"/\\*+ -*"}}, which matches extra stars and spaces after the @samp{/*} itself. -(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in -the string, which is needed to deny the first star its special meaning -in regexp syntax. @xref{Regexps}.) - -@vindex comment-start -@vindex comment-end - When a comment command makes a new comment, it inserts the value of -@code{comment-start} to begin it. The value of @code{comment-end} is -inserted after point, so that it will follow the text that you will insert -into the comment. In C mode, @code{comment-start} has the value -@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}. - -@vindex comment-multi-line - The variable @code{comment-multi-line} controls how @kbd{C-M-j} -(@code{indent-new-comment-line}) behaves when used inside a comment. If -@code{comment-multi-line} is @code{nil}, as it normally is, then the -comment on the starting line is terminated and a new comment is started -on the new following line. If @code{comment-multi-line} is not -@code{nil}, then the new following line is set up as part of the same -comment that was found on the starting line. This is done by not -inserting a terminator on the old line, and not inserting a starter on -the new line. In languages where multi-line comments work, the choice -of value for this variable is a matter of taste. - -@vindex comment-indent-function - The variable @code{comment-indent-function} should contain a function -that will be called to compute the indentation for a newly inserted -comment or for aligning an existing comment. It is set differently by -various major modes. The function is called with no arguments, but with -point at the beginning of the comment, or at the end of a line if a new -comment is to be inserted. It should return the column in which the -comment ought to start. For example, in Lisp mode, the indent hook -function bases its decision on how many semicolons begin an existing -comment, and on the code in the preceding lines. - -@node Balanced Editing -@section Editing Without Unbalanced Parentheses - -@table @kbd -@item M-( -Put parentheses around next sexp(s) (@code{insert-parentheses}). -@item M-) -Move past next close parenthesis and reindent -(@code{move-past-close-and-reindent}). -@end table - -@kindex M-( -@kindex M-) -@findex insert-parentheses -@findex move-past-close-and-reindent - The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)} -(@code{move-past-close-and-reindent}) are designed to facilitate a style -of editing which keeps parentheses balanced at all times. @kbd{M-(} -inserts a pair of parentheses, either together as in @samp{()}, or, if -given an argument, around the next several sexps. It leaves point after -the open parenthesis. The command @kbd{M-)} moves past the close -parenthesis, deleting any indentation preceding it, and indenting with -@kbd{C-j} after it. - - For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-( -F O O}, which has the same effect except for leaving the cursor before -the close parenthesis. - -@vindex parens-require-spaces - @kbd{M-(} may insert a space before the open parenthesis, depending on -the syntax class of the preceding character. Set -@code{parens-require-spaces} to @code{nil} value if you wish to inhibit -this. - -@findex check-parens -@cindex unbalanced parentheses and quotes -You can use @kbd{M-x check-parens} to find any unbalanced parentheses -and unbalanced quotes in strings in a buffer. - -@node Symbol Completion -@section Completion for Symbol Names -@cindex completion (symbol names) - - Usually completion happens in the minibuffer. But one kind of completion -is available in all buffers: completion for symbol names. - -@kindex M-TAB - The character @kbd{M-@key{TAB}} runs a command to complete the partial -symbol before point against the set of meaningful symbol names. Any -additional characters determined by the partial name are inserted at -point. - - If the partial name in the buffer has more than one possible completion -and they have no additional characters in common, a list of all possible -completions is displayed in another window. - -@cindex completion using tags -@cindex tags completion -@cindex Info index completion -@findex complete-symbol - In most programming language major modes, @kbd{M-@key{TAB}} runs the -command @code{complete-symbol}, which provides two kinds of completion. -Normally it does completion based on a tags table (@pxref{Tags}); with a -numeric argument (regardless of the value), it does completion based on -the names listed in the Info file indexes for your language. Thus, to -complete the name of a symbol defined in your own program, use -@kbd{M-@key{TAB}} with no argument; to complete the name of a standard -library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based -completion works only if there is an Info file for the standard library -functions of your language, and only if it is installed at your site. - -@cindex Lisp symbol completion -@cindex completion in Lisp -@findex lisp-complete-symbol - In Emacs-Lisp mode, the name space for completion normally consists of -nontrivial symbols present in Emacs---those that have function -definitions, values or properties. However, if there is an -open-parenthesis immediately before the beginning of the partial symbol, -only symbols with function definitions are considered as completions. -The command which implements this is @code{lisp-complete-symbol}. - - In Text mode and related modes, @kbd{M-@key{TAB}} completes words -based on the spell-checker's dictionary. @xref{Spelling}. - -@node Which Function -@section Which Function Mode - - Which Function mode is a minor mode that displays the current function -name in the mode line, as you move around in a buffer. - -@findex which-function-mode -@vindex which-func-modes - To enable (or disable) Which Function mode, use the command @kbd{M-x -which-function-mode}. This command is global; it applies to all -buffers, both existing ones and those yet to be created. However, this -only affects certain major modes, those listed in the value of -@code{which-func-modes}. (If the value is @code{t}, then Which Function -mode applies to all major modes that know how to support it---which are -the major modes that support Imenu.) - -@node Hideshow -@section Hideshow minor mode - -@findex hs-minor-mode -Hideshow minor mode provides selective display of blocks. Use @kbd{M-x -hs-minor-mode} to toggle the mode or add @code{hs-minor-mode} to the -hook for major modes with which you want to use it and which support it. - -Blocks are defined dependent on the mode. In C mode or C++ mode, they -are delimited by braces, while in Lisp-ish modes they are delimited by -parens. Multi-line comments can also be hidden. - -@findex hs-hide-all -@findex hs-hide-block -@findex hs-show-all -@findex hs-show-block -@findex hs-show-region -@findex hs-hide-level -@findex hs-minor-mode -@kindex C-c h -@kindex C-c s -@kindex C-c H -@kindex C-c S -@kindex C-c R -@kindex C-c L -@kindex S-mouse-2 -The mode provides the commands @kbd{C-c h} (@kbd{M-x hs-hide-all}), -@kbd{C-c s} (@kbd{M-x hs-hide-block}), @kbd{C-c H} (@kbd{M-x -hs-show-all}), @kbd{C-c S} (@kbd{M-x hs-show-block}), @kbd{C-c R} -(@kbd{M-x hs-show-region}) and @kbd{C-c L} (@kbd{M-x hs-hide-level}) -with obvious functions and @kbd{S-mouse-2} toggles hiding of a block -with the mouse. - -@vindex hs-hide-comments-when-hiding-all -@vindex hs-show-hidden-short-form -@vindex hs-isearch-open -@vindex hs-special-modes-alist -Hideshow is customized by the variables -@table @code -@item hs-hide-comments-when-hiding-all -Specifies whether @kbd{hs-hide-all} should hide comments too. -@item hs-show-hidden-short-form -Specifies whether or not the last line in a form is omitted (saving -screen space). -@item hs-isearch-open -Specifies what kind of hidden blocks to open in Isearch mode. -@item hs-special-modes-alist -Initializes Hideshow variables for different modes. -@end table - -@node Glasses -@section Glasses minor mode -@cindex Glasses mode -@cindex identifiers, unreadable -@cindex StudlyCaps -@findex glasses-mode - -Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} readable -by displaying underscores between all the pairs of lower and upper -English letters or by emboldening the capitals. The text is not -altered, only the display, so that you can use this mode on code written -with such a convention for separating words in identifiers without -modifying the code. It can be customized under the group -@samp{glasses}. You can use it by adding @code{glasses-mode} to the -mode hook of appropriate programming modes. - - -@node Documentation -@section Documentation Commands - - As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f} -(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can -be used to print documentation of functions and variables that you want to -call. These commands use the minibuffer to read the name of a function or -variable to document, and display the documentation in a window. - - For extra convenience, these commands provide default arguments based on -the code in the neighborhood of point. @kbd{C-h f} sets the default to the -function called in the innermost list containing point. @kbd{C-h v} uses -the symbol name around or adjacent to point as its default. - -@cindex Eldoc mode -@findex eldoc-mode - For Emacs Lisp code, you can also use Eldoc mode. This minor mode -constantly displays in the echo area the argument list for the function -being called at point. (In other words, it finds the function call that -point is contained in, and displays the argument list of that function.) -Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use -the command @kbd{M-x eldoc-mode} to enable or disable this feature. - -@findex info-lookup-symbol -@findex info-lookup-file -@kindex C-h C-i - For C, Lisp, and other languages, you can use @kbd{C-h C-i} -(@code{info-lookup-symbol}) to view the Info documentation for a symbol. -You specify the symbol with the minibuffer; by default, it uses the -symbol that appears in the buffer at point. The major mode determines -where to look for documentation for the symbol---which Info files and -which indices. You can also use @kbd{M-x info-lookup-file} to look for -documentation for a file name. Currently the modes supported by -Info-lookup are: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4, -Makefile, Octave, Perl, Scheme and Texinfo. The relevant Info files -mostly must be obtained separately, typically from the appropriate GNU -package. - -@findex manual-entry -@cindex manual pages - You can read the ``man page'' for an operating system command, library -function, or system call, with the @kbd{M-x manual-entry} command. It -runs the @code{man} program to format the man page, and runs it -asynchronously if your system permits, so that you can keep on editing -while the page is being formatted. (MS-DOS and MS-Windows 3 do not -permit asynchronous subprocesses, so on these systems you cannot edit -while Emacs waits for @code{man} to exit.) The result goes in a buffer -named @samp{*Man @var{topic}*}. These buffers use a special major mode, -Man mode, that facilitates scrolling and examining other manual pages. -For details, type @kbd{C-h m} while in a man page buffer. - -@cindex sections of manual pages - Man pages are subdivided into @dfn{sections}, and some man pages have -identical names, but belong to different sections. To read a man page -from a certain section, type @kbd{@var{topic}(@var{section})} or -@kbd{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts for -the topic. For example, to read the man page for the C library function -@code{chmod} (as opposed to a command by the same name), type @kbd{M-x -manual-entry @key{RET} chmod(2v) @key{RET}} (assuming @code{chmod} is in -section @code{2v}). - - If you do not specify a section, the results depend on how the -@code{man} command works on your system. Some of them display only the -first man page they find, others display all the man pages, and you can -page between them with the @kbd{M-n} and @kbd{M-p} keys. The mode line -shows how many manual pages are available in the Man buffer. - -@vindex Man-fontify-manpage-flag - For a long man page, setting the faces properly can take substantial -time. By default, Emacs uses faces in man pages if Emacs can display -different fonts or colors. You can turn off use of faces in man pages -by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}. - -@findex Man-fontify-manpage - If you insert the text of a man page into an Emacs buffer in some -other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to -perform the same conversions that @kbd{M-x manual-entry} does. - -@findex woman -@cindex manual pages, on MS-DOS/MS-Windows - An alternative way of reading manual pages is the @kbd{M-x woman} -command@footnote{The name of the command, @code{woman}, is an acronym -for ``w/o (without) man'', since it doesn't use the @code{man} -program.}. Unlike @kbd{M-x man}, it does not run any external programs -to format and display the man pages, instead it does that entirely in -Emacs Lisp. Thus, it is useful on systems such as MS-Windows, where the -@code{man} program and the programs it runs are not readily available. -When invoked, @kbd{M-x woman} prompts for a name of a manual page and -provides completion based on the list of manual pages that are installed -on your machine; the list of available manual pages is computed -automatically the first time you invoke @code{woman}. The word at point -in the current buffer is used to suggest the default name of the manual -page. - - With a numeric argument, @kbd{M-x woman} recomputes the list of the -manual pages used for completion. This is useful if you add or delete -manual pages. - - If you type a name of a manual page and @kbd{M-x woman} finds that -several manual pages by the same name exist in different sections, it -pops up a window with possible candidates asking you to choose one of -them. - -@vindex woman-manpath - By default, @kbd{M-x woman} looks up the manual pages in directories -listed by the @code{MANPATH} environment variable. (If @code{MANPATH} -is not set, @code{woman} uses a suitable default value, which can be -customized.) More precisely, @code{woman} looks for subdirectories that -match the shell wildcard @file{man*} in each one of these directories, -and tries to find the manual pages in those subdirectories. When first -invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list -of directory names and stores that list in the @code{woman-manpath} -variable. By changing the value of this variable, you can customize the -list of directories where @code{woman} looks for manual pages. - -@vindex woman-path - In addition, you can augment the list of directories searched by -@code{woman} by setting the value of the @code{woman-path} variable. -This variable should hold a list of specific directories which -@code{woman} should search, in addition to those in -@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in -@code{woman-path} are searched for the manual pages, not for @file{man*} -subdirectories. - -@findex woman-find-file - Occasionally, you might need to display manual pages that are not in -any of the directories listed by @code{woman-manpath} and -@code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a -name of a manual page file, with completion, and then formats and -displays that file like @kbd{M-x woman} does. - -@vindex woman-dired-keys - First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W} -key to run the @code{woman-find-file} command on the current line's -file. You can disable this by setting the variable -@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, the -Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current -line's archive member. - - For more information about setting up and using @kbd{M-x woman}, see -@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan -Manual}. - - Eventually the GNU project hopes to replace most man pages with -better-organized manuals that you can browse with Info. @xref{Misc -Help}. Since this process is only partially completed, it is still -useful to read manual pages. - -@node Change Log -@section Change Logs - -@cindex change log -@kindex C-x 4 a -@findex add-change-log-entry-other-window - The Emacs command @kbd{C-x 4 a} adds a new entry to the change log -file for the file you are editing -(@code{add-change-log-entry-other-window}). If that file is actually a -backup file, it makes an entry appropriate for the file's parent. This -is useful for making log entries by comparing a version with deleted -functions. - - A change log file contains a chronological record of when and why you -have changed a program, consisting of a sequence of entries describing -individual changes. Normally it is kept in a file called -@file{ChangeLog} in the same directory as the file you are editing, or -one of its parent directories. A single @file{ChangeLog} file can -record changes for all the files in its directory and all its -subdirectories. - - A change log entry starts with a header line that contains your name, -your email address (taken from the variable @code{user-mail-address}), -and the current date and time. Aside from these header lines, every -line in the change log starts with a space or a tab. The bulk of the -entry consists of @dfn{items}, each of which starts with a line starting -with whitespace and a star. Here are two entries, both dated in May -1993, each with two items: - -@iftex -@medbreak -@end iftex -@smallexample -1993-05-25 Richard Stallman - - * man.el: Rename symbols `man-*' to `Man-*'. - (manual-entry): Make prompt string clearer. - - * simple.el (blink-matching-paren-distance): - Change default to 12,000. - -1993-05-24 Richard Stallman - - * vc.el (minor-mode-map-alist): Don't use it if it's void. - (vc-cancel-version): Doc fix. -@end smallexample - - One entry can describe several changes; each change should have its -own item. Normally there should be a blank line between items. When -items are related (parts of the same change, in different places), group -them by leaving no blank line between them. The second entry above -contains two items grouped in this way. - -@vindex add-log-keep-changes-together - @kbd{C-x 4 a} visits the change log file and creates a new entry -unless the most recent entry is for today's date and your name. It also -creates a new item for the current file. For many languages, it can -even guess the name of the function or other object that was changed. -When the option @code{add-log-keep-changes-together} is set, @kbd{C-x 4 -a} adds to any existing entry for the file rather than starting a new -entry. - -@vindex change-log-version-info-enabled -@vindex change-log-version-number-regexp-list -@cindex file version in change log entries - If the value of the variable @code{change-log-version-info-enabled} is -non-nil, the file's version number is automatically added to change log -entries. The search for the file's version number is performed based on -regular expressions from the variable -@code{change-log-version-number-regexp-list}, which can be customized -(versions of files that are under version control systems are known to -Emacs through the version-control interface). - -@cindex Change Log mode -@findex change-log-mode - The change log file is visited in Change Log mode. In this major -mode, each bunch of grouped items counts as one paragraph, and each -entry is considered a page. This facilitates editing the entries. -@kbd{C-j} and auto-fill indent each new line like the previous line; -this is convenient for entering the contents of an entry. - -@findex change-log-merge -The command @kbd{M-x change-log-merge} can be used to merge other log -files into a buffer in Change Log Mode, preserving the date ordering -of entries with either the current or old-style date formats. - -@findex change-log-redate -@cindex converting change log date style - Versions of Emacs before 20.1 used a different format for the time of -the change log entry: - -@smallexample -Fri May 25 11:23:23 1993 Richard Stallman -@end smallexample - -@noindent -The @kbd{M-x change-log-redate} command converts all the old-style date -entries in the change log file visited in the current buffer to the new -format, so that all entries are kept in unified format. This is handy -when the entries are contributed by many different people some of whom -still use old versions of Emacs. - - Version control systems are another way to keep track of changes in your -program and keep a change log. @xref{Log Buffer}. - -@node Authors -@section @file{AUTHORS} files -@cindex @file{AUTHORS} file - - Programs which have many contributors usually include a file named -@file{AUTHORS} in their distribution, which lists the individual -contributions. Emacs has a special command for maintaining the -@file{AUTHORS} file that is part of the Emacs distribution. - -@findex authors - The @kbd{M-x authors} command prompts for the name of the root of the -Emacs source directory. It then scans @file{ChageLog} files and Lisp -source files under that directory for information about authors of -individual packages and people who made changes in source files, and -puts the information it gleans into a buffer named @samp{*Authors*}. -You can then edit the contents of that buffer and merge it with the -exisiting @file{AUTHORS} file. - -@node Tags -@section Tags Tables -@cindex tags table - - A @dfn{tags table} is a description of how a multi-file program is -broken up into files. It lists the names of the component files and the -names and positions of the functions (or other named subunits) in each -file. Grouping the related files makes it possible to search or replace -through all the files with one command. Recording the function names -and positions makes possible the @kbd{M-.} command which finds the -definition of a function by looking up which of the files it is in. - - Tags tables are stored in files called @dfn{tags table files}. The -conventional name for a tags table file is @file{TAGS}. - - Each entry in the tags table records the name of one tag, the name of the -file that the tag is defined in (implicitly), and the position in that file -of the tag's definition. - - Just what names from the described files are recorded in the tags table -depends on the programming language of the described file. They -normally include all functions and subroutines, and may also include -global variables, data types, and anything else convenient. Each name -recorded is called a @dfn{tag}. - -@cindex C++ class browser, tags -@cindex tags, C++ -@cindex class browser, C++ -@cindex Ebrowse -The Ebrowse is a separate facility tailored for C++, with tags and a -class browser. @xref{,,, ebrowse, Ebrowse User's Manual}. - -@menu -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @code{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Listing and finding tags defined in a file. -@end menu - -@node Tag Syntax -@subsection Source File Tag Syntax - - Here is how tag syntax is defined for the most popular languages: - -@itemize @bullet -@item -In C code, any C function or typedef is a tag, and so are definitions of -@code{struct}, @code{union} and @code{enum}. You can tag function -declarations and external variables in addition to function definitions -by giving the @samp{--declarations} option to @code{etags}. -@code{#define} macro definitions and @code{enum} constants are also -tags, unless you specify @samp{--no-defines} when making the tags table. -Similarly, global variables are tags, unless you specify -@samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines} -can make the tags table file much smaller. - -@item -In C++ code, in addition to all the tag constructs of C code, member -functions are also recognized, and optionally member variables if you -use the @samp{--members} option. Tags for variables and functions in -classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. @code{operator} functions tags are -named, for example @samp{operator+}. - -@item -In Java code, tags include all the constructs recognized in C++, plus -the @code{interface}, @code{extends} and @code{implements} constructs. -Tags for variables and functions in classes are named -@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. - -@item -In La@TeX{} text, the argument of any of the commands @code{\chapter}, -@code{\section}, @code{\subsection}, @code{\subsubsection}, -@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, -@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a -tag.@refill - -Other commands can make tags as well, if you specify them in the -environment variable @env{TEXTAGS} before invoking @code{etags}. The -value of this environment variable should be a colon-separated list of -command names. For example, - -@example -TEXTAGS="def:newcommand:newenvironment" -export TEXTAGS -@end example - -@noindent -specifies (using Bourne shell syntax) that the commands @samp{\def}, -@samp{\newcommand} and @samp{\newenvironment} also define tags. - -@item -In Lisp code, any function defined with @code{defun}, any variable -defined with @code{defvar} or @code{defconst}, and in general the first -argument of any expression that starts with @samp{(def} in column zero, is -a tag. - -@item -In Scheme code, tags include anything defined with @code{def} or with a -construct whose name starts with @samp{def}. They also include variables -set with @code{set!} at top level in the file. -@end itemize - - Several other languages are also supported: - -@itemize @bullet - -@item -In Ada code, functions, procedures, packages, tasks, and types are -tags. Use the @samp{--packages-only} option to create tags for -packages only. - -With Ada, it is possible to have the same name used for different -entity kind (e.g. same name for a procedure and a function). Also, -for things like package, procedures and functions, there is the spec -(i.e. the interface) and the body (i.e. the implementation). To -facilitate the choice to the user, a tag value is appended with a -qualifier : - -@table @asis -@item function - @kbd{/f} -@item procedure - @kbd{/p} -@item package spec - @kbd{/s} -@item package body - @kbd{/b} -@item type - @kbd{/t} -@item task - @kbd{/k} -@end table - -So, as an example, @kbd{M-x find-tag bidule/b} will go directly to the -body of the package @var{bidule} while @kbd{M-x find-tag bidule} will -just search for any tag @var{bidule}. - -@item -In assembler code, labels appearing at the beginning of a line, -followed by a colon, are tags. - -@item -In Bison or Yacc input files, each rule defines as a tag the nonterminal -it constructs. The portions of the file that contain C code are parsed -as C code. - -@item -In Cobol code, tags are paragraph names; that is, any word starting in -column 8 and followed by a period. - -@item -In Erlang code, the tags are the functions, records, and macros defined -in the file. - -@item -In Fortran code, functions, subroutines and blockdata are tags. - -@item -In makefiles, targets are tags. - -@item -In Objective C code, tags include Objective C definitions for classes, -class categories, methods, and protocols. - -@item -In Pascal code, the tags are the functions and procedures defined in -the file. - -@item -In Perl code, the tags are the procedures defined by the @code{sub}, -@code{my} and @code{local} keywords. Use @samp{--globals} if you want -to tag global variables. - -@item -In PostScript code, the tags are the functions. - -@item -In Prolog code, a tag name appears at the left margin. - -@item -In Python code, @code{def} or @code{class} at the beginning of a line -generate a tag. -@end itemize - - You can also generate tags based on regexp matching (@pxref{Etags -Regexps}) to handle other formats and languages. - -@node Create Tags Table -@subsection Creating Tags Tables -@cindex @code{etags} program - - The @code{etags} program is used to create a tags table file. It knows -the syntax of several languages, as described in -@iftex -the previous section. -@end iftex -@ifinfo -@ref{Tag Syntax}. -@end ifinfo -Here is how to run @code{etags}: - -@example -etags @var{inputfiles}@dots{} -@end example - -@noindent -The @code{etags} program reads the specified files, and writes a tags -table named @file{TAGS} in the current working directory. You can -intermix compressed and plain text source file names. @code{etags} -knows about the most common compression formats, and does the right -thing. So you can compress all your source files and have @code{etags} -look for compressed versions of its file name arguments, if it does not -find uncompressed versions. Under MS-DOS, @code{etags} also looks for -file names like @samp{mycode.cgz} if it is given @samp{mycode.c} on the -command line and @samp{mycode.c} does not exist. - - @code{etags} recognizes the language used in an input file based on -its file name and contents. You can specify the language with the -@samp{--language=@var{name}} option, described below. - - If the tags table data become outdated due to changes in the files -described in the table, the way to update the tags table is the same way it -was made in the first place. It is not necessary to do this often. - - If the tags table fails to record a tag, or records it for the wrong -file, then Emacs cannot possibly find its definition. However, if the -position recorded in the tags table becomes a little bit wrong (due to -some editing in the file that the tag definition is in), the only -consequence is a slight delay in finding the tag. Even if the stored -position is very wrong, Emacs will still find the tag, but it must -search the entire file for it. - - So you should update a tags table when you define new tags that you want -to have listed, or when you move tag definitions from one file to another, -or when changes become substantial. Normally there is no need to update -the tags table after each edit, or even every day. - - One tags table can effectively include another. Specify the included -tags file name with the @samp{--include=@var{file}} option when creating -the file that is to include it. The latter file then acts as if it -contained all the files specified in the included file, as well as the -files it directly contains. - - If you specify the source files with relative file names when you run -@code{etags}, the tags file will contain file names relative to the -directory where the tags file was initially written. This way, you can -move an entire directory tree containing both the tags file and the -source files, and the tags file will still refer correctly to the source -files. - - If you specify absolute file names as arguments to @code{etags}, then -the tags file will contain absolute file names. This way, the tags file -will still refer to the same files even if you move it, as long as the -source files remain in the same place. Absolute file names start with -@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. - - When you want to make a tags table from a great number of files, you -may have problems listing them on the command line, because some systems -have a limit on its length. The simplest way to circumvent this limit -is to tell @code{etags} to read the file names from its standard input, -by typing a dash in place of the file names, like this: - -@smallexample -find . -name "*.[chCH]" -print | etags - -@end smallexample - - Use the option @samp{--language=@var{name}} to specify the language -explicitly. You can intermix these options with file names; each one -applies to the file names that follow it. Specify -@samp{--language=auto} to tell @code{etags} to resume guessing the -language from the file names and file contents. Specify -@samp{--language=none} to turn off language-specific processing -entirely; then @code{etags} recognizes tags by regexp matching alone -(@pxref{Etags Regexps}). - - @samp{etags --help} prints the list of the languages @code{etags} -knows, and the file name rules for guessing the language. It also prints -a list of all the available @code{etags} options, together with a short -explanation. - -@node Etags Regexps -@subsection Etags Regexps - - The @samp{--regex} option provides a general way of recognizing tags -based on regexp matching. You can freely intermix it with file names. -Each @samp{--regex} option adds to the preceding ones, and applies only -to the following files. The syntax is: - -@smallexample ---regex=/@var{tagregexp}[/@var{nameregexp}]/ -@end smallexample - -@noindent -where @var{tagregexp} is used to match the lines to tag. It is always -anchored, that is, it behaves as if preceded by @samp{^}. If you want -to account for indentation, just match any initial number of blanks by -beginning your regular expression with @samp{[ \t]*}. In the regular -expressions, @samp{\} quotes the next character, and @samp{\t} stands -for the tab character. Note that @code{etags} does not handle the other -C escape sequences for special characters. - -@cindex interval operator (in regexps) - The syntax of regular expressions in @code{etags} is the same as in -Emacs, augmented with the @dfn{interval operator}, which works as in -@code{grep} and @code{ed}. The syntax of an interval operator is -@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding -expression at least @var{m} times and up to @var{n} times. - - You should not match more characters with @var{tagregexp} than that -needed to recognize what you want to tag. If the match is such that -more characters than needed are unavoidably matched by @var{tagregexp} -(as will usually be the case), you should add a @var{nameregexp}, to -pick out just the tag. This will enable Emacs to find tags more -accurately and to do completion on tag names more reliably. You can -find some examples below. - - The option @samp{--ignore-case-regex} (or @samp{-c}) is like -@samp{--regex}, except that the regular expression provided will be -matched without regard to case, which is appropriate for various -programming languages. - - The @samp{-R} option deletes all the regexps defined with -@samp{--regex} options. It applies to the file names following it, as -you can see from the following example: - -@smallexample -etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \ - bar.ber -R --lang=lisp los.er -@end smallexample - -@noindent -Here @code{etags} chooses the parsing language for @file{voo.doo} and -@file{bar.ber} according to their contents. @code{etags} also uses -@var{reg1} to recognize additional tags in @file{voo.doo}, and both -@var{reg1} and @var{reg2} to recognize additional tags in -@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp -matching, to recognize tags in @file{los.er}. - - A regular expression can be bound to a given language, by prepending -it with @samp{@{lang@}}. When you do this, @code{etags} will use the -regular expression only for files of that language. @samp{etags --help} -prints the list of languages recognised by @code{etags}. The following -example tags the @code{DEFVAR} macros in the Emacs source files. -@code{etags} applies this regular expression to C files only: - -@smallexample ---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' -@end smallexample - -@noindent -This feature is particularly useful when storing a list of regular -expressions in a file. The following option syntax instructs -@code{etags} to read two files of regular expressions. The regular -expressions contained in the second file are matched without regard to -case. - -@smallexample ---regex=@@first-file --ignore-case-regex=@@second-file -@end smallexample - -@noindent -A regex file contains one regular expressions per line. Empty lines, -and lines beginning with space or tab are ignored. When the first -character in a line is @samp{@@}, @code{etags} assumes that the rest of -the line is the name of a file of regular expressions. This means that -such files can be nested. All the other lines are taken to be regular -expressions. For example, one can create a file called -@samp{emacs.tags} with the following contents (the first line in the -file is a comment): - -@smallexample - -- This is for GNU Emacs source files -@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ -@end smallexample - -@noindent -and then use it like this: - -@smallexample -etags --regex=@@emacs.tags *.[ch] */*.[ch] -@end smallexample - - Here are some more examples. The regexps are quoted to protect them -from shell interpretation. - -@itemize @bullet - -@item -Tag Octave files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ - --regex='/###key \(.*\)/\1/' \ - --regex='/[ \t]*global[ \t].*/' \ - *.m -@end smallexample - -@noindent -Note that tags are not generated for scripts so that you have to add a -line by yourself of the form `###key ' if you want to jump -to it. - -@item -Tag Tcl files: - -@smallexample -etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl -@end smallexample - -@item -Tag VHDL files: - -@smallexample ---language=none \ ---regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ ---regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ -\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' -@end smallexample -@end itemize - -@node Select Tags Table -@subsection Selecting a Tags Table - -@vindex tags-file-name -@findex visit-tags-table - Emacs has at any time one @dfn{selected} tags table, and all the commands -for working with tags tables use the selected one. To select a tags table, -type @kbd{M-x visit-tags-table}, which reads the tags table file name as an -argument. The name @file{TAGS} in the default directory is used as the -default file name. - - All this command does is store the file name in the variable -@code{tags-file-name}. Emacs does not actually read in the tags table -contents until you try to use them. Setting this variable yourself is just -as good as using @code{visit-tags-table}. The variable's initial value is -@code{nil}; that value tells all the commands for working with tags tables -that they must ask for a tags table file name to use. - - Using @code{visit-tags-table} when a tags table is already loaded -gives you a choice: you can add the new tags table to the current list -of tags tables, or start a new list. The tags commands use all the tags -tables in the current list. If you start a new list, the new tags table -is used @emph{instead} of others. If you add the new table to the -current list, it is used @emph{as well as} the others. When the tags -commands scan the list of tags tables, they don't always start at the -beginning of the list; they start with the first tags table (if any) -that describes the current file, proceed from there to the end of the -list, and then scan from the beginning of the list until they have -covered all the tables in the list. - -@vindex tags-table-list - You can specify a precise list of tags tables by setting the variable -@code{tags-table-list} to a list of strings, like this: - -@c keep this on two lines for formatting in smallbook -@example -@group -(setq tags-table-list - '("~/emacs" "/usr/local/lib/emacs/src")) -@end group -@end example - -@noindent -This tells the tags commands to look at the @file{TAGS} files in your -@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} -directory. The order depends on which file you are in and which tags -table mentions that file, as explained above. - - Do not set both @code{tags-file-name} and @code{tags-table-list}. - -@node Find Tag -@subsection Finding a Tag - - The most important thing that a tags table enables you to do is to find -the definition of a specific tag. - -@table @kbd -@item M-.@: @var{tag} @key{RET} -Find first definition of @var{tag} (@code{find-tag}). -@item C-u M-. -Find next alternate definition of last tag specified. -@item C-u - M-. -Go back to previous tag found. -@item C-M-. @var{pattern} @key{RET} -Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). -@item C-u C-M-. -Find the next tag whose name matches the last pattern used. -@item C-x 4 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, but display it in another window -(@code{find-tag-other-window}). -@item C-x 5 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, and create a new frame to select the -buffer (@code{find-tag-other-frame}). -@item M-* -Pop back to where you previously invoked @kbd{M-.} and friends. -@end table - -@kindex M-. -@findex find-tag - @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of -a specified tag. It searches through the tags table for that tag, as a -string, and then uses the tags table info to determine the file that the -definition is in and the approximate character position in the file of -the definition. Then @code{find-tag} visits that file, moves point to -the approximate character position, and searches ever-increasing -distances away to find the tag definition. - - If an empty argument is given (just type @key{RET}), the sexp in the -buffer before or around point is used as the @var{tag} argument. -@xref{Lists}, for info on sexps. - - You don't need to give @kbd{M-.} the full name of the tag; a part -will do. This is because @kbd{M-.} finds tags in the table which -contain @var{tag} as a substring. However, it prefers an exact match -to a substring match. To find other tags that match the same -substring, give @code{find-tag} a numeric argument, as in @kbd{C-u -M-.}; this does not read a tag name, but continues searching the tags -table's text for another tag containing the same substring last used. -If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier -alternative to @kbd{C-u M-.}. - -@kindex C-x 4 . -@findex find-tag-other-window -@kindex C-x 5 . -@findex find-tag-other-frame - Like most commands that can switch buffers, @code{find-tag} has a -variant that displays the new buffer in another window, and one that -makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes -the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .}, -which invokes @code{find-tag-other-frame}. - - To move back to places you've found tags recently, use @kbd{C-u - -M-.}; more generally, @kbd{M-.} with a negative numeric argument. This -command can take you to another buffer. @kbd{C-x 4 .} with a negative -argument finds the previous tag location in another window. - -@kindex M-* -@findex pop-tag-mark -@vindex find-tag-marker-ring-length - As well as going back to places you've found tags recently, you can go -back to places @emph{from where} you found them. Use @kbd{M-*}, which -invokes the command @code{pop-tag-mark}, for this. Typically you would -find and study the definition of something with @kbd{M-.} and then -return to where you were with @kbd{M-*}. - - Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to -a depth determined by the variable @code{find-tag-marker-ring-length}. - -@findex find-tag-regexp -@kindex C-M-. - The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that -match a specified regular expression. It is just like @kbd{M-.} except -that it does regexp matching instead of substring matching. - -@node Tags Search -@subsection Searching and Replacing with Tags Tables -@cindex search and replace in several program files -@cindex multiple-file search and replace (with tag tables) - - The commands in this section visit and search all the files listed in the -selected tags table, one by one. For these commands, the tags table serves -only to specify a sequence of files to search. - -@table @kbd -@item M-x tags-search @key{RET} @var{regexp} @key{RET} -Search for @var{regexp} through the files in the selected tags -table. -@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} -Perform a @code{query-replace-regexp} on each file in the selected tags table. -@item M-, -Restart one of the commands above, from the current location of point -(@code{tags-loop-continue}). -@end table - -@findex tags-search - @kbd{M-x tags-search} reads a regexp using the minibuffer, then -searches for matches in all the files in the selected tags table, one -file at a time. It displays the name of the file being searched so you -can follow its progress. As soon as it finds an occurrence, -@code{tags-search} returns. - -@kindex M-, -@findex tags-loop-continue - Having found one match, you probably want to find all the rest. To find -one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the -@code{tags-search}. This searches the rest of the current buffer, followed -by the remaining files of the tags table.@refill - -@findex tags-query-replace - @kbd{M-x tags-query-replace} performs a single -@code{query-replace-regexp} through all the files in the tags table. It -reads a regexp to search for and a string to replace with, just like -ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x -tags-search}, but repeatedly, processing matches according to your -input. @xref{Replace}, for more information on query replace. - -@vindex tags-case-fold-search -@cindex case-sensitivity, and tags search - You can control the case-sensitivity of tags search commands by -customizing the value of the variable @code{tags-case-fold-search}. The -default is to use the same setting as the value of -@code{case-fold-search} (@pxref{Search Case}). - - It is possible to get through all the files in the tags table with a -single invocation of @kbd{M-x tags-query-replace}. But often it is -useful to exit temporarily, which you can do with any input event that -has no special query replace meaning. You can resume the query replace -subsequently by typing @kbd{M-,}; this command resumes the last tags -search or replace command that you did. - - The commands in this section carry out much broader searches than the -@code{find-tag} family. The @code{find-tag} commands search only for -definitions of tags that match your substring or regexp. The commands -@code{tags-search} and @code{tags-query-replace} find every occurrence -of the regexp, as ordinary search commands and replace commands do in -the current buffer. - - These commands create buffers only temporarily for the files that they -have to search (those which are not already visited in Emacs buffers). -Buffers in which no match is found are quickly killed; the others -continue to exist. - - It may have struck you that @code{tags-search} is a lot like -@code{grep}. You can also run @code{grep} itself as an inferior of -Emacs and have Emacs show you the matching lines one by one. This works -much like running a compilation; finding the source locations of the -@code{grep} matches works like finding the compilation errors. -@xref{Compilation}. - -@node List Tags -@subsection Tags Table Inquiries - -@table @kbd -@item M-x list-tags @key{RET} @var{file} @key{RET} -Display a list of the tags defined in the program file @var{file}. -@item M-x tags-apropos @key{RET} @var{regexp} @key{RET} -Display a list of all tags matching @var{regexp}. -@end table - -@findex list-tags - @kbd{M-x list-tags} reads the name of one of the files described by -the selected tags table, and displays a list of all the tags defined in -that file. The ``file name'' argument is really just a string to -compare against the file names recorded in the tags table; it is read as -a string rather than as a file name. Therefore, completion and -defaulting are not available, and you must enter the file name the same -way it appears in the tags table. Do not include a directory as part of -the file name unless the file name recorded in the tags table includes a -directory. - -@findex tags-apropos - @kbd{M-x tags-apropos} is like @code{apropos} for tags -(@pxref{Apropos}). It reads a regexp, then finds all the tags in the -selected tags table whose entries match that regexp, and displays the -tag names found. -@vindex tags-apropos-additional-actions -You can display additional output with @kbd{M-x tags-apropos} by customizing -the variable @code{tags-apropos-additional-actions}. See its -documentation for details. -@vindex tags-apropos-verbose -Setting the variable @code{tags-apropos-verbose} to a non-nil value -causes @kbd{M-x tags-apropos} to display the names of the tags files -together with the tag names. -@vindex tags-tag-face -The face @code{tags-tag-face} can be used to customize the appearance of -tags in the output of @kbd{M-x tags-apropos}. - - You can also perform completion in the buffer on the name space of tag -names in the current tags tables. @xref{Symbol Completion}. - -@node Imenu -@section Imenu -@cindex indexes of buffer contents -@cindex buffer content indexes -@cindex tags - -The Imenu facility provides mode-specific indexes of the contents of -single buffers and provides selection from a menu. Selecting a menu -item takes you to the indexed point in the buffer, in a similar way to -the Tags facility. Indexing is typically by names of program routines -and variables but in Texinfo mode, for instance, node names are indexed. -Most major modes for which it is appropriate have Imenu support. +expression that is the value of the variable @code{comment-start-skip}. +Make sure this regexp does not match the null string. It may match more +than the comment starting delimiter in the strictest sense of the word; +for example, in C mode the value of the variable is +@c This stops M-q from breaking the line inside that @code. +@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces +after the @samp{/*} itself, and accepts C++ style comments also. +(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in +the string, which is needed to deny the first star its special meaning +in regexp syntax. @xref{Regexp Backslash}.) -@findex imenu -@findex imenu-add-menu-bar-index -@kbd{M-x imenu} builds the index if necessary and presents you with an -electric buffer menu from which to select an entry (with completion). -If you bind @code{imenu} to a mouse event (@pxref{Mouse Buttons}) and -invoke it that way, the index will appear as a popup menu; there is no -such binding by default. You can add an index menubar on the menubar -with @kbd{imenu-add-menu-bar-index}. - -Some major modes provide facilities for invoking Imenu; otherwise you -could add @code{imenu-add-menu-bar-index} to a major mode's hook to -generate an index for each buffer created in that mode. (If you do -that, it takes some time to generate the index when finding a file, -depending on the file's size and the complexity of the indexing function -for that mode.) +@vindex comment-start +@vindex comment-end + When a comment command makes a new comment, it inserts the value of +@code{comment-start} to begin it. The value of @code{comment-end} is +inserted after point, so that it will follow the text that you will +insert into the comment. When @code{comment-end} is non-empty, it +should start with a space. For example, in C mode, +@code{comment-start} has the value @w{@code{"/* "}} and +@code{comment-end} has the value @w{@code{" */"}}. -@vindex imenu-auto-rescan -The index should be regenerated (via the @samp{*Rescan*} menu item) when -indexable items are added to or deleted from the buffer. Rescanning is -done when a menu selction is requested if the option -@code{imenu-auto-rescan} is set. By default buffer positions are in -terms of markers, so that changing non-indexable text doesn't require -rescanning. +@vindex comment-padding + The variable @code{comment-padding} specifies how many spaces +@code{comment-region} should insert on each line between the comment +delimiter and the line's original text. The default is 1, to insert +one space. @code{nil} means 0. Alternatively, @code{comment-padding} +can hold the actual string to insert. -@vindex imenu-sort-function -The way the menus are sorted can be customized via the option -@code{imenu-sort-function}. By default names are ordered as they occur -in the buffer; alphabetic sorting is provided as an alternative. +@vindex comment-multi-line + The variable @code{comment-multi-line} controls how @kbd{C-M-j} +(@code{indent-new-comment-line}) behaves when used inside a comment. +Specifically, when @code{comment-multi-line} is @code{nil}, the +command inserts a comment terminator, begins a new line, and finally +inserts a comment starter. Otherwise it does not insert the +terminator and starter, so it effectively continues the current +comment across multiple lines. In languages that allow multi-line +comments, the choice of value for this variable is a matter of taste. +The default for this variable depends on the major mode. -Imenu provides the information used by Which Function mode (@pxref{Which -Function}). It may also be used by Speedbar (@pxref{Speedbar}). +@vindex comment-indent-function + The variable @code{comment-indent-function} should contain a function +that will be called to compute the alignment for a newly inserted +comment or for aligning an existing comment. It is set differently by +various major modes. The function is called with no arguments, but with +point at the beginning of the comment, or at the end of a line if a new +comment is to be inserted. It should return the column in which the +comment ought to start. For example, in Lisp mode, the indent hook +function bases its decision on how many semicolons begin an existing +comment, and on the code in the preceding lines. -@node Emerge, C Modes, Imenu, Programs -@section Merging Files with Emerge -@cindex Emerge -@cindex merging files +@node Documentation +@section Documentation Lookup -It's not unusual for programmers to get their signals crossed and modify -the same program in two different directions. To recover from this -confusion, you need to merge the two versions. Emerge makes this -easier. See also @ref{Comparing Files}, for commands to compare -in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}. + Emacs provides several features you can use to look up the +documentation of functions, variables and commands that you plan to +use in your program. @menu -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Misc. +* Info Lookup:: Looking up library functions and commands + in Info files. +* Man Page:: Looking up man pages of library functions and commands. +* Lisp Doc:: Looking up Emacs Lisp functions, etc. @end menu -@node Overview of Emerge -@subsection Overview of Emerge - -To start Emerge, run one of these four commands: - -@table @kbd -@item M-x emerge-files -@findex emerge-files -Merge two specified files. - -@item M-x emerge-files-with-ancestor -@findex emerge-files-with-ancestor -Merge two specified files, with reference to a common ancestor. - -@item M-x emerge-buffers -@findex emerge-buffers -Merge two buffers. - -@item M-x emerge-buffers-with-ancestor -@findex emerge-buffers-with-ancestor -Merge two buffers with reference to a common ancestor in a third -buffer. -@end table - -@cindex merge buffer (Emerge) -@cindex A and B buffers (Emerge) - The Emerge commands compare two files or buffers, and display the -comparison in three buffers: one for each input text (the @dfn{A buffer} -and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging -takes place. The merge buffer shows the full merged text, not just the -differences. Wherever the two input texts differ, you can choose which -one of them to include in the merge buffer. - - The Emerge commands that take input from existing buffers use only the -accessible portions of those buffers, if they are narrowed -(@pxref{Narrowing}). - - If a common ancestor version is available, from which the two texts to -be merged were both derived, Emerge can use it to guess which -alternative is right. Wherever one current version agrees with the -ancestor, Emerge presumes that the other current version is a deliberate -change which should be kept in the merged version. Use the -@samp{with-ancestor} commands if you want to specify a common ancestor -text. These commands read three file or buffer names---variant A, -variant B, and the common ancestor. - - After the comparison is done and the buffers are prepared, the -interactive merging starts. You control the merging by typing special -@dfn{merge commands} in the merge buffer. The merge buffer shows you a -full merged text, not just differences. For each run of differences -between the input texts, you can choose which one of them to keep, or -edit them both together. - - The merge buffer uses a special major mode, Emerge mode, with commands -for making these choices. But you can also edit the buffer with -ordinary Emacs commands. - - At any given time, the attention of Emerge is focused on one -particular difference, called the @dfn{selected} difference. This -difference is marked off in the three buffers like this: - -@example -vvvvvvvvvvvvvvvvvvvv -@var{text that differs} -^^^^^^^^^^^^^^^^^^^^ -@end example - -@noindent -Emerge numbers all the differences sequentially and the mode -line always shows the number of the selected difference. - - Normally, the merge buffer starts out with the A version of the text. -But when the A version of a difference agrees with the common ancestor, -then the B version is initially preferred for that difference. - - Emerge leaves the merged text in the merge buffer when you exit. At -that point, you can save it in a file with @kbd{C-x C-w}. If you give a -numeric argument to @code{emerge-files} or -@code{emerge-files-with-ancestor}, it reads the name of the output file -using the minibuffer. (This is the last file name those commands read.) -Then exiting from Emerge saves the merged text in the output file. - - Normally, Emerge commands save the output buffer in its file when you -exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not -save the output buffer, but you can save it yourself if you wish. - -@node Submodes of Emerge -@subsection Submodes of Emerge - - You can choose between two modes for giving merge commands: Fast mode -and Edit mode. In Fast mode, basic merge commands are single -characters, but ordinary Emacs commands are disabled. This is -convenient if you use only merge commands. In Edit mode, all merge -commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs -commands are also available. This allows editing the merge buffer, but -slows down Emerge operations. - - Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to -Fast mode. The mode line indicates Edit and Fast modes with @samp{E} -and @samp{F}. - - Emerge has two additional submodes that affect how particular merge -commands work: Auto Advance mode and Skip Prefers mode. - - If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands -advance to the next difference. This lets you go through the merge -faster as long as you simply choose one of the alternatives from the -input. The mode line indicates Auto Advance mode with @samp{A}. - - If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands -skip over differences in states prefer-A and prefer-B (@pxref{State of -Difference}). Thus you see only differences for which neither version -is presumed ``correct.'' The mode line indicates Skip Prefers mode with -@samp{S}. - -@findex emerge-auto-advance-mode -@findex emerge-skip-prefers-mode - Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or -clear Auto Advance mode. Use @kbd{s s} -(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. -These commands turn on the mode with a positive argument, turns it off -with a negative or zero argument, and toggle the mode with no argument. - -@node State of Difference -@subsection State of a Difference - - In the merge buffer, a difference is marked with lines of @samp{v} and -@samp{^} characters. Each difference has one of these seven states: - -@table @asis -@item A -The difference is showing the A version. The @kbd{a} command always -produces this state; the mode line indicates it with @samp{A}. - -@item B -The difference is showing the B version. The @kbd{b} command always -produces this state; the mode line indicates it with @samp{B}. - -@item default-A -@itemx default-B -The difference is showing the A or the B state by default, because you -haven't made a choice. All differences start in the default-A state -(and thus the merge buffer is a copy of the A buffer), except those for -which one alternative is ``preferred'' (see below). - -When you select a difference, its state changes from default-A or -default-B to plain A or B. Thus, the selected difference never has -state default-A or default-B, and these states are never displayed in -the mode line. - -The command @kbd{d a} chooses default-A as the default state, and @kbd{d -b} chooses default-B. This chosen default applies to all differences -which you haven't ever selected and for which no alternative is preferred. -If you are moving through the merge sequentially, the differences you -haven't selected are those following the selected one. Thus, while -moving sequentially, you can effectively make the A version the default -for some sections of the merge buffer and the B version the default for -others by using @kbd{d a} and @kbd{d b} between sections. - -@item prefer-A -@itemx prefer-B -The difference is showing the A or B state because it is -@dfn{preferred}. This means that you haven't made an explicit choice, -but one alternative seems likely to be right because the other -alternative agrees with the common ancestor. Thus, where the A buffer -agrees with the common ancestor, the B version is preferred, because -chances are it is the one that was actually changed. - -These two states are displayed in the mode line as @samp{A*} and @samp{B*}. - -@item combined -The difference is showing a combination of the A and B states, as a -result of the @kbd{x c} or @kbd{x C} commands. - -Once a difference is in this state, the @kbd{a} and @kbd{b} commands -don't do anything to it unless you give them a numeric argument. - -The mode line displays this state as @samp{comb}. -@end table - -@node Merge Commands -@subsection Merge Commands - - Here are the Merge commands for Fast mode; in Edit mode, precede them -with @kbd{C-c C-c}: - -@table @kbd -@item p -Select the previous difference. - -@item n -Select the next difference. +@node Info Lookup +@subsection Info Documentation Lookup -@item a -Choose the A version of this difference. - -@item b -Choose the B version of this difference. - -@item C-u @var{n} j -Select difference number @var{n}. - -@item . -Select the difference containing point. You can use this command in the -merge buffer or in the A or B buffer. - -@item q -Quit---finish the merge. - -@item C-] -Abort---exit merging and do not save the output. - -@item f -Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) - -@item e -Go into Edit mode. - -@item l -Recenter (like @kbd{C-l}) all three windows. - -@item - -Specify part of a prefix numeric argument. - -@item @var{digit} -Also specify part of a prefix numeric argument. - -@item d a -Choose the A version as the default from here down in -the merge buffer. - -@item d b -Choose the B version as the default from here down in -the merge buffer. - -@item c a -Copy the A version of this difference into the kill ring. +@findex info-lookup-symbol +@findex info-lookup-file +@kindex C-h S + For many major modes, that apply to languages that have +documentation in Info, you can use @kbd{C-h S} +(@code{info-lookup-symbol}) to view the Info documentation for a +symbol used in the program. You specify the symbol with the +minibuffer; the default is the symbol appearing in the buffer at +point. For example, in C mode this looks for the symbol in the C +Library Manual. The command only works if the appropriate manual's +Info files are installed. + + The major mode determines where to look for documentation for the +symbol---which Info files to look in, and which indices to search. +You can also use @kbd{M-x info-lookup-file} to look for documentation +for a file name. + + If you use @kbd{C-h S} in a major mode that does not support it, +it asks you to specify the ``symbol help mode''. You should enter +a command such as @code{c-mode} that would select a major +mode which @kbd{C-h S} does support. + +@node Man Page +@subsection Man Page Lookup + +@cindex manual page + On Unix, the main form of on-line documentation was the @dfn{manual +page} or @dfn{man page}. In the GNU operating system, we aim to +replace man pages with better-organized manuals that you can browse +with Info (@pxref{Misc Help}). This process is not finished, so it is +still useful to read manual pages. -@item c b -Copy the B version of this difference into the kill ring. +@findex manual-entry + You can read the man page for an operating system command, library +function, or system call, with the @kbd{M-x man} command. It +runs the @code{man} program to format the man page; if the system +permits, it runs @code{man} asynchronously, so that you can keep on +editing while the page is being formatted. (On MS-DOS and MS-Windows +3, you cannot edit while Emacs waits for @code{man} to finish.) The +result goes in a buffer named @samp{*Man @var{topic}*}. These buffers +use a special major mode, Man mode, that facilitates scrolling and +jumping to other manual pages. For details, type @kbd{C-h m} while in +a man page buffer. -@item i a -Insert the A version of this difference at point. +@cindex sections of manual pages + Each man page belongs to one of ten or more @dfn{sections}, each +named by a digit or by a digit and a letter. Sometimes there are +multiple man pages with the same name in different sections. To read +a man page from a specific section, type +@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} +when @kbd{M-x manual-entry} prompts for the topic. For example, to +read the man page for the C library function @code{chmod} (as opposed +to a command of the same name), type @kbd{M-x manual-entry @key{RET} +chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in +section @samp{2}.) + +@vindex Man-switches + If you do not specify a section, the results depend on how the +@code{man} program works on your system. Some of them display only +the first man page they find. Others display all man pages that have +the specified name, so you can move between them with the @kbd{M-n} +and @kbd{M-p} keys@footnote{On some systems, the @code{man} program +accepts a @samp{-a} command-line option which tells it to display all +the man pages for the specified topic. If you want this behavior, you +can add this option to the value of the variable @code{Man-switches}.}. +The mode line shows how many manual pages are present in the Man buffer. -@item i b -Insert the B version of this difference at point. +@vindex Man-fontify-manpage-flag + By default, Emacs highlights the text in man pages. For a long man +page, highlighting can take substantial time. You can turn off +highlighting of man pages by setting the variable +@code{Man-fontify-manpage-flag} to @code{nil}. -@item m -Put point and mark around the difference. +@findex Man-fontify-manpage + If you insert the text of a man page into an Emacs buffer in some +other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to +perform the same conversions that @kbd{M-x manual-entry} does. -@item ^ -Scroll all three windows down (like @kbd{M-v}). +@findex woman +@cindex manual pages, on MS-DOS/MS-Windows + An alternative way of reading manual pages is the @kbd{M-x woman} +command@footnote{The name of the command, @code{woman}, is an acronym +for ``w/o (without) man,'' since it doesn't use the @code{man} +program.}. Unlike @kbd{M-x man}, it does not run any external +programs to format and display the man pages; instead it does the job +in Emacs Lisp, so it works on systems such as MS-Windows, where the +@code{man} program (and other programs it uses) are not generally +available. + + @kbd{M-x woman} prompts for a name of a manual page, and provides +completion based on the list of manual pages that are installed on +your machine; the list of available manual pages is computed +automatically the first time you invoke @code{woman}. The word at +point in the current buffer is used to suggest the default for the +name the manual page. -@item v -Scroll all three windows up (like @kbd{C-v}). + With a numeric argument, @kbd{M-x woman} recomputes the list of the +manual pages used for completion. This is useful if you add or delete +manual pages. -@item < -Scroll all three windows left (like @kbd{C-x <}). + If you type a name of a manual page and @kbd{M-x woman} finds that +several manual pages by the same name exist in different sections, it +pops up a window with possible candidates asking you to choose one of +them. -@item > -Scroll all three windows right (like @kbd{C-x >}). + For more information about setting up and using @kbd{M-x woman}, see +@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan +Manual}. -@item | -Reset horizontal scroll on all three windows. +@node Lisp Doc +@subsection Emacs Lisp Documentation Lookup -@item x 1 -Shrink the merge window to one line. (Use @kbd{C-u l} to restore it -to full size.) + As you edit Lisp code to be run in Emacs, you can use the commands +@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} +(@code{describe-variable}) to view documentation of functions and +variables that you want to use. These commands use the minibuffer to +read the name of a function or variable to document, and display the +documentation in a window. Their default arguments are based on the +code in the neighborhood of point. For @kbd{C-h f}, the default is +the function called in the innermost list containing point. @kbd{C-h +v} uses the symbol name around or adjacent to point as its default. -@item x c -Combine the two versions of this difference (@pxref{Combining in -Emerge}). +@cindex Eldoc mode +@findex eldoc-mode + A more automatic but less powerful method is Eldoc mode. This minor +mode constantly displays in the echo area the argument list for the +function being called at point. (In other words, it finds the +function call that point is contained in, and displays the argument +list of that function.) If point is over a documented variable, it +shows the first line of the variable's docstring. Eldoc mode applies +in Emacs Lisp and Lisp Interaction modes, and perhaps a few others +that provide special support for looking up doc strings. Use the +command @kbd{M-x eldoc-mode} to enable or disable this feature. -@item x f -Show the names of the files/buffers Emerge is operating on, in a Help -window. (Use @kbd{C-u l} to restore windows.) +@node Hideshow +@section Hideshow minor mode -@item x j -Join this difference with the following one. -(@kbd{C-u x j} joins this difference with the previous one.) +@findex hs-minor-mode + Hideshow minor mode provides selective display of portions of a +program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} +to enable or disable this mode, or add @code{hs-minor-mode} to the +mode hook for certain major modes in order to enable it automatically +for those modes. -@item x s -Split this difference into two differences. Before you use this -command, position point in each of the three buffers at the place where -you want to split the difference. + Just what constitutes a block depends on the major mode. In C mode +or C++ mode, they are delimited by braces, while in Lisp mode and +similar modes they are delimited by parentheses. Multi-line comments +also count as blocks. -@item x t -Trim identical lines off the top and bottom of the difference. -Such lines occur when the A and B versions are -identical but differ from the ancestor version. +@findex hs-hide-all +@findex hs-hide-block +@findex hs-show-all +@findex hs-show-block +@findex hs-show-region +@findex hs-hide-level +@findex hs-minor-mode +@kindex C-c @@ C-h +@kindex C-c @@ C-s +@kindex C-c @@ C-M-h +@kindex C-c @@ C-M-s +@kindex C-c @@ C-r +@kindex C-c @@ C-l +@kindex S-Mouse-2 +@table @kbd +@item C-c @@ C-h +Hide the current block (@code{hs-hide-block}). +@item C-c @@ C-s +Show the current block (@code{hs-show-block}). +@item C-c @@ C-c +Either hide or show the current block (@code{hs-toggle-hiding}). +@item S-Mouse-2 +Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). +@item C-c @@ C-M-h +Hide all top-level blocks (@code{hs-hide-all}). +@item C-c @@ C-M-s +Show everything in the buffer (@code{hs-show-all}). +@item C-c @@ C-l +Hide all blocks @var{n} levels below this block +(@code{hs-hide-level}). @end table -@node Exiting Emerge -@subsection Exiting Emerge +@vindex hs-hide-comments-when-hiding-all +@vindex hs-isearch-open +@vindex hs-special-modes-alist + These variables exist for customizing Hideshow mode. - The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing -the results into the output file if you specified one. It restores the -A and B buffers to their proper contents, or kills them if they were -created by Emerge and you haven't changed them. It also disables the -Emerge commands in the merge buffer, since executing them later could -damage the contents of the various buffers. +@table @code +@item hs-hide-comments-when-hiding-all +Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. - @kbd{C-]} aborts the merge. This means exiting without writing the -output file. If you didn't specify an output file, then there is no -real difference between aborting and finishing the merge. +@item hs-isearch-open +Specifies what kind of hidden blocks incremental search should make +visible. The value should be one of these four symbols: - If the Emerge command was called from another Lisp program, then its -return value is @code{t} for successful completion, or @code{nil} if you -abort. +@table @code +@item code +Open only code blocks. +@item comment +Open only comments. +@item t +Open both code blocks and comments. +@item nil +Open neither code blocks nor comments. +@end table -@node Combining in Emerge -@subsection Combining the Two Versions +@item hs-special-modes-alist +A list of elements, each specifying how to initialize Hideshow +variables for one major mode. See the variable's documentation string +for more information. +@end table - Sometimes you want to keep @emph{both} alternatives for a particular -difference. To do this, use @kbd{x c}, which edits the merge buffer -like this: +@node Symbol Completion +@section Completion for Symbol Names +@cindex completion (symbol names) -@example -@group -#ifdef NEW -@var{version from A buffer} -#else /* not NEW */ -@var{version from B buffer} -#endif /* not NEW */ -@end group -@end example + In Emacs, completion is something you normally do in the minibuffer. +But one kind of completion is available in all buffers: completion for +symbol names. -@noindent -@vindex emerge-combine-versions-template -While this example shows C preprocessor conditionals delimiting the two -alternative versions, you can specify the strings to use by setting -the variable @code{emerge-combine-versions-template} to a string of your -choice. In the string, @samp{%a} says where to put version A, and -@samp{%b} says where to put version B. The default setting, which -produces the results shown above, looks like this: +@kindex M-TAB + The character @kbd{M-@key{TAB}} runs a command to complete the +partial symbol before point against the set of meaningful symbol +names. This command inserts at point any additional characters that +it can determine from the partial name. (If your window manager +defines @kbd{M-@key{TAB}} to switch windows, you can type +@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) + + If the partial name in the buffer has multiple possible completions +that differ in the very next character, so that it is impossible to +complete even one more character, @kbd{M-@key{TAB}} displays a list of +all possible completions in another window. + +@cindex tags-based completion +@cindex Info index completion +@findex complete-symbol + In most programming language major modes, @kbd{M-@key{TAB}} runs the +command @code{complete-symbol}, which provides two kinds of completion. +Normally it does completion based on a tags table (@pxref{Tags}); with a +numeric argument (regardless of the value), it does completion based on +the names listed in the Info file indexes for your language. Thus, to +complete the name of a symbol defined in your own program, use +@kbd{M-@key{TAB}} with no argument; to complete the name of a standard +library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based +completion works only if there is an Info file for the standard library +functions of your language, and only if it is installed at your site. -@example -@group -"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" -@end group -@end example +@cindex Lisp symbol completion +@cindex completion (Lisp symbols) +@findex lisp-complete-symbol + In Emacs-Lisp mode, the name space for completion normally consists of +nontrivial symbols present in Emacs---those that have function +definitions, values or properties. However, if there is an +open-parenthesis immediately before the beginning of the partial symbol, +only symbols with function definitions are considered as completions. +The command which implements this is @code{lisp-complete-symbol}. -@node Fine Points of Emerge -@subsection Fine Points of Emerge + In Text mode and related modes, @kbd{M-@key{TAB}} completes words +based on the spell-checker's dictionary. @xref{Spelling}. - During the merge, you mustn't try to edit the A and B buffers yourself. -Emerge modifies them temporarily, but ultimately puts them back the way -they were. +@node Glasses +@section Glasses minor mode +@cindex Glasses mode +@cindex identifiers, making long ones readable +@cindex StudlyCaps, making them readable +@findex glasses-mode - You can have any number of merges going at once---just don't use any one -buffer as input to more than one merge at once, since the temporary -changes made in these buffers would get in each other's way. + Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} +readable by altering the way they display. It knows two different +ways to do this: by displaying underscores between a lower-case letter +and the following capital letter, and by emboldening the capital +letters. It does not alter the buffer text, only the way they +display, so you can use it even on read-only buffers. You can use the +command @kbd{M-x glasses-mode} to enable or disable the mode in the +current buffer; you can also add @code{glasses-mode} to the mode hook +of the programming language major modes in which you normally want +to use Glasses mode. + +@node Misc for Programs +@section Other Features Useful for Editing Programs + + A number of Emacs commands that aren't designed specifically for +editing programs are useful for that nonetheless. + + The Emacs commands that operate on words, sentences and paragraphs +are useful for editing code. Most symbols names contain words +(@pxref{Words}); sentences can be found in strings and comments +(@pxref{Sentences}). Paragraphs in the strict sense can be found in +program code (in long comments), but the paragraph commands are useful +in other places too, because programming language major modes define +paragraphs to begin and end at blank lines (@pxref{Paragraphs}). +Judicious use of blank lines to make the program clearer will also +provide useful chunks of text for the paragraph commands to work on. +Auto Fill mode, if enabled in a programming language major mode, +indents the new lines which it creates. - Starting Emerge can take a long time because it needs to compare the -files fully. Emacs can't do anything else until @code{diff} finishes. -Perhaps in the future someone will change Emerge to do the comparison in -the background when the input files are large---then you could keep on -doing other things with Emacs until Emerge is ready to accept -commands. + The selective display feature is useful for looking at the overall +structure of a function (@pxref{Selective Display}). This feature +hides the lines that are indented more than a specified amount. +Programming modes often support Outline minor mode (@pxref{Outline +Mode}). The Foldout package provides folding-editor features +(@pxref{Foldout}). -@vindex emerge-startup-hook - After setting up the merge, Emerge runs the hook -@code{emerge-startup-hook} (@pxref{Hooks}). + The ``automatic typing'' features may be useful for writing programs. +@xref{Top,,Autotyping, autotype, Autotyping}. @node C Modes @section C and Related Modes @@ -2970,25 +1412,27 @@ commands. @cindex CORBA IDL mode @cindex Objective C mode @cindex C++ mode +@cindex AWK mode @cindex mode, Java @cindex mode, C +@cindex mode, C++ @cindex mode, Objective C @cindex mode, CORBA IDL @cindex mode, Pike +@cindex mode, AWK - This section describes special features available in C, C++, -Objective-C, Java, CORBA IDL, and Pike modes. When we say ``C mode and -related modes,'' those are the modes we mean. - -Additional information is available in the separate manual for these -modes. @xref{Top, CC Mode, ccmode, , CC Mode}. + This section gives a brief description of the special features +available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. +(These are called ``C mode and related modes.'') @xref{Top, , CC Mode, +ccmode, CC Mode}, for a more extensive description of these modes +and their special features. @menu -* Motion in C:: -* Electric C:: -* Hungry Delete:: -* Other C Commands:: -* Comments in C:: +* Motion in C:: Commands to move by C statements, etc. +* Electric C:: Colon and other chars can automatically reindent. +* Hungry Delete:: A more powerful DEL command. +* Other C Commands:: Filling comments, viewing expansion of macros, + and other neat features. @end menu @node Motion in C @@ -2998,15 +1442,29 @@ modes. @xref{Top, CC Mode, ccmode, , CC Mode}. related modes. @table @code +@item M-x c-beginning-of-defun +@itemx M-x c-end-of-defun +@findex c-beginning-of-defun +@findex c-end-of-defun +Move point to the beginning or end of the current function or +top-level definition. These are found by searching for the least +enclosing braces. (By contrast, @code{beginning-of-defun} and +@code{end-of-defun} search for braces in column zero.) If you are +editing code where the opening brace of a function isn't placed in +column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to +these commands. @xref{Moving by Defuns}. + @item C-c C-u @kindex C-c C-u @r{(C mode)} @findex c-up-conditional Move point back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point forward to the end of the containing -preprocessor conditional. When going backwards, @code{#elif} is treated -like @code{#else} followed by @code{#if}. When going forwards, -@code{#elif} is ignored.@refill +preprocessor conditional. + +@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so +the function will stop at a @samp{#elif} when going backward, but not +when going forward. @item C-c C-p @kindex C-c C-p @r{(C mode)} @@ -3023,185 +1481,112 @@ behind. A prefix argument acts as a repeat count. With a negative argument, move backward. @item M-a -@kindex ESC a +@kindex M-a (C mode) @findex c-beginning-of-statement Move point to the beginning of the innermost C statement (@code{c-beginning-of-statement}). If point is already at the beginning of a statement, move to the beginning of the preceding statement. With prefix argument @var{n}, move back @var{n} @minus{} 1 statements. -If point is within a string or comment, or next to a comment (only -whitespace between them), this command moves by sentences instead of -statements. - -When called from a program, this function takes three optional -arguments: the numeric prefix argument, a buffer position limit -(don't move back before that place), and a flag that controls whether -to do sentence motion when inside of a comment. +In comments or in strings which span more than one line, this command +moves by sentences instead of statements. @item M-e -@kindex ESC e +@kindex M-e (C mode) @findex c-end-of-statement -Move point to the end of the innermost C statement; like @kbd{M-a} -except that it moves in the other direction (@code{c-end-of-statement}). - -@item M-x c-backward-into-nomenclature -@findex c-backward-into-nomenclature -Move point backward to beginning of a C++ nomenclature section or word. -With prefix argument @var{n}, move @var{n} times. If @var{n} is -negative, move forward. C++ nomenclature means a symbol name in the -style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter -begins a section or word. - -In the GNU project, we recommend using underscores to separate words -within an identifier in C or C++, rather than using case distinctions. - -@item M-x c-forward-into-nomenclature -@findex c-forward-into-nomenclature -Move point forward to end of a C++ nomenclature section or word. -With prefix argument @var{n}, move @var{n} times. +Move point to the end of the innermost C statement or sentence; like +@kbd{M-a} except that it moves in the other direction +(@code{c-end-of-statement}). @end table @node Electric C @subsection Electric C Characters In C mode and related modes, certain printing characters are -``electric''---in addition to inserting themselves, they also reindent -the current line and may insert newlines. This feature is controlled by -the variable @code{c-auto-newline}. The ``electric'' characters are -@kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<}, -@kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. - - Electric characters insert newlines only when the @dfn{auto-newline} -feature is enabled (indicated by @samp{/a} in the mode line after the -mode name). This feature is controlled by the variable -@code{c-auto-newline}. You can turn this feature on or off with the -command @kbd{C-c C-a}: +@dfn{electric}---in addition to inserting themselves, they also +reindent the current line, and optionally also insert newlines. The +``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, +@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and +@kbd{)}. + + You might find electric indentation inconvenient if you are editing +chaotically indented code. If you are new to CC Mode, you might find +it disconcerting. You can toggle electric action with the command +@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line +after the mode name: @table @kbd -@item C-c C-a -@kindex C-c C-a @r{(C mode)} -@findex c-toggle-auto-state -Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a -prefix argument, this command turns the auto-newline feature on if the -argument is positive, and off if it is negative. +@item C-c C-l +@kindex C-c C-l @r{(C mode)} +@findex c-toggle-electric-state +Toggle electric action (@code{c-toggle-electric-state}). With a +prefix argument, this command enables electric action if the argument +is positive, disables it if it is negative. @end table - The colon character is electric because that is appropriate for a -single colon. But when you want to insert a double colon in C++, the -electric behavior of colon is inconvenient. You can insert a double -colon with no reindentation or newlines by typing @kbd{C-c :}: + Electric characters insert newlines only when, in addition to the +electric state, the @dfn{auto-newline} feature is enabled (indicated +by @samp{/la} in the mode line after the mode name). You can turn +this feature on or off with the command @kbd{C-c C-a}: @table @kbd -@item C-c : -@kindex C-c : @r{(C mode)} -@findex c-scope-operator -Insert a double colon scope operator at point, without reindenting the -line or adding any newlines (@code{c-scope-operator}). +@item C-c C-a +@kindex C-c C-a @r{(C mode)} +@findex c-toggle-auto-newline +Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a +prefix argument, this command turns the auto-newline feature on if the +argument is positive, and off if it is negative. @end table - The electric @kbd{#} key reindents the line if it appears to be the -beginning of a preprocessor directive. This happens when the value of -@code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn -this feature off by setting @code{c-electric-pound-behavior} to -@code{nil}. - - The variable @code{c-hanging-braces-alist} controls the insertion of -newlines before and after inserted braces. It is an association list -with elements of the following form: @code{(@var{syntactic-symbol} -. @var{nl-list})}. Most of the syntactic symbols that appear in -@code{c-offsets-alist} are meaningful here as well. - - The list @var{nl-list} may contain either of the symbols -@code{before} or @code{after}, or both; or it may be @code{nil}. When a -brace is inserted, the syntactic context it defines is looked up in -@code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used -to determine where newlines are inserted: either before the brace, -after, or both. If not found, the default is to insert a newline both -before and after braces. - - The variable @code{c-hanging-colons-alist} controls the insertion of -newlines before and after inserted colons. It is an association list -with elements of the following form: @code{(@var{syntactic-symbol} -. @var{nl-list})}. The list @var{nl-list} may contain either of the -symbols @code{before} or @code{after}, or both; or it may be @code{nil}. - - When a colon is inserted, the syntactic symbol it defines is looked -up in this list, and if found, the @var{nl-list} is used to determine -where newlines are inserted: either before the brace, after, or both. -If the syntactic symbol is not found in this list, no newlines are -inserted. - - Electric characters can also delete newlines automatically when the -auto-newline feature is enabled. This feature makes auto-newline more -acceptable, by deleting the newlines in the most common cases where you -do not want them. Emacs can recognize several cases in which deleting a -newline might be desirable; by setting the variable -@code{c-cleanup-list}, you can specify @emph{which} of these cases that -should happen. The variable's value is a list of symbols, each -describing one case for possible deletion of a newline. Here are the -meaningful symbols, and their meanings: - -@table @code -@item brace-catch-brace -Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the -entire construct on a single line. The clean-up occurs when you type -the @samp{@{}, if there is nothing between the braces aside from -@code{catch} and @var{condition}. - -@item brace-else-brace -Clean up @samp{@} else @{} constructs by placing the entire construct on -a single line. The clean-up occurs when you type the @samp{@{} after -the @code{else}, but only if there is nothing but white space between -the braces and the @code{else}. - -@item brace-elseif-brace -Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire -construct on a single line. The clean-up occurs when you type the -@samp{@{}, if there is nothing but white space between the @samp{@}} and -@samp{@{} aside from the keywords and the @code{if}-condition. - -@item empty-defun-braces -Clean up empty defun braces by placing the braces on the same -line. Clean-up occurs when you type the closing brace. - -@item defun-close-semi -Clean up the semicolon after a @code{struct} or similar type -declaration, by placing the semicolon on the same line as the closing -brace. Clean-up occurs when you type the semicolon. - -@item list-close-comma -Clean up commas following braces in array and aggregate -initializers. Clean-up occurs when you type the comma. - -@item scope-operator -Clean up double colons which may designate a C++ scope operator, by -placing the colons together. Clean-up occurs when you type the second -colon, but only when the two colons are separated by nothing but -whitespace. -@end table + Usually the CC Mode style configures the exact circumstances in +which Emacs inserts auto-newlines. You can also configure this +directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. @node Hungry Delete @subsection Hungry Delete Feature in C +@cindex hungry deletion (C Mode) - When the @dfn{hungry-delete} feature is enabled (indicated by -@samp{/h} or @samp{/ah} in the mode line after the mode name), a single -@key{DEL} command deletes all preceding whitespace, not just one space. -To turn this feature on or off, use @kbd{C-c C-d}: + 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. +@dfn{Whitespace} here includes tabs and newlines, but not comments or +preprocessor commands. @table @kbd +@item C-c C-@key{DEL} +@itemx C-c @key{DEL} +@findex c-hungry-backspace +@kindex C-c C-@key{DEL} (C Mode) +@kindex C-c @key{DEL} (C Mode) +@code{c-hungry-backspace}---Delete the entire block of whitespace +preceding point. + @item C-c C-d -@kindex C-c C-d @r{(C mode)} -@findex c-toggle-hungry-state -Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a -prefix argument, this command turns the hungry-delete feature on if the -argument is positive, and off if it is negative. +@itemx C-c C-@key{DELETE} +@itemx C-c @key{DELETE} +@findex c-hungry-delete-forward +@kindex C-c C-d (C Mode) +@kindex C-c C-@key{DELETE} (C Mode) +@kindex C-c @key{DELETE} (C Mode) +@code{c-hungry-delete-forward}---Delete the entire block of whitespace +following point. +@end table -@item C-c C-t -@kindex C-c C-t @r{(C mode)} -@findex c-toggle-auto-hungry-state -Toggle the auto-newline and hungry-delete features, both at once -(@code{c-toggle-auto-hungry-state}). + As an alternative to the above commands, you can enable @dfn{hungry +delete mode}. When this feature is enabled (indicated by @samp{/h} in +the mode line after the mode name), a single @key{DEL} deletes all +preceding whitespace, not just one space, and a single @kbd{C-c C-d} +(but @emph{not} plain @key{DELETE}) deletes all following whitespace. + +@table @kbd +@item M-x c-toggle-hungry-state +@findex c-toggle-hungry-state +Toggle the hungry-delete feature +(@code{c-toggle-hungry-state})@footnote{This command had the binding +@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now +bound to @code{c-hungry-delete-forward}.}. With a prefix argument, +this command turns the hungry-delete feature on if the argument is +positive, and off if it is negative. @end table @vindex c-hungry-delete-key @@ -3212,9 +1597,39 @@ hungry-delete feature is enabled. @subsection Other Commands for C Mode @table @kbd +@item C-c C-w +@itemx M-x c-subword-mode +@findex c-subword-mode +Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word +commands then recognize upper case letters in +@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by +the flag @samp{/w} on the mode line after the mode name +(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in +non-CC Mode buffers. + +In the GNU project, we recommend using underscores to separate words +within an identifier in C or C++, rather than using case distinctions. + +@item M-x c-context-line-break +@findex c-context-line-break +This command inserts a line break and indents the new line in a manner +appropriate to the context. In normal code, it does the work of +@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it +additionally inserts a @samp{\} at the line break, and within comments +it's like @kbd{M-j} (@code{c-indent-new-comment-line}). + +@code{c-context-line-break} isn't bound to a key by default, but it +needs a binding to be useful. The following code will bind it to +@kbd{C-j}. We use @code{c-initialization-hook} here to make sure +the keymap is loaded before we try to change it. + +@example +(defun my-bind-clb () + (define-key c-mode-base-map "\C-j" 'c-context-line-break)) +(add-hook 'c-initialization-hook 'my-bind-clb) +@end example + @item C-M-h -@findex c-mark-function -@kindex C-M-h @r{(C mode)} Put mark at the end of a function definition, and put point at the beginning (@code{c-mark-function}). @@ -3267,20 +1682,21 @@ click on @samp{[A]pply these settings} (or go to that buffer and type @findex c-show-syntactic-information @kindex C-c C-s @r{(C mode)} Display the syntactic information about the current source line -(@code{c-show-syntactic-information}). This is the information that -directs how the line is indented. +(@code{c-show-syntactic-information}). This information directs how +the line is indented. @item M-x cwarn-mode @itemx M-x global-cwarn-mode @findex cwarn-mode @findex global-cwarn-mode +@vindex global-cwarn-mode @cindex CWarn mode @cindex suspicious constructions in C, C++ -CWarn minor mode highlights suspicious C and C++ constructions: +CWarn minor mode highlights certain suspicious C and C++ constructions: @itemize @bullet{} @item -Assignments inside expressions, including variations like @samp{+=}; +Assignments inside expressions. @item Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} (except after a @samp{do @dots{} while} statement); @@ -3289,541 +1705,35 @@ C++ functions with reference parameters. @end itemize @noindent -You can activate the mode either by customizing @code{global-cwarn-mode} -or by adding @code{cwarn-mode} to @code{c-mode-common-hook}. It -requires Font Lock mode to be active. +You can enable the mode for one buffer with the command @kbd{M-x +cwarn-mode}, or for all suitable buffers with the command @kbd{M-x +global-cwarn-mode} or by customizing the variable +@code{global-cwarn-mode}. You must also enable Font Lock mode to make +it work. @item M-x hide-ifdef-mode @findex hide-ifdef-mode @cindex Hide-ifdef mode Hide-ifdef minor mode hides selected code within @samp{#if} and -@samp{#ifdef} preprocessor blocks. You can activate it by adding -@code{hide-ifdef-mode} to @code{c-mode-common-hook}. See the mode's -help for more information. -@end table - -@node Comments in C -@subsection Comments in C Modes - - C mode and related modes use a number of variables for controlling -comment format. - -@table @code -@item c-comment-only-line-offset -@vindex c-comment-only-line-offset -Extra offset for line which contains only the start of a comment. It -can be either an integer or a cons cell of the form -@code{(@var{non-anchored-offset} . @var{anchored-offset})}, where -@var{non-anchored-offset} is the amount of offset given to -non-column-zero anchored comment-only lines, and @var{anchored-offset} -is the amount of offset to give column-zero anchored comment-only lines. -Just an integer as value is equivalent to @code{(@var{val} . 0)}. - -@item c-comment-start-regexp -@vindex c-comment-start-regexp -This buffer-local variable specifies how to recognize the start of a comment. - -@item c-hanging-comment-ender-p -@vindex c-hanging-comment-ender-p -If this variable is @code{nil}, @code{c-fill-paragraph} leaves the -comment terminator of a block comment on a line by itself. The default -value is @code{t}, which puts the comment-end delimiter @samp{*/} at the -end of the last line of the comment text. - -@item c-hanging-comment-starter-p -@vindex c-hanging-comment-starter-p -If this variable is @code{nil}, @code{c-fill-paragraph} leaves the -starting delimiter of a block comment on a line by itself. The default -value is @code{t}, which puts the comment-start delimiter @samp{/*} at -the beginning of the first line of the comment text. +@samp{#ifdef} preprocessor blocks. See the documentation string of +@code{hide-ifdef-mode} for more information. + +@item M-x ff-find-related-file +@cindex related files +@findex ff-find-related-file +@vindex ff-related-file-alist +Find a file ``related'' in a special way to the file visited by the +current buffer. Typically this will be the header file corresponding +to a C/C++ source file, or vice versa. The variable +@code{ff-related-file-alist} specifies how to compute related file +names. @end table - -@node Fortran -@section Fortran Mode -@cindex Fortran mode -@cindex mode, Fortran - - Fortran mode provides special motion commands for Fortran statements and -subprograms, and indentation commands that understand Fortran conventions -of nesting, line numbers and continuation statements. Fortran mode has -its own Auto Fill mode that breaks long lines into proper Fortran -continuation lines. - - Special commands for comments are provided because Fortran comments -are unlike those of other languages. Built-in abbrevs optionally save -typing when you insert Fortran keywords. - -@findex fortran-mode - Use @kbd{M-x fortran-mode} to switch to this major mode. This command -runs the hook @code{fortran-mode-hook} (@pxref{Hooks}). - -@cindex Fortran77 -@cindex Fortran90 -@findex f90-mode -@findex fortran-mode -Note that Fortan mode described here (obtained with the -@code{fortran-mode} command) is for editing the old Fortran77 -idiosyncratic `fixed format' source form. For editing the modern -Fortran90 `free format' source form (which is supported by the GNU -Fortran compiler) use @code{f90-mode}. - -By default @code{fortran-mode} is invoked on files with extension -@samp{.f}, @samp{.F} or @samp{.for} and @code{f90-mode} is invoked for -the extension @samp{.f90}. - -@menu -* Motion: Fortran Motion. Moving point by statements or subprograms. -* Indent: Fortran Indent. Indentation commands for Fortran. -* Comments: Fortran Comments. Inserting and aligning comments. -* Autofill: Fortran Autofill. Auto fill minor mode for Fortran. -* Columns: Fortran Columns. Measuring columns for valid Fortran. -* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. -* Misc: Fortran Misc. Other Fortran mode features. -@end menu - -@node Fortran Motion -@subsection Motion Commands - -In addition to the normal commands for moving by and operating on -`defuns' (Fortran subprograms---functions -and subroutines) Fortran mode provides special commands to move by statements. - -@kindex C-c C-p @r{(Fortran mode)} -@kindex C-c C-n @r{(Fortran mode)} -@findex fortran-previous-statement -@findex fortran-next-statement - -@table @kbd -@item C-c C-n -Move to beginning of current or next statement -(@code{fortran-next-statement}). -@item C-c C-p -Move to beginning of current or previous statement -(@code{fortran-previous-statement}). -@end table - -@node Fortran Indent -@subsection Fortran Indentation - - Special commands and features are needed for indenting Fortran code in -order to make sure various syntactic entities (line numbers, comment line -indicators and continuation line flags) appear in the columns that are -required for standard Fortran. - -@menu -* Commands: ForIndent Commands. Commands for indenting and filling Fortran. -* Contline: ForIndent Cont. How continuation lines indent. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. -@end menu - -@node ForIndent Commands -@subsubsection Fortran-Specific Indentation and Filling Commands - -@table @kbd -@item C-M-j -Break the current line and set up a continuation line -(@code{fortran-split-line}). -@item M-^ -Join this line to the previous line (@code{fortran-join-line}). -@item C-M-q -Indent all the lines of the subprogram point is in -(@code{fortran-indent-subprogram}). -@item M-q -Fill a comment block or statement. -@end table - -@kindex C-M-q @r{(Fortran mode)} -@findex fortran-indent-subprogram - The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command -to reindent all the lines of the Fortran subprogram (function or -subroutine) containing point. - -@kindex C-M-j @r{(Fortran mode)} -@findex fortran-split-line - The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits -a line in the appropriate fashion for Fortran. In a non-comment line, -the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. - -@kindex M-^ @r{(Fortran mode)} -@kindex C-c C-d @r{(Fortran mode)} -@findex fortran-join-line - @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, -which joins a continuation line back to the previous line, roughly as -the inverse of @code{fortran-split-line}. The point must be on a -continuation line when this command is invoked. - -@kindex M-q @r{(Fortran mode)} -Fortran mode defines the function for filling paragraphs such that -@kbd{M-q} fills the comment block or statement around point. Filling a -statement removes excess statement continuations. - -@node ForIndent Cont -@subsubsection Continuation Lines -@cindex Fortran continuation lines - -@vindex fortran-continuation-string - Most modern Fortran compilers allow two ways of writing continuation -lines. If the first non-space character on a line is in column 5, then -that line is a continuation of the previous line. We call this -@dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The -variable @code{fortran-continuation-string} specifies what character to -put on column 5. A line that starts with a tab character followed by -any digit except @samp{0} is also a continuation line. We call this -style of continuation @dfn{tab format}. - -@vindex indent-tabs-mode @r{(Fortran mode)} - Fortran mode can make either style of continuation line, but you -must specify which one you prefer. The value of the variable -@code{indent-tabs-mode} controls the choice: @code{nil} for fixed -format, and non-@code{nil} for tab format. You can tell which style -is presently in effect by the presence or absence of the string -@samp{Tab} in the mode line. - - If the text on a line starts with the conventional Fortran -continuation marker @samp{$}, or if it begins with any non-whitespace -character in column 5, Fortran mode treats it as a continuation line. -When you indent a continuation line with @key{TAB}, it converts the line -to the current continuation style. When you split a Fortran statement -with @kbd{C-M-j}, the continuation marker on the newline is created -according to the continuation style. - - The setting of continuation style affects several other aspects of -editing in Fortran mode. In fixed format mode, the minimum column -number for the body of a statement is 6. Lines inside of Fortran -blocks that are indented to larger column numbers always use only the -space character for whitespace. In tab format mode, the minimum -column number for the statement body is 8, and the whitespace before -column 8 must always consist of one tab character. - -@vindex fortran-tab-mode-default -@vindex fortran-analyze-depth - When you enter Fortran mode for an existing file, it tries to deduce the -proper continuation style automatically from the file contents. The first -line that begins with either a tab character or six spaces determines the -choice. The variable @code{fortran-analyze-depth} specifies how many lines -to consider (at the beginning of the file); if none of those lines -indicates a style, then the variable @code{fortran-tab-mode-default} -specifies the style. If it is @code{nil}, that specifies fixed format, and -non-@code{nil} specifies tab format. - -@node ForIndent Num -@subsubsection Line Numbers - - If a number is the first non-whitespace in the line, Fortran -indentation assumes it is a line number and moves it to columns 0 -through 4. (Columns always count from 0 in GNU Emacs.) - -@vindex fortran-line-number-indent - Line numbers of four digits or less are normally indented one space. -The variable @code{fortran-line-number-indent} controls this; it -specifies the maximum indentation a line number can have. Line numbers -are indented to right-justify them to end in column 4 unless that would -require more than this maximum indentation. The default value of the -variable is 1. - -@vindex fortran-electric-line-number - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -@code{fortran-electric-line-number} to @code{nil}. Then inserting line -numbers is like inserting anything else. - -@node ForIndent Conv -@subsubsection Syntactic Conventions - - Fortran mode assumes that you follow certain conventions that simplify -the task of understanding a Fortran program well enough to indent it -properly: - -@itemize @bullet -@item -Two nested @samp{do} loops never share a @samp{continue} statement. - -@item -Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} -and others are written without embedded whitespace or line breaks. - -Fortran compilers generally ignore whitespace outside of string -constants, but Fortran mode does not recognize these keywords if they -are not contiguous. Constructs such as @samp{else if} or @samp{end do} -are acceptable, but the second word should be on the same line as the -first and not on a continuation line. -@end itemize - -@noindent -If you fail to follow these conventions, the indentation commands may -indent some lines unaesthetically. However, a correct Fortran program -retains its meaning when reindented even if the conventions are not -followed. - -@node ForIndent Vars -@subsubsection Variables for Fortran Indentation - -@vindex fortran-do-indent -@vindex fortran-if-indent -@vindex fortran-structure-indent -@vindex fortran-continuation-indent -@vindex fortran-check-all-num@dots{} -@vindex fortran-minimum-statement-indent@dots{} - Several additional variables control how Fortran indentation works: - -@table @code -@item fortran-do-indent -Extra indentation within each level of @samp{do} statement (default 3). - -@item fortran-if-indent -Extra indentation within each level of @samp{if} statement (default 3). -This value is also used for extra indentation within each level of the -Fortran 90 @samp{where} statement. - -@item fortran-structure-indent -Extra indentation within each level of @samp{structure}, @samp{union}, or -@samp{map} statements (default 3). - -@item fortran-continuation-indent -Extra indentation for bodies of continuation lines (default 5). - -@item fortran-check-all-num-for-matching-do -If this is @code{nil}, indentation assumes that each @samp{do} statement -ends on a @samp{continue} statement. Therefore, when computing -indentation for a statement other than @samp{continue}, it can save time -by not checking for a @samp{do} statement ending there. If this is -non-@code{nil}, indenting any numbered statement must check for a -@samp{do} that ends there. The default is @code{nil}. - -@item fortran-blink-matching-if -If this is @code{t}, indenting an @samp{endif} statement moves the -cursor momentarily to the matching @samp{if} statement to show where it -is. The default is @code{nil}. - -@item fortran-minimum-statement-indent-fixed -Minimum indentation for fortran statements when using fixed format -continuation line style. Statement bodies are never indented less than -this much. The default is 6. - -@item fortran-minimum-statement-indent-tab -Minimum indentation for fortran statements for tab format continuation line -style. Statement bodies are never indented less than this much. The -default is 8. -@end table - -@node Fortran Comments -@subsection Fortran Comments - - The usual Emacs comment commands assume that a comment can follow a line -of code. In Fortran, the standard comment syntax requires an entire line -to be just a comment. Therefore, Fortran mode replaces the standard Emacs -comment commands and defines some new variables. - - Fortran mode can also handle the Fortran90 comment syntax where comments -start with @samp{!} and can follow other text. Because only some Fortran77 -compilers accept this syntax, Fortran mode will not insert such comments -unless you have said in advance to do so. To do this, set the variable -@code{comment-start} to @samp{"!"} (@pxref{Variables}). - -@table @kbd -@item M-; -Align comment or insert new comment (@code{fortran-comment-indent}). - -@item C-x ; -Applies to nonstandard @samp{!} comments only. - -@item C-c ; -Turn all lines of the region into comments, or (with argument) turn them back -into real code (@code{fortran-comment-region}). -@end table - - @kbd{M-;} in Fortran mode is redefined as the command -@code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this -recognizes any kind of existing comment and aligns its text appropriately; -if there is no existing comment, a comment is inserted and aligned. But -inserting and aligning comments are not the same in Fortran mode as in -other modes. - - When a new comment must be inserted, if the current line is blank, a -full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} -comment is inserted if you have said you want to use them. Otherwise a -full-line comment is inserted on a new line before the current line. - - Nonstandard @samp{!} comments are aligned like comments in other -languages, but full-line comments are different. In a standard full-line -comment, the comment delimiter itself must always appear in column zero. -What can be aligned is the text within the comment. You can choose from -three styles of alignment by setting the variable -@code{fortran-comment-indent-style} to one of these values: - -@vindex fortran-comment-indent-style -@vindex fortran-comment-line-extra-indent -@table @code -@item fixed -Align the text at a fixed column, which is the sum of -@code{fortran-comment-line-extra-indent} and the minimum statement -indentation. This is the default. - -The minimum statement indentation is -@code{fortran-minimum-statement-indent-fixed} for fixed format -continuation line style and @code{fortran-minimum-statement-indent-tab} -for tab format style. - -@item relative -Align the text as if it were a line of code, but with an additional -@code{fortran-comment-line-extra-indent} columns of indentation. - -@item nil -Don't move text in full-line comments automatically at all. -@end table - -@vindex fortran-comment-indent-char - In addition, you can specify the character to be used to indent within -full-line comments by setting the variable -@code{fortran-comment-indent-char} to the single-character string you want -to use. - -@vindex comment-line-start -@vindex comment-line-start-skip - Fortran mode introduces two variables @code{comment-line-start} and -@code{comment-line-start-skip}, which play for full-line comments the same -roles played by @code{comment-start} and @code{comment-start-skip} for -ordinary text-following comments. Normally these are set properly by -Fortran mode, so you do not need to change them. - - The normal Emacs comment command @kbd{C-x ;} has not been redefined. If -you use @samp{!} comments, this command can be used with them. Otherwise -it is useless in Fortran mode. - -@kindex C-c ; @r{(Fortran mode)} -@findex fortran-comment-region -@vindex fortran-comment-region - The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the -lines of the region into comments by inserting the string @samp{C$$$} at -the front of each one. With a numeric argument, it turns the region -back into live code by deleting @samp{C$$$} from the front of each line -in it. The string used for these comments can be controlled by setting -the variable @code{fortran-comment-region}. Note that here we have an -example of a command and a variable with the same name; these two uses -of the name never conflict because in Lisp and in Emacs it is always -clear from the context which one is meant. - -@node Fortran Autofill -@subsection Fortran Auto Fill Mode - - Fortran Auto Fill mode is a minor mode which automatically splits -Fortran statements as you insert them when they become too wide. -Splitting a statement involves making continuation lines using -@code{fortran-continuation-string} (@pxref{ForIndent Cont}). This -splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and -also in the Fortran indentation commands. - -@findex fortran-auto-fill-mode - @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it -was off, or off if it was on. This command works the same as @kbd{M-x -auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A -positive numeric argument turns Fortran Auto Fill mode on, and a -negative argument turns it off. You can see when Fortran Auto Fill mode -is in effect by the presence of the word @samp{Fill} in the mode line, -inside the parentheses. Fortran Auto Fill mode is a minor mode, turned -on or off for each buffer individually. @xref{Minor Modes}. - -@vindex fortran-break-before-delimiters - Fortran Auto Fill mode breaks lines at spaces or delimiters when the -lines get longer than the desired width (the value of @code{fill-column}). -The delimiters that Fortran Auto Fill mode may break at are @samp{,}, -@samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}. -The line break comes after the delimiter if the variable -@code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by -default), the break comes before the delimiter. - - By default, Fortran Auto Fill mode is not enabled. If you want this -feature turned on permanently, add a hook function to -@code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}. -@xref{Hooks}. - -@node Fortran Columns -@subsection Checking Columns in Fortran - -@table @kbd -@item C-c C-r -Display a ``column ruler'' momentarily above the current line -(@code{fortran-column-ruler}). -@item C-c C-w -Split the current window horizontally temporarily so that it is 72 -columns wide. This may help you avoid making lines longer than the -72-character limit that some Fortran compilers impose -(@code{fortran-window-create-momentarily}). -@end table - -@kindex C-c C-r @r{(Fortran mode)} -@findex fortran-column-ruler -@vindex fortran-column-ruler - The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column -ruler momentarily above the current line. The comment ruler is two lines -of text that show you the locations of columns with special significance in -Fortran programs. Square brackets show the limits of the columns for line -numbers, and curly brackets show the limits of the columns for the -statement body. Column numbers appear above them. - - Note that the column numbers count from zero, as always in GNU Emacs. -As a result, the numbers may be one less than those you are familiar -with; but the positions they indicate in the line are standard for -Fortran. - - The text used to display the column ruler depends on the value of -the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is -@code{nil}, then the value of the variable -@code{fortran-column-ruler-fixed} is used as the column ruler. -Otherwise, the variable @code{fortran-column-ruler-tab} is displayed. -By changing these variables, you can change the column ruler display. - -@kindex C-u C-c C-w @r{(Fortran mode)} -@findex fortran-window-create - For even more help, use @kbd{M-x fortran-window-create}), a -command which splits the current window horizontally, making a window 72 -columns wide. By editing in this window you can immediately see when you -make a line too wide to be correct Fortran. - -@kindex C-c C-w @r{(Fortran mode)} -@findex fortran-window-create-momentarily -Also, @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) can be -used temporarily to split the current window horizontally, making a -window 72 columns wide to check column widths rather than to edit in -this mode. The normal width is restored when you type a space. - -@node Fortran Abbrev -@subsection Fortran Keyword Abbrevs - - Fortran mode provides many built-in abbrevs for common keywords and -declarations. These are the same sort of abbrev that you can define -yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}. - - The built-in abbrevs are unusual in one way: they all start with a -semicolon. You cannot normally use semicolon in an abbrev, but Fortran -mode makes this possible by changing the syntax of semicolon to ``word -constituent.'' - - For example, one built-in Fortran abbrev is @samp{;c} for -@samp{continue}. If you insert @samp{;c} and then insert a punctuation -character such as a space or a newline, the @samp{;c} expands automatically -to @samp{continue}, provided Abbrev mode is enabled.@refill - - Type @samp{;?} or @samp{;C-h} to display a list of all the built-in -Fortran abbrevs and what they stand for. - -@node Fortran Misc -@subsection Other Fortran Mode Commands - -The command @kbd{fortran-strip-sqeuence-nos} can be used to remove text -past Fortran column 72, which is typically old `sequence numbers'. - @node Asm Mode @section Asm Mode @cindex Asm mode -@cindex Assembler mode +@cindex assembler mode Asm mode is a major mode for editing files of assembler code. It defines these commands: @@ -3841,3 +1751,11 @@ Insert or align a comment. The variable @code{asm-comment-char} specifies which character starts comments in assembler syntax. + +@ifnottex +@include fortran-xtra.texi +@end ifnottex + +@ignore + arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 +@end ignore