diff options
Diffstat (limited to 'doc/emacs')
| -rw-r--r-- | doc/emacs/ChangeLog | 118 | ||||
| -rw-r--r-- | doc/emacs/building.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/cmdargs.texi | 33 | ||||
| -rw-r--r-- | doc/emacs/custom.texi | 11 | ||||
| -rw-r--r-- | doc/emacs/display.texi | 142 | ||||
| -rw-r--r-- | doc/emacs/emacs.texi | 56 | ||||
| -rw-r--r-- | doc/emacs/emacsver.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/files.texi | 10 | ||||
| -rw-r--r-- | doc/emacs/frames.texi | 660 | ||||
| -rw-r--r-- | doc/emacs/glossary.texi | 16 | ||||
| -rw-r--r-- | doc/emacs/indent.texi | 386 | ||||
| -rw-r--r-- | doc/emacs/modes.texi | 259 | ||||
| -rw-r--r-- | doc/emacs/programs.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/rmail.texi | 16 | ||||
| -rw-r--r-- | doc/emacs/text.texi | 1485 | ||||
| -rw-r--r-- | doc/emacs/windows.texi | 6 | ||||
| -rw-r--r-- | doc/emacs/xresources.texi | 62 |
17 files changed, 1563 insertions, 1703 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 6e687bcefc9..d16443ccf31 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,121 @@ +2011-12-03 Chong Yidong <cyd@gnu.org> + + * text.texi (TeX Mode): Mention AUCTeX package. + (TeX Editing): Add xref to documentation for Occur. + (LaTeX Editing): Add xref to Completion node. + (TeX Print): Fix description of tex-directory. + (Enriched Text): Renamed from Formatted Text. Make this node and + its subnodes less verbose, since text/enriched files are + practically unused. + (Enriched Mode): Renamed from Requesting Formatted Text. + (Format Colors): Node deleted. + (Enriched Faces): Renamed from Format Faces. Describe commands + for applying colors too. + (Forcing Enriched Mode): Node deleted; merged into Enriched Mode. + + * frames.texi (Menu Mouse Clicks): Tweak description of C-Mouse-2. + + * display.texi (Colors): New node. + + * cmdargs.texi (Colors X): + * xresources.texi (GTK styles): + * custom.texi (Face Customization): Reference it. + + * glossary.texi (Glossary): Remove "formatted text" and "WYSIWYG". + Link to Fill Commands for Justification entry. + +2011-12-03 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Auto Scrolling): More accurate description of what + scroll-*-aggressively does, including the effect of non-zero + margin. Fix "i.e." markup. + +2011-12-02 Chong Yidong <cyd@gnu.org> + + * text.texi (Pages): Mention how formfeed chars are displayed. + (Auto Fill): Note convention for calling auto-fill-mode from Lisp. + Describe adaptive filling more precisely. + (Fill Commands): Note that filling removes excess whitespace. + (Text Mode): Note auto-mode-alist entries for Text mode. TAB is + now bound to indent-for-tab-command in Text mode. + (Outline Mode): Copyedits. + (Outline Visibility): Note that Reveal mode is a buffer-local + minor mode. + + * modes.texi (Major Modes): Move note about checking major-mode in + a hook function here, from Text mode. + +2011-11-28 Chong Yidong <cyd@gnu.org> + + * text.texi (Words): Add xref to Position Info. + (Paragraphs): Add xref to Regexps. + + * indent.texi (Indentation): Rewrite introduction. Move table to + Indentation Commands node. + (Indentation Commands): Add index entries to table. Copyedits. + (Tab Stops, Just Spaces): Copyedits. + (Indent Convenience): New node. Document electric-indent-mode. + + * programs.texi (Basic Indent): + * windows.texi (Pop Up Window): Fix kindex entry. + +2011-11-28 Chong Yidong <cyd@gnu.org> + + * modes.texi (Major Modes): Move major-mode variable doc here from + Choosing Modes. Document describe-mode. Document prog-mode-hook + and text-mode-hook. Add example of using hooks. + (Minor Modes): Document behavior of mode command calls from Lisp. + Note that setting the mode variable using Customize will DTRT. + (Choosing Modes): Add example of setting a minor mode using a + local variable. + +2011-11-27 Chong Yidong <cyd@gnu.org> + + * frames.texi (Creating Frames): Move frame parameter example to + Frame Parameters node. + (Frame Commands): C-x 5 o does not warp the mouse by default. + (Fonts): Add more GTK-style properties; also, they should be + capitalized. + (Special Buffer Frames): Node deleted; special-display is on the + way out. + (Frame Parameters): Example moved here from Creating Frames. + Clarify that default-frame-alist affects the initial frame too. + Delete auto-raise-mode and auto-lower-mode. + (Wheeled Mice): Node deleted. Content moved to Mouse Commands. + (Dialog Boxes): Delete x-gtk-use-old-file-dialog. + + * windows.texi (Window Choice): Add xref to Lisp manual for + special-display-*. + +2011-11-26 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Text Display): Update the description, + cross-references, and indexing related to display of control + characters and raw bytes. + +2011-11-25 Chong Yidong <cyd@gnu.org> + + * frames.texi (Frames): Rewrite introduction. + (Mouse Commands): Default for mouse-drag-copy-region is now t. + Mouse-3 does not copy to kill ring by default. DEL does not + behave specially for mouse commands any more. + (Mouse References): Document mouse-1-click-follows-link more + thoroughly. + (Menu Mouse Clicks): Move footnote to the main text and add xref + to Init Rebinding node. + (Mode Line Mouse): Mouse-3 on the mode-line does not bury buffer. + + * files.texi (Visiting): `C-x 5 f' works on ttys too. + +2011-11-24 Juanma Barranquero <lekktu@gmail.com> + + * display.texi (Font Lock): Fix typo. + +2011-11-24 Glenn Morris <rgm@gnu.org> + + * rmail.texi (Rmail Output): + Mention rmail-automatic-folder-directives. (Bug#9657) + 2011-11-21 Chong Yidong <cyd@gnu.org> * mark.texi (Global Mark Ring): Fix description of global mark diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index ac62e2d9652..9c5b2e7dcd7 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -995,7 +995,7 @@ breakpoint}, the breakpoint which point is on. Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}). On a graphical display, this changes the color of a bullet in the margin of a source buffer at the relevant line. This is red when -the breakpoint is enabled and grey when it is disabled. Text-only +the breakpoint is enabled and gray when it is disabled. Text-only terminals correspondingly display a @samp{B} or @samp{b}. @item D diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 07cca53ce4d..d9109045570 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -69,7 +69,7 @@ arguments.) * Environment:: Environment variables that Emacs uses. * Display X:: Changing the default display and using remote login. * Font X:: Choosing a font for text, under X. -* Colors:: Choosing display colors. +* Colors X:: Choosing display colors. * Window Size X:: Start-up window size, under X. * Borders X:: Internal and external borders, under X. * Title X:: Specifying the initial frame's title. @@ -784,7 +784,7 @@ Use @var{font} as the default font. When passing a font specification to Emacs on the command line, you may need to ``quote'' it, by enclosing it in quotation marks, if it -contains characters that the shell treats specially (e.g. spaces). +contains characters that the shell treats specially (e.g.@: spaces). For example: @smallexample @@ -794,27 +794,14 @@ emacs -fn "DejaVu Sans Mono-12" @xref{Fonts}, for other ways to specify the default font and font name formats. -@node Colors +@node Colors X @appendixsec Window Color Options @cindex color of window, from command line @cindex text colors, from command line -@findex list-colors-display -@cindex available colors - On a color display, you can specify which color to use for various -parts of the Emacs display. To find out what colors are available on -your system, type @kbd{M-x list-colors-display}, or press -@kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu. -(A particular window system might support many more colors, but the -list displayed by @code{list-colors-display} shows their portable -subset that can be safely used on any display supported by Emacs.) -If you do not specify colors, on windowed displays the default for the -background is white and the default for all other colors is black. On a -monochrome display, the foreground is black, the background is white, -and the border is gray if the display supports that. On terminals, the -background is usually black and the foreground is white. - - Here is a list of the command-line options for specifying colors: + You can use the following command-line options to specify the colors +to use for various parts of the Emacs display. Colors may be +specified using either color names or RGB triplets (@pxref{Colors}). @table @samp @item -fg @var{color} @@ -822,15 +809,15 @@ background is usually black and the foreground is white. @itemx --foreground-color=@var{color} @opindex --foreground-color @cindex foreground color, command-line argument -Specify the foreground color. @var{color} should be a standard color -name, or a numeric specification of the color's red, green, and blue -components as in @samp{#4682B4} or @samp{RGB:46/82/B4}. +Specify the foreground color, overriding the color specified by the +@code{default} face (@pxref{Faces}). @item -bg @var{color} @opindex -bg @itemx --background-color=@var{color} @opindex --background-color @cindex background color, command-line argument -Specify the background color. +Specify the background color, overriding the color specified by the +@code{default} face. @item -bd @var{color} @opindex -bd @itemx --border-color=@var{color} diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 5b98216369d..e807aebdeee 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -430,15 +430,8 @@ means that it's disabled. You can enable or disable the attribute by clicking that button. When the attribute is enabled, you can change the attribute value in the usual ways. - You can specify a color name (use @kbd{M-x list-colors-display} for -a list of them) or a hexadecimal color specification of the form -@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black, -@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is -blue, and @samp{#ffffff} is white.) On a black-and-white display, the -colors you can use for the background are @samp{black}, @samp{white}, -@samp{gray}, @samp{gray1}, and @samp{gray3}. Emacs supports these -shades of gray by using background stipple patterns instead of a -color. + The foreground and background colors can be specified using color +names or RGB triplets. @xref{Colors}. Setting, saving and resetting a face work like the same operations for variables (@pxref{Changing a Variable}). diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 8995b1242b1..ea9bd95b8ee 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -21,6 +21,7 @@ the text is displayed. * View Mode:: Viewing read-only buffers. * Follow Mode:: Follow mode lets two windows scroll as one. * Faces:: How to change the display style using faces. +* Colors:: Specifying colors for faces. * Standard Faces:: Emacs' predefined faces. * Text Scale:: Increasing or decreasing text size in a buffer. * Font Lock:: Minor mode for syntactic highlighting using faces. @@ -122,7 +123,7 @@ moving it to the topmost or bottommost line. With any other non-@code{nil} value, Emacs adjusts point this way even if the scroll command leaves point in the window. This variable affects all the scroll commands documented in this section, as well as scrolling with -the mouse wheel (@pxref{Wheeled Mice}); in general, it affects any +the mouse wheel (@pxref{Mouse Commands}); in general, it affects any command that has a non-@code{nil} @code{scroll-command} property. @xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}. @@ -238,26 +239,32 @@ centered after scrolling. @cindex aggressive scrolling @vindex scroll-up-aggressively @vindex scroll-down-aggressively - When the window does scroll by a longer distance, you can control -how aggressively it scrolls by setting the variables -@code{scroll-up-aggressively} and @code{scroll-down-aggressively}. -The value of @code{scroll-up-aggressively} should be either -@code{nil}, or a fraction @var{f} between 0 and 1. A fraction -specifies where on the screen to put point when scrolling upward, -i.e. forward. When point goes off the window end, the new start -position is chosen to put point @var{f} parts of the window height -from the bottom. Thus, larger @var{f} means more aggressive -scrolling: more new text is brought into view. The default value, -@code{nil}, is equivalent to 0.5. + When the window does scroll by a distance longer than +@code{scroll-step}, you can control how aggressively it scrolls by +setting the variables @code{scroll-up-aggressively} and +@code{scroll-down-aggressively}. The value of +@code{scroll-up-aggressively} should be either @code{nil}, or a +fraction @var{f} between 0 and 1. A fraction specifies where on the +screen to put point when scrolling upward, i.e.@: forward. When point +goes off the window end, the new start position is chosen to put point +@var{f} parts of the window height from the bottom margin. Thus, +larger @var{f} means more aggressive scrolling: more new text is +brought into view. The default value, @code{nil}, is equivalent to +0.5. Likewise, @code{scroll-down-aggressively} is used for scrolling -down, i.e. backward. The value specifies how far point should be -placed from the top of the window; thus, as with +down, i.e.@: backward. The value specifies how far point should be +placed from the top margin of the window; thus, as with @code{scroll-up-aggressively}, a larger value is more aggressive. These two variables are ignored if either @code{scroll-step} or @code{scroll-conservatively} are set to a non-zero value. + Note that @code{scroll-margin}, described below, limits the amount +of scrolling so as to put point outside of the top or bottom margin, +even if aggressive scrolling specifies a fraction @var{f} that is +larger than the window portion between the top and the bottom margins. + @vindex scroll-margin The variable @code{scroll-margin} restricts how close point can come to the top or bottom of a window. Its value is a number of screen @@ -455,7 +462,7 @@ one large window. To turn off Follow mode, type @kbd{M-x follow-mode} a second time. @node Faces -@section Faces: Controlling Text Display Style +@section Text Faces @cindex faces Emacs can display text in several different styles, called @@ -474,10 +481,8 @@ matching that regular expression (@pxref{Regexps}). It's possible for a given face to look different in different frames. For instance, some text-only terminals do not support all face attributes, particularly font, height, and width, and some -support a limited range of colors. The @code{list-faces-display} -command shows the appearance for the selected frame. +support a limited range of colors. -@cindex face colors, setting @cindex background color @cindex default face You can customize a face to alter its appearance, and save those @@ -492,25 +497,58 @@ background color. You can also use X resources to specify attributes of any particular face. @xref{Resources}. + Emacs can display variable-width fonts, but some Emacs commands, +particularly indentation commands, do not account for variable +character display widths. Therefore, we recommend not using +variable-width fonts for most faces, particularly those assigned by +Font Lock mode. + +@node Colors +@section Colors for Faces +@cindex color name +@cindex RGB triplet + + Faces can have various foreground and background colors. When you +specify a color for a face---for instance, when customizing the face +(@pxref{Face Customization})---you can use either a @dfn{color name} +or an @dfn{RGB triplet}. + +@findex list-colors-display + A color name is a pre-defined name, such as @samp{dark orange} or +@samp{medium sea green}. To view a list of color names, type @kbd{M-x +list-colors-display}. If you run this command on a graphical display, +it shows the full range of color names known to Emacs (these are the +standard X11 color names, defined in X's @file{rgb.txt} file). If you +run the command on a text-only terminal, it shows only a small subset +of colors that can be safely displayed on such terminals. However, +Emacs understands X11 color names even on text-only terminals; if a +face is given a color specified by an X11 color name, it is displayed +using the closest-matching terminal color. + + An RGB triplet is a string of the form @samp{#RRGGBB}. Each of the +R, G, and B components is a hexadecimal number specifying the +component's relative intensity, one to four digits long (usually two +digits are used). The components must have the same number of digits. +For hexadecimal values A to F, either upper or lower case are +acceptable. + + The @kbd{M-x list-colors-display} command also shows the equivalent +RGB triplet for each named color. For instance, @samp{medium sea +green} is equivalent to @samp{#3CB371}. + +@cindex face colors, setting @findex set-face-foreground @findex set-face-background - You can also change the foreground and background colors of a face -with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}. -These commands prompt in the minibuffer for a face name and a color -name, with completion, and then set that face to use the specified -color (@pxref{Face Customization}, for information about color names). + You can change the foreground and background colors of a face with +@kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}. +These commands prompt in the minibuffer for a face name and a color, +with completion, and then set that face to use the specified color. They affect the face colors on all frames, but their effects do not persist for future Emacs sessions, unlike using the customization buffer or X resources. You can also use frame parameters to set -foreground and background colors for a specific frame; see @ref{Frame +foreground and background colors for a specific frame; @xref{Frame Parameters}. - Emacs can display variable-width fonts, but some Emacs commands, -particularly indentation commands, do not account for variable -character display widths. Therefore, we recommend not using -variable-width fonts for most faces, particularly those assigned by -Font Lock mode. - @node Standard Faces @section Standard Faces @@ -762,7 +800,7 @@ relies on analysis of the syntactic structure of the buffer text. For the sake of speed, some modes, including Lisp mode, rely on a special convention: an open-parenthesis or open-brace in the leftmost column always defines the beginning of a defun, and is thus always outside -any string or comment. Therefore, you should avoid placing a an +any string or comment. Therefore, you should avoid placing an open-parenthesis or open-brace in the leftmost column, if it is inside a string or comment. @xref{Left Margin Paren}, for details. @@ -1016,13 +1054,13 @@ trailing whitespace in the region instead. @cindex fringes, and unused line indication On graphical displays, Emacs can indicate unused lines at the end of the window with a small image in the left fringe (@pxref{Fringes}). -The image appears for window lines that do not correspond to any -buffer text. Blank lines at the end of the buffer then stand out -because they do not have this image in the fringe. To enable this -feature, set the buffer-local variable @code{indicate-empty-lines} to -a non-@code{nil} value. You can enable or disable this feature for -all new buffers by setting the default value of this variable, -e.g.@:@code{(setq-default indicate-empty-lines t)}. +The image appears for screen lines that do not correspond to any +buffer text, so blank lines at the end of the buffer stand out because +they lack this image. To enable this feature, set the buffer-local +variable @code{indicate-empty-lines} to a non-@code{nil} value. You +can enable or disable this feature for all new buffers by setting the +default value of this variable, e.g.@: @code{(setq-default +indicate-empty-lines t)}. @node Selective Display @section Selective Display @@ -1216,7 +1254,7 @@ characters include @acronym{ASCII} numbers, letters, and punctuation characters, as well as many non-@acronym{ASCII} characters. @vindex tab-width -@cindex control character +@cindex control characters on display The @acronym{ASCII} character set contains non-printing @dfn{control characters}. Two of these are displayed specially: the newline character (Unicode code point @code{U+000A}) is displayed by starting @@ -1228,19 +1266,21 @@ value between 1 and 1000, inclusive. Note that how the tab character in the buffer is displayed has nothing to do with the definition of @key{TAB} as a command. - Other @acronym{ASCII} control characters are displayed as a caret + Other @acronym{ASCII} control characters, whose codes are below +@code{U+0020} (octal 40, decimal 32), are displayed as a caret (@samp{^}) followed by the non-control version of the character, with the @code{escape-glyph} face. For instance, the @samp{control-A} character, @code{U+0001}, is displayed as @samp{^A}. +@cindex octal escapes @vindex ctl-arrow - The non-@acronym{ASCII}, non-printing characters @code{U+0080} -(octal 200) through @code{U+009F} (octal 237) are displayed as octal -escape sequences, with the @code{escape-glyph} face. For instance, + The raw bytes with codes @code{U+0080} (octal 200) through +@code{U+009F} (octal 237) are displayed as @dfn{octal escape +sequences}, with the @code{escape-glyph} face. For instance, character code @code{U+0098} (octal 230) is displayed as @samp{\230}. If you change the buffer-local variable @code{ctl-arrow} to -@code{nil}, @acronym{ASCII} control characters are also displayed as -octal escape sequences instead of caret escape sequences. +@code{nil}, the @acronym{ASCII} control characters are also displayed +as octal escape sequences instead of caret escape sequences. @vindex nobreak-char-display @cindex non-breaking space @@ -1249,7 +1289,7 @@ octal escape sequences instead of caret escape sequences. Some non-@acronym{ASCII} characters have the same appearance as an @acronym{ASCII} space or hyphen (minus) character. Such characters can cause problems if they are entered into a buffer without your -realization, e.g. by yanking; for instance, source code compilers +realization, e.g.@: by yanking; for instance, source code compilers typically do not treat non-@acronym{ASCII} spaces as whitespace characters. To deal with this problem, Emacs displays such characters specially: it displays @code{U+00A0} (no-break space) with the @@ -1270,10 +1310,12 @@ elisp, The Emacs Lisp Reference Manual}. On graphical displays, some characters may have no glyphs in any of the fonts available to Emacs. These @dfn{glyphless characters} are normally displayed as boxes containing the hexadecimal character code. -You can control the display method by customizing the variable -@code{glyphless-char-display-control}. @xref{Glyphless Chars,, -Glyphless Character Display, elisp, The Emacs Lisp Reference Manual}, -for details. +Similarly, on text terminals, characters that cannot be displayed +using the terminal encoding (@pxref{Terminal Coding}) are normally +displayed as question signs. You can control the display method by +customizing the variable @code{glyphless-char-display-control}. +@xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs +Lisp Reference Manual}, for details. @node Cursor Display @section Displaying the Cursor diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 55fdb9ec875..aca3735ff03 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -113,25 +113,6 @@ Emacs Lisp Reference Manual}. @insertcopying @end ifnottex -@ignore -These subcategories have been deleted for simplicity -and to avoid conflicts. -Completion -Backup Files -Auto-Saving: Protection Against Disasters -Tags -Text Mode -Outline Mode -@TeX{} Mode -Formatted Text -Shell Command History - -The ones for Dired and Rmail have had the items turned into :: items -to avoid conflicts. -Also Running Shell Commands from Emacs -and Sending Mail and Registers and Minibuffer. -@end ignore - @menu * Distrib:: How to get the latest Emacs distribution. * Intro:: An introduction to Emacs concepts. @@ -350,6 +331,7 @@ Controlling the Display * View Mode:: Viewing read-only buffers. * Follow Mode:: Follow mode lets two windows scroll as one. * Faces:: How to change the display style using faces. +* Colors:: Specifying colors for faces. * Standard Faces:: Emacs' predefined faces. * Text Scale:: Increasing or decreasing text size in a buffer. * Font Lock:: Minor mode for syntactic highlighting using faces. @@ -505,10 +487,8 @@ Frames and Graphical Displays * Fonts:: Changing the frame font. * Speedbar:: How to make and use a speedbar frame. * Multiple Displays:: How one Emacs job can talk to several displays. -* Special Buffer Frames:: You can make certain buffers have their own frames. * Frame Parameters:: Changing the colors and other modes of frames. * Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Wheeled Mice:: Using mouse wheels for scrolling. * Drag and Drop:: Using drag and drop to open files and insert text. * Menu Bars:: Enabling and disabling the menu bar. * Tool Bars:: Enabling and disabling the tool bar. @@ -553,10 +533,10 @@ Modes Indentation -* Indentation Commands:: Various commands and techniques for indentation. -* Tab Stops:: You can set arbitrary "tab stops" and then - indent to the next tab stop when you want to. -* Just Spaces:: You can request indentation using just spaces. +* Indentation Commands:: More commands for performing indentation. +* Tab Stops:: Stop points for indentation in Text modes. +* Just Spaces:: Using only space characters for indentation. +* Indent Convenience:: Optional indentation features. Commands for Human Languages @@ -571,8 +551,8 @@ Commands for Human Languages * TeX Mode:: Editing input to the formatter TeX. * HTML Mode:: Editing HTML and SGML files. * Nroff Mode:: Editing input to the formatter nroff. -* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. -* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. +* Enriched Text:: Editing text ``enriched'' with fonts, colors, etc. +* Text Based Tables:: Commands for editing text-based tables. * Two-Column:: Splitting text columns into separate windows. Filling Text @@ -599,18 +579,16 @@ Outline Mode * TeX Print:: Commands for printing part of a file with TeX. * TeX Misc:: Customization of TeX mode, and related features. -Editing Formatted Text +Editing Enriched Text -* 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. -* Format Faces:: Bold, italic, underline, etc. -* Format Colors:: Changing the color of text. -* Format Indentation:: Changing the left and right margins. -* Format Justification:: Centering, setting text flush with the - left or right margin, etc. -* Format Properties:: The "special" text properties submenu. -* Forcing Enriched Mode:: How to force use of Enriched mode. +* Enriched Mode:: Entering and exiting Enriched mode. +* Hard and Soft Newlines:: There are two different kinds of newlines. +* Editing Format Info:: How to edit text properties. +* Enriched Faces:: Bold, italic, underline, etc. +* Enriched Indentation:: Changing the left and right margins. +* Enriched Justification:: Centering, setting text flush with the + left or right margin, etc. +* Enriched Properties:: The "special" text properties submenu. @c The automatic texinfo menu update inserts some duplicate items here @c (faces, colors, indentation, justification, properties), because @@ -1152,7 +1130,7 @@ Command Line Arguments for Emacs Invocation * Environment:: Environment variables that Emacs uses. * Display X:: Changing the default display and using remote login. * Font X:: Choosing a font for text, under X. -* Colors:: Choosing display colors. +* Colors X:: Choosing display colors. * Window Size X:: Start-up window size, under X. * Borders X:: Internal and external borders, under X. * Title X:: Specifying the initial frame's title. diff --git a/doc/emacs/emacsver.texi b/doc/emacs/emacsver.texi index 87f9dddbba8..cb3f3f39778 100644 --- a/doc/emacs/emacsver.texi +++ b/doc/emacs/emacsver.texi @@ -1,4 +1,4 @@ @c It would be nicer to generate this using configure and @version@. @c However, that would mean emacsver.texi would always be newer @c then the info files in release tarfiles. -@set EMACSVER 24.0.91 +@set EMACSVER 24.0.92 diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 2317f876b08..e3da0ca44e6 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -267,9 +267,8 @@ newly requested file. @xref{Windows}. @kindex C-x 5 f @findex find-file-other-frame @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a -new frame, or makes visible any existing frame showing the file you -seek. This feature is available only when you are using a window -system. @xref{Frames}. +new frame, or selects any existing frame showing the specified file. +@xref{Frames}. @cindex file selection dialog On graphical displays, there are two additional methods for visiting @@ -298,8 +297,9 @@ original encoding and end-of-line convention. @xref{Coding Systems}. If you wish to edit a file as a sequence of @acronym{ASCII} characters with no special encoding or conversion, use the @kbd{M-x find-file-literally} command. This visits a file, like @kbd{C-x C-f}, -but does not do format conversion (@pxref{Formatted Text}), character -code conversion (@pxref{Coding Systems}), or automatic uncompression +but does not do format conversion (@pxref{Format Conversion,, Format +Conversion, elisp, the Emacs Lisp Reference Manual}), character code +conversion (@pxref{Coding Systems}), or automatic uncompression (@pxref{Compressed Files}), and does not add a final newline because of @code{require-final-newline} (@pxref{Customize Save}). If you have already visited the same file in the usual (non-literal) manner, this diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 49222451cce..1445d25be15 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -6,31 +6,41 @@ @chapter Frames and Graphical Displays @cindex frames - When using a graphical display, you can create multiple system-level -``windows'' in a single Emacs session. We refer to these system-level -windows as @dfn{frames}. A frame initially contains a single Emacs -window; however, you can subdivide this Emacs window into smaller -windows, all fitting into the same frame. Each frame normally -contains its own echo area and minibuffer. - - To avoid confusion, we reserve the word ``window'' for the -subdivisions that Emacs implements, and never use it to refer to a -frame. - - Any editing you do in one frame affects the other frames. For -instance, if you put text in the kill ring in one frame, you can yank -it in another frame. If you exit Emacs through @kbd{C-x C-c} in one -frame, it terminates all the frames. To delete just one frame, use + When Emacs is started on a graphical display, e.g.@: on the X Window +System, it occupies a graphical system-level ``window''. In this +manual, we call this a @dfn{frame}, reserving the word ``window'' for +the part of the frame used for displaying a buffer. A frame initially +contains one window, but it can be subdivided into multiple windows +(@pxref{Windows}). A frame normally also contains a menu bar, tool +bar, and echo area. + + You can also create additional frames (@pxref{Creating Frames}). +All frames created in the same Emacs session have access to the same +underlying buffers and other data. For instance, if a buffer is being +shown in more than one frame, any changes made to it in one frame show +up immediately in the other frames too. + + Typing @kbd{C-x C-c} closes all the frames on the current display, +and ends the Emacs session if it has no frames open on any other +displays (@pxref{Exiting}). To close just the selected frame, type @kbd{C-x 5 0} (that is zero, not @kbd{o}). - Emacs compiled for MS-DOS emulates some windowing functionality, -so that you can use many of the features described in this chapter. + This chapter describes Emacs features specific to graphical displays +(particularly mouse commands), and features for managing multiple +frames. On text-only terminals, many of these features are +unavailable. However, it is still possible to create multiple +``frames'' on text-only terminals; such frames are displayed one at a +time, filling the entire terminal screen (@pxref{Non-Window +Terminals}). It is also possible to use the mouse on some text-only +terminals (@pxref{Text-Only Mouse}, for doing so on GNU and UNIX +systems; and @iftex -@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}. +@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, @end iftex @ifnottex -@xref{MS-DOS Mouse}. +@pxref{MS-DOS Mouse}, @end ifnottex +for doing so on MS-DOS). @menu * Mouse Commands:: Moving, cutting, and pasting, with the mouse. @@ -43,10 +53,8 @@ so that you can use many of the features described in this chapter. * Fonts:: Changing the frame font. * Speedbar:: How to make and use a speedbar frame. * Multiple Displays:: How one Emacs job can talk to several displays. -* Special Buffer Frames:: You can make certain buffers have their own frames. * Frame Parameters:: Changing the colors and other modes of frames. * Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Wheeled Mice:: Using mouse wheels for scrolling. * Drag and Drop:: Using drag and drop to open files and insert text. * Menu Bars:: Enabling and disabling the menu bar. * Tool Bars:: Enabling and disabling the tool bar. @@ -85,31 +93,32 @@ ring; on a second click, kill it (@code{mouse-save-then-kill}). @findex mouse-set-point The most basic mouse command is @code{mouse-set-point}, which is -called by clicking with the left mouse button, @kbd{Mouse-1}, in the +invoked by clicking with the left mouse button, @kbd{Mouse-1}, in the text area of a window. This moves point to the position where you -clicked. +clicked. If that window was not the selected window, it becomes the +selected window. @vindex x-mouse-click-focus-ignore-position - Normally, Emacs does not distinguish between ordinary mouse clicks -and clicks that select a frame. When you click on a frame to select -it, that also changes the selected window and cursor position -according to the mouse click position. On the X Window System, you -can change this behavior by setting the variable -@code{x-mouse-click-focus-ignore-position} to @code{t}. Then the -first click selects the frame, but does not affect the selected window -or cursor position. If you click again in the same place, that click -will be in the selected frame, so it will change the window or cursor -position. + Normally, if the frame you clicked in was not the selected frame, it +is made the selected frame, in addition to selecting the window and +setting the cursor. On the X Window System, you can change this by +setting the variable @code{x-mouse-click-focus-ignore-position} to +@code{t}. In that case, the initial click on an unselected frame just +selects the frame, without doing anything else; clicking again selects +the window and sets the cursor position. @findex mouse-set-region -@vindex mouse-drag-copy-region Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch of text activates the region around that text -(@code{mouse-set-region}). @xref{Mark}. Emacs places the mark where -you started holding down the mouse button, and point where you release -it. In addition, the region is copied into the kill ring (@pxref{Kill -Ring}). If you don't want Emacs to copy the region, change the -variable @code{mouse-drag-copy-region} to @code{nil}. +(@code{mouse-set-region}), placing the mark where you started holding +down the mouse button, and point where you release it (@pxref{Mark}). +In addition, the text in the region becomes the primary selection +(@pxref{Primary Selection}). + +@vindex mouse-drag-copy-region + If you change the variable @code{mouse-drag-copy-region} to a +non-@code{nil} value, dragging the mouse over a stretch of text also +adds the text to the kill ring. The default is @code{nil}. @vindex mouse-scroll-min-lines If you move the mouse off the top or bottom of the window while @@ -124,7 +133,7 @@ on how far away from the window edge the mouse has gone; the variable Clicking with the middle mouse button, @kbd{Mouse-2}, moves point to the position where you clicked and inserts the contents of the primary selection (@code{mouse-yank-primary}). @xref{Primary Selection}. -This behavior is consistent with other X applications; alternatively, +This behavior is consistent with other X applications. Alternatively, you can rebind @kbd{Mouse-2} to @code{mouse-yank-at-click}, which performs a yank at point. @@ -144,7 +153,6 @@ depending on where you click and the status of the region: @item If no region is active, clicking @kbd{Mouse-3} activates the region, placing the mark where point was and point at the clicked position. -In addition, the text in the region is copied to the kill ring. @item If a region is active, clicking @kbd{Mouse-3} adjusts the nearer end @@ -155,8 +163,8 @@ region was already on the kill ring, it replaces it there. @item If you originally specified the region using a double or triple @kbd{Mouse-1}, so that the region is defined to consist of entire -words or lines, then adjusting the region with @kbd{Mouse-3} also -proceeds by entire words or lines. +words or lines (@pxref{Word and Line Mouse}), then adjusting the +region with @kbd{Mouse-3} also proceeds by entire words or lines. @item If you use @kbd{Mouse-3} a second time consecutively, at the same @@ -168,23 +176,33 @@ just once---or just drag across the text with @kbd{Mouse-1}. Then you can copy it elsewhere by yanking it. @end itemize + The @code{mouse-save-then-kill} command also obeys the variable +@code{mouse-drag-copy-region} (described above). If the value is +non-@code{nil}, then whenever the command sets or adjusts the active +region, the text in the region is also added to the kill ring. If the +latest kill ring entry had been added the same way, that entry is +replaced rather than making a new entry. + Whenever you set the region using any of the mouse commands described above, the mark will be deactivated by any subsequent unshifted cursor motion command, in addition to the usual ways of -deactivating the mark. @xref{Shift Selection}. While the region -remains active, typing @key{Backspace} or @key{Delete} deletes the -text in that region and deactivates the mark; this behavior follows a -convention established by other graphical programs, and it does -@emph{not} apply when you set the region any other way, including -shift-selection (@pxref{Shift Selection}). - -@cindex Delete Selection mode -@cindex mode, Delete Selection -@findex delete-selection-mode - Many graphical applications also follow the convention that -insertion while text is selected deletes the selected text. You can -make Emacs behave this way by enabling Delete Selection mode. -@xref{Using Region}. +deactivating the mark. @xref{Shift Selection}. + +@cindex mouse wheel +@findex mouse-wheel-mode +@cindex Mouse Wheel minor mode +@cindex mode, Mouse Wheel +@vindex mouse-wheel-follow-mouse +@vindex mouse-wheel-scroll-amount +@vindex mouse-wheel-progressive-speed + Some mice have a ``wheel'' which can be used for scrolling. Emacs +supports scrolling windows with the mouse wheel, by default, on most +graphical displays. To toggle this feature, use @kbd{M-x +mouse-wheel-mode}. The variables @code{mouse-wheel-follow-mouse} and +@code{mouse-wheel-scroll-amount} determine where and by how much +buffers are scrolled. The variable +@code{mouse-wheel-progressive-speed} determines whether the scroll +speed is linked to how fast you move the wheel. @node Word and Line Mouse @section Mouse Commands for Words and Lines @@ -202,7 +220,7 @@ underscore, in C mode) selects the symbol surrounding that character. Double-clicking on a character with open- or close-parenthesis syntax selects the parenthetical grouping which that character starts or ends. Double-clicking on a character with string-delimiter syntax -(such as a singlequote or doublequote in C) selects the string +(such as a single-quote or double-quote in C) selects the string constant (Emacs uses heuristics to figure out whether that character is the beginning or the end of it). @@ -220,50 +238,54 @@ Select the text you drag across, in the form of whole lines. @section Following References with the Mouse @kindex Mouse-1 @r{(selection)} @kindex Mouse-2 @r{(selection)} +@cindex hyperlinks +@cindex links +@cindex text buttons +@cindex buttons @vindex mouse-highlight - Some Emacs buffers include @dfn{buttons}. A button is a piece of -text that performs some action when you activate it, such as following -a reference. Usually, a button's text is visually highlighted: it is -underlined, or a box is drawn around it. If you move the mouse over a -button, the shape of the mouse cursor changes and the button lights up -(if you change the variable @code{mouse-highlight} to @code{nil}, -Emacs disables this highlighting). + Some Emacs buffers include @dfn{buttons}, or @dfn{hyperlinks}: +pieces of text that perform some action (e.g.@: following a reference) +when activated (e.g.@: by clicking on them). Usually, a button's text +is visually highlighted: it is underlined, or a box is drawn around +it. If you move the mouse over a button, the shape of the mouse +cursor changes and the button lights up. If you change the variable +@code{mouse-highlight} to @code{nil}, Emacs disables this +highlighting. You can activate a button by moving point to it and typing @key{RET}, or by clicking either @kbd{Mouse-1} or @kbd{Mouse-2} on the -button. For example, typing @key{RET} or clicking on a file name in a -Dired buffer visits that file (@pxref{Dired}). Doing it on an error -message in the @samp{*Compilation*} buffer goes to the source code for -that error message (@pxref{Compilation}). Doing it on a completion in -the @samp{*Completions*} buffer chooses that completion -(@pxref{Completion}). - - Although clicking @kbd{Mouse-1} on a button usually activates that -button, if you hold the mouse button down for a short period of time -before releasing it (specifically, for more than 450 milliseconds), -then Emacs moves point where you clicked instead. This behavior -allows you to use the mouse to move point over a button without -following it. Dragging---moving the mouse while it is held down---has -its usual behavior of setting the region, even if you drag from or -onto a button. +button. For example, in a Dired buffer, each file name is a button; +activating it causes Emacs to visit that file (@pxref{Dired}). In a +@samp{*Compilation*} buffer, each error message is a button, and +activating it visits the source code for that error +(@pxref{Compilation}). + + Although clicking @kbd{Mouse-1} on a button usually activates the +button, if you hold the mouse button down for a period of time before +releasing it (specifically, for more than 450 milliseconds), then +Emacs moves point where you clicked, without activating the button. +In this way, you can use the mouse to move point over a button without +activating it. Dragging the mouse over or onto a button has its usual +behavior of setting the region, and does not activate the button. + + You can change how @kbd{Mouse-1} applies to buttons by customizing +the variable @code{mouse-1-click-follows-link}. If the value is a +positive integer, that determines how long you need to hold the mouse +button down for, in milliseconds, to cancel button activation; the +default is 450, as described in the previous paragraph. If the value +is @code{nil}, @kbd{Mouse-1} just sets point where you clicked, and +does not activate buttons. If the value is @code{double}, double +clicks activate buttons but single clicks just set point. @vindex mouse-1-click-in-non-selected-windows - Normally, clicking @kbd{Mouse-1} on a button activates the button -even if it is in a nonselected window. If you change the variable -@code{mouse-1-click-in-non-selected-windows} to @code{nil}, clicking -@kbd{Mouse-1} on a button in an un-selected window moves point to the + Normally, @kbd{Mouse-1} on a button activates the button even if it +is in a non-selected window. If you change the variable +@code{mouse-1-click-in-non-selected-windows} to @code{nil}, +@kbd{Mouse-1} on a button in an unselected window moves point to the clicked position and selects that window, without activating the button. -@vindex mouse-1-click-follows-link - In Emacs versions before 22, only @kbd{Mouse-2} activates buttons -and @kbd{Mouse-1} always sets point. If you prefer this older -behavior, set the variable @code{mouse-1-click-follows-link} to -@code{nil}. This variable also lets you choose various other -alternatives for following links with the mouse. Type @kbd{C-h v -mouse-1-click-follows-link @key{RET}} for more details. - @node Menu Mouse Clicks @section Mouse Clicks for Menus @@ -280,28 +302,35 @@ menu smarter and more customizable. @xref{Buffer Menus}. @item C-Mouse-2 @kindex C-Mouse-2 -This menu is for specifying faces and other text properties -for editing formatted text. @xref{Formatted Text}. +This menu contains entries for examining faces and other text +properties, and well as for setting them (the latter is mainly useful +when editing enriched text; @pxref{Enriched Text}). @item C-Mouse-3 @kindex C-Mouse-3 This menu is mode-specific. For most modes if Menu-bar mode is on, this menu has the same items as all the mode-specific menu-bar menus put together. Some modes may specify a different menu for this -button.@footnote{Some systems use @kbd{Mouse-3} for a mode-specific -menu. We took a survey of users, and found they preferred to keep -@kbd{Mouse-3} for selecting and killing regions. Hence the decision -to use @kbd{C-Mouse-3} for this menu. To use @kbd{Mouse-3} instead, -do @code{(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)}.} If -Menu-bar mode is off, this menu contains all the items which would be -present in the menu bar---not just the mode-specific ones---so that -you can access them without having to display the menu bar. +button. If Menu Bar mode is off, this menu contains all the items +which would be present in the menu bar---not just the mode-specific +ones---so that you can access them without having to display the menu +bar. @item S-Mouse-1 This menu is for changing the default face within the window's buffer. @xref{Text Scale}. @end table + Some graphical applications use @kbd{Mouse-3} for a mode-specific +menu. If you prefer @kbd{Mouse-3} in Emacs to bring up such a menu +instead of running the @code{mouse-save-then-kill} command, rebind +@kbd{Mouse-3} by adding the following line to your init file +(@pxref{Init Rebinding}): + +@smallexample +(global-set-key [mouse-3] 'mouse-popup-menubar-stuff) +@end smallexample + @node Mode Line Mouse @section Mode Line Mouse Commands @cindex mode line, mouse @@ -332,34 +361,33 @@ make any window smaller than the minimum height. @item Mouse-3 @kindex Mouse-3 @r{(mode line)} @kbd{Mouse-3} on a mode line deletes the window it belongs to. If the -frame has only one window, it buries the current buffer instead, and -switches to another buffer. +frame has only one window, it does nothing. @item C-Mouse-2 @kindex C-mouse-2 @r{(mode line)} -@kbd{C-Mouse-2} on a mode line splits the window above -horizontally, above the place in the mode line where you click. +@kbd{C-Mouse-2} on a mode line splits that window, producing two +side-by-side windows with the boundary running through the click +position (@pxref{Split Window}). @end table @kindex C-Mouse-2 @r{(scroll bar)} @kindex Mouse-1 @r{(scroll bar)} - Using @kbd{Mouse-1} on the divider between two side-by-side mode -lines, you can move the vertical boundary left or right. Using -@kbd{C-Mouse-2} on a scroll bar splits the corresponding window -vertically. @xref{Split Window}. + Furthermore, by clicking and dragging @kbd{Mouse-1} on the divider +between two side-by-side mode lines, you can move the vertical +boundary to the left or right. @node Creating Frames @section Creating Frames @cindex creating frames @kindex C-x 5 - The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with -parallel subcommands. The difference is that @kbd{C-x 5} commands -create a new frame rather than just a new window in the selected frame -(@pxref{Pop Up Window}). If an existing visible or iconified -(``minimized'') frame already displays the requested material, these -commands use the existing frame, after raising or deiconifying -(``un-minimizing'') as necessary. + The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}. Whereas +each @kbd{C-x 4} command pops up a buffer in a different window in the +selected frame (@pxref{Pop Up Window}), the @kbd{C-x 5} commands use a +different frame. If an existing visible or iconified (``minimized'') +frame already displays the requested buffer, that frame is raised and +deiconified (``un-minimized''); otherwise, a new frame is created on +the current display terminal. The various @kbd{C-x 5} commands differ in how they find or create the buffer to select: @@ -394,56 +422,32 @@ frame. This runs @code{find-file-read-only-other-frame}. @xref{Visiting}. @end table -@cindex default-frame-alist -@cindex initial-frame-alist -@cindex face customization, in init file -@cindex color customization, in init file - You can control the appearance of new frames you create by setting the -frame parameters in @code{default-frame-alist}. You can use the -variable @code{initial-frame-alist} to specify parameters that affect -only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs -Lisp Reference Manual}, for more information. - -@cindex font (default) - Here is an example of using @code{default-frame-alist} to specify -the default foreground color and font: - -@example -(add-to-list 'default-frame-alist '(font . "10x20")) -(add-to-list 'default-frame-alist - '(foreground-color . "blue")) -@end example - -@noindent -By putting such customizations in your init file, you can control the -appearance of all the frames Emacs creates, including the initial one -(@pxref{Init File}). @xref{Fonts}, for other ways to set the default -font. + You can control the appearance and behavior of the newly-created +frames by specifying @dfn{frame parameters}. @xref{Frame Parameters}. @node Frame Commands @section Frame Commands - The following commands let you create, delete and operate on frames: + The following commands are used to delete and operate on frames: @table @kbd +@item C-x 5 0 +@kindex C-x 5 0 +@findex delete-frame +Delete the selected frame (@code{delete-frame}). This signals an +error if there is only one frame. + @item C-z @kindex C-z @r{(X windows)} @findex suspend-frame Minimize (or ``iconify) the selected Emacs frame (@code{suspend-frame}). @xref{Exiting}. -@item C-x 5 0 -@kindex C-x 5 0 -@findex delete-frame -Delete the selected frame (@code{delete-frame}). This is not allowed -if there is only one frame. - @item C-x 5 o @kindex C-x 5 o @findex other-frame -Select another frame, raise it, and warp the mouse to it. If you -repeat this command, it cycles through all the frames on your -terminal. +Select another frame, and raise it. If you repeat this command, it +cycles through all the frames on your terminal. @item C-x 5 1 @kindex C-x 5 1 @@ -451,43 +455,37 @@ terminal. Delete all frames on the current terminal, except the selected one. @end table - The @kbd{C-x 5 0} (@code{delete-frame}) command never deletes the -last frame. This prevents you from losing the ability to interact -with the Emacs process. Note that when Emacs is run as a daemon -(@pxref{Emacs Server}), there is always a ``virtual frame'' that -remains after all the ordinary, interactive frames are deleted. In -this case, @kbd{C-x 5 0} can delete the last interactive frame; you -can use @command{emacsclient} to reconnect to the Emacs session. - - The @kbd{C-x 5 1} (@code{delete-other-frames}) command only deletes -frames on the current terminal. For example, if you call it from an X -frame, it deletes the other frames on that X display; if the Emacs -process has frames open on other X displays or text terminals, those -are not deleted. + The @kbd{C-x 5 0} (@code{delete-frame}) command deletes the selected +frame. However, it will refuse to delete the last frame in an Emacs +session, to prevent you from losing the ability to interact with the +Emacs session. Note that when Emacs is run as a daemon (@pxref{Emacs +Server}), there is always a ``virtual frame'' that remains after all +the ordinary, interactive frames are deleted. In this case, @kbd{C-x +5 0} can delete the last interactive frame; you can use +@command{emacsclient} to reconnect to the Emacs session. + + The @kbd{C-x 5 1} (@code{delete-other-frames}) command deletes all +other frames on the current terminal (this terminal refers to either a +graphical display, or a text-only terminal; @pxref{Non-Window +Terminals}). If the Emacs session has frames open on other graphical +displays or text terminals, those are not deleted. @vindex focus-follows-mouse - On X, you may have to tell Emacs how the window manager handles -focus-switching between windows, in order for @kbd{C-x 5 o} -(@code{other-frame}) to work properly. Unfortunately, there is no way -for Emacs to detect this automatically, so you should set the variable -@code{focus-follows-mouse}. The default is @code{nil}, meaning you -have to click on the window to select it (the default for most modern -window managers). You should change it to @code{t} if your window -manager selects a window and gives it focus anytime you move the mouse -onto the window. - - The window manager that is part of MS-Windows always gives focus to -a frame that raises, so this variable has no effect in the native -MS-Windows build of Emacs. However, you may still wish to set this -variable to @code{t} to have Emacs automatically move the mouse -pointer to the raised frame. + The @kbd{C-x 5 o} (@code{other-frame}) command selects the next +frame on the current terminal. If you are using Emacs on the X Window +System with a window manager that selects (or @dfn{gives focus to}) +whatever frame the mouse cursor is over, you have to change the +variable @code{focus-follows-mouse} to @code{t} in order for this +command to work properly. Then invoking @kbd{C-x 5 o} will also warp +the mouse cursor to the chosen frame. @node Fonts @section Fonts @cindex fonts - By default, Emacs displays text in X using a 12-point monospace -font. There are several different ways to specify a different font: + By default, Emacs displays text on graphical displays using a +12-point monospace font. There are several different ways to specify +a different font: @itemize @item @@ -501,7 +499,7 @@ variable @code{default-frame-alist} to specify the @code{font} parameter (@pxref{Creating Frames}), like this: @smallexample -(add-to-list 'default-frame-alist '(font . "DejaVu Sans Mono-12")) +(add-to-list 'default-frame-alist '(font . "DejaVu Sans Mono-10")) @end smallexample @cindex X defaults file @@ -523,18 +521,16 @@ font in your X resources file, you should not quote it. If you are running Emacs on the GNOME desktop, you can tell Emacs to use the default system font by setting the variable @code{font-use-system-font} to @code{t} (the default is @code{nil}). -For this to work, Emacs must be compiled with Gconf support; this is -done automatically if the libraries are present at compile time. +For this to work, Emacs must have been compiled with Gconf support. @item Use the command line option @samp{-fn} (or @samp{--font}). @xref{Font X}. @end itemize -To check what font you're currently using, the @kbd{C-u C-x =} -command can be helpful. It'll describe the character under point, and -also say what font it's rendered in, if the window system you're -running under supports that. + To check what font you're currently using, the @kbd{C-u C-x =} +command can be helpful. It describes the character at point, and +names the font that it's rendered in. @cindex fontconfig On X, there are four different ways to express a ``font name''. The @@ -548,7 +544,7 @@ the following form: @noindent Within this format, any of the elements in braces may be omitted. Here, @var{fontname} is the @dfn{family name} of the font, such as -@samp{Monospace} or @samp{DejaVu Serif}; @var{fontsize} is the +@samp{Monospace} or @samp{DejaVu Sans Mono}; @var{fontsize} is the @dfn{point size} of the font (one @dfn{printer's point} is about 1/72 of an inch); and the @samp{@var{name}=@var{values}} entries specify settings such as the slant and weight of the font. Each @var{values} @@ -561,7 +557,7 @@ Here is a list of common font properties: @table @samp @item slant -One of @samp{italic}, @samp{oblique} or @samp{roman}. +One of @samp{italic}, @samp{oblique}, or @samp{roman}. @item weight One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or @@ -595,8 +591,9 @@ For a more detailed description of Fontconfig patterns, see the Fontconfig manual, which is distributed with Fontconfig and available online at @url{http://fontconfig.org/fontconfig-user.html}. - The second way to specify a font is to use a @dfn{GTK font -description}. These have the syntax +@cindex GTK font pattern + The second way to specify a font is to use a @dfn{GTK font pattern}. +These have the syntax @smallexample @var{fontname} [@var{properties}] [@var{fontsize}] @@ -605,20 +602,24 @@ description}. These have the syntax @noindent where @var{fontname} is the family name, @var{properties} is a list of property values separated by spaces, and @var{fontsize} is the point -size. The properties that you may specify are as follows: +size. The properties that you may specify for GTK font patterns are +as follows: -@table @samp -@item style -One of @samp{roman}, @samp{italic} or @samp{oblique}. If omitted, the -@samp{roman} style is used. -@item weight -One of @samp{medium}, @samp{ultra-light}, @samp{light}, -@samp{semi-bold}, or @samp{bold}. If omitted, @samp{medium} weight is -used. -@end table +@itemize +@item +Slant properties: @samp{Italic} or @samp{Oblique}. If omitted, the +default (roman) slant is implied. +@item +Weight properties: @samp{Bold}, @samp{Book}, @samp{Light}, +@samp{Medium}, @samp{Semi-bold}, or @samp{Ultra-light}. If omitted, +@samp{Medium} weight is implied. +@item +Width properties: @samp{Semi-Condensed} or @samp{Condensed}. If +omitted, a default width is used. +@end itemize @noindent -Here are some examples of GTK font descriptions: +Here are some examples of GTK font patterns: @smallexample Monospace 12 @@ -657,7 +658,7 @@ The entries have the following meanings: @item maker The name of the font manufacturer. @item family -The name of the font family (e.g. @samp{courier}). +The name of the font family (e.g.@: @samp{courier}). @item weight The font weight---normally either @samp{bold}, @samp{medium} or @samp{light}. Some font names support other values. @@ -670,8 +671,8 @@ The font width---normally @samp{normal}, @samp{condensed}, @samp{extended}, or @samp{semicondensed} (some font names support other values). @item style -An optional additional style name. Usually it is empty---most long -font names have two hyphens in a row at this point. +An optional additional style name. Usually it is empty---most XLFDs +have two hyphens in a row at this point. @item pixels The font height, in pixels. @item height @@ -840,116 +841,40 @@ input stream for each server. Each server also has its own selected frame. The commands you enter with a particular X server apply to that server's selected frame. - It is even possible to use this feature to let two or more users -type simultaneously on the two displays, within the same Emacs job. -In practice, however, the different users can easily interfere with -each others' edits if they are not careful. - -@node Special Buffer Frames -@section Special Buffer Frames - -@vindex special-display-buffer-names - You can make certain chosen buffers, which Emacs normally displays -in ``some other window'' (@pxref{Displaying Buffers}), appear in -special frames of their own. To do this, set the variable -@code{special-display-buffer-names} to a list of buffer names; any -buffer whose name is in that list automatically gets a special frame. -@xref{Window Choice}, for how this fits in with the other ways for -Emacs to choose a window to display in. - - For example, if you set the variable this way, +@node Frame Parameters +@section Frame Parameters +@cindex default-frame-alist -@example -(setq special-display-buffer-names - '("*Completions*" "*grep*" "*tex-shell*")) -@end example + You can control the default appearance and behavior of all frames by +specifying a default list of @dfn{frame parameters} in the variable +@code{default-frame-alist}. Its value should be a list of entries, +each specifying a parameter name and a value for that parameter. +These entries take effect whenever Emacs creates a new frame, +including the initial frame. -@noindent -then completion lists, @code{grep} output and the @TeX{} mode shell -buffer get individual frames of their own. These frames, and the -windows in them, are never automatically split or reused for any other -buffers. They continue to show the buffers they were created for, -unless you alter them by hand. Killing the special buffer deletes its -frame automatically. - -@vindex special-display-regexps - More generally, you can set @code{special-display-regexps} to a list -of regular expressions; then a buffer gets its own frame if its name -matches any of those regular expressions. (Once again, this applies only -to buffers that normally get displayed for you in ``another window.'') - -@vindex special-display-frame-alist - The variable @code{special-display-frame-alist} specifies the frame -parameters for these frames. It has a default value, so you don't need -to set it. - - For those who know Lisp, an element of -@code{special-display-buffer-names} or @code{special-display-regexps} -can also be a list. Then the first element is the buffer name or -regular expression; the rest of the list specifies how to create the -frame. It can be an association list specifying frame parameter -values; these values take precedence over parameter values specified -in @code{special-display-frame-alist}. If you specify the symbol -@code{same-window} as a ``frame parameter'' in this list, with a -non-@code{nil} value, that means to use the selected window if -possible. If you use the symbol @code{same-frame} as a ``frame -parameter'' in this list, with a non-@code{nil} value, that means to -use the selected frame if possible. - - Alternatively, the value can have this form: +@cindex frame size, specifying default + For example, you can add the following lines to your init file +(@pxref{Init File}) to set the default frame width to 90 character +columns, the default frame height to 40 character rows, and the +default font to @samp{Monospace-10}: @example -(@var{function} @var{args}...) +(add-to-list 'default-frame-alist '(width . 90)) +(add-to-list 'default-frame-alist '(height . 40)) +(add-to-list 'default-frame-alist '(font . "Monospace-10")) @end example -@noindent -where @var{function} is a symbol. Then the frame is constructed by -calling @var{function}; its first argument is the buffer, and its -remaining arguments are @var{args}. - -@node Frame Parameters -@section Setting Frame Parameters -@cindex Auto-Raise mode -@cindex Auto-Lower mode - - These commands are available for controlling the window management -behavior of the selected frame: + For a list of frame parameters and their effects, see @ref{Frame +Parameters,,, elisp, The Emacs Lisp Reference Manual}. -@table @kbd -@findex auto-raise-mode -@item M-x auto-raise-mode -Toggle whether or not the selected frame should auto-raise. Auto-raise -means that every time you move the mouse onto the frame, it raises the -frame. - -Some window managers also implement auto-raise. If you enable -auto-raise for Emacs frames in your window manager, it will work, but -it is beyond Emacs' control, so @code{auto-raise-mode} has no effect -on it. - -@findex auto-lower-mode -@item M-x auto-lower-mode -Toggle whether or not the selected frame should auto-lower. -Auto-lower means that every time you move the mouse off the frame, -the frame moves to the bottom of the stack on the screen. - -The command @code{auto-lower-mode} has no effect on auto-lower -implemented by the window manager. To control that, you must use the -appropriate window manager features. -@end table +@cindex initial-frame-alist + You can also specify a list of frame parameters which apply to just +the initial frame, by customizing the variable +@code{initial-frame-alist}. - In Emacs versions that use an X toolkit, the color-setting and -font-setting functions don't affect menus and the menu bar, since they -are displayed by their own widget classes. To change the appearance of -the menus and menu bar, you must use X resources (@pxref{Resources}). -@xref{Colors}, regarding colors. @xref{Font X}, regarding choice of -font. - - Colors, fonts, and other attributes of the frame's display can also -be customized by setting frame parameters in the variable -@code{default-frame-alist} (@pxref{Creating Frames}). For a detailed -description of frame parameters and customization, see @ref{Frame -Parameters,,, elisp, The Emacs Lisp Reference Manual}. + If Emacs is compiled to use an X toolkit, frame parameters that +specify colors and fonts don't affect menus and the menu bar, since +those are drawn by the toolkit and not directly by Emacs. @node Scroll Bars @section Scroll Bars @@ -994,41 +919,17 @@ or disable the scroll bars (@pxref{Resources}). To control the scroll bar width, change the @code{scroll-bar-width} frame parameter (@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). -@node Wheeled Mice -@section Scrolling With ``Wheeled'' Mice - -@cindex mouse wheel -@cindex wheel, mouse -@findex mouse-wheel-mode -@cindex Mouse Wheel minor mode -@cindex mode, Mouse Wheel - Some mice have a ``wheel'' instead of a third button. You can -usually click the wheel to act as either @kbd{Mouse-2} or -@kbd{Mouse-3}, depending on the setup. You can also use the wheel to -scroll windows instead of using the scroll bar or keyboard commands. -Mouse wheel support only works if the system generates appropriate -events; whenever possible, it is turned on by default. To toggle this -feature, use @kbd{M-x mouse-wheel-mode}. - -@vindex mouse-wheel-follow-mouse -@vindex mouse-wheel-scroll-amount -@vindex mouse-wheel-progressive-speed - The two variables @code{mouse-wheel-follow-mouse} and -@code{mouse-wheel-scroll-amount} determine where and by how much -buffers are scrolled. The variable -@code{mouse-wheel-progressive-speed} determines whether the scroll -speed is linked to how fast you move the wheel. - @node Drag and Drop @section Drag and Drop @cindex drag and drop - Emacs supports @dfn{drag and drop} using the mouse. For instance, -dropping text onto an Emacs frame inserts the text where it is dropped. -Dropping a file onto an Emacs frame visits that file. As a special -case, dropping the file on a Dired buffer moves or copies the file -(according to the conventions of the application it came from) into the -directory displayed in that buffer. + In most graphical desktop environments, Emacs has basic support for +@dfn{drag and drop} operations. For instance, dropping text onto an +Emacs frame inserts the text where it is dropped. Dropping a file +onto an Emacs frame visits that file. As a special case, dropping the +file on a Dired buffer moves or copies the file (according to the +conventions of the application it came from) into the directory +displayed in that buffer. @vindex dnd-open-file-other-window Dropping a file normally visits it in the window you drop it on. If @@ -1045,13 +946,12 @@ protocol, are currently supported. @findex menu-bar-mode @vindex menu-bar-mode - You can turn display of menu bars on or off with @kbd{M-x -menu-bar-mode} or by customizing the variable @code{menu-bar-mode}. -With no argument, this command toggles Menu Bar mode, a -minor mode. With an argument, the command turns Menu Bar mode on if the -argument is positive, off if the argument is not positive. You can use -the X resource @samp{menuBar} to control the initial setting of -Menu Bar mode. @xref{Resources}. + You can toggle the use of menu bars with @kbd{M-x menu-bar-mode}. +With no argument, this command toggles Menu Bar mode, a global minor +mode. With an argument, the command turns Menu Bar mode on if the +argument is positive, off if the argument is not positive. To control +the use of menu bars at startup, customize the variable +@code{menu-bar-mode}. @kindex C-Mouse-3 @r{(when menu bar is disabled)} Expert users often turn off the menu bar, especially on text-only @@ -1135,47 +1035,39 @@ toggle to be activated by default, change the variable help text to the GTK+ file chooser dialog; to disable this help text, change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. -@vindex x-gtk-use-old-file-dialog - In GTK+ versions 2.4 through 2.10, you can choose to use an older -version of the GTK+ file dialog by setting the variable -@code{x-gtk-use-old-file-dialog} to a non-@code{nil} value. If Emacs -is built with a GTK+ version that has only one file dialog, this -variable has no effect. - @node Tooltips @section Tooltips @cindex tooltips - @dfn{Tooltips} are small windows that display text information at the -current mouse position. They activate when there is a pause in mouse -movement. There are two types of tooltip: help tooltips and GUD -tooltips. - - @dfn{Help tooltips} typically display over text---including the mode -line---but are also available for other parts of the Emacs frame, such -as the tool bar and menu items. + @dfn{Tooltips} are small windows that display text information at +the current mouse position. They activate when there is a pause in +mouse movement over some significant piece of text in a window, or the +mode line, or some other part of the Emacs frame such as a tool bar +button or menu item. @findex tooltip-mode - You can toggle display of help tooltips (Tooltip mode) with the -command @kbd{M-x tooltip-mode}. When Tooltip mode is disabled, the -help text is displayed in the echo area instead. - - @dfn{GUD tooltips} show values of variables. They are useful when -you are debugging a program. @xref{Debugger Operation}. + You can toggle the use of tooltips with the command @kbd{M-x +tooltip-mode}. When Tooltip mode is disabled, the help text is +displayed in the echo area instead. To control the use of tooltips at +startup, customize the variable @code{tooltip-mode}. @vindex tooltip-delay The variables @code{tooltip-delay} specifies how long Emacs should wait before displaying a tooltip. For additional customization options for displaying tooltips, use @kbd{M-x customize-group -@key{RET} tooltip @key{RET}}. @xref{X Resources}, for information on -customizing the windows that display tooltips. +@key{RET} tooltip @key{RET}}. @vindex x-gtk-use-system-tooltips If Emacs is built with GTK+ support, it displays tooltips via GTK+, using the default appearance of GTK+ tooltips. To disable this, change the variable @code{x-gtk-use-system-tooltips} to @code{nil}. -If you do this, or if Emacs is built without GTK+ support, the -@code{tooltip} face specifies most attributes of the tooltip text. +If you do this, or if Emacs is built without GTK+ support, most +attributes of the tooltip text are specified by the @code{tooltip} +face, and by X resources (@pxref{X Resources}). + + @dfn{GUD tooltips} are special tooltips that show the values of +variables when debugging a program with GUD. @xref{Debugger +Operation}. @node Mouse Avoidance @section Mouse Avoidance @@ -1248,23 +1140,31 @@ to select a frame according to its name. The name you specify appears in the mode line when the frame is selected. @node Text-Only Mouse -@section Using a Mouse in Terminal Emulators +@section Using a Mouse in Text-only Terminals @cindex mouse support @cindex terminal emulators, mouse support Some text-only terminals support mouse clicks in the terminal window. @cindex xterm -In a terminal emulator which is compatible with @code{xterm}, -you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over -simple use of the mouse---basically, only non-modified single clicks -are supported. The normal @code{xterm} mouse functionality for such + In a terminal emulator which is compatible with @command{xterm}, you +can use @kbd{M-x xterm-mouse-mode} to give Emacs control over simple +uses of the mouse---basically, only non-modified single clicks are +supported. The normal @command{xterm} mouse functionality for such clicks is still available by holding down the @kbd{SHIFT} key when you press the mouse button. Xterm Mouse mode is a global minor mode (@pxref{Minor Modes}). Repeating the command turns the mode off again. @findex gpm-mouse-mode -In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to -enable terminal mouse support. You must have the gpm package -installed and running on your system in order for this to work. + In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to +enable mouse support. You must have the gpm server installed and +running on your system in order for this to work. + +@iftex +@pxref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}, +@end iftex +@ifnottex +@pxref{MS-DOS Mouse}, +@end ifnottex +for information about mouse support on MS-DOS. diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index e37e80bfab8..3af75245e69 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -509,11 +509,6 @@ character sets and which font to use to display each of them. Fontsets make it easy to change several fonts at once by specifying the name of a fontset, rather than changing each font separately. @xref{Fontsets}. -@item Formatted Text -Formatted text is text that displays with formatting information while -you edit. Formatting information includes fonts, colors, and specified -margins. @xref{Formatted Text}. - @item Formfeed Character See `page.' @@ -702,9 +697,8 @@ that someone else is already editing. See `incremental search.' @item Justification -Justification means adding extra spaces within lines of text -in order to adjust the position of the text edges. -@xref{Format Justification}. +Justification means adding extra spaces within lines of text in order +to adjust the position of the text edges. @xref{Fill Commands}. @item Key Binding See `binding.' @@ -1362,12 +1356,6 @@ See `abbrev.' Word search is searching for a sequence of words, considering the punctuation between them as insignificant. @xref{Word Search}. -@item WYSIWYG -WYSIWYG stands for ``What you see is what you get.'' Emacs generally -provides WYSIWYG editing for files of characters; in Enriched mode -(@pxref{Formatted Text}), it provides WYSIWYG editing for files that -include text formatting information. - @item Yanking Yanking means reinserting text previously killed (q.v.@:). It can be used to undo a mistaken kill, or for copying or moving text. Some diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi index e13b2808f09..f99e3519710 100644 --- a/doc/emacs/indent.texi +++ b/doc/emacs/indent.texi @@ -8,214 +8,154 @@ @cindex tabs @cindex columns (indentation) - This chapter describes the Emacs commands that add, remove, or -adjust indentation. - -@table @kbd -@item @key{TAB} -Indent the current line appropriately, in a mode-dependent fashion. -@item @kbd{C-j} -Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). -@item M-^ -Merge the previous and the current line (@code{delete-indentation}). -This would cancel the effect of a preceding @kbd{C-j}. -@item C-M-o -Split the current line at point; text on the line after point becomes a -new line indented to the same column where point is located -(@code{split-line}). -@item M-m -Move (forward or back) to the first nonblank character on the current -line (@code{back-to-indentation}). -@item C-M-\ -Indent lines in the region to the same column (@code{indent-region}). -@item C-x @key{TAB} -Shift lines in the region rigidly right or left (@code{indent-rigidly}). -@item M-i -Indent from point to the next prespecified tab stop column -(@code{tab-to-tab-stop}). -@item M-x indent-relative -Indent from point to under an indentation point in the previous line. +@cindex whitespace character + @dfn{Indentation} refers to inserting or adjusting @dfn{whitespace +characters} (space and/or tab characters) at the beginning of a line +of text. This chapter documents indentation commands and options +which are common to Text mode and related modes, as well as +programming language modes. @xref{Program Indent}, for additional +documentation about indenting in programming modes. + +@findex indent-for-tab-command +@kindex TAB @r{(indentation)} + The simplest way to perform indentation is the @key{TAB} key. In +most major modes, this runs the command @code{indent-for-tab-command}. +(In C and related modes, @key{TAB} runs the command +@code{c-indent-line-or-region}, which behaves similarly). + +@table @key +@item TAB +Insert whitespace, or indent the current line, in a mode-appropriate +way (@code{indent-for-tab-command}). If the region is active, indent +all the lines within it. @end table -@noindent -The @key{TAB} key runs @code{indent-for-tab-command} in most major -modes (in C and related modes, @key{TAB} runs a separate command, -@code{c-indent-line-or-region}, which behaves similarly). The major -mode determines just what this entails. - - In text modes, @key{TAB} inserts some combination of space and tab -characters to advance point to the next tab stop (@pxref{Tab Stops}). -If the region is active and spans multiple lines, it advances the -first character of each of those lines to the next tab stop -(@pxref{Using Region}). For the purposes of this command, the -position of the first non-whitespace character on the preceding line -is treated as an additional tab stop. Thus, you can use @key{TAB} to -``align'' point with the preceding line. - - In programming modes, @key{TAB} adds or removes some combination of -space and tab characters at the start of the line, in a way that makes -sense given the text in the preceding lines. If the region is active -and spans multiple lines, all those lines are indented this way. If -point was initially within the current line's indentation, it is -positioned after that indentation; otherwise, it remains at same point -in the newly-indented text. @xref{Program Indent}. + The exact behavior of @key{TAB} depends on the major mode. In Text +mode and related major modes, @key{TAB} normally inserts some +combination of space and tab characters to advance point to the next +tab stop (@pxref{Tab Stops}). For this purpose, the position of the +first non-whitespace character on the preceding line is treated as an +additional tab stop, so you can use @key{TAB} to ``align'' point with +the preceding line. If the region is active (@pxref{Using Region}), +@key{TAB} acts specially: it indents each line in the region so that +its first non-whitespace character is aligned with the preceding line. + + In programming modes, @key{TAB} indents the current line of code in +a way that makes sense given the code in the preceding lines. If the +region is active, all the lines in the region are indented this way. +If point was initially within the current line's indentation, it is +repositioned to the first non-whitespace character on the line. -@vindex tab-width - Normally, indentation commands insert (or remove) an optimal mix of -@dfn{tab characters} and spaces to align to the desired column. Tab -characters (@acronym{ASCII} code 9) are displayed as a stretch of -empty space extending to the next @dfn{display tab stop}. By default, -there is one display tab stop every eight columns; the number of -columns is determined by the variable @code{tab-width}. You can -insert a single tab character by typing @kbd{C-q @key{TAB}}. -@xref{Text Display}. + If you just want to insert a tab character in the buffer, type +@kbd{C-q @key{TAB}} (@pxref{Inserting Text}). -@findex edit-tab-stops -@findex tab-to-tab-stop -@kindex M-i - The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the -whitespace characters around point, inserting just enough whitespace -to advance point up to the next tab stop. By default, this involves -deleting the existing whitespace and inserting a single tab character. +@menu +* Indentation Commands:: More commands for performing indentation. +* Tab Stops:: Stop points for indentation in Text modes. +* Just Spaces:: Using only space characters for indentation. +* Indent Convenience:: Optional indentation features. +@end menu - @xref{Just Spaces}, for how to disable use of tabs. However, -@kbd{C-q @key{TAB}} always inserts a tab, even when tabs are disabled -for the indentation commands. +@node Indentation Commands +@section Indentation Commands -@vindex tab-always-indent - The variable @code{tab-always-indent} tweaks the behavior of the -@key{TAB} (@code{indent-for-tab-command}) command. The default value, -@code{t}, gives the behavior described above. If you change the value -to the symbol @code{complete}, then @key{TAB} first tries to indent -the current line, and if the line was already indented, it tries to -complete the text at point (@pxref{Symbol Completion}). If the value -is @code{nil}, then @key{TAB} indents the current line only if point -is at the left margin or in the line's indentation; otherwise, it -inserts a real tab character. +Apart from the @key{TAB} (@code{indent-for-tab-command}) command, +Emacs provides a variety of commands to perform indentation in other +ways. -@menu -* Indentation Commands:: Various commands and techniques for indentation. -* Tab Stops:: You can set arbitrary "tab stops" and then - indent to the next tab stop when you want to. -* Just Spaces:: You can request indentation using just spaces. -@end menu +@table @kbd +@item C-j +@kindex C-j +@findex newline-and-indent +Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). -@node Indentation Commands, Tab Stops, Indentation, Indentation -@section Indentation Commands and Techniques +@item C-M-o +@kindex C-M-o +@findex split-line +Split the current line at point (@code{split-line}). The text on the +line after point becomes a new line, indented to the same column where +point is located. This command first moves point forward over any +spaces and tabs. Afterward, point is positioned before the inserted +newline. @kindex M-m @findex back-to-indentation - To move over the indentation on a line, do @kbd{M-m} -(@code{back-to-indentation}). This command, given anywhere on a line, -positions point at the first nonblank character on the line, if any, -or else at the end of the line. - - To insert an indented line before the current line, do @kbd{C-a C-o -@key{TAB}}. To make an indented line after the current line, use -@kbd{C-e C-j}. +@item M-m +Move (forward or back) to the first non-whitespace character on the +current line (@code{back-to-indentation}). If there are no +non-whitespace characters on the line, move to the end of the line. - If you just want to insert a tab character in the buffer, type -@kbd{C-q @key{TAB}}. +@item M-i +@kindex M-i +@findex tab-to-tab-stop +Indent whitespace at point, up to the next tab stop +(@code{tab-to-tab-stop}). @xref{Tab Stops}. -@kindex C-M-o -@findex split-line - @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of -the line vertically down, so that the current line becomes two lines. -@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it -inserts after point a newline and enough indentation to reach the same -column point is on. Point remains before the inserted newline; in this -regard, @kbd{C-M-o} resembles @kbd{C-o}. +@findex indent-relative +@item M-x indent-relative +Insert whitespace at point, until point is aligned with the first +non-whitespace character on the previous line (actually, the last +non-blank line). If point is already farther right than that, run +@code{tab-to-tab-stop} instead---unless called with a numeric +argument, in which case do nothing. +@item M-^ @kindex M-^ @findex delete-indentation - To join two lines cleanly, use the @kbd{M-^} -(@code{delete-indentation}) command. It deletes the indentation at -the front of the current line, and the line boundary as well, -replacing them with a single space. As a special case (useful for -Lisp code) the single space is omitted if the characters to be joined -are consecutive open parentheses or closing parentheses, or if the -junction follows another newline. To delete just the indentation of a -line, go to the beginning of the line and use @kbd{M-\} -(@code{delete-horizontal-space}), which deletes all spaces and tabs -around the cursor. - - If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it +Merge the previous and the current line (@code{delete-indentation}). +This ``joins'' the two lines cleanly, by replacing any indentation at +the front of the current line, together with the line boundary, with a +single space. + +As a special case (useful for Lisp code), the single space is omitted +if the characters to be joined are consecutive opening and closing +parentheses, or if the junction follows another newline. + +If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it appears after the newline that is deleted. @xref{Fill Prefix}. +@item C-M-\ @kindex C-M-\ -@kindex C-x TAB @findex indent-region -@findex indent-rigidly - There are also commands for changing the indentation of several lines -at once. They apply to all the lines that begin in the region. -@kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual'' -way, as if you had typed @key{TAB} at the beginning of the line. A -numeric argument specifies the column to indent to, and each line is -shifted left or right so that its first nonblank character appears in -that column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of -the lines in the region right by its argument (left, for negative -arguments). The whole group of lines moves rigidly sideways, which is -how the command gets its name. +Indent all the lines in the region, as though you had typed @key{TAB} +at the beginning of each line (@code{indent-region}). +If a numeric argument is supplied, indent every line in the region to +that column number. + +@item C-x @key{TAB} +@kindex C-x TAB +@findex indent-rigidly @cindex remove indentation - To remove all indentation from all of the lines in the region, -invoke @kbd{C-x @key{TAB}} with a large negative argument, such as --1000. +Shift each line in the region by a fixed distance, to the right or +left (@code{indent-rigidly}). The distance to move is determined by +the numeric argument (positive to move rightward, negative to move +leftward). + +This command can be used to remove all indentation from the lines in +the region, by invoking it with a large negative argument, +e.g. @kbd{C-u -1000 C-x @key{TAB}}. +@end table -@findex indent-relative - @kbd{M-x indent-relative} indents at point based on the previous line -(actually, the last nonempty line). It inserts whitespace at point, moving -point, until it is underneath the next indentation point in the previous line. -An indentation point is the end of a sequence of whitespace or the end of -the line. If point is farther right than any indentation point in the -previous line, @code{indent-relative} runs @code{tab-to-tab-stop} -@ifnottex -(@pxref{Tab Stops}), -@end ifnottex -@iftex -(see next section), -@end iftex -unless it is called with a numeric argument, in which case it does -nothing. - - @xref{Format Indentation}, for another way of specifying the -indentation for part of your text. - -@node Tab Stops, Just Spaces, Indentation Commands, Indentation +@node Tab Stops @section Tab Stops - @cindex tab stops -@cindex using tab stops in making tables -@cindex tables, indentation for -@kindex M-i -@findex tab-to-tab-stop - For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}). -This command inserts indentation before point, enough to reach the -next tab stop column. + +@vindex tab-stop-list + Emacs defines certain column numbers to be @dfn{tab stops}. These +are used as stopping points by @key{TAB} when inserting whitespace in +Text mode and related modes (@pxref{Indentation}), and by commands +like @kbd{M-i} (@pxref{Indentation Commands}). By default, tab stops +are located every 8 columns. These positions are stored in the +variable @code{tab-stop-list}, whose value is a list of column numbers +in increasing order. @findex edit-tab-stops -@findex edit-tab-stops-note-changes @kindex C-c C-c @r{(Edit Tab Stops)} -@vindex tab-stop-list - You can change the tab stops used by @kbd{M-i} and other indentation -commands, so that they need not be spaced every eight characters, or -even regularly spaced. The tab stops are stored in the variable -@code{tab-stop-list}, as a list of column numbers in increasing order. - - A convenient way to set the tab stops is with @kbd{M-x -edit-tab-stops}, which creates and selects a buffer containing a -description of the tab stop settings. You can edit this buffer to -specify different tab stops, and then type @kbd{C-c C-c} to make those -new tab stops take effect. The buffer uses Overwrite mode -(@pxref{Minor Modes}). @code{edit-tab-stops} records which buffer was -current when you invoked it, and stores the tab stops back in that -buffer; normally all buffers share the same tab stops and changing -them in one buffer affects all, but if you happen to make -@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in -that buffer will edit the local settings. - - Here is what the text representing the tab stops looks like for ordinary -tab stops every eight columns. + Instead of customizing the variable @code{tab-stop-list} directly, a +convenient way to view and set tab stops is via the command @kbd{M-x +edit-tab-stops}. This switches to a buffer containing a description +of the tab stop settings, which looks like this: @example : : : : : : @@ -224,37 +164,77 @@ tab stops every eight columns. To install changes, type C-c C-c @end example - The first line contains a colon at each tab stop. The remaining lines -are present just to help you see where the colons are and know what to do. +@noindent +The first line contains a colon at each tab stop. The numbers on the +next two lines are present just to indicate where the colons are. + + You can edit this buffer to specify different tab stops by placing +colons on the desired columns. The buffer uses Overwrite mode +(@pxref{Minor Modes}). When you are done, type @kbd{C-c C-c} to make +the new tab stops take effect. Normally, the new tab stop settings +apply to all buffers. However, if you have made the +@code{tab-stop-list} variable local to the buffer where you called +@kbd{M-x edit-tab-stops} (@pxref{Locals}), then the new tab stop +settings apply only to that buffer. To save the tab stop settings for +future Emacs sessions, use the Customize interface to save the value +of @code{tab-stop-list} (@pxref{Easy Customization}). + + Note that the tab stops discussed in this section have nothing to do +with how tab characters are displayed in the buffer. Tab characters +are always displayed as empty spaces extending to the next +@dfn{display tab stop}. @xref{Text Display}. + +@node Just Spaces +@section Tabs vs. Spaces - Note that the tab stops that control @code{tab-to-tab-stop} have -nothing to do with how tab characters are displayed in the buffer. -Tab characters are always displayed as empty spaces extending to the -next display tab stop, which occurs every @code{tab-width} columns -regardless of the contents of @code{tab-stop-list}. @xref{Text +@vindex tab-width + Normally, indentation commands insert (or remove) an optimal mix of +space characters and tab characters to align to the desired column. +Tab characters are displayed as a stretch of empty space extending to +the next @dfn{display tab stop}. By default, there is one display tab +stop every @code{tab-width} columns (the default is 8). @xref{Text Display}. -@node Just Spaces,, Tab Stops, Indentation -@section Tabs vs. Spaces - @vindex indent-tabs-mode - Emacs normally uses both tabs and spaces to indent lines. If you -prefer, all indentation can be made from spaces only. To request -this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer -variable, so altering the variable affects only the current buffer, -but there is a default value which you can change as well. -@xref{Locals}. - - A tab is not always displayed in the same way. By default, tabs are -eight columns wide, but some people like to customize their editors to -use a different tab width (e.g., by changing the variable -@code{tab-width} in Emacs). By using spaces only, you can make sure -that your file looks the same regardless of the tab width setting. + If you prefer, all indentation can be made from spaces only. To +request this, set the buffer-local variable @code{indent-tabs-mode} to +@code{nil}. @xref{Locals}, for information about setting buffer-local +variables. Note, however, that @kbd{C-q @key{TAB}} always inserts a +tab character, regardless of the value of @code{indent-tabs-mode}. + + One reason to set @code{indent-tabs-mode} to @code{nil} is that not +all editors display tab characters in the same way. Emacs users, too, +may have different customized values of @code{tab-width}. By using +spaces only, you can make sure that your file always looks the same. +If you only care about how it looks within Emacs, another way to +tackle this problem is to set the @code{tab-width} variable in a +file-local variable (@pxref{File Variables}). @findex tabify @findex untabify There are also commands to convert tabs to spaces or vice versa, always -preserving the columns of all nonblank text. @kbd{M-x tabify} scans the +preserving the columns of all non-whitespace text. @kbd{M-x tabify} scans the region for sequences of spaces, and converts sequences of at least two spaces to tabs if that can be done without changing indentation. @kbd{M-x untabify} changes all tabs in the region to appropriate numbers of spaces. + +@node Indent Convenience +@section Convenience Features for Indentation + +@vindex tab-always-indent + The variable @code{tab-always-indent} tweaks the behavior of the +@key{TAB} (@code{indent-for-tab-command}) command. The default value, +@code{t}, gives the behavior described in @ref{Indentation}. If you +change the value to the symbol @code{complete}, then @key{TAB} first +tries to indent the current line, and if the line was already +indented, it tries to complete the text at point (@pxref{Symbol +Completion}). If the value is @code{nil}, then @key{TAB} indents the +current line only if point is at the left margin or in the line's +indentation; otherwise, it inserts a tab character. + +@cindex Electric Indent mode +@cindex mode, Electric Indent +@findex electric-indent-mode + Electric Indent mode is a global minor mode that automatically +indents the line after every @key{RET} you type. To toggle this minor +mode, type @kbd{M-x electric-indent-mode}. diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi index 5a786be62cf..4d574242c8d 100644 --- a/doc/emacs/modes.texi +++ b/doc/emacs/modes.texi @@ -3,11 +3,11 @@ @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Modes, Indentation, International, Top -@chapter Editing Modes +@chapter Major and Minor Modes - Emacs contains many @dfn{editing modes}, each of which alters its -basic behavior in useful ways. These are divided into @dfn{major -modes} and @dfn{minor modes}. + Emacs contains many @dfn{editing modes} that alter its basic +behavior in useful ways. These are divided into @dfn{major modes} and +@dfn{minor modes}. Major modes provide specialized facilities for working on a particular file type, such as a C source file (@pxref{Programs}), or a @@ -38,15 +38,8 @@ one another, and of the selected major mode. Every buffer possesses a major mode, which determines the editing behavior of Emacs while that buffer is current. The mode line -normally shows the name of the current major mode, in parentheses. -@xref{Mode Line}. - - Usually, the major mode is automatically set by Emacs, when you -first visit a file or create a buffer. @xref{Choosing Modes}. You -can explicitly select a new major mode by using an @kbd{M-x} command. -Take the name of the mode and add @code{-mode} to get the name of the -command to select that mode. Thus, you can enter Lisp mode with -@kbd{M-x lisp-mode}. +normally shows the name of the current major mode, in parentheses +(@pxref{Mode Line}). The least specialized major mode is called @dfn{Fundamental mode}. This mode has no mode-specific redefinitions or variable settings, so @@ -55,73 +48,142 @@ user option variable is in its default state. For editing text of a specific type that Emacs knows about, such as Lisp code or English text, you typically use a more specialized major -mode, such as Lisp mode or Text mode. Such major modes change the -meanings of some keys to become more specifically adapted to the -language being edited. The ones that are commonly changed are -@key{TAB}, @key{DEL}, and @kbd{C-j}. The prefix key @kbd{C-c} -normally contains mode-specific commands. In addition, the commands -which handle comments use the mode to determine how comments are to be -delimited. Many major modes redefine the syntactical properties of -characters appearing in the buffer. - - The major modes fall into three major groups. The first group -contains modes for normal text, either plain or with mark-up. It -includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline -mode. The second group contains modes for specific programming -languages. These include Lisp mode (which has several variants), C -mode, Fortran mode, and others. The remaining major modes are not -intended for use on users' files; they are used in buffers created for -specific purposes by Emacs, such as Dired mode for buffers made by -Dired (@pxref{Dired}), Message mode for buffers made by @kbd{C-x m} -(@pxref{Sending Mail}), and Shell mode for buffers used for -communicating with an inferior shell process (@pxref{Interactive -Shell}). - - Most programming-language major modes specify that only blank lines -separate paragraphs. This is to make the paragraph commands useful. -(@xref{Paragraphs}.) They also cause Auto Fill mode to use the -definition of @key{TAB} to indent the new lines it creates. This is -because most lines in a program are usually indented -(@pxref{Indentation}). +mode, such as Lisp mode or Text mode. Most major modes fall into +three major groups. The first group contains modes for normal text, +either plain or with mark-up. It includes Text mode, HTML mode, SGML +mode, @TeX{} mode and Outline mode. The second group contains modes +for specific programming languages. These include Lisp mode (which +has several variants), C mode, Fortran mode, and others. The third +group consists of major modes that are not associated directly with +files; they are used in buffers created for specific purposes by +Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), +Message mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), +and Shell mode for buffers used to communicate with an inferior shell +process (@pxref{Interactive Shell}). + + Usually, the major mode is automatically set by Emacs, when you +first visit a file or create a buffer (@pxref{Choosing Modes}). You +can explicitly select a new major mode by using an @kbd{M-x} command. +Take the name of the mode and add @code{-mode} to get the name of the +command to select that mode. Thus, you can enter Lisp mode with +@kbd{M-x lisp-mode}. + +@vindex major-mode + The value of the buffer-local variable @code{major-mode} is a symbol +with the same name as the major mode command (e.g. @code{lisp-mode}). +This variable is set automatically; you should not change it yourself. + + The default value of @code{major-mode} determines the major mode to +use for files that do not specify a major mode, and for new buffers +created with @kbd{C-x b}. Normally, this default value is the symbol +@code{fundamental-mode}, which specifies Fundamental mode. You can +change this default value via the Customization interface (@pxref{Easy +Customization}), or by adding a line like this to your init file +(@pxref{Init File}): + +@smallexample +(setq-default major-mode 'text-mode) +@end smallexample + +@noindent +If the default value of @code{major-mode} is @code{nil}, the major +mode is taken from the previously current buffer. + + Specialized major modes often change the meanings of certain keys to +do something more suitable for the mode. For instance, programming +language modes bind @key{TAB} to indent the current line according to +the rules of the language (@pxref{Indentation}). The keys that are +commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes +also define special commands of their own, usually bound in the prefix +key @kbd{C-c}. Major modes can also alter user options and variables; +for instance, programming language modes typicaly set a buffer-local +value for the variable @code{comment-start}, which determines how +source code comments are delimited (@pxref{Comments}). + +@findex describe-mode +@kindex C-h m + To view the documentation for the current major mode, including a +list of its key bindings, type @code{C-h m} (@code{describe-mode}). + +@cindex mode hook +@vindex text-mode-hook +@vindex prog-mode-hook + Every major mode, apart from Fundamental mode, defines a @dfn{mode +hook}, a customizable list of Lisp functions to run each time the mode +is enabled in a buffer. @xref{Hooks}, for more information about +hooks. Each mode hook is named after its major mode, e.g. Fortran +mode has @code{fortran-mode-hook}. Furthermore, all text-based major +modes run @code{text-mode-hook}, and all programming language modes +run @code{prog-mode-hook}, prior to running their own mode hooks. +Hook functions can look at the value of the variable @code{major-mode} +to see which mode is actually being entered. + + Mode hooks are commonly used to enable minor modes (@pxref{Minor +Modes}). For example, you can put the following lines in your init +file to enable Flyspell minor mode in all text-based major modes +(@pxref{Spelling}), and Eldoc minor mode in Emacs Lisp mode +(@pxref{Lisp Doc}): + +@example +(add-hook 'text-mode-hook 'flyspell-mode) +(add-hook 'emacs-lisp-mode-hook 'eldoc-mode) +@end example @node Minor Modes @section Minor Modes @cindex minor modes @cindex mode, minor - A minor mode is an optional editing modes that alters the behavior -of Emacs in some well-defined way. Unlike major modes, any number of + A minor mode is an optional editing mode that alters the behavior of +Emacs in some well-defined way. Unlike major modes, any number of minor modes can be in effect at any time. Some minor modes are -@dfn{buffer-local}: they apply only to the current buffer, so you can -enable the mode in certain buffers and not others. Other minor modes -are @dfn{global}: while enabled, they affect everything you do in the -Emacs session, in all buffers. Some global minor modes are enabled by -default. - - Most minor modes say in the mode line when they are enabled, just -after the major mode indicator. For example, @samp{Fill} in the mode -line means that Auto Fill mode is enabled. @xref{Mode Line}. - - Each minor mode is associated with a command, called the @dfn{mode -command}, which turns it on or off. The name of this command consists -of the name of the minor mode, followed by @samp{-mode}; for instance, -the mode command for Auto Fill mode is @code{auto-fill-mode}. Calling -the minor mode command with no prefix argument @dfn{toggles} the mode, -turning it on if it was off, and off if it was on. A positive -argument always turns the mode on, and a zero or negative argument -always turns it off. Mode commands are usually invoked with -@kbd{M-x}, but you can bind keys to them if you wish (@pxref{Key -Bindings}). +@dfn{buffer-local}, and can be turned on (enabled) in certain buffers +and off (disabled) in others. Other minor modes are @dfn{global}: +while enabled, they affect everything you do in the Emacs session, in +all buffers. Most minor modes are disabled by default, but a few are +enabled by default. + + Most buffer-local minor modes say in the mode line when they are +enabled, just after the major mode indicator. For example, +@samp{Fill} in the mode line means that Auto Fill mode is enabled. +@xref{Mode Line}. + +@cindex mode commands for minor modes + Like major modes, each minor mode is associated with a @dfn{mode +command}, whose name consists of the mode name followed by +@samp{-mode}. For instance, the mode command for Auto Fill mode is +@code{auto-fill-mode}. But unlike a major mode command, which simply +enables the mode, the mode command for a minor mode can either enable +or disable it: + +@itemize +@item +If you invoke the mode command directly with no prefix argument +(either via @kbd{M-x}, or by binding it to a key and typing that key; +@pxref{Key Bindings}), that @dfn{toggles} the minor mode. The minor +mode is turned on if it was off, and turned off if it was on. + +@item +If you invoke the mode command with a prefix argument, the minor mode +is unconditionally turned off if that argument is zero or negative; +otherwise, it is unconditionally turned on. + +@item +If the mode command is called via Lisp, the minor mode is +unconditionally turned on if the argument is omitted or @code{nil}. +This makes it easy to turn on a minor mode from a major mode's mode +hook (@pxref{Major Modes}). A non-@code{nil} argument is handled like +an interactive prefix argument, as described above. +@end itemize Most minor modes also have a @dfn{mode variable}, with the same name as the mode command. Its value is non-@code{nil} if the mode is -enabled, and @code{nil} if it is disabled. In some minor modes---but -not all---the value of the variable alone determines whether the mode -is active: the mode command works simply by setting the variable, and -changing the value of the variable has the same effect as calling the -mode command. Because not all minor modes work this way, we recommend -that you avoid changing the mode variables directly; use the mode -commands instead. +enabled, and @code{nil} if it is disabled. In general, you should not +try to enable or disable the mode by changing the value of the mode +variable directly in Lisp; you should run the mode command instead. +However, setting the mode variable through the Customize interface +(@pxref{Easy Customization}) will always properly enable or disable +the mode, since Customize automatically runs the mode command for you. The following is a list of some buffer-local minor modes: @@ -140,7 +202,7 @@ amount of work you can lose in case of a crash. @xref{Auto Save}. @item Enriched mode enables editing and saving of formatted text. -@xref{Formatted Text}. +@xref{Enriched Text}. @item Flyspell mode automatically highlights misspelled words. @@ -189,11 +251,8 @@ Visual Line mode performs ``word wrapping'', causing long lines to be wrapped at word boundaries. @xref{Visual Line Mode}. @end itemize - Here are some useful global minor modes. Since Line Number mode and -Transient Mark mode can be enabled or disabled just by setting the -value of the minor mode variable, you @emph{can} set them differently -for particular buffers, by explicitly making the corresponding -variable local in those buffers. @xref{Locals}. +@noindent +And here are some useful global minor modes: @itemize @bullet @item @@ -261,22 +320,27 @@ text may appear on the line as well. For example, @noindent tells Emacs to use Lisp mode. Note how the semicolon is used to make -Lisp treat this line as a comment. Alternatively, you could write +Lisp treat this line as a comment. You could equivalently write @example ; -*- mode: Lisp;-*- @end example @noindent -The latter format allows you to specify local variables as well, like -this: +You can also use file-local variables to specify buffer-local minor +modes, by using @code{eval} specifications. For example, this first +nonblank line puts the buffer in Lisp mode and enables Auto-Fill mode: @example -; -*- mode: Lisp; tab-width: 4; -*- +; -*- mode: Lisp; eval: (auto-fill-mode 1); -*- @end example - If a file variable specifies a buffer-local minor mode, Emacs -enables that minor mode in the buffer. +@noindent +Note, however, that it is usually inappropriate to enable minor modes +this way, since most minor modes represent individual user +preferences. If you personally want to use a minor mode for a +particular file type, it is better to enable the minor mode via a +major mode hook (@pxref{Major Modes}). @vindex interpreter-mode-alist Second, if there is no file variable specifying a major mode, Emacs @@ -310,9 +374,9 @@ elements of the form @noindent where @var{regexp} is a regular expression (@pxref{Regexps}), and -@var{mode-function} is a Lisp function that toggles a major mode. If -the text at the beginning of the file matches @var{regexp}, Emacs -chooses the major mode specified by @var{mode-function}. +@var{mode-function} is a major mode command. If the text at the +beginning of the file matches @var{regexp}, Emacs chooses the major +mode specified by @var{mode-function}. Alternatively, an element of @code{magic-mode-alist} may have the form @@ -323,7 +387,7 @@ Alternatively, an element of @code{magic-mode-alist} may have the form @noindent where @var{match-function} is a Lisp function that is called at the beginning of the buffer; if the function returns non-@code{nil}, Emacs -set the major mode wit @var{mode-function}. +set the major mode with @var{mode-function}. Fourth---if Emacs still hasn't found a suitable major mode---it looks at the file's name. The correspondence between file names and @@ -370,29 +434,6 @@ only after @code{auto-mode-alist}. By default, @code{magic-fallback-mode-alist} contains forms that check for image files, HTML/XML/SGML files, and PostScript files. -@vindex major-mode - Once a major mode is chosen, Emacs sets the value of the variable -@code{major-mode} to the symbol for that major mode (e.g., -@code{text-mode} for Text mode). This is a per-buffer variable -(@pxref{Locals}); its buffer-local value is set automatically, and you -should not change it yourself. - - The default value of @code{major-mode} determines the major mode to -use for files that do not specify a major mode, and for new buffers -created with @kbd{C-x b}. Normally, this default value is the symbol -@code{fundamental-mode}, which specifies Fundamental mode. You can -change it via the Customization interface (@pxref{Easy -Customization}), or by adding a line like this to your init file -(@pxref{Init File}): - -@smallexample -(setq-default major-mode 'text-mode) -@end smallexample - -@noindent -If the default value of @code{major-mode} is @code{nil}, the major -mode is taken from the previously current buffer. - @findex normal-mode If you have changed the major mode of a buffer, you can return to the major mode Emacs would have chosen automatically, by typing diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 2357902341e..675977c2c35 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -397,7 +397,7 @@ the syntax and conventions for its particular language. Use @kbd{C-q @key{TAB}} to insert a tab character at point. -@kindex C-j +@kindex C-j @r{(indenting source code)} @findex newline-and-indent When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}), which inserts a newline and then adjusts diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index 71c23655608..0df4a3a7bb5 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -571,6 +571,22 @@ the file name to use, or more generally it may be any Lisp expression that returns a file name as a string. @code{rmail-output-file-alist} applies to both @kbd{o} and @kbd{C-o}. +@vindex rmail-automatic-folder-directives +Rmail can automatically save messages from your primary Rmail file +(the one that @code{rmail-file-name} specifies) to other files, based +on the value of the variable @code{rmail-automatic-folder-directives}. +This variable is a list of elements (@samp{directives}) that say which +messages to save where. Each directive is a list consisting of an +output file, followed by one or more pairs of a header name and a regular +expression. If a message has a header matching the specified regular +expression, that message is saved to the given file. If the directive +has more than one header entry, all must match. Rmail checks directives +when it shows a message from the file @code{rmail-file-name}, and +applies the first that matches (if any). If the output file is +@code{nil}, the message is deleted, not saved. For example, you can use +this feature to save messages from a particular address, or with a +particular subject, to a dedicated file. + @node Rmail Labels @section Labels @cindex label (Rmail) diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 562ce92d427..8f353961afb 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -32,10 +32,9 @@ structure. @findex nxml-mode Emacs has other major modes for text which contains ``embedded'' commands, such as @TeX{} and La@TeX{} (@pxref{TeX Mode}); HTML and -SGML (@pxref{HTML Mode}); XML (@pxref{Top, nXML Mode,,nxml-mode, nXML -Mode}); and Groff and Nroff (@pxref{Nroff Mode}). In addition, you -can edit formatted text in WYSIWYG style (``what you see is what you -get''), using Enriched mode (@pxref{Formatted Text}). +SGML (@pxref{HTML Mode}); XML (@pxref{Top,The nXML Mode +Manual,,nxml-mode, nXML Mode}); and Groff and Nroff (@pxref{Nroff +Mode}). @cindex ASCII art If you need to edit pictures made out of text characters (commonly @@ -48,13 +47,14 @@ for editing such pictures. @xref{Picture Mode}. @end ifnottex - +@ifinfo @cindex skeletons @cindex templates @cindex autotyping @cindex automatic typing The ``automatic typing'' features may be useful when writing text. -@inforef{Top,, autotype}. +@inforef{Top,The Autotype Manual,autotype}. +@end ifinfo @menu * Words:: Moving over and killing words. @@ -68,8 +68,8 @@ for editing such pictures. * TeX Mode:: Editing input to the formatter TeX. * HTML Mode:: Editing HTML and SGML files. * Nroff Mode:: Editing input to the formatter nroff. -* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. -* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. +* Enriched Text:: Editing text ``enriched'' with fonts, colors, etc. +* Text Based Tables:: Commands for editing text-based tables. * Two-Column:: Splitting text columns into separate windows. @end menu @@ -78,8 +78,8 @@ for editing such pictures. @cindex words @cindex Meta commands and words - Emacs has commands for moving over or operating on words. By convention, -the keys for them are all Meta characters. + Emacs defines several commands for moving over or operating on +words: @table @kbd @item M-f @@ -157,13 +157,17 @@ the syntax table. Any character can, for example, be declared to be a word delimiter. @xref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp Reference Manual}. + In addition, see @ref{Position Info} for the @kbd{M-=} +(@code{count-words-region}) and @kbd{M-x count-words} commands, which +count and report the number of words in the region or buffer. + @node Sentences @section Sentences @cindex sentences @cindex manipulating sentences - The Emacs commands for manipulating sentences and paragraphs are mostly -on Meta keys, so as to be like the word-handling commands. + The Emacs commands for manipulating sentences and paragraphs are +mostly on Meta keys, like the word-handling commands. @table @kbd @item M-a @@ -180,12 +184,12 @@ Kill back to the beginning of the sentence (@code{backward-kill-sentence}). @kindex M-e @findex backward-sentence @findex forward-sentence - The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and -@code{forward-sentence}) move to the beginning and end of the current -sentence, respectively. They were chosen to resemble @kbd{C-a} and -@kbd{C-e}, which move to the beginning and end of a line. Unlike -them, @kbd{M-a} and @kbd{M-e} move over successive sentences if -repeated. + The commands @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e} +(@code{forward-sentence}) move to the beginning and end of the current +sentence, respectively. Their bindings were chosen to resemble +@kbd{C-a} and @kbd{C-e}, which move to the beginning and end of a +line. Unlike them, @kbd{M-a} and @kbd{M-e} move over successive +sentences if repeated. Moving backward over a sentence places point just before the first character of the sentence; moving forward places point right after the @@ -207,15 +211,14 @@ it kills back to the beginning of the @var{n}th preceding sentence. to the beginning of a sentence. The sentence commands assume that you follow the American typist's -convention of putting two spaces at the end of a sentence; they consider -a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!} +convention of putting two spaces at the end of a sentence. That is, a +sentence ends wherever there is a @samp{.}, @samp{?} or @samp{!} followed by the end of a line or two spaces, with any number of -@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between. -A sentence also begins or ends wherever a paragraph begins or ends. -It is useful to follow this convention, because it makes a distinction -between periods that end a sentence and periods that indicate -abbreviations; that enables the Emacs sentence commands to distinguish, -too. These commands do not stop for periods that indicate abbreviations. +@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in +between. A sentence also begins or ends wherever a paragraph begins +or ends. It is useful to follow this convention, because it allows +the Emacs sentence commands to distinguish between periods that end a +sentence and periods that indicate abbreviations. @vindex sentence-end-double-space If you want to use just one space between sentences, you can set the @@ -225,7 +228,7 @@ drawback: there is no way to distinguish between periods that end sentences and those that indicate abbreviations. For convenient and reliable editing, we therefore recommend you follow the two-space convention. The variable @code{sentence-end-double-space} also -affects filling (@pxref{Fill Commands}) in related ways. +affects filling (@pxref{Fill Commands}). @vindex sentence-end The variable @code{sentence-end} controls how to recognize the end @@ -237,19 +240,14 @@ Emacs computes sentence ends according to various criteria such as the value of @code{sentence-end-double-space}. @vindex sentence-end-without-period - Some languages do not use periods to indicate the end of a sentence. -For example, sentences in Thai end with a double space but without a -period. Set the variable @code{sentence-end-without-period} to + Some languages, such as Thai, do not use periods to indicate the end +of a sentence. Set the variable @code{sentence-end-without-period} to @code{t} in such cases. @node Paragraphs @section Paragraphs @cindex paragraphs @cindex manipulating paragraphs -@kindex M-@{ -@kindex M-@} -@findex backward-paragraph -@findex forward-paragraph The Emacs commands for manipulating paragraphs are also on Meta keys. @@ -262,23 +260,15 @@ Move forward to next paragraph end (@code{forward-paragraph}). Put point and mark around this or next paragraph (@code{mark-paragraph}). @end table - @kbd{M-@{} moves to the beginning of the current or previous -paragraph, while @kbd{M-@}} moves to the end of the current or next -paragraph. Blank lines and text-formatter command lines separate -paragraphs and are not considered part of any paragraph. If there is -a blank line before the paragraph, @kbd{M-@{} moves to the blank line, -because that is convenient in practice. - - In Text mode, an indented line is not a paragraph break. If you -want indented lines to have this effect, use Paragraph-Indent Text -mode instead. @xref{Text Mode}. - - In major modes for programs, paragraphs begin and end only at blank -lines. This makes the paragraph commands useful, even though there -are no paragraphs as such in a program. - - When you have set a fill prefix, then paragraphs are delimited by -all lines which don't start with the fill prefix. @xref{Filling}. +@kindex M-@{ +@kindex M-@} +@findex backward-paragraph +@findex forward-paragraph + @kbd{M-@{} (@code{backward-paragraph}) moves to the beginning of the +current or previous paragraph (see below for the definition of a +paragraph). @kbd{M-@}} (@code{forward-paragraph}) moves to the end of +the current or next paragraph. If there is a blank line before the +paragraph, @kbd{M-@{} moves to the blank line. @kindex M-h @findex mark-paragraph @@ -287,46 +277,57 @@ all lines which don't start with the fill prefix. @xref{Filling}. @kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h} puts point at the beginning and mark at the end of the paragraph point was in. If point is between paragraphs (in a run of blank lines, or -at a boundary), the paragraph following point is surrounded by point -and mark. If there are blank lines preceding the first line of the -paragraph, one of these blank lines is included in the region. If the -region is already active, the command sets the mark without changing -point; furthermore, each subsequent @kbd{M-h} further advances the +at a boundary), @kbd{M-h} sets the region around the paragraph +following point. If there are blank lines preceding the first line of +the paragraph, one of these blank lines is included in the region. If +the region is already active, the command sets the mark without +changing point, and each subsequent @kbd{M-h} further advances the mark by one paragraph. + The definition of a paragraph depends on the major mode. In +Fundamental mode, as well as Text mode and related modes, a paragraph +is separated each neighboring paragraph another by one or more +@dfn{blank lines}---lines that are either empty, or consist solely of +space, tab and/or formfeed characters. In programming language modes, +paragraphs are usually defined in a similar way, so that you can use +the paragraph commands even though there are no paragraphs as such in +a program. + + Note that an indented line is @emph{not} itself a paragraph break in +Text mode. If you want indented lines to separate paragraphs, use +Paragraph-Indent Text mode instead. @xref{Text Mode}. + + If you set a fill prefix, then paragraphs are delimited by all lines +which don't start with the fill prefix. @xref{Filling}. + @vindex paragraph-start @vindex paragraph-separate The precise definition of a paragraph boundary is controlled by the variables @code{paragraph-separate} and @code{paragraph-start}. The -value of @code{paragraph-start} is a regexp that should match any line -that either starts or separates paragraphs. The value of -@code{paragraph-separate} is another regexp that should match only lines -that separate paragraphs without being part of any paragraph (for -example, blank lines). Lines that start a new paragraph and are -contained in it must match only @code{paragraph-start}, not -@code{paragraph-separate}. Each regular expression must match at the -left margin. For example, in Fundamental mode, @code{paragraph-start} -is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is -@w{@code{"[ \t\f]*$"}}. - - Normally it is desirable for page boundaries to separate paragraphs. -The default values of these variables recognize the usual separator for -pages. +value of @code{paragraph-start} is a regular expression that should +match lines that either start or separate paragraphs +(@pxref{Regexps}). The value of @code{paragraph-separate} is another +regular expression that should match lines that separate paragraphs +without being part of any paragraph (for example, blank lines). Lines +that start a new paragraph and are contained in it must match only +@code{paragraph-start}, not @code{paragraph-separate}. For example, +in Fundamental mode, @code{paragraph-start} is @w{@code{"\f\\|[ +\t]*$"}}, and @code{paragraph-separate} is @w{@code{"[ \t\f]*$"}}. @node Pages @section Pages @cindex pages @cindex formfeed character - Within some text files, text is divided into @dfn{pages}, which are -delimited by the @dfn{formfeed character} (@acronym{ASCII} code 12, -sometimes denoted as @key{control-L}). When you print hardcopy for a -file, the formfeed character forces a page break: each page of the -file goes on a separate page on paper. Most Emacs commands treat the -formfeed character just like any other character: you can insert it -with @kbd{C-q C-l}, and delete it with @key{DEL}. However, since -pages are often meaningful divisions of the file, Emacs provides -commands to move over them and operate on them. + Within some text files, text is divided into @dfn{pages} delimited +by the @dfn{formfeed character} (@acronym{ASCII} code 12, also denoted +as @key{control-L}), which is displayed in Emacs as the escape +sequence @samp{^L} (@pxref{Text Display}). Traditionally, when such +text files are printed to hardcopy, each formfeed character forces a +page break. Most Emacs commands treat it just like any other +character, so you can insert it with @kbd{C-q C-l}, delete it with +@key{DEL}, etc. In addition, Emacs provides commands to move over +pages and operate on them. @table @kbd @item M-x what-page @@ -358,9 +359,9 @@ command moves forward past the next page delimiter. @kindex C-x C-p @findex mark-page The @kbd{C-x C-p} command (@code{mark-page}) puts point at the -beginning of the current page and the mark at the end. The page -delimiter at the end is included (the mark follows it). The page -delimiter at the front is excluded (point follows it). +beginning of the current page (after that page delimiter at the +front), and the mark at the end of the page (after the page delimiter +at the end). @kbd{C-x C-p C-w} is a handy way to kill a page to move it elsewhere. If you move to another page delimiter with @kbd{C-x [} and @@ -402,9 +403,7 @@ beginning of a line. specified width. Emacs does filling in two ways. In Auto Fill mode, inserting text with self-inserting characters also automatically fills it. There are also explicit fill commands that you can use when editing -text leaves it unfilled. When you edit formatted text, you can specify -a style of filling for each portion of the text (@pxref{Formatted -Text}). +text leaves it unfilled. @menu * Auto Fill:: Auto Fill mode breaks long lines automatically. @@ -418,9 +417,9 @@ Text}). @cindex Auto Fill mode @cindex mode, Auto Fill - @dfn{Auto Fill} mode is a minor mode in which lines are broken -automatically when they become too wide. Breaking happens only when -you type a @key{SPC} or @key{RET}. + @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor +Modes}) in which lines are broken automatically when they become too +wide. Breaking happens only when you type a @key{SPC} or @key{RET}. @table @kbd @item M-x auto-fill-mode @@ -431,45 +430,43 @@ In Auto Fill mode, break lines when appropriate. @end table @findex auto-fill-mode - @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off -if it was on. With a positive numeric argument it always turns Auto -Fill mode on, and with a negative argument always turns it off. You can -see when Auto Fill mode is in effect by the presence of the word -@samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is -a minor mode which is enabled or disabled for each buffer individually. -@xref{Minor Modes}. - - In Auto Fill mode, lines are broken automatically at spaces when they -get longer than the desired width. Line breaking and rearrangement -takes place only when you type @key{SPC} or @key{RET}. If you wish to -insert a space or newline without permitting line-breaking, type -@kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a -control-J). Also, @kbd{C-o} inserts a newline without line breaking. - - Auto Fill mode works well with programming-language modes, because it -indents new lines with @key{TAB}. If a line ending in a comment gets -too long, the text of the comment is split into two comment lines. -Optionally, new comment delimiters are inserted at the end of the first -line and the beginning of the second so that each line is a separate -comment; the variable @code{comment-multi-line} controls the choice -(@pxref{Comments}). - - Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as -well as for explicit fill commands. It takes a fill prefix -automatically from the second or first line of a paragraph. - - Auto Fill mode does not refill entire paragraphs; it can break lines but -cannot merge lines. So editing in the middle of a paragraph can result in -a paragraph that is not correctly filled. The easiest way to make the -paragraph properly filled again is usually with the explicit fill commands. + The mode command @kbd{M-x auto-fill-mode} toggles Auto Fill mode in +the current buffer. With a positive numeric argument, it enables Auto +Fill mode, and with a negative argument it disables it. If +@code{auto-fill-mode} is called from Lisp with an omitted or +@code{nil} argument, it enables Auto Fill mode. To enable Auto Fill +mode automatically in certain major modes, add @code{auto-fill-mode} +to the mode hooks (@pxref{Major Modes}). When Auto Fill mode is +enabled, the mode indicator @samp{Fill} appears in the mode line +(@pxref{Mode Line}). + + Auto Fill mode breaks lines automatically at spaces whenever they +get longer than the desired width. This line breaking occurs only +when you type @key{SPC} or @key{RET}. If you wish to insert a space +or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} +or @kbd{C-q C-j} respectively. Also, @kbd{C-o} inserts a newline +without line breaking. + + When Auto Fill mode breaks a line, it tries to obey the +@dfn{adaptive fill prefix}: if a fill prefix can be deduced from the +first and/or second line of the current paragraph, it is inserted into +the new line (@pxref{Adaptive Fill}). Otherwise the new line is +indented, as though you had typed @key{TAB} on it +(@pxref{Indentation}). In a programming language mode, if a line is +broken in the middle of a comment, the comment is split by inserting +new comment delimiters as appropriate. + + Auto Fill mode does not refill entire paragraphs; it breaks lines +but does not merge lines. Therefore, editing in the middle of a +paragraph can result in a paragraph that is not correctly filled. To +fill it, call the explicit fill commands +@iftex +described in the next section. +@end iftex @ifnottex -@xref{Fill Commands}. +(@pxref{Fill Commands}). @end ifnottex - Many users like Auto Fill mode and want to use it in all text files. -The section on init files says how to arrange this permanently for yourself. -@xref{Init File}. - @node Fill Commands @subsection Explicit Fill Commands @@ -488,21 +485,23 @@ Center a line. @kindex M-q @findex fill-paragraph - To refill a paragraph, use the command @kbd{M-q} -(@code{fill-paragraph}). This operates on the paragraph that point is -inside, or the one after point if point is between paragraphs. -Refilling works by removing all the line-breaks, then inserting new -ones where necessary. When there is an active region, this command -operates on the text within the region like @code{fill-region}. + The command @kbd{M-q} (@code{fill-paragraph}) @dfn{fills} the +current paragraph. It redistributes the line breaks within the +paragraph, and deletes any excess space and tab characters occurring +within the paragraph, in such a way that the lines end up fitting +within a certain maximum width. @findex fill-region - To refill many paragraphs, use @kbd{M-x fill-region}, which -finds the paragraphs in the region and fills each of them. + Normally, @kbd{M-q} acts on the paragraph where point is, but if +point is between paragraphs, it acts on the paragraph after point. If +the region is active, it acts instead on the text in the region. You +can also call @kbd{M-x fill-region} to specifically fill the text in +the region. @findex fill-region-as-paragraph - @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h} -for finding paragraph boundaries (@pxref{Paragraphs}). For more -control, you can use @kbd{M-x fill-region-as-paragraph}, which refills + @kbd{M-q} and @code{fill-region} use the usual Emacs criteria for +finding paragraph boundaries (@pxref{Paragraphs}). For more control, +you can use @kbd{M-x fill-region-as-paragraph}, which refills everything between point and mark as a single paragraph. This command deletes any blank lines within the region, so separate blocks of text end up combined into one block. @@ -512,9 +511,18 @@ end up combined into one block. as well as filling it. This means that extra spaces are inserted to make the right margin line up exactly at the fill column. To remove the extra spaces, use @kbd{M-q} with no argument. (Likewise for -@code{fill-region}.) Another way to control justification, and choose -other styles of filling, is with the @code{justification} text -property; see @ref{Format Justification}. +@code{fill-region}.) + +@vindex fill-column +@kindex C-x f +@findex set-fill-column + The maximum line width for filling is specified by the buffer-local +variable @code{fill-column}. The default value (@pxref{Locals}) is +70. The easiest way to set @code{fill-column} in the current buffer +is to use the command @kbd{C-x f} (@code{set-fill-column}). With a +numeric argument, it uses that as the new fill column. With just +@kbd{C-u} as argument, it sets @code{fill-column} to the current +horizontal position of point. @kindex M-o M-s @r{(Text mode)} @cindex centering @@ -525,40 +533,27 @@ within the current fill column. With an argument @var{n}, it centers made by Text mode and is available only in that and related modes (@pxref{Text Mode}). -@vindex fill-column -@kindex C-x f -@findex set-fill-column - The maximum line width for filling is in the variable -@code{fill-column}. Altering the value of @code{fill-column} makes it -local to the current buffer; until that time, the default value is in -effect. The default is initially 70. @xref{Locals}. The easiest way -to set @code{fill-column} is to use the command @kbd{C-x f} -(@code{set-fill-column}). With a numeric argument, it uses that as the -new fill column. With just @kbd{C-u} as argument, it sets -@code{fill-column} to the current horizontal position of point. - - Emacs commands normally consider a period followed by two spaces or by -a newline as the end of a sentence; a period followed by just one space -indicates an abbreviation and not the end of a sentence. To preserve -the distinction between these two ways of using a period, the fill -commands do not break a line after a period followed by just one space. - - If the variable @code{sentence-end-double-space} is @code{nil}, the -fill commands expect and leave just one space at the end of a sentence. -Ordinarily this variable is @code{t}, so the fill commands insist on -two spaces for the end of a sentence, as explained above. @xref{Sentences}. + By default, Emacs considers a period followed by two spaces or by a +newline as the end of a sentence; a period followed by just one space +indicates an abbreviation, not the end of a sentence. Accordingly, +the fill commands will not break a line after a period followed by +just one space. If you change the variable +@code{sentence-end-double-space} to a non-@code{nil} value, the fill +commands will break a line after a period followed by one space, and +put just one space after each period. @xref{Sentences}, for other +effects and possible drawbacks of this. @vindex colon-double-space If the variable @code{colon-double-space} is non-@code{nil}, the fill commands put two spaces after a colon. @vindex fill-nobreak-predicate - The variable @code{fill-nobreak-predicate} is a hook (an abnormal -hook, @pxref{Hooks}) specifying additional conditions where -line-breaking is not allowed. Each function is called with no -arguments, with point at a place where Emacs is considering breaking -the line. If a function returns a non-@code{nil} value, then that's -a bad place to break the line. Two standard functions you can use are + To specify additional conditions where line-breaking is not allowed, +customize the abnormal hook variable @code{fill-nobreak-predicate} +(@pxref{Hooks}). Each function in this hook is called with no +arguments, with point positioned where Emacs is considering breaking a +line. If a function returns a non-@code{nil} value, Emacs will not +break the line there. Two functions you can use are @code{fill-single-word-nobreak-p} (don't break after the first word of a sentence or before the last) and @code{fill-french-nobreak-p} (don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). @@ -567,12 +562,11 @@ break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). @subsection The Fill Prefix @cindex fill prefix - To fill a paragraph in which each line starts with a special marker -(which might be a few spaces, giving an indented paragraph), you can use -the @dfn{fill prefix} feature. The fill prefix is a string that Emacs -expects every line to start with, and which is not included in filling. -You can specify a fill prefix explicitly; Emacs can also deduce the -fill prefix automatically (@pxref{Adaptive Fill}). + The @dfn{fill prefix} feature allows paragraphs to be filled so that +each line starts with a special string of characters (such as a +sequence of spaces, giving an indented paragraph). You can specify a +fill prefix explicitly; otherwise, Emacs tries to deduce one +automatically (@pxref{Adaptive Fill}). @table @kbd @item C-x . @@ -596,15 +590,15 @@ after the @kbd{C-x}.) To turn off the fill prefix, specify an empty prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line. When a fill prefix is in effect, the fill commands remove the fill -prefix from each line of the paragraph before filling and insert it on -each line after filling. (The beginning of the first line of the +prefix from each line of the paragraph before filling, and insert it +on each line after filling. (The beginning of the first line of the paragraph is left unchanged, since often that is intentionally different.) Auto Fill mode also inserts the fill prefix automatically -when it makes a new line. The @kbd{C-o} command inserts the fill -prefix on new lines it creates, when you use it at the beginning of a -line (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes -the prefix (if it occurs) after the newline that it deletes -(@pxref{Indentation}). +when it makes a new line (@pxref{Auto Fill}). The @kbd{C-o} command +inserts the fill prefix on new lines it creates, when you use it at +the beginning of a line (@pxref{Blank Lines}). Conversely, the +command @kbd{M-^} deletes the prefix (if it occurs) after the newline +that it deletes (@pxref{Indentation}). For example, if @code{fill-column} is 40 and you set the fill prefix to @samp{;; }, then @kbd{M-q} in the following text @@ -657,7 +651,8 @@ per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. @xref{Locals}. The @code{indentation} text property provides another way to control -the amount of indentation paragraphs receive. @xref{Format Indentation}. +the amount of indentation paragraphs receive. @xref{Enriched +Indentation}. @node Adaptive Fill @subsection Adaptive Filling @@ -754,17 +749,16 @@ Convert region to upper case (@code{upcase-region}). @findex downcase-word @findex upcase-word @findex capitalize-word - The word conversion commands are the most useful. @kbd{M-l} -(@code{downcase-word}) converts the word after point to lower case, moving -past it. Thus, repeating @kbd{M-l} converts successive words. -@kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while -@kbd{M-c} (@code{capitalize-word}) puts the first letter of the word -into upper case and the rest into lower case. All these commands convert -several words at once if given an argument. They are especially convenient -for converting a large amount of text from all upper case to mixed case, -because you can move through the text using @kbd{M-l}, @kbd{M-u} or -@kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead -to skip a word. + @kbd{M-l} (@code{downcase-word}) converts the word after point to +lower case, moving past it. Thus, repeating @kbd{M-l} converts +successive words. @kbd{M-u} (@code{upcase-word}) converts to all +capitals instead, while @kbd{M-c} (@code{capitalize-word}) puts the +first letter of the word into upper case and the rest into lower case. +All these commands convert several words at once if given an argument. +They are especially convenient for converting a large amount of text +from all upper case to mixed case, because you can move through the +text using @kbd{M-l}, @kbd{M-u} or @kbd{M-c} on each word as +appropriate, occasionally using @kbd{M-f} instead to skip a word. When given a negative argument, the word case conversion commands apply to the appropriate number of words before point, but do not move point. @@ -798,9 +792,10 @@ enable the command, which means it will not ask for confirmation again. @cindex mode, Text @findex text-mode - When you edit files of text in a human language, it's more convenient -to use Text mode rather than Fundamental mode. To enter Text mode, type -@kbd{M-x text-mode}. + Text mode is a major mode for editing files of text in a human +language. Files which have names ending in the extension @file{.txt} +are usually opened in Text mode (@pxref{Choosing Modes}). To +explicitly switch to Text mode, type @kbd{M-x text-mode}. In Text mode, only blank lines and page delimiters separate paragraphs. As a result, paragraphs can be indented, and adaptive @@ -808,46 +803,49 @@ filling determines what indentation to use when filling a paragraph. @xref{Adaptive Fill}. @kindex TAB @r{(Text mode)} - Text mode defines @key{TAB} to run @code{indent-relative} -(@pxref{Indentation}), so that you can conveniently indent a line like -the previous line. + In Text mode, the @key{TAB} (@code{indent-for-tab-command}) command +usually inserts whitespace up to the next tab stop, instead of +indenting the current line. @xref{Indentation}, for details. Text mode turns off the features concerned with comments except when you explicitly invoke them. It changes the syntax table so that -single-quotes are considered part of words. However, if a word starts -with single-quotes, these are treated as a prefix for purposes such as -capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into -@samp{'Hello'}, as expected. +single-quotes are considered part of words (e.g.@: @samp{don't} is +considered one word). However, if a word starts with a single-quote, +it is treated as a prefix for the purposes of capitalization +(e.g.@: @kbd{M-c} converts @samp{'hello'} into @samp{'Hello'}, as +expected). @cindex Paragraph-Indent Text mode @cindex mode, Paragraph-Indent Text @findex paragraph-indent-text-mode @findex paragraph-indent-minor-mode If you indent the first lines of paragraphs, then you should use -Paragraph-Indent Text mode rather than Text mode. In this mode, you -do not need to have blank lines between paragraphs, because the -first-line indentation is sufficient to start a paragraph; however -paragraphs in which every line is indented are not supported. Use -@kbd{M-x paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x -paragraph-indent-minor-mode} to enable an equivalent minor mode in -situations where you can't change the major mode---in mail +Paragraph-Indent Text mode (@kbd{M-x paragraph-indent-text-mode}) +rather than Text mode. In that mode, you do not need to have blank +lines between paragraphs, because the first-line indentation is +sufficient to start a paragraph; however paragraphs in which every +line is indented are not supported. Use @kbd{M-x +paragraph-indent-minor-mode} to enable an equivalent minor mode for +situations where you shouldn't change the major mode---in mail composition, for instance. @kindex M-TAB @r{(Text mode)} - Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} -as the command @code{ispell-complete-word}, which performs completion -of the partial word in the buffer before point, using the spelling -dictionary as the space of possible words. @xref{Spelling}. If your -window manager defines @kbd{M-@key{TAB}} to switch windows, you can -type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}. + Text mode binds @kbd{M-@key{TAB}} to @code{ispell-complete-word}. +This command performs completion of the partial word in the buffer +before point, using the spelling dictionary as the space of possible +words. @xref{Spelling}. If your window manager defines +@kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC} +@key{TAB}} or @kbd{C-M-i} instead. @vindex text-mode-hook - Entering Text mode runs the hook @code{text-mode-hook}. Other major -modes related to Text mode also run this hook, followed by hooks of -their own; this includes Paragraph-Indent Text mode, Nroff mode, -@TeX{} mode, Outline mode, and Message mode. Hook functions on -@code{text-mode-hook} can look at the value of @code{major-mode} to -see which of these modes is actually being entered. @xref{Hooks}. + Entering Text mode runs the mode hook @code{text-mode-hook} +(@pxref{Major Modes}). + + The following sections describe several major modes that are +@dfn{derived} from Text mode. These derivatives share most of the +features of Text mode described above. In particular, derivatives of +Text mode run @code{text-mode-hook} prior to running their own mode +hooks. @node Outline Mode @section Outline Mode @@ -858,29 +856,34 @@ see which of these modes is actually being entered. @xref{Hooks}. @findex outline-mode @findex outline-minor-mode @vindex outline-minor-mode-prefix - Outline mode is a major mode much like Text mode but intended for -editing outlines. It allows you to make parts of the text temporarily -invisible so that you can see the outline structure. Type @kbd{M-x -outline-mode} to switch to Outline mode as the major mode of the current -buffer. - - When Outline mode makes a line invisible, the line does not appear -on the screen. The screen appears exactly as if the invisible line -were deleted, except that an ellipsis (three periods in a row) appears -at the end of the previous visible line. (Multiple consecutive -invisible lines produce just one ellipsis.) +@vindex outline-mode-hook + Outline mode is a major mode derived from Text mode, which is +specialized for editing outlines. It provides commands to navigate +between entries in the outline structure, and commands to make parts +of a buffer temporarily invisible, so that the outline structure may +be more easily viewed. Type @kbd{M-x outline-mode} to switch to +Outline mode. Entering Outline mode runs the hook +@code{text-mode-hook} followed by the hook @code{outline-mode-hook} +(@pxref{Hooks}). + + When you use an Outline mode command to make a line invisible +(@pxref{Outline Visibility}), the line disappears from the screen. An +ellipsis (three periods in a row) is displayed at the end of the +previous visible line, to indicate the hidden text. Multiple +consecutive invisible lines produce just one ellipsis. Editing commands that operate on lines, such as @kbd{C-n} and -@kbd{C-p}, treat the text of the invisible line as part of the previous -visible line. Killing the ellipsis at the end of a visible line -really kills all the following invisible lines. - - Outline minor mode provides the same commands as the major mode, -Outline mode, but you can use it in conjunction with other major modes. -Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in -the current buffer. You can also specify this in the text of a file, -with a file local variable of the form @samp{mode: outline-minor} -(@pxref{File Variables}). +@kbd{C-p}, treat the text of the invisible line as part of the +previous visible line. Killing the ellipsis at the end of a visible +line really kills all the following invisible text associated with the +ellipsis. + + Outline minor mode is a buffer-local minor mode which provides the +same commands as the major mode, Outline mode, but can be used in +conjunction with other major modes. You can type @kbd{M-x +outline-minor-mode} to toggle Outline minor mode in the current +buffer, or use a file-local variable setting to enable it in a +specific file (@pxref{File Variables}). @kindex C-c @@ @r{(Outline minor mode)} The major mode, Outline mode, provides special key bindings on the @@ -889,17 +892,12 @@ with a file local variable of the form @samp{mode: outline-minor} major mode's special commands. (The variable @code{outline-minor-mode-prefix} controls the prefix used.) -@vindex outline-mode-hook - Entering Outline mode runs the hook @code{text-mode-hook} followed by -the hook @code{outline-mode-hook} (@pxref{Hooks}). - @menu -* Format: Outline Format. What the text of an outline looks like. -* Motion: Outline Motion. Special commands for moving through - outlines. -* Visibility: Outline Visibility. Commands to control what is visible. -* Views: Outline Views. Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. +* Outline Format:: What the text of an outline looks like. +* Outline Motion:: Special commands for moving through outlines. +* Outline Visibility:: Commands to control what is visible. +* Outline Views:: Outlines and multiple views. +* Foldout:: Folding means zooming in on outlines. @end menu @node Outline Format @@ -909,13 +907,13 @@ the hook @code{outline-mode-hook} (@pxref{Hooks}). @cindex body lines (Outline mode) Outline mode assumes that the lines in the buffer are of two types: @dfn{heading lines} and @dfn{body lines}. A heading line represents a -topic in the outline. Heading lines start with one or more stars; the -number of stars determines the depth of the heading in the outline -structure. Thus, a heading line with one star is a major topic; all the -heading lines with two stars between it and the next one-star heading -are its subtopics; and so on. Any line that is not a heading line is a -body line. Body lines belong with the preceding heading line. Here is -an example: +topic in the outline. Heading lines start with one or more asterisk +(@samp{*}) characters; the number of asterisks determines the depth of +the heading in the outline structure. Thus, a heading line with one +@samp{*} is a major topic; all the heading lines with two @samp{*}s +between it and the next one-@samp{*} heading are its subtopics; and so +on. Any line that is not a heading line is a body line. Body lines +belong with the preceding heading line. Here is an example: @example * Food @@ -997,12 +995,10 @@ Move point up to a lower-level (more inclusive) visible heading line @findex outline-previous-visible-heading @kindex C-c C-n @r{(Outline mode)} @kindex C-c C-p @r{(Outline mode)} - @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next -heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves -similarly backward. Both accept numeric arguments as repeat counts. The -names emphasize that invisible headings are skipped, but this is not really -a special feature. All editing commands that look for lines ignore the -invisible lines automatically. + @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to +the next heading line. @kbd{C-c C-p} +(@code{outline-previous-visible-heading}) moves similarly backward. +Both accept numeric arguments as repeat counts. @findex outline-up-heading @findex outline-forward-same-level @@ -1010,21 +1006,19 @@ invisible lines automatically. @kindex C-c C-f @r{(Outline mode)} @kindex C-c C-b @r{(Outline mode)} @kindex C-c C-u @r{(Outline mode)} - More powerful motion commands understand the level structure of headings. -@kbd{C-c C-f} (@code{outline-forward-same-level}) and + The commands @kbd{C-c C-f} (@code{outline-forward-same-level}) and @kbd{C-c C-b} (@code{outline-backward-same-level}) move from one -heading line to another visible heading at the same depth in -the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves -backward to another heading that is less deeply nested. +heading line to another visible heading at the same depth in the +outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves backward to +another heading that is less deeply nested. @node Outline Visibility @subsection Outline Visibility Commands - The other special commands of outline mode are used to make lines visible -or invisible. Their names all start with @code{hide} or @code{show}. -Most of them fall into pairs of opposites. They are not undoable; instead, -you can undo right past them. Making lines visible or invisible is simply -not recorded by the undo mechanism. + Outline mode provides several commands for temporarily hiding or +revealing parts of the buffer, based on the outline structure. These +commands are not undoable; their effects are simply not recorded by +the undo mechanism, so you can undo right past them (@pxref{Undo}). Many of these commands act on the ``current'' heading line. If point is on a heading line, that is the current heading line; if point @@ -1068,72 +1062,64 @@ the headings leading up from there to the top level of the outline @findex show-entry @kindex C-c C-c @r{(Outline mode)} @kindex C-c C-e @r{(Outline mode)} - Two commands that are exact opposites are @kbd{C-c C-c} -(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They apply -to the body lines directly following the current heading line. -Subheadings and their bodies are not affected. + The simplest of these commands are @kbd{C-c C-c} +(@code{hide-entry}), which hides the body lines directly following the +current heading line, and @kbd{C-c C-e} (@code{show-entry}), which +reveals them. Subheadings and their bodies are not affected. @findex hide-subtree @findex show-subtree @kindex C-c C-s @r{(Outline mode)} @kindex C-c C-d @r{(Outline mode)} @cindex subtree (Outline mode) - Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) -and @kbd{C-c C-s} (@code{show-subtree}). Both apply to the current -heading line's @dfn{subtree}: its body, all its subheadings, both -direct and indirect, and all of their bodies. In other words, the -subtree contains everything following the current heading line, up to -and not including the next heading of the same or higher rank. + The commands @kbd{C-c C-d} (@code{hide-subtree}) and @kbd{C-c C-s} +(@code{show-subtree}) are more powerful. They apply to the current +heading line's @dfn{subtree}: its body, all of its subheadings, both +direct and indirect, and all of their bodies. @findex hide-leaves @findex show-branches +@findex show-children @kindex C-c C-l @r{(Outline mode)} @kindex C-c C-k @r{(Outline mode)} - Intermediate between a visible subtree and an invisible one is having -all the subheadings visible but none of the body. There are two -commands for doing this, depending on whether you want to hide the -bodies or make the subheadings visible. They are @kbd{C-c C-l} -(@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}). - @kindex C-c C-i @r{(Outline mode)} -@findex show-children - A little weaker than @code{show-branches} is @kbd{C-c C-i} -(@code{show-children}). It makes just the direct subheadings -visible---those one level down. Deeper subheadings remain invisible, if -they were invisible. + The command @kbd{C-c C-l} (@code{hide-leaves}) hides the body of the +current heading line as well as all the bodies in its subtree; the +subheadings themselves are left visible. The command @kbd{C-c C-k} +(@code{show-branches}) reveals the subheadings, if they had previously +been hidden (e.g.@: by @kbd{C-c C-d}). The command @kbd{C-c C-i} +(@code{show-children}) is a weaker version of this; it reveals just +the direct subheadings, i.e.@: those one level down. + +@findex hide-other +@kindex C-c C-o @r{(Outline mode)} + The command @kbd{C-c C-o} (@code{hide-other}) hides everything +except the entry that point is in, plus its parents (the headers +leading up from there to top level in the outline) and the top level +headings. @findex hide-body @findex show-all @kindex C-c C-t @r{(Outline mode)} @kindex C-c C-a @r{(Outline mode)} - Two commands have a blanket effect on the whole file. @kbd{C-c C-t} -(@code{hide-body}) makes all body lines invisible, so that you see just -the outline structure (as a special exception, it will not hide lines -at the top of the file, preceding the first header line, even though -these are technically body lines). @kbd{C-c C-a} (@code{show-all}) -makes all lines visible. These commands can be thought of as a pair -of opposites even though @kbd{C-c C-a} applies to more than just body -lines. - @findex hide-sublevels @kindex C-c C-q @r{(Outline mode)} - The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the -top level headings. With a numeric argument @var{n}, it hides everything -except the top @var{n} levels of heading lines. - -@findex hide-other -@kindex C-c C-o @r{(Outline mode)} - The command @kbd{C-c C-o} (@code{hide-other}) hides everything except -the heading and body text that point is in, plus its parents (the headers -leading up from there to top level in the outline) and the top level -headings. + The remaining commands affect the whole buffer. @kbd{C-c C-t} +(@code{hide-body}) makes all body lines invisible, so that you see +just the outline structure (as a special exception, it will not hide +lines at the top of the file, preceding the first header line, even +though these are technically body lines). @kbd{C-c C-a} +(@code{show-all}) makes all lines visible. @kbd{C-c C-q} +(@code{hide-sublevels}) hides all but the top level headings; with a +numeric argument @var{n}, it hides everything except the top @var{n} +levels of heading lines. @findex reveal-mode When incremental search finds text that is hidden by Outline mode, -it makes that part of the buffer visible. If you exit the search -at that position, the text remains visible. You can also -automatically make text visible as you navigate in it by using -@kbd{M-x reveal-mode}. +it makes that part of the buffer visible. If you exit the search at +that position, the text remains visible. You can also automatically +make text visible as you navigate in it by using Reveal mode (@kbd{M-x +reveal-mode}), a buffer-local minor mode. @node Outline Views @subsection Viewing One Outline in Multiple Views @@ -1253,7 +1239,7 @@ it in order for this to take effect. To use the Foldout package, you can type @kbd{M-x load-library @key{RET} foldout @key{RET}}; or you can arrange for to do that -automatically by putting this in your @file{.emacs} file: +automatically by putting this in your init file (@pxref{Init File}): @example (eval-after-load "outline" '(require 'foldout)) @@ -1300,18 +1286,48 @@ Emacs does not guess right, you can select the correct variant of @TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}. - Emacs also provides Bib@TeX{} mode, a major mode for editing -Bib@TeX{} files. Bib@TeX{} is a tool for storing and formatting -bibliographic references, which is commonly used together with -La@TeX{}. In addition, the Ref@TeX{} package provides a minor mode -which can be used in conjunction with La@TeX{} mode to manage -bibliographic references. @inforef{Top,, reftex}. + The following sections document the features of @TeX{} mode and its +variants. There are several other @TeX{}-related Emacs packages, +which are not documented in this manual: + +@itemize @bullet +@item +Bib@TeX{} mode is a major mode for Bib@TeX{} files, which are commonly +used for keeping bibliographic references for La@TeX{} documents. For +more information, see the documentation string for the command +@code{bibtex-mode}. + +@item +The Ref@TeX{} package provides a minor mode which can be used in +conjunction with La@TeX{} mode to manage bibliographic references. +@ifinfo +@xref{Top,The Ref@TeX{} Manual,,reftex}. +@end ifinfo +@ifnotinfo +For more information, see the Ref@TeX{} Info manual, which is +distributed with Emacs. +@end ifnotinfo + +@item +The AUC@TeX{} package provides more advanced features for editing +@TeX{} and its related formats, including the ability to preview +@TeX{} equations within Emacs buffers. Unlike Bib@TeX{} mode and the +Ref@TeX{} package, AUC@TeX{} is not distributed with Emacs by default. +It can be downloaded via the Package Menu (@pxref{Packages}); once +installed, see +@ifinfo +@ref{Top,The AUC@TeX{} Manual,,auctex}. +@end ifinfo +@ifnotinfo +the AUC@TeX{} manual, which is included with the package. +@end ifnotinfo +@end itemize @menu -* Editing: TeX Editing. Special commands for editing in TeX mode. -* LaTeX: LaTeX Editing. Additional commands for LaTeX input files. -* Printing: TeX Print. Commands for printing part of a file with TeX. -* Misc: TeX Misc. Customization of TeX mode, and related features. +* TeX Editing:: Special commands for editing in TeX mode. +* LaTeX Editing:: Additional commands for LaTeX input files. +* TeX Print:: Commands for printing part of a file with TeX. +* TeX Misc:: Customization of TeX mode, and related features. @end menu @node TeX Editing @@ -1336,12 +1352,10 @@ Move forward past the next unmatched close brace (@code{up-list}). @findex tex-insert-quote @kindex " @r{(@TeX{} mode)} In @TeX{}, the character @samp{"} is not normally used; instead, -quotations begin with @samp{``} and end with @samp{''}. For -convenience, @TeX{} mode overrides the normal meaning of the key -@kbd{"} with a command that inserts a pair of single-quotes or -backquotes (@code{tex-insert-quote}). To be precise, it inserts -@samp{``} after whitespace or an open brace, @samp{"} after a -backslash, and @samp{''} after any other character. +quotations begin with @samp{``} and end with @samp{''}. @TeX{} mode +therefore binds the @kbd{"} key to the @code{tex-insert-quote} +command. This inserts @samp{``} after whitespace or an open brace, +@samp{"} after a backslash, and @samp{''} after any other character. As a special exception, if you type @kbd{"} when the text before point is either @samp{``} or @samp{''}, Emacs replaces that preceding @@ -1349,9 +1363,6 @@ text with a single @samp{"} character. You can therefore type @kbd{""} to insert @samp{"}, should you ever need to do so. (You can also use @kbd{C-q "} to insert this character.) - To disable the @kbd{"} expansion feature, eliminate that binding in -the local map (@pxref{Key Bindings}). - In @TeX{} mode, @samp{$} has a special syntax code which attempts to understand the way @TeX{} math mode delimiters match. When you insert a @samp{$} that is meant to exit math mode, the position of the matching @@ -1376,13 +1387,14 @@ text that belongs inside. Afterward, use the command @kbd{C-c @}} @findex tex-validate-region @findex tex-terminate-paragraph @kindex C-j @r{(@TeX{} mode)} - There are two commands for checking the matching of braces. @kbd{C-j} -(@code{tex-terminate-paragraph}) checks the paragraph before point, and -inserts two newlines to start a new paragraph. It outputs a message in -the echo area if any mismatch is found. @kbd{M-x tex-validate-region} -checks a region, paragraph by paragraph. The errors are listed in the -@samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in -that buffer to go to a particular mismatch. + There are two commands for checking the matching of braces. +@kbd{C-j} (@code{tex-terminate-paragraph}) checks the paragraph before +point, and inserts two newlines to start a new paragraph. It outputs +a message in the echo area if any mismatch is found. @kbd{M-x +tex-validate-region} checks a region, paragraph by paragraph. The +errors are listed in an @samp{*Occur*} buffer; you can use the usual +Occur mode commands in that buffer, such as @kbd{C-c C-c}, to visit a +particular mismatch (@pxref{Other Repeating Search}). Note that Emacs commands count square brackets and parentheses in @TeX{} mode, not just braces. This is not strictly correct for the @@ -1394,8 +1406,8 @@ to work with them. @node LaTeX Editing @subsection La@TeX{} Editing Commands - La@TeX{} mode (and its obsolete variant, Sli@TeX{} mode) provide a -few extra features not applicable to plain @TeX{}: + La@TeX{} mode provides a few extra features not applicable to plain +@TeX{}: @table @kbd @item C-c C-o @@ -1408,60 +1420,59 @@ Close the innermost La@TeX{} block not yet closed @findex tex-latex-block @kindex C-c C-o @r{(La@TeX{} mode)} -@vindex latex-block-names - In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to -group blocks of text. To insert a @samp{\begin} and a matching -@samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c -C-o} (@code{tex-latex-block}). A blank line is inserted between the -two, and point is left there. You can use completion when you enter the -block type; to specify additional block type names beyond the standard -list, set the variable @code{latex-block-names}. For example, here's -how to add @samp{theorem}, @samp{corollary}, and @samp{proof}: + In La@TeX{} input, @samp{\begin} and @samp{\end} tags are used to +group blocks of text. To insert a block, type @kbd{C-c C-o} +(@code{tex-latex-block}). This prompts for a block type, and inserts +the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a +blank line between the two and moving point there. -@example -(setq latex-block-names '("theorem" "corollary" "proof")) -@end example +@vindex latex-block-names + When entering the block type argument to @kbd{C-c C-o}, you can use +the usual completion commands (@pxref{Completion}). The default +completion list contains the standard La@TeX{} block types. If you +want additional block types for completion, customize the list +variable @code{latex-block-names}. @findex tex-close-latex-block @kindex C-c C-e @r{(La@TeX{} mode)} - In La@TeX{} input, @samp{\begin} and @samp{\end} commands must -balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to -insert automatically a matching @samp{\end} to match the last unmatched -@samp{\begin}. It indents the @samp{\end} to match the corresponding -@samp{\begin}. It inserts a newline after @samp{\end} if point is at -the beginning of a line. + In La@TeX{} input, @samp{\begin} and @samp{\end} tags must balance. +You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an +@samp{\end} tag which matches the last unmatched @samp{\begin}. It +also indents the @samp{\end} to match the corresponding @samp{\begin}, +and inserts a newline after the @samp{\end} tag if point is at the +beginning of a line. @node TeX Print @subsection @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. + You can invoke @TeX{} as an subprocess of Emacs, supplying either +the entire contents of the buffer or just part of it (e.g.@: one +chapter of a larger document). @table @kbd +@item C-c C-b +Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). @item C-c C-r Invoke @TeX{} on the current region, together with the buffer's header (@code{tex-region}). -@item C-c C-b -Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). -@item C-c @key{TAB} -Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). @item C-c C-f Invoke @TeX{} on the current file (@code{tex-file}). -@item C-c C-l -Recenter the window showing output from the inferior @TeX{} so that -the last line can be seen (@code{tex-recenter-output-buffer}). -@item C-c C-k -Kill the @TeX{} subprocess (@code{tex-kill-job}). -@item C-c C-p -Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c -C-f} command (@code{tex-print}). + @item C-c C-v Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c C-f} command (@code{tex-view}). -@item C-c C-q -Show the printer queue (@code{tex-show-print-queue}). + +@item C-c C-p +Print the output from the last @kbd{C-c C-b}, @kbd{C-c C-r}, or +@kbd{C-c C-f} command (@code{tex-print}). + +@item C-c @key{TAB} +Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). +@item C-c C-l +Recenter the window showing output from @TeX{} so that the last line +can be seen (@code{tex-recenter-output-buffer}). +@item C-c C-k +Kill the @TeX{} subprocess (@code{tex-kill-job}). @item C-c C-c Invoke some other compilation command on the entire current buffer (@code{tex-compile}). @@ -1469,49 +1480,51 @@ Invoke some other compilation command on the entire current buffer @findex tex-buffer @kindex C-c C-b @r{(@TeX{} mode)} -@findex tex-print -@kindex C-c C-p @r{(@TeX{} mode)} @findex tex-view @kindex C-c C-v @r{(@TeX{} mode)} -@findex tex-show-print-queue -@kindex C-c C-q @r{(@TeX{} mode)} - You can pass the current buffer through an inferior @TeX{} by means of -@kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a -temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}). -Afterward, you can use @kbd{C-c C-q} (@code{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 @kbd{C-c C-v} (@code{tex-view}). +@findex tex-print +@kindex C-c C-p @r{(@TeX{} mode)} + To pass the current buffer through @TeX{}, type @kbd{C-c C-b} +(@code{tex-buffer}). The formatted output goes in a temporary file, +normally a @file{.dvi} file. Afterwards, you can type @kbd{C-c C-v} +(@code{tex-view}) to launch an external program, such as +@command{xdvi}, to view this output file. You can also type @kbd{C-c +C-p} (@code{tex-print}) to print a hardcopy of the output file. @cindex @env{TEXINPUTS} environment variable @vindex tex-directory - You can specify the directory to use for running @TeX{} by setting the -variable @code{tex-directory}. @code{"."} is the default value. If -your environment variable @env{TEXINPUTS} contains relative directory -names, or if your files contains @samp{\input} commands with relative -file names, then @code{tex-directory} @emph{must} be @code{"."} or you -will get the wrong results. Otherwise, it is safe to specify some other -directory, such as @code{"/tmp"}. + By default, @kbd{C-c C-b} runs @TeX{} in the current directory. The +output of @TeX{} also goes in this directory. To run @TeX{} in a +different directory, change the variable @code{tex-directory} to the +desired directory name. If your environment variable @env{TEXINPUTS} +contains relative directory names, or if your files contains +@samp{\input} commands with relative file names, then +@code{tex-directory} @emph{must} be @code{"."} or you will get the +wrong results. Otherwise, it is safe to specify some other directory, +such as @code{"/tmp"}. @vindex tex-run-command @vindex latex-run-command -@vindex slitex-run-command -@vindex tex-dvi-print-command @vindex tex-dvi-view-command -@vindex tex-show-queue-command - 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 @code{tex-run-command}, -@code{latex-run-command}, @code{slitex-run-command}, -@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and -@code{tex-show-queue-command}. The default values 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, @samp{latex @var{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 @samp{*} in the command string. For example, +@vindex tex-dvi-print-command + The buffer's @TeX{} variant determines what shell command @kbd{C-c +C-b} actually runs. In Plain @TeX{} mode, it is specified by the +variable @code{tex-run-command}, which defaults to @code{"tex"}. In +La@TeX{} mode, it is specified by @code{latex-run-command}, which +defaults to @code{"latex"}. The shell command that @kbd{C-c C-v} runs +to view the @file{.dvi} output is determined by the variable +@code{tex-dvi-view-command}, regardless of the @TeX{} variant. The +shell command that @kbd{C-c C-p} runs to print the output is +determined by the variable @code{tex-dvi-print-command}. + + Normally, Emacs automatically appends the output file name to the +shell command strings described in the preceding paragraph. For +example, if @code{tex-dvi-view-command} is @code{"xdvi"}, @kbd{C-c +C-v} runs @command{xdvi @var{output-file-name}}. In some cases, +however, the file name needs to be embedded in the command, e.g.@: if +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 @samp{*} in the command string. For example, @example (setq tex-dvi-print-command "dvips -f * | lpr") @@ -1521,12 +1534,12 @@ the file name with @samp{*} in the command string. For example, @kindex C-c C-k @r{(@TeX{} mode)} @findex tex-recenter-output-buffer @kindex C-c C-l @r{(@TeX{} mode)} - The terminal output from @TeX{}, including any error messages, appears -in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can -switch to this buffer and feed it input (this works as in Shell mode; -@pxref{Interactive Shell}). Without switching to this buffer you can -scroll it so that its last line is visible by typing @kbd{C-c -C-l}. + The terminal output from @TeX{}, including any error messages, +appears in a buffer called @samp{*tex-shell*}. If @TeX{} gets an +error, you can switch to this buffer and feed it input (this works as +in Shell mode; @pxref{Interactive Shell}). Without switching to this +buffer you can scroll it so that its last line is visible by typing +@kbd{C-c C-l}. Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if you see that its output is no longer useful. Using @kbd{C-c C-b} or @@ -1534,14 +1547,14 @@ you see that its output is no longer useful. Using @kbd{C-c C-b} or @findex tex-region @kindex C-c C-r @r{(@TeX{} mode)} - You can also pass an arbitrary region through an inferior @TeX{} by typing -@kbd{C-c C-r} (@code{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, @kbd{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 @dfn{header}. + You can also pass an arbitrary region through @TeX{} by typing +@kbd{C-c C-r} (@code{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, @kbd{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 @dfn{header}. @cindex header (@TeX{} mode) To indicate the bounds of the header in Plain @TeX{} mode, you insert two @@ -1639,29 +1652,6 @@ keys (@pxref{Completion}). The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert between Latin-1 encoded files and @TeX{}-encoded equivalents. -@ignore -@c Too cryptic to be useful, too cryptic for me to make it better -- rms. - They -are included by default in the @code{format-alist} variable, so they -can be used with @kbd{M-x format-find-file}, for instance. -@end ignore - -@ignore @c Not worth documenting if it is only for Czech -- rms. -@findex tildify-buffer -@findex tildify-region -@cindex ties, @TeX{}, inserting -@cindex hard spaces, @TeX{}, inserting - The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region} -insert @samp{~} (@dfn{tie}) characters where they are conventionally -required. This is set up for Czech---customize the group -@samp{tildify} for other languages or for other sorts of markup. -@end ignore - -@cindex Ref@TeX{} package -@cindex references, La@TeX{} -@cindex La@TeX{} references - For managing all kinds of references for La@TeX{}, you can use -Ref@TeX{}. @inforef{Top,, reftex}. @node HTML Mode @section SGML and HTML Modes @@ -1764,22 +1754,27 @@ used as a cheap preview (@code{sgml-tags-invisible}). @cindex mode, nXML @findex nxml-mode @cindex XML schema - The default mode for editing XML documents is called nXML mode -(@code{xml-mode} or @code{nxml-mode}). This is a powerful major mode -that can recognize many existing XML schema and use them to provide -completion of XML elements via @kbd{C-@key{RET}} or @kbd{M-@key{TAB}}, -as well as ``on-the-fly'' XML validation with error highlighting. It -is described in its own manual. @xref{Top, nXML Mode,,nxml-mode, nXML -Mode}. + The major mode for editing XML documents is called nXML mode. This +is a powerful major mode that can recognize many existing XML schema +and use them to provide completion of XML elements via +@kbd{C-@key{RET}} or @kbd{M-@key{TAB}}, as well as ``on-the-fly'' XML +validation with error highlighting. To enable nXML mode in an +existing buffer, type @kbd{M-x nxml-mode}, or, equivalently, @kbd{M-x +xml-mode}. Emacs uses nXML mode for files which have the extension +@file{.xml}. For XHTML files, which have the extension @file{.xhtml}, +Emacs uses HTML mode by default; you can make it use nXML mode by +customizing the variable @code{auto-mode-alist} (@pxref{Choosing +Modes}). nXML mode is described in its own manual: @xref{Top, nXML +Mode,,nxml-mode, nXML Mode}. @vindex sgml-xml-mode - However, you can also use SGML mode to edit XML, since XML is a -strict subset of SGML. In XML, every opening tag must have an -explicit closing tag. When the variable @code{sgml-xml-mode} is -non-@code{nil}, the tag insertion commands described above always -insert explicit closing tags as well. When you visit a file in SGML -mode, Emacs determines whether it is XML by examining the file -contents, and sets @code{sgml-xml-mode} accordingly. + You may choose to use the less powerful SGML mode for editing XML, +since XML is a strict subset of SGML. To enable SGML mode in an +existing buffer, type @kbd{M-x sgml-mode}. On enabling SGML mode, +Emacs examines the buffer to determine whether it is XML; if so, it +sets the variable @code{sgml-xml-mode} to a non-@code{nil} value. +This causes SGML mode's tag insertion commands, described above, to +always insert explicit closing tags as well. @node Nroff Mode @section Nroff Mode @@ -1830,86 +1825,84 @@ header level). Entering Nroff mode runs the hook @code{text-mode-hook}, followed by the hook @code{nroff-mode-hook} (@pxref{Hooks}). -@node Formatted Text -@section Editing Formatted Text - +@node Enriched Text +@section Enriched Text @cindex Enriched mode @cindex mode, Enriched -@cindex formatted text +@cindex enriched text @cindex WYSIWYG @cindex word processing - @dfn{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. +@cindex text/enriched MIME format - Enriched mode is a minor mode (@pxref{Minor Modes}). It is -typically used in conjunction with Text mode (@pxref{Text Mode}), but -you can also use it with other major modes such as Outline mode and -Paragraph-Indent Text mode. + Enriched mode is a minor mode for editing formatted text files in a +WYSIWYG (``what you see is what you get'') fashion. When Enriched +mode is enabled, you can apply various formatting properties to the +text in the buffer, such as fonts and colors; upon saving the buffer, +those properties are saved together with the text, using the MIME +@samp{text/enriched} file format. -@cindex text/enriched MIME format - Potentially, Emacs can store formatted text files in various file -formats. Currently, only one format is implemented: @dfn{text/enriched} -format, which is defined by the MIME protocol. @xref{Format -Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual}, -for details of how Emacs recognizes and converts file formats. + Enriched mode is typically used with Text mode (@pxref{Text Mode}). +It is @emph{not} compatible with Font Lock mode, which is used by many +major modes, including most programming language modes, for syntax +highlighting (@pxref{Font Lock}). Unlike Enriched mode, Font Lock +mode assigns text properties automatically, based on the current +buffer contents; those properties are not saved to disk. - The Emacs distribution contains a formatted text file that can serve as -an example. Its name is @file{etc/enriched.doc}. It contains samples -illustrating all the features described in this section. It also -contains a list of ideas for future enhancements. + The file @file{etc/enriched.doc} in the Emacs distribution serves as +an example of the features of Enriched mode. @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. -* Special: Format Properties. The "special" text properties submenu. -* Forcing Enriched Mode:: How to force use of Enriched mode. +* Enriched Mode:: Entering and exiting Enriched mode. +* Hard and Soft Newlines:: There are two different kinds of newlines. +* Editing Format Info:: How to edit text properties. +* Enriched Faces:: Bold, italic, underline, etc. +* Enriched Indentation:: Changing the left and right margins. +* Enriched Justification:: Centering, setting text flush with the + left or right margin, etc. +* Enriched Properties:: The "special" text properties submenu. @end menu -@node Requesting Formatted Text -@subsection Requesting to Edit Formatted Text +@node Enriched Mode +@subsection Enriched Mode - 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 (known as @dfn{text -properties}), and turns on Enriched mode. + Enriched mode is a buffer-local minor mode (@pxref{Minor Modes}). +When you visit a file that has been saved in the @samp{text/enriched} +format, Emacs automatically enables Enriched mode, and applies the +formatting information in the file to the buffer text. When you save +a buffer with Enriched mode enabled, it is saved using the +@samp{text/enriched} format, including the formatting information. @findex enriched-mode - To create a new file of formatted text, first visit the nonexistent -file, then type @kbd{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 @code{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. + To create a new file of formatted text, visit the nonexistent file +and type @kbd{M-x enriched-mode}. This command actually toggles +Enriched mode. With a prefix argument, it enables Enriched mode if +the argument is positive, and disables Enriched mode otherwise. If +you disable Enriched mode, Emacs no longer saves the buffer using the +@samp{text/enriched} format; any formatting properties that have been +added to the buffer remain in the buffer, but they are not saved to +disk. @vindex enriched-translations - You can add annotations for saving additional text properties, which -Emacs normally does not save, by adding to @code{enriched-translations}. -Note that the text/enriched standard requires any non-standard -annotations to have names starting with @samp{x-}, as in -@samp{x-read-only}. This ensures that they will not conflict with -standard annotations that may be added later. - - @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual}, -for more information about text properties. + Enriched mode does not save all Emacs text properties, only those +specified in the variable @code{enriched-translations}. These include +properties for fonts, colors, indentation, and justification. + +@findex format-decode-buffer + If you visit a file and Emacs fails to recognize that it is in the +@samp{text/enriched} format, type @kbd{M-x format-decode-buffer}. +This command prompts for a file format, and re-reads the file in that +format. Specifying the @samp{text/enriched} format automatically +enables Enriched mode. + + To view a @samp{text/enriched} file in raw form (as plain text with +markup tags rather than formatted text), use @kbd{M-x +find-file-literally} (@pxref{Visiting}). + + @xref{Format Conversion,, Format Conversion, elisp, the Emacs Lisp +Reference Manual}, for details of how Emacs recognizes and converts +file formats like @samp{text/enriched}. @xref{Text Properties,,, +elisp, the Emacs Lisp Reference Manual}, for more information about +text properties. @node Hard and Soft Newlines @subsection Hard and Soft Newlines @@ -1918,56 +1911,44 @@ for more information about text properties. @cindex newlines, hard and soft @cindex use-hard-newlines - In formatted text, Emacs distinguishes between two different kinds of -newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable -or disable this feature separately in any buffer with the command -@code{use-hard-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 @key{RET} command (@code{newline}) and @kbd{C-o} -(@code{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 @key{RET} 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. @xref{Auto Fill}. - - On the other hand, in tables and lists, where the lines should always -remain as you type them, you can use @key{RET} to end lines. For these -lines, you may also want to set the justification style to -@code{unfilled}. @xref{Format Justification}. + In Enriched mode, Emacs distinguishes between two different kinds of +newlines, @dfn{hard} newlines and @dfn{soft} newlines. You can also +enable or disable this feature in other buffers, by typing @kbd{M-x +use-hard-newlines}. + + Hard newlines are used to separate paragraphs, or anywhere there +needs to be a line break regardless of how the text is filled; soft +newlines are used for filling. The @key{RET} (@code{newline}) and +@kbd{C-o} (@code{open-line}) commands insert hard newlines. The fill +commands, including Auto Fill (@pxref{Auto Fill}), insert only soft +newlines and delete only soft newlines, leaving hard newlines alone. + + Thus, when editing with Enriched mode, you should not use @key{RET} +or @kbd{C-o} to break lines in the middle of filled paragraphs. Use +Auto Fill mode or explicit fill commands (@pxref{Fill Commands}) +instead. Use @key{RET} or @kbd{C-o} where line breaks should always +remain, such as in tables and lists. For such lines, you may also +want to set the justification style to @code{unfilled} +(@pxref{Enriched Justification}). @node Editing Format Info @subsection 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 @kbd{@key{F10} e t} if you have no mouse), -or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle -mouse button). There are also keyboard commands described in the -following section. - - These items in the Text Properties menu run commands directly: + The easiest way to alter properties is with the Text Properties +menu. You can get to this menu from the Edit menu in the menu bar +(@pxref{Menu Bar}), or with @kbd{C-Mouse-2} (@pxref{Menu Mouse +Clicks}). Some of the commands in the Text Properties menu are listed +below (you can also invoke them with @kbd{M-x}): @table @code @findex facemenu-remove-face-props @item Remove Face Properties -Delete from the region all face and color text properties +Remove face properties from the region (@code{facemenu-remove-face-props}). @findex facemenu-remove-all @item Remove Text Properties -Delete @emph{all} text properties from the region +Remove all text properties from the region, including face properties (@code{facemenu-remove-all}). @findex describe-text-properties @@ -1976,168 +1957,98 @@ Delete @emph{all} text properties from the region @cindex widgets at buffer position @cindex buttons at buffer position @item Describe Properties -List all the text properties, widgets, buttons, and overlays of the -character following point (@code{describe-text-properties}). +List all text properties and other information about the character +following point (@code{describe-text-properties}). @item Display Faces -Display a list of all the defined faces (@code{list-faces-display}). +Display a list of defined faces (@code{list-faces-display}). +@xref{Faces}. @item Display Colors -Display a list of all the defined colors (@code{list-colors-display}). +Display a list of defined colors (@code{list-colors-display}). +@xref{Colors}. @end table -@ifinfo - Other items in the Text Properties menu lead to submenus: - -@menu -* 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. -* Special: Format Properties. The "special" text properties submenu. -@end menu -@end ifinfo -@ifnotinfo - The rest lead to submenus which are described in the following sections. -@end ifnotinfo - -@node Format Faces -@subsection Faces in Formatted Text +@noindent +The other menu entries are described in the following sections. - The Faces submenu under Text Properties lists various Emacs faces -including @code{bold}, @code{italic}, and @code{underline} -(@pxref{Faces}). These menu items operate on the region if it is -active and nonempty. Otherwise, they specify to use that face for an -immediately following self-inserting character. There is also an item -@samp{Other} with which you can enter a face name through the -minibuffer (@pxref{Standard Faces}). +@node Enriched Faces +@subsection Faces in Enriched Text - Instead of the Faces submenu, you can use these keyboard commands: + The following commands can be used to add or remove faces +(@pxref{Faces}). Each applies to the text in the region if the mark +is active, and to the next self-inserting character if the mark is +inactive. With a prefix argument, each command applies to the next +self-inserting character even if the region is active. @table @kbd @kindex M-o d @r{(Enriched mode)} @findex facemenu-set-default @item M-o d -Remove all @code{face} properties from the region (which includes -specified colors), or force the following inserted character to have no -@code{face} property (@code{facemenu-set-default}). +Remove all @code{face} properties (@code{facemenu-set-default}). + @kindex M-o b @r{(Enriched mode)} @findex facemenu-set-bold @item M-o b -Add the face @code{bold} to the region or to the following inserted -character (@code{facemenu-set-bold}). +Apply the @code{bold} face (@code{facemenu-set-bold}). + @kindex M-o i @r{(Enriched mode)} @findex facemenu-set-italic @item M-o i -Add the face @code{italic} to the region or to the following inserted -character (@code{facemenu-set-italic}). +Apply the @code{italic} face (@code{facemenu-set-italic}). + @kindex M-o l @r{(Enriched mode)} @findex facemenu-set-bold-italic @item M-o l -Add the face @code{bold-italic} to the region or to the following -inserted character (@code{facemenu-set-bold-italic}). +Apply the @code{bold-italic} face (@code{facemenu-set-bold-italic}). + @kindex M-o u @r{(Enriched mode)} @findex facemenu-set-underline @item M-o u -Add the face @code{underline} to the region or to the following inserted -character (@code{facemenu-set-underline}). +Apply the @code{underline} face (@code{facemenu-set-underline}). + @kindex M-o o @r{(Enriched mode)} @findex facemenu-set-face @item M-o o @var{face} @key{RET} -Add the face @var{face} to the region or to the following inserted -character (@code{facemenu-set-face}). -@end table +Apply the face @var{face} (@code{facemenu-set-face}). - With a prefix argument, all these commands apply to an immediately -following self-inserting character, disregarding the region. +@findex facemenu-set-foreground +@item M-x facemenu-set-foreground +Prompt for a color (@pxref{Colors}), and apply it as a foreground +color. - A self-inserting character normally inherits the @code{face} -property (and most other text properties) from the preceding character -in the buffer. If you use the above commands to specify face for the -next self-inserting character, or the next section's commands to -specify a foreground or background color for it, then it does not -inherit the @code{face} property from the preceding character; instead -it uses whatever you specified. It will still inherit other text -properties, though. +@findex facemenu-set-background +@item M-x facemenu-set-background +Prompt for a color, and apply it as a background color. +@end table - Strictly speaking, these commands apply only to the first following -self-inserting character that you type. But if you insert additional -characters after it, they will inherit from the first one. So it -appears that these commands apply to all of them. +@noindent +These command are also available via the Text Properties menu. - Enriched mode defines two additional faces: @code{excerpt} and -@code{fixed}. These correspond to codes used in the text/enriched file -format. - - The @code{excerpt} face is intended for quotations. This face is the -same as @code{italic} unless you customize it (@pxref{Face Customization}). - - The @code{fixed} face means, ``Use a fixed-width font for this part -of the text.'' Applying the @code{fixed} face to a part of the text -will cause that part of the text to appear in a fixed-width font, even -if the default font is variable-width. 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 @code{fixed} face for that part. - - By default, the @code{fixed} face looks the same as @code{bold}. -This is an attempt to distinguish it from @code{default}. You may -wish to customize @code{fixed} to some other fixed-width medium font. -@xref{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. - -@node Format Colors -@subsection Colors in Formatted Text - - You can specify foreground and background colors for portions of the -text. Under Text Properties, there is a submenu for specifying the -foreground color, and a submenu for specifying the background color. -Each one lists all the colors that you have used in Enriched mode in -the current Emacs session. - - If the region is active, the command applies to the text in the -region; otherwise, it applies to any immediately following -self-inserting input. When Transient Mark mode is off -(@pxref{Disabled Transient Mark}), it always applies to the region -unless a prefix argument is given, in which case it applies to the -following input. - - Each of the two color submenus contains one additional item: -@samp{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 a list of available colors and their names, use the -@samp{Display Colors} menu item in the Text Properties menu -(@pxref{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 the corresponding -color menu for the duration of the Emacs session. + A self-inserting character normally inherits the face properties +(and most other text properties) from the preceding character in the +buffer. If you use one of the above commands to specify the face for +the next self-inserting character, that character will not inherit the +faces properties from the preceding character, but it will still +inherit other text properties. -@findex facemenu-set-foreground -@findex facemenu-set-background - There are no predefined key bindings for specifying colors, but you can do so -with the extended commands @kbd{M-x facemenu-set-foreground} and -@kbd{M-x facemenu-set-background}. Both of these commands read the name -of the color with the minibuffer. + Enriched mode defines two additional faces: @code{excerpt} and +@code{fixed}. These correspond to codes used in the text/enriched +file format. The @code{excerpt} face is intended for quotations; by +default, it appears the same as @code{italic}. The @code{fixed} face +specifies fixed-width text; by default, it appears the same as +@code{bold}. -@node Format Indentation -@subsection Indentation in Formatted Text +@node Enriched Indentation +@subsection Indentation in Enriched 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 (@pxref{Filling}) and line-breaking commands. + In Enriched mode, you can specify different amounts of indentation +for the right or left margin of a paragraph or a part of a paragraph. +These margins also affect fill commands such as @kbd{M-q} +(@pxref{Filling}). - The Indentation submenu of Text Properties provides a convenient -interface for specifying these properties. The submenu contains four -items: + The Indentation submenu of Text Properties provides four commands +for specifying indentation: @table @code @kindex C-x TAB @r{(Enriched mode)} @@ -2158,44 +2069,20 @@ Make the text narrower by indenting 4 columns at the right margin. Remove 4 columns of indentation from the right margin. @end table - You can use these commands repeatedly to increase or decrease the -indentation. - - The most common way to use them is to change the indentation of an -entire paragraph. For other uses, the effects of refilling can be -hard to predict, except in some special cases like the one described -next. - - The most common other use is to format paragraphs with @dfn{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. - @vindex standard-indent The variable @code{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 @code{fill-column}, as usual. +value is 4. The default right margin for Enriched mode is controlled +by the variable @code{fill-column}, as usual. @kindex C-c [ @r{(Enriched mode)} @kindex C-c ] @r{(Enriched mode)} @findex set-left-margin @findex set-right-margin - There are also two commands for setting the left or right margin of -the region absolutely: @code{set-left-margin} and -@code{set-right-margin}. Enriched mode binds these commands to -@kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the -margin width either with a numeric argument or in the minibuffer. - - 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 @kbd{M-q} (@code{fill-paragraph}) to -refill the paragraph. + You can also type @kbd{C-c [} (@code{set-left-margin}) and @kbd{C-c +]} (@code{set-right-margin}) to set the left and right margins. You +can specify the margin width with a numeric argument; otherwise these +commands prompt for a value via the minibuffer. The fill prefix, if any, works in addition to the specified paragraph indentation: @kbd{C-x .} does not include the specified indentation's @@ -2203,148 +2090,76 @@ whitespace in the new value for the fill prefix, and the fill commands look for the fill prefix after the indentation on each line. @xref{Fill Prefix}. -@node Format Justification -@subsection 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. +@node Enriched Justification +@subsection Justification in Enriched Text - The Justification submenu of Text Properties provides a convenient -interface for specifying the style. The submenu contains five items: - -@table @code -@item 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. - -@item 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. - -@item 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. - -@item Center -This centers every line between the current margins. - -@item Unfilled -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 (@pxref{Hard -and Soft Newlines}) . -@end table - - In Enriched mode, you can also specify justification from the keyboard -using the @kbd{M-j} prefix character: + In Enriched mode, you can use the following commands to specify +various @dfn{justification styles} for filling. These commands apply +to the paragraph containing point, or, if the region is active, to all +paragraphs overlapping the region. @table @kbd @kindex M-j l @r{(Enriched mode)} @findex set-justification-left @item M-j l -Make the region left-filled (@code{set-justification-left}). +Align lines to the left margin (@code{set-justification-left}). + @kindex M-j r @r{(Enriched mode)} @findex set-justification-right @item M-j r -Make the region right-filled (@code{set-justification-right}). +Align lines to the right margin (@code{set-justification-right}). + @kindex M-j b @r{(Enriched mode)} @findex set-justification-full @item M-j b -Make the region fully justified (@code{set-justification-full}). +Align lines to both margins, inserting spaces in the middle of the +line to achieve this (@code{set-justification-full}). + @kindex M-j c @r{(Enriched mode)} @kindex M-S @r{(Enriched mode)} @findex set-justification-center @item M-j c @itemx M-S -Make the region centered (@code{set-justification-center}). +Center lines between the margins (@code{set-justification-center}). + @kindex M-j u @r{(Enriched mode)} @findex set-justification-none @item M-j u -Make the region unfilled (@code{set-justification-none}). +Turn off filling entirely (@code{set-justification-none}). The fill +commands do nothing on text with this setting. You can, however, +still indent the left margin. @end table - 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. + You can also specify justification styles using the Justification +submenu in the Text Properties menu. @vindex default-justification - The default justification style is specified by the variable -@code{default-justification}. Its value should be one of the symbols -@code{left}, @code{right}, @code{full}, @code{center}, or @code{none}. -This is a per-buffer variable. Setting the variable directly affects -only the current buffer. However, customizing it in a Custom buffer -sets (as always) the default value for buffers that do not override it. -@xref{Locals}, and @ref{Easy Customization}. - -@node Format Properties -@subsection Setting Other Text Properties - - The Special Properties submenu of Text Properties can add or remove -three other useful text properties: @code{read-only}, @code{invisible} -and @code{intangible}. The @code{intangible} property disallows -moving point within the text, the @code{invisible} text property hides -text from display, and the @code{read-only} property disallows -alteration of the text. + The default justification style is specified by the per-buffer +variable @code{default-justification}. Its value should be one of the +symbols @code{left}, @code{right}, @code{full}, @code{center}, or +@code{none}. - Each of these special properties has a menu item to add it to the -region. The last menu item, @samp{Remove Special}, removes all of these -special properties from the text in the region. - - Currently, the @code{invisible} and @code{intangible} properties are -@emph{not} saved in the text/enriched format. The @code{read-only} -property is saved, but it is not a standard part of the text/enriched -format, so other editors may not respect it. - -@node Forcing Enriched Mode -@subsection 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, sometimes you must take special actions to convert file -contents or turn on Enriched mode: - -@itemize @bullet -@item -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 @kbd{M-x format-decode-buffer} to -translate it. This also automatically turns on Enriched mode. +@node Enriched Properties +@subsection Setting Other Text Properties -@item -When you @emph{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 @kbd{M-x -enriched-mode}. -@end itemize + The Special Properties submenu of Text Properties has entries for +adding or removing three other text properties: @code{read-only}, +(which disallows alteration of the text), @code{invisible} (which +hides text), and @code{intangible} (which disallows moving point +within the text). The @samp{Remove Special} menu item removes all of +these special properties from the text in the region. - The command @code{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 @key{RET}, which -tells Emacs to guess the format. - -@findex format-find-file - If you wish to look at a text/enriched file in its raw form, as a -sequence of characters rather than as formatted text, use the @kbd{M-x -find-file-literally} command. This visits a file, like -@code{find-file}, but does not do format conversion. It also inhibits -character code conversion (@pxref{Coding Systems}) and automatic -uncompression (@pxref{Compressed Files}). To disable format conversion -but allow character code conversion and/or automatic uncompression if -appropriate, use @code{format-find-file} with suitable arguments. + The @code{invisible} and @code{intangible} properties are @emph{not} +saved in the text/enriched format. The @code{read-only} property is +saved, but it is not a standard part of the text/enriched format, so +other editors may not respect it. @node Text Based Tables @section Editing Text-based Tables @cindex table mode @cindex text-based tables - Table mode provides an easy and intuitive way to create and edit WYSIWYG + Table mode provides an easy and intuitive way to create and edit text-based tables. Here is an example of such a table: @smallexample diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index c44b67454a2..6a6f7b1a4d7 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -193,6 +193,7 @@ Select buffer @var{bufname} in another window @findex display-buffer @item C-x 4 C-o @var{bufname} @key{RET} +@kindex C-x 4 C-o Display buffer @var{bufname} in some window, without trying to select it (@code{display-buffer}). @xref{Displaying Buffers}, for details about how the window is chosen. @@ -385,7 +386,8 @@ change @code{pop-up-frames} (see below) to @code{t}. @item Otherwise, if you specified that the buffer should be displayed in a special frame by customizing @code{special-display-buffer-names} or -@code{special-display-regexps}, do so. @xref{Special Buffer Frames}. +@code{special-display-regexps}, do so. @xref{Choosing Window +Options,,, elisp, The Emacs Lisp Reference Manual}. @vindex pop-up-frames @item @@ -420,7 +422,7 @@ and display the buffer there. @end itemize @node Window Convenience -@section Window Handling Convenience Features and Customization +@section Convenience Features for Window Handling @findex winner-mode @cindex Winner mode diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi index c2e65268d1b..b32b3d905e4 100644 --- a/doc/emacs/xresources.texi +++ b/doc/emacs/xresources.texi @@ -306,14 +306,14 @@ Name to display in the title bar of the initial Emacs frame. @item @code{toolBar} (class @code{ToolBar}) @cindex tool bar Number of lines to reserve for the tool bar. A zero value suppresses -the tool bar. For the Emacs tool bar (i.e. not Gtk+), if the value is -non-zero and @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's -size will be changed automatically so that all tool bar items are visible. - If the value of @code{auto-resize-tool-bars} is @code{grow-only}, -the tool bar expands automatically, but does not contract automatically. -To contract the tool bar, you must redraw the frame by entering @kbd{C-l}. -For the Gtk+ tool bar, any non-zero value means on and -@code{auto-resize-tool-bars} has no effect. +the tool bar. For the Emacs tool bar (i.e.@: not Gtk+), if the value +is non-zero and @code{auto-resize-tool-bars} is non-@code{nil}, the +tool bar's size will be changed automatically so that all tool bar +items are visible. If the value of @code{auto-resize-tool-bars} is +@code{grow-only}, the tool bar expands automatically, but does not +contract automatically. To contract the tool bar, you must redraw the +frame by entering @kbd{C-l}. For the Gtk+ tool bar, any non-zero +value means on and @code{auto-resize-tool-bars} has no effect. @item @code{useXIM} (class @code{UseXIM}) @cindex XIM @@ -641,17 +641,18 @@ The color for the border shadow, on the top and the left. @node GTK resources @appendixsec GTK resources @iftex - The most common way to customize the GTK widgets Emacs uses (menus, dialogs -tool bars and scroll bars) is by choosing an appropriate theme, for example -with the GNOME theme selector. - -You can also do Emacs specific customization -by inserting GTK style directives in the file @file{~/.emacs.d/gtkrc}, -but only if you have a Gtk+ version earlier than 3 (i.e. 2). Some GTK -themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything -works with all themes. To customize Emacs font, background, faces, etc., use -the normal X resources (@pxref{Resources}). We will present some examples of -customizations here, but for a more detailed description, see the online manual + The most common way to customize the GTK widgets Emacs uses (menus, +dialogs tool bars and scroll bars) is by choosing an appropriate +theme, for example with the GNOME theme selector. + +You can also do Emacs specific customization by inserting GTK style +directives in the file @file{~/.emacs.d/gtkrc}, but only if you have a +Gtk+ version earlier than 3 (i.e.@: 2). Some GTK themes ignore +customizations in @file{~/.emacs.d/gtkrc} so not everything works with +all themes. To customize Emacs font, background, faces, etc., use the +normal X resources (@pxref{Resources}). We will present some examples +of customizations here, but for a more detailed description, see the +online manual The first example is just one line. It changes the font on all GTK widgets to courier with size 12: @@ -1065,7 +1066,7 @@ possible states are: This is the default state for widgets. @item ACTIVE This is the state for a widget that is ready to do something. It is -also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"} +also for the trough of a scroll bar, i.e.@: @code{bg[ACTIVE] = "red"} sets the scroll bar trough to red. Buttons that have been pressed but not released yet (``armed'') are in this state. @item PRELIGHT @@ -1109,7 +1110,7 @@ You can't specify the file by its absolute file name. GTK looks for the pixmap file in directories specified in @code{pixmap_path}. @code{pixmap_path} is a colon-separated list of directories within double quotes, specified at the top level in a @file{gtkrc} file -(i.e. not inside a style definition; see example above): +(i.e.@: not inside a style definition; see example above): @smallexample pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" @@ -1131,19 +1132,18 @@ Bold 12}, @samp{Courier 14}, @samp{Times 18}. See below for exact syntax. The names are case insensitive. @end table - There are three ways to specify a color: by name, in hexadecimal -form, and with an RGB triplet. + There are three ways to specify a color: a color name, an RGB +triplet, or a GTK-style RGB triplet. @xref{Colors}, for a description +of color names and RGB triplets. Color names should be enclosed with +double quotes, e.g.@: @samp{"red"}. RGB triplets should be written +without double quotes, e.g.@: @samp{#ff0000}. GTK-style RGB triplets +have the form -@noindent -A color name is written within double quotes, for example @code{"red"}. - -@noindent -Hexadecimal form is the same as in X: -@code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs -must have the same number of hex digits (1, 2, 3 or 4). +@smallexample +@code{@{ @var{r}, @var{g}, @var{b} @}} +@end smallexample @noindent -An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}}, where @var{r}, @var{g} and @var{b} are either integers in the range 0-65535 or floats in the range 0.0-1.0. |