X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/cf1c48d4ff55d4c643802f7fd0a0f3efb07a02d5..07dfe73898a43069d9d85ef74978e3fc9509773a:/man/programs.texi diff --git a/man/programs.texi b/man/programs.texi index 218b1dcacf..e19c8364f2 100644 --- a/man/programs.texi +++ b/man/programs.texi @@ -1,5 +1,5 @@ @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,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Programs, Building, Text, Top @chapter Editing Programs @@ -7,82 +7,43 @@ @cindex C editing @cindex program editing - Emacs provides many features to facilitate editing programs. These -features can: + Emacs provides many features to facilitate editing programs. Some +of these features can @itemize @bullet @item -Move over or kill balanced expressions (@pxref{Lists}). +Find or move over top-level definitions (@pxref{Defuns}). @item -Move over or mark top-level expressions, such as @dfn{defuns} in -Lisp, or function definitions in C (@pxref{Defuns}). -@item -Show how parentheses balance (@pxref{Matching}). +Apply the usual indentation conventions of the language +(@pxref{Program Indent}). @item Insert, kill or align comments (@pxref{Comments}). @item -Follow the usual indentation conventions of the language -(@pxref{Program Indent}). +Balance parentheses (@pxref{Parentheses}). @item Highlight program syntax (@pxref{Font Lock}). -@item -Compile and debug programs (@pxref{Building}). @end itemize + This chapter describes these features and many more. + @menu -* Misc for Programs:: Other Emacs features useful for editing programs. * 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. * 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. +* Parentheses:: Commands that operate on parentheses. +* 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. @end menu -@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 it 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 may 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. - - 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}). - - The ``automatic typing'' features may be useful for writing programs. -@xref{Top,,Autotyping, autotype, Autotyping}. - @node Program Modes @section Major Modes for Programming Languages @cindex modes for programming languages @@ -91,20 +52,19 @@ Mode}). The Foldout package provides folding-editor features @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. They often provide -facilities for compiling and debugging programs as well. +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 enable it by typing @kbd{M-x @var{l}-mode @key{RET}}. +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 @@ -121,32 +81,29 @@ and you can enable it by typing @kbd{M-x @var{l}-mode @key{RET}}. @cindex PostScript mode The existing programming language major modes include Lisp, Scheme (a variant of Lisp) and the Scheme-based DSSSL expression language, Ada, -Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed +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, Simula, and Tcl, and VHDL. There is +Perl, Pike, PostScript, Prolog, Simula, Tcl, and VHDL. There is also a major mode for makefiles, called Makefile mode. An alternative mode for Perl is called CPerl mode. Modes are available for the -scripting languages of the common Unix shells, VMS DCL, and +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 various sorts of configuration files. @kindex DEL @r{(programming modes)} @findex c-electric-backspace - 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. This -makes it possible to reduce 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. + 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 +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}). @@ -156,191 +113,94 @@ Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL @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 -Control-Meta characters. They act like the corresponding Control and -Meta equivalents, except that they operate on balanced expressions -instead of on characters or words. For instance, the command -@kbd{C-M-b} moves backward over a balanced expression, just as -@kbd{C-b} moves back over a character and @kbd{M-b} moves back over a -word. These commands are intended for expressions in programming -languages, but can be useful for editing any text that has -parentheses. - -@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 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. + In most programming language modes, Emacs assumes that a defun is +any pair of parentheses (or braces, if the language uses braces this +way) that starts at the left margin. For example, in C, the body of a +function definition is normally a defun, because the open-brace that +begins it is normally at the left margin. A variable's initializer +can also count as a defun, if the open-brace that begins the +initializer is at the left margin. -@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 + However, some language modes provide their own code for recognizing +defuns in a way that suits the language syntax and conventions better. -@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. +@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 -@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. +@node Left Margin Paren +@subsection Left Margin Convention -@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. +@cindex open-parenthesis in leftmost column +@cindex ( in leftmost column + In most major modes, Emacs assumes that any opening delimiter found +at the left margin is the start of a top-level definition, or defun. +Therefore, @strong{never put an opening delimiter at the left margin +unless it should have that significance.} 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. Never put an open-brace or other opening +delimiter at the beginning of a line of C code unless it is at top +level. + + 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}). + + 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. 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, it mandates following the convention described +above. + +@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}. -@cindex move to beginning or end of function -@cindex function, move to beginning or end -@kindex C-M-a -@kindex C-M-e -@kindex C-M-h -@findex beginning-of-defun -@findex end-of-defun -@findex mark-defun -@c doublewidecommands @table @kbd @item C-M-a Move to beginning of current or preceding defun @@ -351,38 +211,116 @@ Move to end of current or following defun (@code{end-of-defun}). Put region around whole current or following defun (@code{mark-defun}). @end table +@cindex move to beginning or end of function +@cindex function, move to beginning or end +@kindex C-M-a +@kindex C-M-e +@kindex C-M-h +@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}). 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. + + 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 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 only takes effect 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 @@ -401,28 +339,29 @@ 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 - Programming language major modes define the @key{TAB} key to indent -according to the usual conventions of the language you are editing. -@kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB}; -thus, it too indents in a mode-specific fashion. + The basic indentation commands indent a single line according to the +usual conventions of the language you are editing. -@c WideCommands @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}). +@item @key{LINEFEED} +This key, if the keyboard has it, is another way to enter @kbd{C-j}. @end table @kindex TAB @r{(programming modes)} @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 @@ -445,20 +384,20 @@ the characters around it. followed by a @key{TAB}. @kbd{C-j} at the end of a line 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. + @key{TAB} indents lines that start within a parenthetical grouping +each under the preceding line (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. 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. +commands fast; you must simply accept it. @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, see @ref{Just Spaces}. @@ -466,43 +405,56 @@ to use spaces only, see @ref{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-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}. + 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-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. @node Lisp Indent @subsection Customizing Lisp Indentation @@ -526,60 +478,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 @@ -592,14 +507,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. @@ -609,13 +525,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 @@ -627,592 +537,291 @@ 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}. - - 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. + 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}. - 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): - -@example -1: void swap (int& a, int& b) -2: @{ -3: int tmp = a; -4: a = b; -5: b = tmp; -6: @} -@end example - - 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: - -@example -syntactic analysis: ((statement . 32)) -@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 -syntactic analysis: ((defun-block-intro . 28)) -@end example +@table @kbd +@item C-c . @key{RET} @var{style} @key{RET} +Select a predefined style @var{style} (@code{c-set-style}). +@end table - 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. + A @dfn{style} is a named collection of customizations that can +be used in C mode and the related modes. 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}, @code{cc-mode}, and @code{user}. +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 @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 in the buffer. To reindent the whole buffer in the new +style, you can type @kbd{C-x h C-M-\}. -@noindent -Here is another example: +@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 -1: int add (int val, int incr, int doit) -2: @{ -3: if (doit) -4: @{ -5: return (val + incr); -6: @} -7: return (val); -8: @} +(setq c-default-style + '((java-mode . "java") (other . "gnu"))) @end example @noindent -Typing @kbd{C-c C-s} on line 4 displays this: - -@example -syntactic analysis: ((substatement-open . 43)) -@end example - - 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: - -@example -1: void swap (int& a, int& b) -2: @{ -3: int tmp = a; -4: a = b; -5: b = tmp; -6: @} -@end example - - 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: - -@example -((defun-block-intro . 28)) -@end example +specifies an explicit choice for Java mode, and the default @samp{gnu} +style for the other C-like modes. 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. - 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. + 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. - 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. + @xref{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. -@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 +@node Parentheses +@section Commands for Editing with Parentheses - 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: +@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. -@example -((substatement-open . 43)) -@end 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. - 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. + You can use @kbd{M-x check-parens} to find any unbalanced +parentheses and unbalanced string quotes in the buffer. -@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. +@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 -@node Changing Indent Style -@subsubsection Changing Indentation Style +@node Expressions +@subsection Expressions with Balanced Parentheses - 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. +@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.}. @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-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 - 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}. + 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. -@table @code -@item string -Inside a multi-line string. +@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. -@item c -Inside a multi-line C style block comment. +@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. -@item defun-open -On a brace that opens a function definition. + 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. -@item defun-close -On a brace that closes a function definition. + @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. -@item defun-block-intro -In the first line in a top-level defun. +@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. -@item class-open -On a brace that opens a class definition. +@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, and 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. -@item class-close -On a brace that closes a class definition. +@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-@@}. + + 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. -@item inline-open -On a brace that opens an in-class inline method. +@table @kbd +@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 -@item inline-close -On a brace that closes an in-class inline method. +@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 extern-lang-open -On a brace that opens an external language block. +@kindex C-M-u +@kindex C-M-d +@findex backward-up-list +@findex down-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. + + 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 extern-lang-close -On a brace that closes an external language block. +@node Matching +@subsection Automatic Display Of Matching Parentheses +@cindex matching parentheses +@cindex parentheses, displaying matches -@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. + 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 knr-argdecl-intro -On the first line of a K&R C argument declaration. + If the opening delimiter and closing delimiter are mismatched---such +as in @samp{[x)}---a warning message is displayed in the echo area. -@item knr-argdecl -In one of the subsequent lines in a K&R C argument declaration. +@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} +disables it, but the default is @code{t} to enable match display. -@item topmost-intro -On the first line in a topmost construct definition. + @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 topmost-intro-cont -On the topmost definition continuation lines. + @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 member-init-intro -On the first line in a member initialization list. - -@item member-init-cont -On one of the subsequent member initialization list lines. - -@item inher-intro -On the first line of a multiple inheritance list. - -@item inher-cont -On one of the subsequent multiple inheritance lines. - -@item block-open -On a statement block open brace. - -@item block-close -On a statement block close brace. - -@item brace-list-open -On the opening brace of an @code{enum} or @code{static} array list. - -@item brace-list-close -On the closing brace of an @code{enum} or @code{static} array list. - -@item brace-list-intro -On the first line in an @code{enum} or @code{static} array list. - -@item brace-list-entry -On one of the subsequent lines in an @code{enum} or @code{static} array -list. - -@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. However, if you make changes in variables such as -@code{c-basic-offset} and @code{c-offsets-alist} in your -@file{~/.emacs} file, your changes override the what @code{gnu} style -says. - -@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 25600. - -@cindex Show Paren mode -@cindex highlighting matching parentheses -@findex show-paren-mode - Show Paren mode provides a more powerful kind of automatic -parenthesis matching. 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. +@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. By default, @code{show-paren-mode} uses colors to highlight the parentheses. However, if your display doesn't support colors, you can @@ -1225,12 +834,14 @@ underline. @xref{Face Customization}. @cindex comments Because comments are such an important part of programming, Emacs -provides special commands for editing and inserting comments. +provides special commands for editing and inserting comments. It can +also do spell checking on comments with Flyspell Prog mode +(@pxref{Spelling}). @menu -* Comment Commands:: -* Multi-Line Comments:: -* Options for Comments:: +* Comment Commands:: Inserting, killing, and indenting comments. +* Multi-Line Comments:: Commands for adding and editing multi-line comments. +* Options for Comments::Customizing the comment features. @end menu @node Comment Commands @@ -1240,18 +851,20 @@ provides special commands for editing and inserting comments. The comment commands in this table insert, kill and align comments. They are described in this section and following sections. -@table @kbd -@item M-; +@table @asis +@item @kbd{M-;} Insert or realign comment on current line; alternatively, comment or uncomment the region (@code{comment-dwim}). -@item C-u M-; +@item @kbd{C-u M-;} Kill comment on current line (@code{comment-kill}). -@item C-x ; +@item @kbd{C-x ;} Set comment column (@code{comment-set-column}). -@item C-M-j +@item @kbd{C-M-j} +@itemx @kbd{M-j} Like @key{RET} followed by inserting and aligning a comment (@code{comment-indent-new-line}). -@item M-x comment-region +@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 @@ -1314,1682 +927,471 @@ 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. - -@node Multi-Line Comments -@subsection Multiple Lines of Comments - -@kindex C-M-j -@cindex blank lines in programs -@findex comment-indent-new-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{comment-indent-new-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 or three, if between defuns; -if within a defun, it must be three. - -@node Options for Comments -@subsection Options Controlling Comments - -@vindex comment-column -@kindex C-x ; -@findex comment-set-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{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 -default value which you can change with @code{setq-default}. -@xref{Locals}. Many major modes initialize this variable for the -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 -@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{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-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. - -@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 string quotes 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 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. - -@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}. - - 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 portions of a -file, 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. - - 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. - -@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 - -@vindex hs-hide-comments-when-hiding-all -@vindex hs-isearch-open -@vindex hs-special-modes-alist - These user options exist for customizing Hideshow mode. - -@table @code -@item hs-hide-comments-when-hiding-all -Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. -@item hs-isearch-open -Specifies what kind of hidden blocks to open in Isearch mode. -@item hs-special-modes-alist -Specifies -Initializes Hideshow variables for different modes. -@end table - -@node Glasses -@section Glasses minor mode -@cindex Glasses mode -@cindex identifiers, making long ones readable -@cindex StudlyCaps, making them readable -@findex glasses-mode - - Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} -readable by altering the display. It can do this in two different -ways: by displaying underscores between an lower-case letter and the -following capital letter, or 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; you can also add -@code{glasses-mode} to the mode hook of appropriate programming -language major 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 this supports the following -modes: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4, -Makefile, Octave, Perl, Scheme and Texinfo, provided you have installed -the relevant Info files, which are typically available with 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 classified into @dfn{sections}; sometimes there are -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 by the same name), type -@kbd{M-x manual-entry @key{RET} chmod(2v) @key{RET}} (assuming -@code{chmod} is in section @samp{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 man pages that have -the specified name, so 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 the job -in Emacs Lisp, so it works on systems such as MS-Windows, where the -@code{man} program and other the programs it needs are not readily -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 -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---that is useful for making log entries for functions that -have been deleted in the current version. - - 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. - - @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. - -@vindex add-log-keep-changes-together - When the option @code{add-log-keep-changes-together} is -non-@code{nil}, @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-@code{nil}, @kbd{C-x 4 a} ads the file's version number to the -change log entry. It finds the version number by searching the first -ten percent of the file, using regular expressions from the variable -@code{change-log-version-number-regexp-list}. - -@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 - You can use the command @kbd{M-x change-log-merge} to merge other -log files into a buffer in Change Log Mode, preserving the date -ordering of entries. - -@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, to make the file uniform in style. This is handy when -entries are contributed by many different people, some of whom 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. - - Do not assume that this command finds all the contributors; don't -assume that a person not listed in the output was not a contributor. -If you merged in someone's contribution and did not put his name -in the change log, he won't show up in @kbd{M-x authors} either. - -@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 file names, 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 - See also the Ebrowse facility, which is tailored for C++. -@xref{Top,, Ebrowse, 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}. -@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. - -You can tag function declarations and external variables in addition -to function definitions by giving the @samp{--declarations} option to -@code{etags}. - -@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} definitions have -tag names like @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. - -In Ada, the same name can be used for different kinds of entity -(e.g.@:, for a procedure and for a function). Also, for things like -packages, procedures and functions, there is the spec (i.e.@: the -interface) and the body (i.e.@: the implementation). To make it -easier to pick the definition you want, Ada tag name have suffixes -indicating the type of entity: - -@table @samp -@item /b -package body. -@item /f -function. -@item /k -task. -@item /p -procedure. -@item /s -package spec. -@item /t -type. -@end table - - Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go -directly to the body of the package @code{bidule}, while @kbd{M-x -find-tag @key{RET} bidule @key{RET}} will just search for any tag -@code{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. - - If the specified files don't exist, @code{etags} looks for -compressed versions of them and uncompresses them to read them. Under -MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz} -if it is given @samp{mycode.c} on the command line and @file{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. But it is not necessary to do -this very 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 virtually 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 covered all the source 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}) works like -@samp{--regex}, except that matching ignores case. This is -appropriate for certain 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}. - - You can specify a regular expression for a particular language, by -writing @samp{@{lang@}} in front of it. Then @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, for the C language only: - -@smallexample ---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' -@end smallexample - -@noindent -This feature is particularly useful when you store 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; thus, one -such file can include another file. All the other lines are taken to -be regular expressions. If the first non-whitespace text on the line -is @samp{--}, that line is a comment. - - For example, one can create a file called @samp{emacs.tags} with the -following contents: - -@smallexample - -- This is for GNU Emacs C 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 @samp{###key @var{scriptname}} 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 -etags --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 multiple files -@cindex multiple-file search and replace - - 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 -@vindex tags-apropos-verbose - @kbd{M-x tags-apropos} is like @code{apropos} for tags -(@pxref{Apropos}). It finds all the tags in the selected tags table -whose entries match @var{regexp}, and displays them. If the variable -@code{tags-apropos-verbose} is non-@code{nil}, it displays the names -of the tags files together with the tag names. - -@vindex tags-tag-face -@vindex tags-apropos-additional-actions -You can customize the appearance of the output with the face -@code{tags-tag-face}. 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. - - You can also use the collection of tag names to complete a symbol -name in the buffer. @xref{Symbol Completion}. - -@node Imenu -@section Imenu -@cindex indexes of buffer contents -@cindex buffer content indexes -@cindex tags - - The Imenu facility is another way to find definitions or sections -in a file. It is similar in spirit to Tags, but operates on a single -buffer only, and works entirely within Emacs with no need for a separate -tags table. - -@findex imenu -@findex imenu-add-menu-bar-index - If you type @kbd{M-x imenu}, it reads the name of a section or -definition in the current buffer, then goes to that section or -definition. You can use completion to specify the name, and a -complete list of possible names is always displayed. - - Alternatively you can bind the command @code{imenu} to a mouse -click. Then it displays mouse menus for you to select the section or -definition you want. You can also add the buffer's index to the menu -bar by calling @code{imenu-add-menu-bar-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-menu-bar-index} to its mode -hook. But then you will have to wait for the buffer to be searched -for sections and definitions, each time you visit a file which uses -that mode. - -@vindex imenu-auto-rescan - When you change the contents of a buffer, if you add or delete -definitions or sections, you can update the buffer's index to -correspond to the new contents by invoking the @samp{*Rescan*} item in -the menu. Rescanning happens automatically if -@code{imenu-auto-rescan} is non-@code{nil}. 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 via the variable -@code{imenu-sort-function}. By default names are ordered as they -occur in the buffer; alphabetic sorting is provided as an alternative. - - Imenu provides the information to guide Which Function mode -(@pxref{Which Function}). The Speedbar can also use it -(@pxref{Speedbar}). +;; 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 -@node Emerge, C Modes, Imenu, Programs -@section Merging Files with Emerge -@cindex Emerge -@cindex merging files + In C code, a comment preceded on its line by nothing but whitespace +is indented like a line of code. -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}. +@node Multi-Line Comments +@subsection Multiple Lines of Comments -@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. -@end menu +@kindex C-M-j +@kindex M-j +@cindex blank lines in programs +@findex comment-indent-new-line + 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}). 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 you +type the command, the text on the rest of the line becomes part of the +new comment line. + +@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. 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. -@node Overview of Emerge -@subsection Overview of Emerge + 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 or three, if between defuns; +if within a defun, it must be three. -To start Emerge, run one of these four commands: +@node Options for Comments +@subsection Options Controlling Comments -@table @kbd -@item M-x emerge-files -@findex emerge-files -Merge two specified files. +@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. -@item M-x emerge-files-with-ancestor -@findex emerge-files-with-ancestor -Merge two specified files, with reference to a common ancestor. + The variable @code{comment-column} is per-buffer: setting the variable +in the normal fashion affects only the current buffer, but there is a +default value which you can change with @code{setq-default}. +@xref{Locals}. Many major modes initialize this variable for the +current buffer. -@item M-x emerge-buffers -@findex emerge-buffers -Merge two buffers. +@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 +@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{Regexps}.) -@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 +@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{" */"}}. -@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: +@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. -@example -vvvvvvvvvvvvvvvvvvvv -@var{text that differs} -^^^^^^^^^^^^^^^^^^^^ -@end example +@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 +default value), 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. -@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: +@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. -@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 Documentation +@section Documentation Lookup -@node Merge Commands -@subsection Merge Commands + 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. - Here are the Merge commands for Fast mode; in Edit mode, precede them -with @kbd{C-c C-c}: +@menu +* 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 -@table @kbd -@item p -Select the previous difference. +@node Info Lookup +@subsection Info Documentation Lookup -@item n -Select the next difference. +@findex info-lookup-symbol +@findex info-lookup-file +@kindex C-h S + For C, Lisp, and other 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. You specify the symbol with the +minibuffer; the default is the symbol appearing in the buffer at +point. -@item a -Choose the A version of this difference. + 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. -@item b -Choose the B version of this difference. + This feature currently supports the modes AWK, Autoconf, Bison, C, +Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo, +provided you have installed the relevant Info files, which are +typically available with the appropriate GNU package. -@item C-u @var{n} j -Select difference number @var{n}. +@node Man Page +@subsection Man Page Lookup -@item . -Select the difference containing point. You can use this command in the -merge buffer or in the A or B buffer. +@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 hope 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 q -Quit---finish the merge. +@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 C-] -Abort---exit merging and do not save the output. +@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 f -Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) +@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 e -Go into Edit mode. +@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 l -Recenter (like @kbd{C-l}) all three windows. +@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 the other programs it uses) are not generally +available. -@item - -Specify part of a prefix numeric argument. + @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 @var{digit} -Also specify part of a prefix numeric argument. + 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 d a -Choose the A version as the default from here down in -the merge buffer. + 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 d b -Choose the B version as the default from here down in -the merge buffer. +@vindex woman-manpath + By default, @kbd{M-x woman} looks for manual pages in the +directories specified in 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 pattern @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. Changing the value of this +variable is another way to control the list of directories used. -@item c a -Copy the A version of this difference into the kill ring. +@vindex woman-path + You can also 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. -@item c b -Copy the B version of this difference into the kill ring. +@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. -@item i a -Insert the A version of this difference at point. +@vindex woman-dired-keys + The 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 define to invoke @code{woman-find-file} on +the current line's archive member. -@item i b -Insert the B version of this difference at point. + 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 m -Put point and mark around the difference. +@node Lisp Doc +@subsection Emacs Lisp Documentation Lookup -@item ^ -Scroll all three windows down (like @kbd{M-v}). + 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 v -Scroll all three windows up (like @kbd{C-v}). +@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.) 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. -@item < -Scroll all three windows left (like @kbd{C-x <}). +@node Hideshow +@section Hideshow minor mode -@item > -Scroll all three windows right (like @kbd{C-x >}). +@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 | -Reset horizontal scroll on all three windows. + 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 1 -Shrink the merge window to one line. (Use @kbd{C-u l} to restore it -to full size.) +@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 -@item x c -Combine the two versions of this difference (@pxref{Combining in -Emerge}). +@vindex hs-hide-comments-when-hiding-all +@vindex hs-isearch-open +@vindex hs-special-modes-alist + These user options exist for customizing Hideshow mode. -@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.) +@table @code +@item hs-hide-comments-when-hiding-all +Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. -@item x j -Join this difference with the following one. -(@kbd{C-u x j} joins this difference with the previous one.) +@item hs-isearch-open +Specifies what kind of hidden blocks to open in Isearch mode. +The value should be one of these four symbols. -@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. +@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 -@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. +@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 -@node Exiting Emerge -@subsection Exiting Emerge +@node Symbol Completion +@section Completion for Symbol Names +@cindex completion (symbol names) - 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. + 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. - @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. +@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 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. + 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. -@node Combining in Emerge -@subsection Combining the Two Versions +@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. - 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: +@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}. -@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 Text mode and related modes, @kbd{M-@key{TAB}} completes words +based on the spell-checker's dictionary. @xref{Spelling}. -@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: +@node Glasses +@section Glasses minor mode +@cindex Glasses mode +@cindex identifiers, making long ones readable +@cindex StudlyCaps, making them readable +@findex glasses-mode -@example -@group -"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" -@end group -@end example + 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 Fine Points of Emerge -@subsection Fine Points of Emerge +@node Misc for Programs +@section Other Features Useful for Editing Programs - 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. + A number of Emacs commands that aren't designed specifically for +editing programs are useful for that nonetheless. - 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. + 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 @@ -3000,24 +1402,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 gives a brief description of the special features -available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes. -(These are called ``C mode and related modes.'') @xref{Top, CC Mode, -ccmode, , CC Mode}, for a more extensive description of these modes +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 @@ -3027,15 +1432,29 @@ and their special features. 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)} @@ -3052,27 +1471,22 @@ 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}). +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}). @item M-x c-backward-into-nomenclature @findex c-backward-into-nomenclature @@ -3123,18 +1537,27 @@ colon with no reindentation or newlines by typing @kbd{C-c :}: @table @kbd @item C-c : +@ifinfo +@c This uses ``colon'' instead of a literal `:' because Info cannot +@c cope with a `:' in a menu +@kindex C-c @key{colon} @r{(C mode)} +@end ifinfo +@ifnotinfo @kindex C-c : @r{(C mode)} +@end ifnotinfo @findex c-scope-operator Insert a double colon scope operator at point, without reindenting the line or adding any newlines (@code{c-scope-operator}). @end table +@vindex c-electric-pound-behavior 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}. +@vindex c-hanging-braces-alist 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} @@ -3149,6 +1572,7 @@ 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. +@vindex c-hanging-colons-alist 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} @@ -3161,6 +1585,7 @@ 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. +@vindex c-cleanup-list 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 @@ -3212,6 +1637,7 @@ whitespace. @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 @@ -3241,6 +1667,21 @@ hungry-delete feature is enabled. @subsection Other Commands for C Mode @table @kbd +@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}. +@example +(define-key c-mode-base-map "\C-j" 'c-context-line-break) +@end example + @item C-M-h Put mark at the end of a function definition, and put point at the beginning (@code{c-mark-function}). @@ -3301,6 +1742,7 @@ directs how the line is indented. @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 certain suspicious C and C++ constructions: @@ -3340,42 +1782,6 @@ to a C/C++ source file, or vice versa. The variable names. @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. -@end table - @node Fortran @section Fortran Mode @cindex Fortran mode @@ -3397,7 +1803,7 @@ runs the hook @code{fortran-mode-hook} (@pxref{Hooks}). @cindex Fortran77 and Fortran90 @findex f90-mode @findex fortran-mode - Fortan mode is meant for editing Fortran77 ``fixed format'' source + Fortran mode is meant for editing Fortran77 ``fixed format'' source code. For editing the modern Fortran90 ``free format'' source code, use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode @@ -3714,6 +2120,15 @@ full-line comments by setting the variable @code{fortran-comment-indent-char} to the single-character string you want to use. +@vindex fortran-directive-re + Compiler directive lines, or preprocessor lines, have much the same +appearance as comment lines. It is important, though, that such lines +never be indented at all, no matter what the value of +@code{fortran-comment-indent-style}. The variable +@code{fortran-directive-re} is a regular expression that specifies which +lines are directives. Matching lines are never indented, and receive +distinctive font-locking. + @vindex comment-line-start @vindex comment-line-start-skip Fortran mode introduces two variables @code{comment-line-start} and @@ -3876,3 +2291,7 @@ Insert or align a comment. The variable @code{asm-comment-char} specifies which character starts comments in assembler syntax. + +@ignore + arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 +@end ignore