This is ../info/emacs, produced by makeinfo version 4.3 from emacs.texi. This is the Fourteenth edition of the `GNU Emacs Manual', updated for Emacs version 21.3. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Emacs: (emacs). The extensible self-documenting text editor. END-INFO-DIR-ENTRY Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1985,1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "The GNU Manifesto", "Distribution" and "GNU GENERAL PUBLIC LICENSE", with the Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License." (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: emacs, Node: TeX Print, Next: TeX Misc, Prev: LaTeX Editing, Up: TeX Mode TeX Printing Commands --------------------- You can invoke TeX as an inferior of Emacs on either the entire contents of the buffer or just a region at a time. Running TeX in this way on just one chapter is a good way to see what your changes look like without taking the time to format the entire file. `C-c C-r' Invoke TeX on the current region, together with the buffer's header (`tex-region'). `C-c C-b' Invoke TeX on the entire current buffer (`tex-buffer'). `C-c ' Invoke BibTeX on the current file (`tex-bibtex-file'). `C-c C-f' Invoke TeX on the current file (`tex-file'). `C-c C-l' Recenter the window showing output from the inferior TeX so that the last line can be seen (`tex-recenter-output-buffer'). `C-c C-k' Kill the TeX subprocess (`tex-kill-job'). `C-c C-p' Print the output from the last `C-c C-r', `C-c C-b', or `C-c C-f' command (`tex-print'). `C-c C-v' Preview the output from the last `C-c C-r', `C-c C-b', or `C-c C-f' command (`tex-view'). `C-c C-q' Show the printer queue (`tex-show-print-queue'). You can pass the current buffer through an inferior TeX by means of `C-c C-b' (`tex-buffer'). The formatted output appears in a temporary file; to print it, type `C-c C-p' (`tex-print'). Afterward, you can use `C-c C-q' (`tex-show-print-queue') to view the progress of your output towards being printed. If your terminal has the ability to display TeX output files, you can preview the output on the terminal with `C-c C-v' (`tex-view'). You can specify the directory to use for running TeX by setting the variable `tex-directory'. `"."' is the default value. If your environment variable `TEXINPUTS' contains relative directory names, or if your files contains `\input' commands with relative file names, then `tex-directory' _must_ be `"."' or you will get the wrong results. Otherwise, it is safe to specify some other directory, such as `"/tmp"'. If you want to specify which shell commands are used in the inferior TeX, you can do so by setting the values of the variables `tex-run-command', `latex-run-command', `slitex-run-command', `tex-dvi-print-command', `tex-dvi-view-command', and `tex-show-queue-command'. You _must_ set the value of `tex-dvi-view-command' for your particular terminal; this variable has no default value. The other variables have default values that may (or may not) be appropriate for your system. Normally, the file name given to these commands comes at the end of the command string; for example, `latex FILENAME'. In some cases, however, the file name needs to be embedded in the command; an example is when you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with `*' in the command string. For example, (setq tex-dvi-print-command "dvips -f * | lpr") The terminal output from TeX, including any error messages, appears in a buffer called `*tex-shell*'. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; *note Interactive Shell::). Without switching to this buffer you can scroll it so that its last line is visible by typing `C-c C-l'. Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also kills any TeX process still running. You can also pass an arbitrary region through an inferior TeX by typing `C-c C-r' (`tex-region'). This is tricky, however, because most files of TeX input contain commands at the beginning to set parameters and define macros, without which no later part of the file will format correctly. To solve this problem, `C-c C-r' allows you to designate a part of the file as containing essential commands; it is included before the specified region as part of the input to TeX. The designated part of the file is called the "header". To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert `%**start of header' before the header, and `%**end of header' after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If `%**start of header' does not appear within the first 100 lines of the buffer, `C-c C-r' assumes that there is no header. In LaTeX mode, the header begins with `\documentclass' or `\documentstyle' and ends with `\begin{document}'. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header. The commands (`tex-buffer') and (`tex-region') do all of their work in a temporary directory, and do not have available any of the auxiliary files needed by TeX for cross-references; these commands are generally not suitable for running the final copy in which all of the cross-references need to be correct. When you want the auxiliary files for cross references, use `C-c C-f' (`tex-file') which runs TeX on the current buffer's file, in that file's directory. Before running TeX, it offers to save any modified buffers. Generally, you need to use (`tex-file') twice to get the cross-references right. The value of the variable `tex-start-options-string' specifies options for the TeX run. The default value causes TeX to run in nonstop mode. To run TeX interactively, set the variable to `""'. Large TeX documents are often split into several files--one main file, plus subfiles. Running TeX on a subfile typically does not work; you have to run it on the main file. In order to make `tex-file' useful when you are editing a subfile, you can set the variable `tex-main-file' to the name of the main file. Then `tex-file' runs TeX on that file. The most convenient way to use `tex-main-file' is to specify it in a local variable list in each of the subfiles. *Note File Variables::. For LaTeX files, you can use BibTeX to process the auxiliary file for the current buffer's file. BibTeX looks up bibliographic citations in a data base and prepares the cited references for the bibliography section. The command `C-c TAB' (`tex-bibtex-file') runs the shell command (`tex-bibtex-command') to produce a `.bbl' file for the current buffer's file. Generally, you need to do `C-c C-f' (`tex-file') once to generate the `.aux' file, then do `C-c TAB' (`tex-bibtex-file'), and then repeat `C-c C-f' (`tex-file') twice more to get the cross-references correct.  File: emacs, Node: TeX Misc, Prev: TeX Print, Up: TeX Mode TeX Mode Miscellany ------------------- Entering any variant of TeX mode runs the hooks `text-mode-hook' and `tex-mode-hook'. Then it runs either `plain-tex-mode-hook', `latex-mode-hook', or `slitex-mode-hook', whichever is appropriate. Starting the TeX shell runs the hook `tex-shell-hook'. *Note Hooks::. TeX encoding The commands `M-x iso-iso2tex', `M-x iso-tex2iso', `M-x iso-iso2gtex' and `M-x iso-gtex2iso' can be used to convert between Latin-1 encoded files and TeX-encoded equivalents. For managing all kinds of references for LaTeX, you can use RefTeX. *Note RefTeX: (reftex)Top.  File: emacs, Node: Nroff Mode, Next: Formatted Text, Prev: TeX Mode, Up: Text Nroff Mode ========== Nroff mode is a mode like Text mode but modified to handle nroff commands present in the text. Invoke `M-x nroff-mode' to enter this mode. It differs from Text mode in only a few ways. All nroff command lines are considered paragraph separators, so that filling will never garble the nroff commands. Pages are separated by `.bp' commands. Comments start with backslash-doublequote. Also, three special commands are provided that are not in Text mode: `M-n' Move to the beginning of the next line that isn't an nroff command (`forward-text-line'). An argument is a repeat count. `M-p' Like `M-n' but move up (`backward-text-line'). `M-?' Displays in the echo area the number of text lines (lines that are not nroff commands) in the region (`count-text-lines'). The other feature of Nroff mode is that you can turn on Electric Nroff mode. This is a minor mode that you can turn on or off with `M-x electric-nroff-mode' (*note Minor Modes::). When the mode is on, each time you use to end a line that contains an nroff command that opens a kind of grouping, the matching nroff command to close that grouping is automatically inserted on the following line. For example, if you are at the beginning of a line and type `. ( b ', this inserts the matching command `.)b' on a new line following point. If you use Outline minor mode with Nroff mode (*note Outline Mode::), heading lines are lines of the form `.H' followed by a number (the header level). Entering Nroff mode runs the hook `text-mode-hook', followed by the hook `nroff-mode-hook' (*note Hooks::).  File: emacs, Node: Formatted Text, Prev: Nroff Mode, Up: Text Editing Formatted Text ====================== "Enriched mode" is a minor mode for editing files that contain formatted text in WYSIWYG fashion, as in a word processor. Currently, formatted text in Enriched mode can specify fonts, colors, underlining, margins, and types of filling and justification. In the future, we plan to implement other formatting features as well. Enriched mode is a minor mode (*note Minor Modes::). It is typically used in conjunction with Text mode (*note Text Mode::), but you can also use it with other major modes such as Outline mode and Paragraph-Indent Text mode. Potentially, Emacs can store formatted text files in various file formats. Currently, only one format is implemented: "text/enriched" format, which is defined by the MIME protocol. *Note Format Conversion: (elisp)Format Conversion, for details of how Emacs recognizes and converts file formats. The Emacs distribution contains a formatted text file that can serve as an example. Its name is `etc/enriched.doc'. It contains samples illustrating all the features described in this section. It also contains a list of ideas for future enhancements. * Menu: * Requesting Formatted Text:: Entering and exiting Enriched mode. * Hard and Soft Newlines:: There are two different kinds of newlines. * Editing Format Info:: How to edit text properties. * Faces: Format Faces. Bold, italic, underline, etc. * Color: Format Colors. Changing the color of text. * Indent: Format Indentation. Changing the left and right margins. * Justification: Format Justification. Centering, setting text flush with the left or right margin, etc. * Other: Format Properties. The "special" text properties submenu. * Forcing Enriched Mode:: How to force use of Enriched mode.  File: emacs, Node: Requesting Formatted Text, Next: Hard and Soft Newlines, Up: Formatted Text Requesting to Edit Formatted Text --------------------------------- Whenever you visit a file that Emacs saved in the text/enriched format, Emacs automatically converts the formatting information in the file into Emacs's own internal format (text properties), and turns on Enriched mode. To create a new file of formatted text, first visit the nonexistent file, then type `M-x enriched-mode' before you start inserting text. This command turns on Enriched mode. Do this before you begin inserting text, to ensure that the text you insert is handled properly. More generally, the command `enriched-mode' turns Enriched mode on if it was off, and off if it was on. With a prefix argument, this command turns Enriched mode on if the argument is positive, and turns the mode off otherwise. When you save a buffer while Enriched mode is enabled in it, Emacs automatically converts the text to text/enriched format while writing it into the file. When you visit the file again, Emacs will automatically recognize the format, reconvert the text, and turn on Enriched mode again. Normally, after visiting a file in text/enriched format, Emacs refills each paragraph to fit the specified right margin. You can turn off this refilling, to save time, by setting the variable `enriched-fill-after-visiting' to `nil' or to `ask'. However, when visiting a file that was saved from Enriched mode, there is no need for refilling, because Emacs saves the right margin settings along with the text. You can add annotations for saving additional text properties, which Emacs normally does not save, by adding to `enriched-translations'. Note that the text/enriched standard requires any non-standard annotations to have names starting with `x-', as in `x-read-only'. This ensures that they will not conflict with standard annotations that may be added later.  File: emacs, Node: Hard and Soft Newlines, Next: Editing Format Info, Prev: Requesting Formatted Text, Up: Formatted Text Hard and Soft Newlines ---------------------- In formatted text, Emacs distinguishes between two different kinds of newlines, "hard" newlines and "soft" newlines. Hard newlines are used to separate paragraphs, or items in a list, or anywhere that there should always be a line break regardless of the margins. The command (`newline') and `C-o' (`open-line') insert hard newlines. Soft newlines are used to make text fit between the margins. All the fill commands, including Auto Fill, insert soft newlines--and they delete only soft newlines. Although hard and soft newlines look the same, it is important to bear the difference in mind. Do not use to break lines in the middle of filled paragraphs, or else you will get hard newlines that are barriers to further filling. Instead, let Auto Fill mode break lines, so that if the text or the margins change, Emacs can refill the lines properly. *Note Auto Fill::. On the other hand, in tables and lists, where the lines should always remain as you type them, you can use to end lines. For these lines, you may also want to set the justification style to `unfilled'. *Note Format Justification::.  File: emacs, Node: Editing Format Info, Next: Format Faces, Prev: Hard and Soft Newlines, Up: Formatted Text Editing Format Information -------------------------- There are two ways to alter the formatting information for a formatted text file: with keyboard commands, and with the mouse. The easiest way to add properties to your document is with the Text Properties menu. You can get to this menu in two ways: from the Edit menu in the menu bar (use ` e t' if you have no mouse), or with `C-Mouse-2' (hold the key and press the middle mouse button). There are also keyboard commands described in the following section. Most of the items in the Text Properties menu lead to other submenus. These are described in the sections that follow. Some items run commands directly: `Remove Face Properties' Delete from the region all the text properties that the Text Properties menu works with (`facemenu-remove-face-props'). `Remove All' Delete _all_ text properties from the region (`facemenu-remove-all'). `List Properties' List all the text properties of the character following point (`list-text-properties-at'). `Display Faces' Display a list of all the defined faces (`list-faces-display'). `Display Colors' Display a list of all the defined colors (`list-colors-display').  File: emacs, Node: Format Faces, Next: Format Colors, Prev: Editing Format Info, Up: Formatted Text Faces in Formatted Text ----------------------- The Faces submenu lists various Emacs faces including `bold', `italic', and `underline'. Selecting one of these adds the chosen face to the region. *Note Faces::. You can also specify a face with these keyboard commands: `M-g d' Set the region, or the next inserted character, to the `default' face (`facemenu-set-default'). `M-g b' Set the region, or the next inserted character, to the `bold' face (`facemenu-set-bold'). `M-g i' Set the region, or the next inserted character, to the `italic' face (`facemenu-set-italic'). `M-g l' Set the region, or the next inserted character, to the `bold-italic' face (`facemenu-set-bold-italic'). `M-g u' Set the region, or the next inserted character, to the `underline' face (`facemenu-set-underline'). `M-g o FACE ' Set the region, or the next inserted character, to the face FACE (`facemenu-set-face'). If you use these commands with a prefix argument--or, in Transient Mark mode, if the region is not active--then these commands specify a face to use for your next self-inserting input. *Note Transient Mark::. This applies to both the keyboard commands and the menu commands. Enriched mode defines two additional faces: `excerpt' and `fixed'. These correspond to codes used in the text/enriched file format. The `excerpt' face is intended for quotations. This face is the same as `italic' unless you customize it (*note Face Customization::). The `fixed' face means, "Use a fixed-width font for this part of the text." This makes a visible difference only if you have specified a variable-width font in the default face; however, even if the default font is fixed-width, applying the `fixed' face to a part of the text will cause that part of the text to appear in a fixed-width font, if the file is ever displayed with a variable-width default font. This applies to Emacs and to other systems that display text/enriched format. So if you specifically want a certain part of the text to use a fixed-width font, you should specify the `fixed' face for that part. The `fixed' face is normally set up to use a different font from the default, even if the default face is also fixed-width. Different systems have different fonts installed, so you may need to customize this. *Note Face Customization::. If your terminal cannot display different faces, you will not be able to see them, but you can still edit documents containing faces, and even add faces and colors to documents. The faces you specify will be visible when the file is viewed on a terminal that can display them.  File: emacs, Node: Format Colors, Next: Format Indentation, Prev: Format Faces, Up: Formatted Text Colors in Formatted Text ------------------------ You can specify foreground and background colors for portions of the text. There is a menu for specifying the foreground color and a menu for specifying the background color. Each color menu lists all the colors that you have used in Enriched mode in the current Emacs session. If you specify a color with a prefix argument--or, in Transient Mark mode, if the region is not active--then it applies to your next self-inserting input. *Note Transient Mark::. Otherwise, the command applies to the region. Each color menu contains one additional item: `Other'. You can use this item to specify a color that is not listed in the menu; it reads the color name with the minibuffer. To display list of available colors and their names, use the `Display Colors' menu item in the Text Properties menu (*note Editing Format Info::). Any color that you specify in this way, or that is mentioned in a formatted text file that you read in, is added to both color menus for the duration of the Emacs session. There are no key bindings for specifying colors, but you can do so with the extended commands `M-x facemenu-set-foreground' and `M-x facemenu-set-background'. Both of these commands read the name of the color with the minibuffer.  File: emacs, Node: Format Indentation, Next: Format Justification, Prev: Format Colors, Up: Formatted Text Indentation in Formatted Text ----------------------------- When editing formatted text, you can specify different amounts of indentation for the right or left margin of an entire paragraph or a part of a paragraph. The margins you specify automatically affect the Emacs fill commands (*note Filling::) and line-breaking commands. The Indentation submenu provides a convenient interface for specifying these properties. The submenu contains four items: `Indent More' Indent the region by 4 columns (`increase-left-margin'). In Enriched mode, this command is also available on `C-x '; if you supply a numeric argument, that says how many columns to add to the margin (a negative argument reduces the number of columns). `Indent Less' Remove 4 columns of indentation from the region. `Indent Right More' Make the text narrower by indenting 4 columns at the right margin. `Indent Right Less' Remove 4 columns of indentation from the right margin. You can use these commands repeatedly to increase or decrease the indentation. The most common way to use these commands is to change the indentation of an entire paragraph. However, that is not the only use. You can change the margins at any point; the new values take effect at the end of the line (for right margins) or the beginning of the next line (for left margins). This makes it possible to format paragraphs with "hanging indents", which means that the first line is indented less than subsequent lines. To set up a hanging indent, increase the indentation of the region starting after the first word of the paragraph and running until the end of the paragraph. Indenting the first line of a paragraph is easier. Set the margin for the whole paragraph where you want it to be for the body of the paragraph, then indent the first line by inserting extra spaces or tabs. Sometimes, as a result of editing, the filling of a paragraph becomes messed up--parts of the paragraph may extend past the left or right margins. When this happens, use `M-q' (`fill-paragraph') to refill the paragraph. The variable `standard-indent' specifies how many columns these commands should add to or subtract from the indentation. The default value is 4. The overall default right margin for Enriched mode is controlled by the variable `fill-column', as usual. The fill prefix, if any, works in addition to the specified paragraph indentation: `C-x .' does not include the specified indentation's whitespace in the new value for the fill prefix, and the fill commands look for the fill prefix after the indentation on each line. *Note Fill Prefix::.  File: emacs, Node: Format Justification, Next: Format Properties, Prev: Format Indentation, Up: Formatted Text Justification in Formatted Text ------------------------------- When editing formatted text, you can specify various styles of justification for a paragraph. The style you specify automatically affects the Emacs fill commands. The Justification submenu provides a convenient interface for specifying the style. The submenu contains five items: `Flush Left' This is the most common style of justification (at least for English). Lines are aligned at the left margin but left uneven at the right. `Flush Right' This aligns each line with the right margin. Spaces and tabs are added on the left, if necessary, to make lines line up on the right. `Full' This justifies the text, aligning both edges of each line. Justified text looks very nice in a printed book, where the spaces can all be adjusted equally, but it does not look as nice with a fixed-width font on the screen. Perhaps a future version of Emacs will be able to adjust the width of spaces in a line to achieve elegant justification. `Center' This centers every line between the current margins. `None' This turns off filling entirely. Each line will remain as you wrote it; the fill and auto-fill functions will have no effect on text which has this setting. You can, however, still indent the left margin. In unfilled regions, all newlines are treated as hard newlines (*note Hard and Soft Newlines::) . In Enriched mode, you can also specify justification from the keyboard using the `M-j' prefix character: `M-j l' Make the region left-filled (`set-justification-left'). `M-j r' Make the region right-filled (`set-justification-right'). `M-j f' Make the region fully-justified (`set-justification-full'). `M-j c' `M-S' Make the region centered (`set-justification-center'). `M-j u' Make the region unfilled (`set-justification-none'). Justification styles apply to entire paragraphs. All the justification-changing commands operate on the paragraph containing point, or, if the region is active, on all paragraphs which overlap the region. The default justification style is specified by the variable `default-justification'. Its value should be one of the symbols `left', `right', `full', `center', or `none'.  File: emacs, Node: Format Properties, Next: Forcing Enriched Mode, Prev: Format Justification, Up: Formatted Text Setting Other Text Properties ----------------------------- The Other Properties menu lets you add or remove three other useful text properties: `read-only', `invisible' and `intangible'. The `intangible' property disallows moving point within the text, the `invisible' text property hides text from display, and the `read-only' property disallows alteration of the text. Each of these special properties has a menu item to add it to the region. The last menu item, `Remove Special', removes all of these special properties from the text in the region. Currently, the `invisible' and `intangible' properties are _not_ saved in the text/enriched format. The `read-only' property is saved, but it is not a standard part of the text/enriched format, so other editors may not respect it.  File: emacs, Node: Forcing Enriched Mode, Prev: Format Properties, Up: Formatted Text Forcing Enriched Mode --------------------- Normally, Emacs knows when you are editing formatted text because it recognizes the special annotations used in the file that you visited. However, there are situations in which you must take special actions to convert file contents or turn on Enriched mode: * When you visit a file that was created with some other editor, Emacs may not recognize the file as being in the text/enriched format. In this case, when you visit the file you will see the formatting commands rather than the formatted text. Type `M-x format-decode-buffer' to translate it. * When you _insert_ a file into a buffer, rather than visiting it. Emacs does the necessary conversions on the text which you insert, but it does not enable Enriched mode. If you wish to do that, type `M-x enriched-mode'. The command `format-decode-buffer' translates text in various formats into Emacs's internal format. It asks you to specify the format to translate from; however, normally you can type just , which tells Emacs to guess the format. If you wish to look at text/enriched file in its raw form, as a sequence of characters rather than as formatted text, use the `M-x find-file-literally' command. This visits a file, like `find-file', but does not do format conversion. It also inhibits character code conversion (*note Coding Systems::) and automatic uncompression (*note Compressed Files::). To disable format conversion but allow character code conversion and/or automatic uncompression if appropriate, use `format-find-file' with suitable arguments.  File: emacs, Node: Programs, Next: Building, Prev: Text, Up: Top Editing Programs **************** Emacs provides many features to facilitate editing programs. Some of these features can * Find or move over top-level definitions (*note Defuns::). * Apply the usual indentation conventions of the language (*note Program Indent::). * Insert, kill or align comments (*note Comments::). * Balance parentheses (*note Parentheses::). * Highlight program syntax (*note Font Lock::). This chapter describes these features and many more. * Menu: * Program Modes:: Major modes for editing programs. * Defuns:: Commands to operate on major top-level parts of a program. * Program Indent:: Adjusting indentation to show the nesting. * Comments:: Inserting, killing, and aligning comments. * 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. * 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.  File: emacs, Node: Program Modes, Next: Defuns, Up: Programs Major Modes for Programming Languages ===================================== Emacs has specialized major modes for various programming languages. *Note Major Modes::. A programming language major mode typically specifies the syntax of expressions, the customary rules for indentation, how to do syntax highlighting for the language, and how to find the beginning of a function definition. It often customizes or provides facilities for compiling and debugging programs as well. Ideally, Emacs should provide a major mode for each programming language that you might want to edit; if it doesn't have a mode for your favorite language, you can contribute one. But often the mode for one language can serve for other syntactically similar languages. The major mode for language L is called `L-mode', and you can select it by typing `M-x L-mode '. *Note Choosing Modes::. 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 format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (TeX's companion for font creation), Modula2, Objective-C, Octave, Pascal, 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 GNU and Unix shells, VMS DCL, and MS-DOS/MS-Windows `BAT' files. There are also major modes for editing various sorts of configuration files. 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 to update the indentation of the current line. They also rebind 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 `C-b C-d' to delete a tab character before point, in these modes. Separate manuals are available for the modes for Ada (*note Ada Mode: (ada-mode)Top.), C/C++/Objective C/Java/Corba IDL (*note CC Mode: (ccmode)Top.) and the IDLWAVE modes (*note IDLWAVE: (idlwave)Top.). Turning on a major mode runs a normal hook called the "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 `-hook'. For example, turning on C mode runs the hook `c-mode-hook', while turning on Lisp mode runs the hook `lisp-mode-hook'. The purpose of the mode hook is to give you a place to set up customizations for that major mode. *Note Hooks::.  File: emacs, Node: Defuns, Next: Program Indent, Prev: Program Modes, Up: Programs Top-Level Definitions, or Defuns ================================ In Emacs, a major definition at the top level in the buffer is called a "defun". The name comes from Lisp, but in Emacs we use it for all languages. 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. However, some language modes provide their own code for recognizing defuns in a way that suits the language syntax and conventions better. * 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.  File: emacs, Node: Left Margin Paren, Next: Moving by Defuns, Up: Defuns Left Margin Convention ---------------------- 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, *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 (*note Program Indent::) and Font Lock mode (*note 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 (`\', in C and Emacs Lisp, `/' 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: (insert "Foo: \(bar) ") 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.  File: emacs, Node: Moving by Defuns, Next: Imenu, Prev: Left Margin Paren, Up: Defuns Moving by Defuns ---------------- These commands move point or set up the region based on top-level major definitions, also called "defuns". `C-M-a' Move to beginning of current or preceding defun (`beginning-of-defun'). `C-M-e' Move to end of current or following defun (`end-of-defun'). `C-M-h' Put region around whole current or following defun (`mark-defun'). The commands to move to the beginning and end of the current defun are `C-M-a' (`beginning-of-defun') and `C-M-e' (`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. `C-M-a' with a negative argument -N moves forward N times to the next beginning of a defun. This is not exactly the same place that `C-M-e' with argument 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, `C-M-e' with a negative argument moves back to an end of a defun, which is not quite the same as `C-M-a' with a positive argument. To operate on the current defun, use `C-M-h' (`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, `C-M-h' runs the function `c-mark-function', which is almost the same as `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.  File: emacs, Node: Imenu, Next: Which Function, Prev: Moving by Defuns, Up: Defuns Imenu ----- The Imenu facility offers a way to find the 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. (*Note Tags::, for a more powerful feature that handles multiple files together.) If you type `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. Alternatively, you can bind the command `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 `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 `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. 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 `*Rescan*' item in the menu. Rescanning happens automatically if you set `imenu-auto-rescan' to a non-`nil' value. There is no need to rescan because of small changes in the text. You can customize the way the menus are sorted by setting the variable `imenu-sort-function'. By default, names are ordered as they occur in the buffer; if you want alphabetic sorting, use the symbol `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 (*note Which Function::). The Speedbar can also use it (*note Speedbar::).  File: emacs, Node: Which Function, Prev: Imenu, Up: Defuns Which Function Mode ------------------- 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. To enable (or disable) Which Function mode, use the command `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 `which-func-modes'. If the value is `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.  File: emacs, Node: Program Indent, Next: Comments, Prev: Defuns, Up: Programs Indentation for Programs ======================== The best way to keep a program properly indented is to use Emacs to reindent it as you change it. Emacs has commands to indent properly either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping. * Menu: * Basic Indent:: Indenting a single line. * Multi-line Indent:: Commands to reindent many lines at once. * Lisp Indent:: Specifying how each Lisp function should be indented. * C Indent:: Extra features for indenting C and related modes. * Custom C Indent:: Controlling indentation style for C and related modes. Emacs also provides a Lisp pretty-printer in the library `pp'. This program reformats a Lisp object with indentation chosen to look nice.  File: emacs, Node: Basic Indent, Next: Multi-line Indent, Up: Program Indent Basic Program Indentation Commands ---------------------------------- The basic indentation commands indent a single line according to the usual conventions of the language you are editing. `' Adjust indentation of current line. `C-j' Equivalent to followed by (`newline-and-indent'). `' This key, if the keyboard has it, is another way to enter `C-j'. The basic indentation command is , which gives the current line the correct indentation as determined from the previous lines. The function that runs depends on the major mode; it is `indent-for-tab-command' in Lisp mode, `c-indent-command' in C mode, etc. These functions understand the syntax and conventions of different languages, but they all do conceptually the same job: in any programming-language major mode inserts or deletes whitespace at the beginning of the current line, independent of where point is in the line. If point was inside the whitespace at the beginning of the line, puts it at the end of that whitespace; otherwise, keeps point fixed with respect to the characters around it. Use `C-q ' to insert a tab at point. When entering lines of new code, use `C-j' (`newline-and-indent'), which is equivalent to a followed by a . `C-j' at the end of a line creates a blank line and then gives it the appropriate indentation. 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 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. *Note 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 *Note Just Spaces::.  File: emacs, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Program Indent Indenting Several Lines ----------------------- 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. `C-M-q' Reindent all the lines within one parenthetical grouping(`indent-sexp'). `C-M-\' Reindent all lines in the region (`indent-region'). `C-u ' Shift an entire parenthetical grouping rigidly sideways so that its first line is properly indented. `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. You can reindent the contents of a single parenthetical grouping by positioning point before the beginning of it and typing `C-M-q' (`indent-sexp' in Lisp mode, `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 first. Another way to specify the range to be reindented is with the region. The command `C-M-\' (`indent-region') applies 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 `C-u ' to reindent the whole grouping as a rigid unit. (This works in Lisp modes and C and related modes.) 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, or C preprocessor lines when in C mode. You can also perform this operation on the region, using the command `M-x indent-code-rigidly'. It rigidly shifts all the lines in the region sideways, like `indent-rigidly' does (*note Indentation Commands::). It doesn't alter the indentation of lines that start inside a comment or a string, unless the region starts inside that comment or string.  File: emacs, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Program Indent Customizing Lisp Indentation ---------------------------- The indentation pattern for a Lisp expression can depend on the function called by the expression. For each Lisp function, you can choose among several predefined patterns of indentation, or define an arbitrary one with a Lisp program. The standard pattern of indentation is as follows: the second line of the expression is indented under the first argument, if that is on the same line as the beginning of the expression; otherwise, the second line is indented underneath the function name. Each following line is indented under the previous line whose nesting depth is the same. If the variable `lisp-indent-offset' is non-`nil', it overrides the usual indentation pattern for the second line of an expression, so that such lines are always indented `lisp-indent-offset' more columns than the containing list. Certain functions override the standard pattern. Functions whose names start with `def' treat the the second lines as the start of a "body", by indenting the second line `lisp-body-indent' additional columns beyond the open-parenthesis that starts the expression. You can override the standard pattern in various ways for individual functions, according to the `lisp-indent-function' property of the function name. There are four possibilities for this property: `nil' This is the same as no property--use the standard indentation pattern. `defun' Handle this function like a `def' construct: treat the second line as the start of a "body". a number, NUMBER The first NUMBER arguments of the function are "distinguished" arguments; the rest are considered the 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 `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 _twice_ that many extra columns. If the argument is distinguished and not the first or second argument, the line uses the standard pattern. a symbol, SYMBOL 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: STATE The value returned by `parse-partial-sexp' (a Lisp primitive for indentation and nesting computation) when it parses up to the beginning of this line. POS The position at which the line being indented begins. 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 `C-M-q'; if the value is a number, `C-M-q' need not recalculate indentation for the following lines until the end of the list.