diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/emacs/ChangeLog | 18 | ||||
| -rw-r--r-- | doc/emacs/abbrevs.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/buffers.texi | 5 | ||||
| -rw-r--r-- | doc/emacs/display.texi | 175 | ||||
| -rw-r--r-- | doc/emacs/emacs.texi | 3 | ||||
| -rw-r--r-- | doc/emacs/frames.texi | 121 | ||||
| -rw-r--r-- | doc/emacs/kmacro.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/macos.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/programs.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/rmail.texi | 11 | ||||
| -rw-r--r-- | doc/emacs/search.texi | 4 | ||||
| -rw-r--r-- | doc/lispref/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/lispref/modes.texi | 54 | ||||
| -rw-r--r-- | doc/misc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/misc/cc-mode.texi | 97 | ||||
| -rw-r--r-- | doc/misc/trampver.texi | 2 |
16 files changed, 329 insertions, 179 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 726f565e83..9a501d3837 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,5 +1,23 @@ +2011-10-26 Juanma Barranquero <[email protected]> + + * emacs.texi (Top): Fix typo. + +2011-10-25 Glenn Morris <[email protected]> + + * abbrevs.texi (Saving Abbrevs): + quietly-read-abbrev-file is not a command. (Bug#9866) + +2011-10-24 Chong Yidong <[email protected]> + + * display.texi (Scrolling): Document scroll-up-line and + scroll-down-line. Document scroll-command property. + (Recentering): New node, split off from Scrolling. + 2011-10-23 Chong Yidong <[email protected]> + * frames.texi (Scroll Bars): GTK uses right scroll bars now. + (Tool Bars): Copyedits. + * buffers.texi (Misc Buffer): Don't mention vc-toggle-read-only. 2011-10-22 Chong Yidong <[email protected]> diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index d0833ea085..2eafadf484 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -286,8 +286,6 @@ sessions. Write a file @var{file} describing all defined abbrevs. @item M-x read-abbrev-file @key{RET} @var{file} @key{RET} Read the file @var{file} and define abbrevs as specified therein. -@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET} -Similar but do not display a message about what is going on. @item M-x define-abbrevs Define abbrevs from definitions in current buffer. @item M-x insert-abbrevs diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index aed5473ac1..302693aece 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -229,9 +229,8 @@ have special commands to operate on the text; also by visiting a file whose access control says you cannot write it. @findex toggle-read-only - If you wish to make changes in a read-only buffer, use the command -@kbd{C-x C-q} (@code{toggle-read-only}). It makes a read-only buffer -writable, and makes a writable buffer read-only. This works by + The command @kbd{C-x C-q} (@code{toggle-read-only}) makes a read-only +buffer writable, and makes a writable buffer read-only. This works by setting the variable @code{buffer-read-only}, which has a local value in each buffer and makes the buffer read-only if its value is non-@code{nil}. diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index b72e24bf24..8995b1242b 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -13,6 +13,7 @@ the text is displayed. @menu * Scrolling:: Commands to move text up and down in a window. +* Recentering:: A scroll command that centers the current line. * Auto Scrolling:: Redisplay scrolls text automatically when needed. * Horizontal Scrolling:: Moving text left and right in a window. * Narrowing:: Restricting display and editing to a portion @@ -48,15 +49,15 @@ portion of the buffer is displayed. Scrolling ``forward'' or ``up'' advances the portion of the buffer displayed in the window; equivalently, it moves the buffer text upwards relative to the window. Scrolling ``backward'' or ``down'' -moves the displayed portion backwards, and moves the text downwards -relative to the window. In Emacs, scrolling ``up'' or ``down'' refers -to the direction that the text moves in the window, @emph{not} the -direction that the window moves relative to the text; this terminology -was taken up by Emacs before the modern meaning of ``scrolling up'' -and ``scrolling down'' became widely adopted. Hence the strange -result that @key{PageDown} scrolls ``up'' in the Emacs sense. In this -manual, we refer to scrolling ``forward'' and ``backward'' where -possible, in order to minimize confusion. +displays an earlier portion of the buffer, and moves the text +downwards relative to the window. + + In Emacs, scrolling ``up'' or ``down'' refers to the direction that +the text moves in the window, @emph{not} the direction that the window +moves relative to the text. This terminology was adopted by Emacs +before the modern meaning of ``scrolling up'' and ``scrolling down'' +became widespread. Hence, the strange result that @key{PageDown} +scrolls ``up'' in the Emacs sense. The portion of a buffer displayed in a window always contains point. If you move point past the bottom or top of the window, scrolling @@ -64,11 +65,6 @@ occurs automatically to bring it back onscreen (@pxref{Auto Scrolling}). You can also scroll explicitly with these commands: @table @kbd -@item C-l -Scroll the selected window so that the current line is the center-most -text line; on subsequent consecutive invocations, make the current -line the top-most line, the bottom-most line, and so on in cyclic -order; also, maybe redisplay the screen (@code{recenter-top-bottom}). @item C-v @itemx @key{next} @itemx @key{PageDown} @@ -77,6 +73,86 @@ Scroll forward by nearly a full window (@code{scroll-up-command}). @itemx @key{prior} @itemx @key{PageUp} Scroll backward (@code{scroll-down-command}). +@end table + +@kindex C-v +@kindex M-v +@kindex next +@kindex prior +@kindex PageDown +@kindex PageUp +@findex scroll-up-command +@findex scroll-down-command + @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the +whole window height. The effect is to take the two lines at the +bottom of the window and put them at the top, followed by lines that +were not previously visible. If point was in the text that scrolled +off the top, it ends up on the window's new topmost line. The +@key{next} (or @key{PageDown}) key is equivalent to @kbd{C-v}. + + @kbd{M-v} (@code{scroll-down-command}) scrolls backward in a similar +way. The @key{prior} (or @key{PageUp}) key is equivalent to +@kbd{M-v}. + +@vindex next-screen-context-lines + The number of lines of overlap left by these scroll commands is +controlled by the variable @code{next-screen-context-lines}, whose +default value is 2. You can supply the commands with a numeric prefix +argument, @var{n}, to scroll by @var{n} lines; Emacs attempts to leave +point unchanged, so that the text and point move up or down together. +@kbd{C-v} with a negative argument is like @kbd{M-v} and vice versa. + +@vindex scroll-error-top-bottom + By default, these commands signal an error (by beeping or flashing +the screen) if no more scrolling is possible, because the window has +reached the beginning or end of the buffer. If you change the +variable @code{scroll-error-top-bottom} to @code{t}, the command moves +point to the farthest possible position. If point is already there, +the command signals an error. + +@vindex scroll-preserve-screen-position +@cindex @code{scroll-command} property + Some users like scroll commands to keep point at the same screen +position, so that scrolling back to the same screen conveniently +returns point to its original position. You can enable this behavior +via the variable @code{scroll-preserve-screen-position}. If the value +is @code{t}, Emacs adjusts point to keep the cursor at the same screen +position whenever a scroll command moves it off-window, rather than +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 +command that has a non-@code{nil} @code{scroll-command} property. +@xref{Property Lists,,, elisp, The Emacs Lisp Reference Manual}. + +@vindex scroll-up +@vindex scroll-down +@findex scroll-up-line +@findex scroll-down-line + The commands @kbd{M-x scroll-up} and @kbd{M-x scroll-down} behave +similarly to @code{scroll-up-command} and @code{scroll-down-command}, +except they do not obey @code{scroll-error-top-bottom}. Prior to +Emacs 24, these were the default commands for scrolling up and down. +The commands @kbd{M-x scroll-up-line} and @kbd{M-x scroll-down-line} +scroll the current window by one line at a time. If you intend to use +any of these commands, you might want to give them key bindings +(@pxref{Init Rebinding}). + +@node Recentering +@section Recentering + +@table @kbd +@item C-l +Scroll the selected window so the current line is the center-most text +line; on subsequent consecutive invocations, make the current line the +top line, the bottom line, and so on in cyclic order. Possibly +redisplay the screen too (@code{recenter-top-bottom}). + +@item M-x recenter +Scroll the selected window so the current line is the center-most text +line. Possibly redisplay the screen too. + @item C-M-l Scroll heuristically to bring useful information onto the screen (@code{reposition-window}). @@ -107,14 +183,13 @@ non-zero value @var{n}, @kbd{C-l} always leaves at least @var{n} screen lines between point and the top or bottom of the window (@pxref{Auto Scrolling}). - You can also supply @kbd{C-l} with a prefix argument. With a plain -prefix argument, @kbd{C-u C-l}, Emacs simply recenters point. With a -positive argument @var{n}, it scrolls to place point @var{n} lines -down from the top of the window. An argument of zero puts point on -the topmost line. A negative argument @var{-n} puts point @var{n} -lines from the bottom of the window. When given an argument, -@kbd{C-l} does not clear the screen or cycle through different screen -positions. + You can also give @kbd{C-l} a prefix argument. A plain prefix +argument, @kbd{C-u C-l}, simply recenters point. A positive argument +@var{n} puts point @var{n} lines down from the top of the window. An +argument of zero puts point on the topmost line. A negative argument +@var{-n} puts point @var{n} lines from the bottom of the window. When +given an argument, @kbd{C-l} does not clear the screen or cycle +through different screen positions. @vindex recenter-redisplay If the variable @code{recenter-redisplay} has a non-@code{nil} @@ -127,62 +202,6 @@ becomes garbled for any reason (@pxref{Screen Garbled}). The more primitive command @kbd{M-x recenter} behaves like @code{recenter-top-bottom}, but does not cycle among screen positions. -@kindex C-v -@kindex M-v -@kindex next -@kindex prior -@kindex PageDown -@kindex PageUp -@findex scroll-up-command -@findex scroll-down-command - @kbd{C-v} (@code{scroll-up-command}) scrolls forward by nearly the -whole window height. The effect is to take the two lines at the -bottom of the window and put them at the top, followed by lines that -were not previously visible. If point was in the text that scrolled -off the top, it ends up on the window's new topmost line. - - Similarly, @kbd{M-v} (@code{scroll-down-command}) scrolls backward. - - We refer to @kbd{C-v} and @kbd{M-v} as @dfn{full-screen scroll -commands}. The function key @key{next}, or @key{PageDown}, is -equivalent to @kbd{C-v}; the function key @key{prior}, or -@key{PageUp}, is equivalent to @kbd{M-v}. - -@vindex next-screen-context-lines - The variable @code{next-screen-context-lines} controls the number of -lines of overlap left by the full-screen scroll commands; by default, -it is 2. You can supply these commands with a numeric prefix argument -@var{n}. This scrolls the window by @var{n} lines, while attempting -to leave point unchanged (so that the text and point move up or down -together). @kbd{C-v} with a negative argument is like @kbd{M-v} and -vice versa. - -@vindex scroll-error-top-bottom - By default, the full-screen scroll commands signal an error (by -beeping or flashing the screen) if no more scrolling is possible, -because the window has reached the beginning or end of the buffer. If -you change the variable @code{scroll-error-top-bottom} to @code{t}, -Emacs instead moves point to the farthest possible position. If point -is already there, the command signals an error. - -@vindex scroll-preserve-screen-position - Some users like scroll commands to keep point at the same screen -position. Then, scrolling back to the same screen also conveniently -returns point to its original position. You can enable this via the -variable @code{scroll-preserve-screen-position}. If the value is -@code{t}, Emacs adjusts point to keep it at the same vertical position -within the window, rather than the window edge, whenever a scroll -command moves it off the window. With any other non-@code{nil} value, -Emacs adjusts point this way even if the scroll command leaves point -in the window. - -@vindex scroll-up -@vindex scroll-down - The commands @code{scroll-up} and @code{scroll-down} behave -similarly to @code{scroll-up-command} and @code{scroll-down-command}, -except they do not obey @code{scroll-error-top-bottom}. Prior to -Emacs 24, these were the default commands for scrolling up and down. - @kindex C-M-l @findex reposition-window @kbd{C-M-l} (@code{reposition-window}) scrolls the current window diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index cad0e4db3c..55fdb9ec87 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -295,7 +295,7 @@ Help * Package Keywords:: Finding Lisp libraries by keywords (topics). * Language Help:: Help relating to international language support. * Misc Help:: Other help commands. -* Help Files:: Commands to display auxilliary help files. +* Help Files:: Commands to display auxiliary help files. * Help Echo:: Help on active text and tooltips (`balloon help'). The Mark and the Region @@ -342,6 +342,7 @@ Registers Controlling the Display * Scrolling:: Commands to move text up and down in a window. +* Recentering:: A scrolling command that centers the current line. * Auto Scrolling:: Redisplay scrolls text automatically when needed. * Horizontal Scrolling:: Moving text left and right in a window. * Narrowing:: Restricting display and editing to a portion diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 4c239d364f..49222451cc 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -956,55 +956,43 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}. @cindex Scroll Bar mode @cindex mode, Scroll Bar - On graphical displays, Emacs normally makes a @dfn{scroll bar} at -the left of each Emacs window, running the height of the -window.@footnote{Placing it at the left is usually more useful with -overlapping frames with text starting at the left margin.} - - When Emacs is compiled with GTK+ support on the X Window System, or -in operating systems such as Microsoft Windows or Mac OS, you can use -the scroll bar as you do in other graphical applications. If you -click @kbd{Mouse-1} on the scroll bar's up and down buttons, that -scrolls the window by one line at a time. Clicking @kbd{Mouse-1} -above or below the scroll bar's inner box scrolls the window by nearly -the entire height of the window, like @kbd{M-v} and @kbd{C-v} -respectively (@pxref{Moving Point}). Dragging the inner box with -@kbd{Mouse-1} scrolls the window continuously. - - If Emacs is compiled without GTK+ support on the X Window System, -the scroll bar behaves differently. The scroll bar's inner box is -drawn to represent the portion of the buffer currently displayed, with -the entire height of the scroll bar representing the entire length of -the buffer. @kbd{Mouse-1} anywhere on the scroll bar scrolls forward -like @kbd{C-v}, and @kbd{Mouse-3} scrolls backward like @kbd{M-v}. -Clicking @kbd{Mouse-2} in the scroll bar lets you move or drag the -inner box up and down. - - You can also click @kbd{C-Mouse-2} in the scroll bar to split a -window vertically. The split occurs on the line where you click. + On graphical displays, there is a @dfn{scroll bar} on the side of +each Emacs window. Clicking @kbd{Mouse-1} on the scroll bar's up and +down buttons scrolls the window by one line at a time. Clicking +@kbd{Mouse-1} above or below the scroll bar's inner box scrolls the +window by nearly the entire height of the window, like @kbd{M-v} and +@kbd{C-v} respectively (@pxref{Moving Point}). Dragging the inner box +scrolls continuously. + + If Emacs is compiled on the X Window System without X toolkit +support, the scroll bar behaves differently. Clicking @kbd{Mouse-1} +anywhere on the scroll bar scrolls forward like @kbd{C-v}, while +@kbd{Mouse-3} scrolls backward like @kbd{M-v}. Clicking @kbd{Mouse-2} +in the scroll bar lets you drag the inner box up and down. @findex scroll-bar-mode -@vindex scroll-bar-mode - You can toggle the use of the scroll bar with the command @kbd{M-x -scroll-bar-mode}. With a prefix argument, this command turns use of -scroll bars on if and only if the argument is positive. This command -applies to all frames, including frames yet to be created. Customize -the variable @code{scroll-bar-mode} to control the use of scroll bars -at startup. You can use it to specify that they are placed at the -right of windows if you prefer that. You have to set this variable -through the @samp{Customize} interface (@pxref{Easy Customization}), -or it will not work properly. You can also use the X resource -@samp{verticalScrollBars} to control the initial setting of Scroll Bar -mode. @xref{Resources}. - @findex toggle-scroll-bar - To enable or disable scroll bars for just the selected frame, use the + To toggle the use of scroll bars, type @kbd{M-x scroll-bar-mode}. +This command applies to all frames, including frames yet to be +created. To toggle scroll bars for just the selected frame, use the command @kbd{M-x toggle-scroll-bar}. +@vindex scroll-bar-mode + To control the use of scroll bars at startup, customize the variable +@code{scroll-bar-mode}. Its value should be either @code{right} (put +scroll bars on the right side of windows), @code{left} (put them on +the left), or @code{nil} (disable scroll bars). By default, Emacs +puts scroll bars on the right if it was compiled with GTK+ support on +the X Window System, and on MS-Windows or Mac OS; Emacs puts scroll +bars on the left if compiled on the X Window system without GTK+ +support (following the old convention for X applications). + @vindex scroll-bar-width @cindex width of the scroll bar - You can control the scroll bar width by changing the value of the -@code{scroll-bar-width} frame parameter. + You can also use the X resource @samp{verticalScrollBars} to enable +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 @@ -1082,36 +1070,33 @@ menus' visual appearance. @cindex mode, Tool Bar @cindex icons, toolbar - The @dfn{tool bar} is a line (or lines) of icons at the top of the -Emacs window, just below the menu bar. You can click on these icons -with the mouse to do various jobs. - - The global tool bar contains general commands. Some major modes -define their own tool bars to replace it. A few ``special'' modes -that are not designed for ordinary editing remove some items from the -global tool bar. + On graphical displays, Emacs puts a @dfn{tool bar} at the top of +each frame, just below the menu bar. This is a row of icons which you +can click on with the mouse to invoke various commands. - Tool bars work only on a graphical display. The tool bar uses colored -XPM icons if Emacs was built with XPM support. Otherwise, the tool -bar uses monochrome icons (PBM or XBM format). + The global (default) tool bar contains general commands. Some major +modes define their own tool bars; whenever a buffer with such a major +mode is current, the mode's tool bar replaces the global tool bar. @findex tool-bar-mode @vindex tool-bar-mode - You can turn display of tool bars on or off with @kbd{M-x -tool-bar-mode} or by customizing the option @code{tool-bar-mode}. + To toggle the use of tool bars, type @kbd{M-x tool-bar-mode}. This +command applies to all frames, including frames yet to be created. To +control the use of tool bars at startup, customize the variable +@code{tool-bar-mode}. @vindex tool-bar-style @cindex Tool Bar style - When Emacs is compiled with GTK+ support, tool bars can have text and images. -Customize @code{tool-bar-style} to select style. The default style is -the same as for the desktop in the Gnome case. If no default is found, -the tool bar uses just images. + When Emacs is compiled with GTK+ support, each tool bar item can +consist of an image, or a text label, or both. By default, Emacs +follows the Gnome desktop's tool bar style setting; if none is +defined, it displays tool bar items as just images. To impose a +specific tool bar style, customize the variable @code{tool-bar-style}. @cindex Tool Bar position - You can also control the placement of the tool bar for the GTK+ tool bar -with the frame parameter @code{tool-bar-position}. -For a detailed description of frame parameters and customization, -see @ref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}. + You can also control the placement of the tool bar for the GTK+ tool +bar with the frame parameter @code{tool-bar-position}. @xref{Frame +Parameters,,, elisp, The Emacs Lisp Reference Manual}. @node Dialog Boxes @section Using Dialog Boxes @@ -1186,11 +1171,11 @@ options for displaying tooltips, use @kbd{M-x customize-group customizing the windows that display tooltips. @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 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. @node Mouse Avoidance @section Mouse Avoidance diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi index ac81377aec..4676983fc6 100644 --- a/doc/emacs/kmacro.texi +++ b/doc/emacs/kmacro.texi @@ -147,7 +147,7 @@ beginning of the line and then executing the macro. @findex kmacro-start-macro @findex kmacro-end-macro In addition to the @key{F3} and @key{F4} commands described above, -Emacs also supports an older set of keybindings for defining and +Emacs also supports an older set of key bindings for defining and executing keyboard macros. To begin a macro definition, type @kbd{C-x (} (@code{kmacro-start-macro}); as with @key{F3}, a prefix argument appends this definition to the last keyboard macro. To end a macro diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index f4a5a2858c..5a97fa8460 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -36,7 +36,7 @@ Support}), but we hope to improve it in the future. By default, the @key{alt} and @key{option} keys are the same as @key{Meta}. The Mac @key{Cmd} key is the same as @key{Super}, and -Emacs provides a set of keybindings using this modifier key that mimic +Emacs provides a set of key bindings using this modifier key that mimic other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}). You can change these bindings in the usual way (@pxref{Key Bindings}). diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 5745dd7c66..2357902341 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1441,7 +1441,7 @@ parsed, and move point there (@code{semantic-complete-jump}). @kindex C-c , @key{SPC} Display a list of possible completions for the symbol at point (@code{semantic-complete-analyze-inline}). This also activates a set -of special keybindings for choosing a completion: @key{RET} accepts +of special key bindings for choosing a completion: @key{RET} accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible completions, @key{TAB} completes as far as possible and then cycles, and @kbd{C-g} or any other key aborts completion. diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index 9e30b65728..71c2365560 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -1242,11 +1242,12 @@ coding system, the result should be readable. @node Rmail Editing @section Editing Within a Message - Most of the usual Emacs keybindings are available in Rmail mode, though a -few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for -other purposes. However, the Rmail buffer is normally read only, and -most of the letters are redefined as Rmail commands. If you want to -edit the text of a message, you must use the Rmail command @kbd{e}. + Most of the usual Emacs key bindings are available in Rmail mode, +though a few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by +Rmail for other purposes. However, the Rmail buffer is normally read +only, and most of the letters are redefined as Rmail commands. If you +want to edit the text of a message, you must use the Rmail command +@kbd{e}. @table @kbd @item e diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index 31b5aa37f8..a8bd1cdf18 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -268,8 +268,8 @@ use it (@pxref{Rebinding}). @vindex isearch-mode-map When incremental search is active, you can type @kbd{C-h C-h} to -access interactive help options, including a list of special -keybindings. These keybindings are part of the keymap +access interactive help options, including a list of special key +bindings. These key bindings are part of the keymap @code{isearch-mode-map} (@pxref{Keymaps}). @node Isearch Yank diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 490280dae2..acc334ea00 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2011-10-26 Chong Yidong <[email protected]> + + * modes.texi (Running Hooks): Document with-wrapper-hook. + 2011-10-18 Chong Yidong <[email protected]> * display.texi (Glyphless Chars): New node. diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index eb81ebc4ac..9d652901e5 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -84,8 +84,9 @@ its value is just a single function, not a list of functions. @node Running Hooks @subsection Running Hooks - At the appropriate times, Emacs uses the @code{run-hooks} function -and the other functions below to run particular hooks. + In this section, we document the @code{run-hooks} function, which is +used to run a normal hook. We also document the functions for running +various kinds of abnormal hooks. @defun run-hooks &rest hookvars This function takes one or more normal hook variable names as @@ -108,28 +109,49 @@ be run as well. @end defun @defun run-hook-with-args hook &rest args -This function is the way to run an abnormal hook and always call all -of the hook functions. It calls each of the hook functions one by -one, passing each of them the arguments @var{args}. +This function runs an abnormal hook by calling all the hook functions in +@var{hook}, passing each one the arguments @var{args}. @end defun @defun run-hook-with-args-until-failure hook &rest args -This function is the way to run an abnormal hook until one of the hook -functions fails. It calls each of the hook functions, passing each of -them the arguments @var{args}, until some hook function returns -@code{nil}. It then stops and returns @code{nil}. If none of the -hook functions return @code{nil}, it returns a non-@code{nil} value. +This function runs an abnormal hook by calling each hook function in +turn, stopping if one of them ``fails'' by returning @code{nil}. Each +hook function is passed the arguments @var{args}. If this function +stops because one of the hook functions fails, it returns @code{nil}; +otherwise it returns a non-@code{nil} value. @end defun @defun run-hook-with-args-until-success hook &rest args -This function is the way to run an abnormal hook until a hook function -succeeds. It calls each of the hook functions, passing each of them -the arguments @var{args}, until some hook function returns -non-@code{nil}. Then it stops, and returns whatever was returned by -the last hook function that was called. If all hook functions return -@code{nil}, it returns @code{nil} as well. +This function runs an abnormal hook by calling each hook function, +stopping if one of them ``succeeds'' by returning a non-@code{nil} +value. Each hook function is passed the arguments @var{args}. If this +function stops because one of the hook functions returns a +non-@code{nil} value, it returns that value; otherwise it returns +@code{nil}. @end defun +@defmac with-wrapper-hook hook args &rest body +This macro runs the abnormal hook @code{hook} as a series of nested +``wrapper functions'' around the @var{body} forms. The effect is +similar to nested @code{around} advices (@pxref{Around-Advice}). + +Each hook function must accept an argument list consisting of a function +@var{fun}, followed by the additional arguments listed in @var{args}. +The function @var{fun} passed to the very first hook function in +@var{hook} does the same as @var{body}, if it is called with arguments +@var{args}. The @var{fun} passed to each successive hook function is +constructed from all the preceding hook functions (and @var{body}); if +this @var{fun} is called with arguments @var{args}, it does what the +@code{with-wrapper-hook} call would if the preceding hook functions were +the only ones in @var{hook}. + +In the function definition of the hook function, @var{fun} can be called +any number of times (including not calling it at all). This function +definition is then used to construct the @var{fun} passed to the next +hook function in @var{hook}, if any. The last or ``outermost'' +@var{fun} is called once to produce the effect. +@end defmac + @node Setting Hooks @subsection Setting Hooks diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 02c2d2b875..6b0ef9c5d8 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,9 @@ +2011-10-23 Michael Albinus <[email protected]> + + Sync with Tramp 2.2.3. + + * trampver.texi: Update release number. + 2011-10-14 Glenn Morris <[email protected]> * ert.texi (Introduction, How to Run Tests) diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 8818904982..887e3f3c80 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -341,6 +341,11 @@ Line-Up Functions * Comment Line-Up:: * Misc Line-Up:: +Customizing Macros + +* Macro Backslashes:: +* Macros with ;:: + @end detailmenu @end menu @@ -655,6 +660,10 @@ expression, to some statements, or perhaps to whole functions, the syntactic recognition can be wrong. @ccmode{} manages to figure it out correctly most of the time, though. +Some macros, when invoked, ''have their own semicolon''. To get the +next line indented correctly, rather than as a continuation line, +@xref{Macros with ;}. + Reindenting large sections of code can take a long time. When @ccmode{} reindents a region of code, it is essentially equivalent to hitting @key{TAB} on every line of the region. @@ -6561,6 +6570,9 @@ custom line-up function associated with it. @section Other Special Indentations @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +To configure macros which you invoke without a terminating @samp{;}, +see @xref{Macros with ;}. + Here are the remaining odds and ends regarding indentation: @defopt c-label-minimum-indentation @@ -6612,6 +6624,13 @@ functions to this hook, not remove them. @xref{Style Variables}. @cindex preprocessor directives @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +Preprocessor macros in C, C++, and Objective C (introduced by +@code{#define}) have a syntax different from the main language---for +example, a macro declaration is not terminated by a semicolon, and if +it is more than a line long, line breaks in it must be escaped with +backslashes. @ccmode{} has some commands to manipulate these, see +@ref{Macro Backslashes}. + Normally, the lines in a multi-line macro are indented relative to each other as though they were code. You can suppress this behavior by setting the following user option: @@ -6623,6 +6642,28 @@ is @code{nil}, all lines inside macro definitions are analyzed as @code{cpp-macro-cont}. @end defopt +Because a macro can expand into anything at all, near where one is +invoked @ccmode{} can only indent and fontify code heuristically. +Sometimes it gets it wrong. Usually you should try to design your +macros so that they ''look like ordinary code'' when you invoke them. +However, one situation is so common that @ccmode{} handles it +specially: that is when certain macros needn't (or mustn't) be +followed by a @samp{;}. You need to configure @ccmode{} to handle +these macros properly, see @ref{Macros with ;}. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@menu +* Macro Backslashes:: +* Macros with ;:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Macro Backslashes, Macros with ;, Custom Macros, Custom Macros +@comment node-name, next, previous, up +@section Customizing Macro Backslashes +@cindex #define +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + @ccmode{} provides some tools to help keep the line continuation backslashes in macros neat and tidy. Their precise action is customized with these variables: @@ -6665,6 +6706,62 @@ get aligned only when you explicitly invoke the command @end defopt @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Macros with ;, , Macro Backslashes, Custom Macros +@comment node-name, next, previous, up +@section Macros with semicolons +@cindex macros with semicolons +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +Macros which needn't (or mustn't) be followed by a semicolon when you +invoke them, @dfn{macros with semicolons}, are very common. These can +cause @ccmode{} to parse the next line wrongly as a +@code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent +it. + +You can prevent this by specifying which macros have semicolons. It +doesn't matter whether or not such a macro has a parameter list: + +@defopt c-macro-names-with-semicolon +@vindex macro-names-with-semicolon (c-) +This buffer-local variable specifies which macros have semicolons. +After setting its value, you need to call +@code{c-make-macro-with-semi-re} for it to take effect. It should be +set to one of these values: + +@table @asis +@item nil +There are no macros with semicolons. +@item a list of strings +Each string is the name of a macro with a semicolon. Only valid +@code{#define} names are allowed here. For example, to set the +default value, you could write the following into your @file{.emacs}: + +@example +(setq c-macro-names-with-semicolon + '("Q_OBJECT" "Q_PROPERTY" "Q_DECLARE" "Q_ENUMS")) +@end example + +@item a regular expression +This matches each symbol which is a macro with a semicolon. It must +not match any string which isn't a valid @code{#define} name. For +example: + +@example +(setq c-macro-names-with-semicolon + "\\<\\(CLEAN_UP_AND_RETURN\\|Q_[[:upper:]]+\\)\\>") +@end example +@end table +@end defopt + +@defun c-make-macro-with-semi-re +@findex make-macro-with-semi-re (c-) +Call this (non-interactive) function, which sets internal variables, +each time you change the value of +@code{c-macro-names-with-semicolon}. It takes no arguments, and its +return value has no meaning. This function is called by @ccmode{}'s +initialization code. +@end defun + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Odds and Ends, Sample .emacs File, Custom Macros, Top @comment node-name, next, previous, up @chapter Odds and Ends diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 31d3ac0204..63dc78dc4e 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,7 +8,7 @@ @c In the Tramp CVS, the version number is auto-frobbed from @c configure.ac, so you should edit that file and run @c "autoconf && ./configure" to change the version number. -@set trampver 2.2.3-pre +@set trampver 2.2.3-24.1 @c Other flags from configuration @set instprefix /usr/local |