diff options
Diffstat (limited to 'doc')
59 files changed, 4540 insertions, 4801 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index b796acd8b39..7661b8c401b 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,209 @@ +2011-12-10 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (Windows Fonts): Document how to force GDI font + backend on MS-Windows. + +2011-12-10 Chong Yidong <cyd@gnu.org> + + * building.texi (Compilation): Say what the -k flag to make does. + Move subprocess discussion to Compilation Shell. + (Compilation Mode): Add xref for grep, occur, and mouse + references. Define "locus". + (Grep Searching): Use @command. + (Debuggers, Commands of GUD, GDB Graphical Interface): Clarify + intro. + (Starting GUD): Clarify how arguments are specified. + (Debugger Operation): Index entry for "GUD interaction buffer", + and move basic description here from Commands of GUD node. + (GDB User Interface Layout): Copyedits. + (Source Buffers): Remove gdb-find-source-frame, which is not in + gdb-mi.el. + (Other GDB Buffers): Remove gdb-use-separate-io-buffer and + toggle-gdb-all-registers, which are not in gdb-mi.el. Don't + re-document GUD interaction buffers. + + * programs.texi (Symbol Completion): M-TAB can now use Semantic. + (Semantic): Add cindex entries for Semantic. + +2011-12-06 Chong Yidong <cyd@gnu.org> + + * programs.texi (Man Page): Clarify how to use Man-switches. + Don't bother documenting Man-fontify-manpage-flag. + (Lisp Doc): Add xref to Name Help node. + (Hideshow): Add cindex. Mention role of ellipses, and default + value of hs-isearch-open. Don't bother documenting + hs-special-modes-alist. + (Symbol Completion): Add kindex for C-M-i. Don't recommend + changing the window manager binding of M-TAB. + +2011-12-05 Chong Yidong <cyd@gnu.org> + + * programs.texi (Comment Commands): Fix description of for M-; on + blank lines. Move documentation of comment-region here. + (Multi-Line Comments): Clarify the role of comment-multi-line. + Refer to Comment Commands for comment-region doc. + (Options for Comments): Refer to Multi-Line Comments for + comment-multi-line doc, instead of duplicating it. Fix default + values of comment-padding and comment-start-skip. + +2011-12-04 Chong Yidong <cyd@gnu.org> + + * programs.texi (Program Modes): Mention modes that are not + included with Emacs. Fix references to other manuals for tex. + Add index entry for backward-delete-char-untabify. Mention + prog-mode-hook. + (Which Function): Use "global minor mode" terminology. + (Basic Indent, Multi-line Indent): Refer to previous descriptions + in Indentation chapter to avoid duplication. + (Expressions): Copyedit. + (Matching): Document Electric Pair mode. + + * ack.texi (Acknowledgments): + * rmail.texi (Movemail, Other Mailbox Formats): + * frames.texi (Frames): Don't capitalize "Unix". + +2011-12-04 Chong Yidong <cyd@gnu.org> + + * text.texi (Nroff Mode): Mention what nroff is. + (Text Based Tables, Table Recognition): Don't say "Table mode" + since it's not a major or minor mode. + (Text Based Tables): Reduce the size of the example. + (Table Definition): Clarify definitions. + (Table Creation): Add key table. + (Cell Commands): Use kbd for commands. + (Table Rows and Columns): Combine nodes Row Commands and Column + Commands. + (Fixed Width Mode): Node deleted; contents moved to parent. + (Table Conversion): Shorten example. + (Measuring Tables): Merge into Table Misc. + +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 + ring (Bug#10032). + +2011-11-20 Juanma Barranquero <lekktu@gmail.com> + + * msdog.texi (Windows Fonts): Fix typo. + 2011-11-17 Glenn Morris <rgm@gnu.org> * regs.texi (Bookmarks): Small fixes related to saving. (Bug#10058) diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 6801c7f1e0e..ae6338ce5a6 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -549,7 +549,7 @@ Taichi Kawabata added support for Devanagari script and the Indian languages, and wrote @file{ucs-normalize.el} for Unicode normalization. @item -Taro Kawagishi implented the MD4 Message Digest Algorithm in Lisp; and +Taro Kawagishi implemented the MD4 Message Digest Algorithm in Lisp; and wrote @file{ntlm.el} and @file{sasl-ntlm.el} for NT LanManager authentication support. @@ -1272,8 +1272,8 @@ Colin Walters wrote Ibuffer, an enhanced buffer menu. Barry Warsaw wrote @file{assoc.el}, a set of utility functions for working with association lists; @file{cc-mode.el}, a mode for editing C, C@t{++}, and Java code, based on earlier work by Dave Detlefs, -Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler -for Emacs Lisp programs; @file{man.el}, a mode for reading UNIX manual +Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler for +Emacs Lisp programs; @file{man.el}, a mode for reading Unix manual pages; @file{regi.el}, providing an AWK-like functionality for use in lisp programs; @file{reporter.el}, providing customizable bug reporting for lisp packages; and @file{supercite.el}, a minor mode for diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index ac62e2d9652..5e2cb8119de 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -8,9 +8,9 @@ @cindex program building @cindex running Lisp functions - The previous chapter discusses the Emacs commands that are useful for -making changes in programs. This chapter deals with commands that assist -in the larger process of compiling and testing programs. + The previous chapter discusses the Emacs commands that are useful +for making changes in programs. This chapter deals with commands that +assist in the process of compiling and testing programs. @menu * Compilation:: Compiling programs in languages other @@ -37,10 +37,10 @@ in the larger process of compiling and testing programs. @cindex compilation errors @cindex error log - Emacs can run compilers for noninteractive languages such as C and -Fortran as inferior processes, feeding the error log into an Emacs buffer. -It can also parse the error messages and show you the source lines where -compilation errors occurred. + Emacs can run compilers for languages such as C and Fortran as +inferior processes, feeding the compilation log into an Emacs buffer. +It can also parse the error messages and show you where the errors +occurred. @table @kbd @item M-x compile @@ -54,65 +54,60 @@ Kill the running compilation subprocess. @end table @findex compile - To run @code{make} or another compilation command, do @kbd{M-x -compile}. This command reads a shell command line using the minibuffer, -and then executes the command in an inferior shell, putting output in -the buffer named @samp{*compilation*}. The current buffer's default + To run @code{make} or another compilation command, type @kbd{M-x +compile}. This reads a shell command line using the minibuffer, and +then executes the command in an inferior shell, putting output in the +buffer named @samp{*compilation*}. The current buffer's default directory is used as the working directory for the execution of the -command; normally, therefore, the compilation happens in this +command; normally, therefore, compilation takes place in this directory. @vindex compile-command - The default for the compilation command is normally @samp{make -k}, -which is correct most of the time for nontrivial programs. -@xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x -compile} before, the default each time is the command you used the -previous time. @code{compile} stores this command in the variable -@code{compile-command}, so setting that variable specifies the default -for the next use of @kbd{M-x compile}. If a file specifies a file -local value for @code{compile-command}, that provides the default when -you type @kbd{M-x compile} in that file's buffer. @xref{File -Variables}. - - Starting a compilation displays the buffer @samp{*compilation*} in -another window but does not select it. The buffer's mode line tells -you whether compilation is finished, with the word @samp{run}, -@samp{signal} or @samp{exit} inside the parentheses. You do not have -to keep this buffer visible; compilation continues in any case. While -a compilation is going on, the string @samp{Compiling} appears in the -mode lines of all windows. When this string disappears, the -compilation is finished. - - If you want to watch the compilation transcript as it appears, switch -to the @samp{*compilation*} buffer and move point to the end of the -buffer. When point is at the end, new compilation output is inserted -above point, which remains at the end. If point is not at the end of -the buffer, it remains fixed while more compilation output is added at -the end of the buffer. + The default compilation command is @samp{make -k}, which is usually +correct for programs compiled using the @command{make} utility (the +@samp{-k} flag tells @command{make} to continue compiling as much as +possible after an error). @xref{Top,, Make, make, GNU Make Manual}. +If you have done @kbd{M-x compile} before, the command that you +specified is automatically stored in the variable +@code{compile-command}; this is used as the default the next time you +type @kbd{M-x compile}. A file can also specify a file-local value +for @code{compile-command} (@pxref{File Variables}). + + Starting a compilation displays the @samp{*compilation*} buffer in +another window but does not select it. While the compilation is +running, the word @samp{run} is shown in the major mode indicator for +the @samp{*compilation*} buffer, and the word @samp{Compiling} appears +in all mode lines. You do not have to keep the @samp{*compilation*} +buffer visible while compilation is running; it continues in any case. +When the compilation ends, for whatever reason, the mode line of the +@samp{*compilation*} buffer changes to say @samp{exit} (followed by +the exit code: @samp{[0]} for a normal exit), or @samp{signal} (if a +signal terminated the process). + + If you want to watch the compilation transcript as it appears, +switch to the @samp{*compilation*} buffer and move point to the end of +the buffer. When point is at the end, new compilation output is +inserted above point, which remains at the end. Otherwise, point +remains fixed while compilation output is added at the end of the +buffer. @cindex compilation buffer, keeping point at end @vindex compilation-scroll-output If you change the variable @code{compilation-scroll-output} to a -non-@code{nil} value, the compilation buffer will scroll automatically -to follow the output as it comes in. If the value is -@code{first-error}, the scrolling stops at the first error that -appears, leaving point at that error. For any other non-@code{nil} -value, the buffer continues scrolling until there is no more output. +non-@code{nil} value, the @samp{*compilation*} buffer scrolls +automatically to follow the output. If the value is +@code{first-error}, scrolling stops when the first error appears, +leaving point at that error. For any other non-@code{nil} value, +scrolling continues until there is no more output. @findex recompile To rerun the last compilation with the same command, type @kbd{M-x -recompile}. This automatically reuses the compilation command from -the last invocation of @kbd{M-x compile}. It also reuses the +recompile}. This reuses the compilation command from the last +invocation of @kbd{M-x compile}. It also reuses the @samp{*compilation*} buffer and starts the compilation in its default directory, which is the directory in which the previous compilation was started. - When the compiler process terminates, for whatever reason, the mode -line of the @samp{*compilation*} buffer changes to say @samp{exit} -(followed by the exit code, @samp{[0]} for a normal exit), or -@samp{signal} (if a signal terminated the process), instead of -@samp{run}. - @findex kill-compilation Starting a new compilation also kills any compilation already running in @samp{*compilation*}, as the buffer can only handle one @@ -126,27 +121,6 @@ the @samp{*compilation*} buffer (perhaps using @code{rename-uniquely}; @pxref{Misc Buffer}), then switch buffers and start the other compilation. This will create a new @samp{*compilation*} buffer. - Emacs does not expect a compiler process to launch asynchronous -subprocesses; if it does, and they keep running after the main -compiler process has terminated, Emacs may kill them or their output -may not arrive in Emacs. To avoid this problem, make the main process -wait for its subprocesses to finish. In a shell script, you can do this -using @samp{$!} and @samp{wait}, like this: - -@example -(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} -echo first message -wait $pid # @r{Wait for subprocess} -@end example - - If the background process does not output to the compilation buffer, -so you only need to prevent it from being killed when the main -compilation process terminates, this is sufficient: - -@example -nohup @var{command}; sleep 1 -@end example - @vindex compilation-environment You can control the environment passed to the compilation command with the variable @code{compilation-environment}. Its value is a list @@ -159,153 +133,154 @@ variable settings override the usual ones. @cindex Compilation mode @cindex mode, Compilation - The @samp{*compilation*} buffer uses a special major mode, -Compilation mode, whose main feature is to provide a convenient way to -visit the source line corresponding to an error message. These -commands are also available in other special buffers that list -locations in files, including those made by @kbd{M-x grep} and -@kbd{M-x occur}. +@cindex locus + The @samp{*compilation*} buffer uses a major mode called Compilation +mode. Compilation mode turns each error message in the buffer into a +hyperlink; you can move point to it and type @key{RET}, or click on it +with the mouse (@pxref{Mouse References}), to visit the @dfn{locus} of +the error message in a separate window. The locus is the specific +position in a file where that error occurred. + +@findex compile-goto-error +@vindex compilation-auto-jump-to-first-error + If you change the variable +@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, +Emacs automatically visits the locus of the first error message that +appears in the @samp{*compilation*} buffer. + + Compilation mode provides the following additional commands. These +commands can also be used in @samp{*grep*} buffers, where the +hyperlinks are search matches rather than error messages (@pxref{Grep +Searching}). @table @kbd @item M-g M-n @itemx M-g n @itemx C-x ` -Visit the locus of the next error message or match. +Visit the locus of the next error message or match (@code{next-error}). @item M-g M-p @itemx M-g p -Visit the locus of the previous error message or match. -@item @key{RET} -Visit the locus of the error message that point is on. -This command is used in the compilation buffer. -@item Mouse-2 -Visit the locus of the error message that you click on. +Visit the locus of the previous error message or match +(@code{previous-error}). @item M-n -Find and highlight the locus of the next error message, without -selecting the source buffer. +Move point to the next error message or match, without visiting its +locus (@code{compilation-next-error}). @item M-p -Find and highlight the locus of the previous error message, without -selecting the source buffer. +Move point to the previous error message or match, without visiting +its locus (@code{compilation-previous-error}). @item M-@} -Move point to the next error for a different file than the current -one. +Move point to the next error message or match occurring in a different +file (@code{compilation-next-file}). @item M-@{ -Move point to the previous error for a different file than the current -one. +Move point to the previous error message or match occurring in a +different file (@code{compilation-previous-file}). @item C-c C-f Toggle Next Error Follow minor mode, which makes cursor motion in the compilation buffer produce automatic source display. @end table -@findex compile-goto-error -@vindex compilation-auto-jump-to-first-error - You can visit the source for any particular error message by moving -point in the @samp{*compilation*} buffer to that error message and -typing @key{RET} (@code{compile-goto-error}). Alternatively, you can -click @kbd{Mouse-2} on the error message; you need not switch to the -@samp{*compilation*} buffer first. If you set the variable -@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, -Emacs automatically jumps to the first error, if any, as soon as it -appears in the @samp{*compilation*} buffer. - @kindex M-g M-n @kindex M-g n @kindex C-x ` @findex next-error @vindex next-error-highlight - To parse the compiler error messages sequentially, type @kbd{C-x `} -(@code{next-error}). The character following the @kbd{C-x} is the -backquote or ``grave accent,'' not the single-quote. This command is -available in all buffers, not just in @samp{*compilation*}; it -displays the next error message at the top of one window and source -location of the error in another window. It also temporarily -highlights the relevant source line, for a period controlled by the -variable @code{next-error-highlight}. - - The first time @w{@kbd{C-x `}} is used after the start of a compilation, -it moves to the first error's location. Subsequent uses of @kbd{C-x -`} advance down to subsequent errors. If you visit a specific error -message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}} -commands advance from there. When @w{@kbd{C-x `}} gets to the end of the -buffer and finds no more error messages to visit, it fails and signals -an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of -the compilation buffer, and goes to the first error's location. + To visit errors sequentially, type @w{@kbd{C-x `}} +(@code{next-error}), or equivalently @kbd{M-g M-n} or @kbd{M-g n}. +This command can be invoked from any buffer, not just a Compilation +mode buffer. The first time you invoke it after a compilation, it +visits the locus of the first error message. Each subsequent +@w{@kbd{C-x `}} visits the next error, in a similar fashion. If you +visit a specific error with @key{RET} or a mouse click in the +@samp{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands +advance from there. When @w{@kbd{C-x `}} finds no more error messages +to visit, it signals an error. @w{@kbd{C-u C-x `}} starts again from +the beginning of the compilation buffer, and visits the first locus. + + @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates +through errors in the opposite direction. + + The @code{next-error} and @code{previous-error} commands don't just +act on the errors or matches listed in @samp{*compilation*} and +@samp{*grep*} buffers; they also know how to iterate through error or +match lists produced by other commands, such as @kbd{M-x occur} +(@pxref{Other Repeating Search}). If you are already in a buffer +containing error messages or matches, those are the ones that are +iterated through; otherwise, Emacs looks for a buffer containing error +messages or matches amongst the windows of the selected frame, then +for one that @code{next-error} or @code{previous-error} previously +iterated through, and finally amongst all other buffers. If the +buffer chosen for iterating through is not currently displayed in a +window, it will be displayed. @vindex compilation-skip-threshold - By default, @w{@kbd{C-x `}} skips less important messages. The variable -@code{compilation-skip-threshold} controls this. If its value is 2, -@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less -than warning, and 0 doesn't skip any messages. The default is 1. - - When the window has a left fringe, an arrow in the fringe points to -the current message in the compilation buffer. The variable -@code{compilation-context-lines} controls the number of lines of -leading context to display before the current message. Going to an -error message location scrolls the @samp{*compilation*} buffer to put -the message that far down from the top. The value @code{nil} is -special: if there's a left fringe, the window doesn't scroll at all -if the message is already visible. If there is no left fringe, -@code{nil} means display the message at the top of the window. - - If you're not in the compilation buffer when you run -@code{next-error}, Emacs will look for a buffer that contains error -messages. First, it looks for one displayed in the selected frame, -then for one that previously had @code{next-error} called on it, and -then at the current buffer. Finally, Emacs looks at all the remaining -buffers. @code{next-error} signals an error if it can't find any such -buffer. + By default, the @code{next-error} and @code{previous-error} commands +skip less important messages. The variable +@code{compilation-skip-threshold} controls this. The default value, +1, means to skip anything less important than a warning. A value of 2 +means to skip anything less important than an error, while 0 means not +to skip any messages. + + When Emacs visits the locus of an error message, it momentarily +highlights the relevant source line. The duration of this highlight +is determined by the variable @code{next-error-highlight}. + +@vindex compilation-context-lines + If the @samp{*compilation*} buffer is shown in a window with a left +fringe (@pxref{Fringes}), the locus-visiting commands put an arrow in +the fringe, pointing to the current error message. If the window has +no left fringe, such as on a text-only terminal, these commands scroll +the window so that the current message is at the top of the window. +If you change the variable @code{compilation-context-lines} to an +integer value @var{n}, these commands scroll the window so that the +current error message is @var{n} lines from the top, whether or not +there is a fringe; the default value, @code{nil}, gives the behavior +described above. @vindex compilation-error-regexp-alist @vindex grep-regexp-alist To parse messages from the compiler, Compilation mode uses the variable @code{compilation-error-regexp-alist} which lists various -formats of error messages and tells Emacs how to extract the source file -and the line number from the text of a message. If your compiler isn't -supported, you can tailor Compilation mode to it by adding elements to -that list. A similar variable @code{grep-regexp-alist} tells Emacs how -to parse output of a @code{grep} command. +error message formats and tells Emacs how to extract the locus from +each. A similar variable, @code{grep-regexp-alist}, tells Emacs how +to parse output from a @code{grep} command (@pxref{Grep Searching}). @findex compilation-next-error @findex compilation-previous-error @findex compilation-next-file @findex compilation-previous-file - Compilation mode also redefines the keys @key{SPC} and @key{DEL} to -scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error}) -and @kbd{M-p} (@code{compilation-previous-error}) to move to the next -or previous error message. You can also use @kbd{M-@{} -(@code{compilation-next-file} and @kbd{M-@}} -(@code{compilation-previous-file}) to move up or down to an error -message for a different source file. + Compilation mode also defines the keys @key{SPC} and @key{DEL} to +scroll by screenfuls; @kbd{M-n} (@code{compilation-next-error}) and +@kbd{M-p} (@code{compilation-previous-error}) to move to the next or +previous error message; and @kbd{M-@{} (@code{compilation-next-file}) +and @kbd{M-@}} (@code{compilation-previous-file}) to move to the next +or previous error message for a different source file. @cindex Next Error Follow mode @findex next-error-follow-minor-mode You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In this minor mode, ordinary cursor motion in the compilation buffer -automatically updates the source buffer. For instance, moving the -cursor to the next error message causes the location of that error to -be displayed immediately. +automatically updates the source buffer, i.e.@: moving the cursor over +an error message causes the locus of that error to be displayed. The features of Compilation mode are also available in a minor mode called Compilation Minor mode. This lets you parse error messages in -any buffer, not just a normal compilation output buffer. Type @kbd{M-x -compilation-minor-mode} to enable the minor mode. This defines the keys -@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode. - - Compilation minor mode works in any buffer, as long as the contents -are in a format that it understands. In an Rlogin buffer (@pxref{Remote -Host}), Compilation minor mode automatically accesses remote source -files by FTP (@pxref{File Names}). +any buffer, not just a normal compilation output buffer. Type +@kbd{M-x compilation-minor-mode} to enable the minor mode. For +instance, in an Rlogin buffer (@pxref{Remote Host}), Compilation minor +mode automatically accesses remote source files by FTP (@pxref{File +Names}). @node Compilation Shell @section Subshells for Compilation - Emacs uses a shell to run the compilation command, but specifies the -option for a noninteractive shell. This means, in particular, that -the shell should start with no prompt. If you find your usual shell -prompt making an unsightly appearance in the @samp{*compilation*} -buffer, it means you have made a mistake in your shell's init file by -setting the prompt unconditionally. (This init file's name may be -@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or -various other things, depending on the shell you use.) The shell init + The @kbd{M-x compile} command uses a shell to run the compilation +command, but specifies the option for a noninteractive shell. This +means, in particular, that the shell should start with no prompt. If +you find your usual shell prompt making an unsightly appearance in the +@samp{*compilation*} buffer, it means you have made a mistake in your +shell's init file by setting the prompt unconditionally. (This init +file may be named @file{.bashrc}, @file{.profile}, @file{.cshrc}, +@file{.shrc}, etc., depending on what shell you use.) The shell init file should set the prompt only if there already is a prompt. Here's how to do it in bash: @@ -322,67 +297,80 @@ And here's how to do it in csh: if ($?prompt) set prompt = @dots{} @end example - There may well be other things that your shell's init file -ought to do only for an interactive shell. You can use the same -method to conditionalize them. + Emacs does not expect a compiler process to launch asynchronous +subprocesses; if it does, and they keep running after the main +compiler process has terminated, Emacs may kill them or their output +may not arrive in Emacs. To avoid this problem, make the main +compilation process wait for its subprocesses to finish. In a shell +script, you can do this using @samp{$!} and @samp{wait}, like this: + +@example +(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} +echo first message +wait $pid # @r{Wait for subprocess} +@end example + +@noindent +If the background process does not output to the compilation buffer, +so you only need to prevent it from being killed when the main +compilation process terminates, this is sufficient: + +@example +nohup @var{command}; sleep 1 +@end example - The MS-DOS ``operating system'' does not support asynchronous -subprocesses; to work around this lack, @kbd{M-x compile} runs the -compilation command synchronously on MS-DOS. As a consequence, you must -wait until the command finishes before you can do anything else in -Emacs. -@iftex -@inforef{MS-DOS,,emacs-xtra}. -@end iftex @ifnottex -@xref{MS-DOS}. + On the MS-DOS ``operating system'', asynchronous subprocesses are +not supported, so @kbd{M-x compile} runs the compilation command +synchronously (i.e.@: you must wait until the command finishes before +you can do anything else in Emacs). @xref{MS-DOS}. @end ifnottex @node Grep Searching @section Searching with Grep under Emacs Just as you can run a compiler from Emacs and then visit the lines -with compilation errors, you can also run @code{grep} and then visit -the lines on which matches were found. This works by treating the -matches reported by @code{grep} as if they were ``errors.'' The -buffer of matches uses Grep mode, which is a variant of Compilation +with compilation errors, you can also run @command{grep} and then +visit the lines on which matches were found. This works by treating +the matches reported by @command{grep} as if they were ``errors.'' +The output buffer uses Grep mode, which is a variant of Compilation mode (@pxref{Compilation Mode}). @table @kbd @item M-x grep @itemx M-x lgrep -Run @code{grep} asynchronously under Emacs, with matching lines -listed in the buffer named @samp{*grep*}. +Run @command{grep} asynchronously under Emacs, listing matching lines in +the buffer named @samp{*grep*}. @item M-x grep-find @itemx M-x find-grep @itemx M-x rgrep -Run @code{grep} via @code{find}, and collect output in the buffer -named @samp{*grep*}. +Run @command{grep} via @code{find}, and collect output in the +@samp{*grep*} buffer. @item M-x zrgrep -Run @code{zgrep} and collect output in the buffer named @samp{*grep*}. +Run @code{zgrep} and collect output in the @samp{*grep*} buffer. @item M-x kill-grep -Kill the running @code{grep} subprocess. +Kill the running @command{grep} subprocess. @end table @findex grep - To run @code{grep}, type @kbd{M-x grep}, then enter a command line -that specifies how to run @code{grep}. Use the same arguments you -would give @code{grep} when running it normally: a @code{grep}-style + To run @command{grep}, type @kbd{M-x grep}, then enter a command line +that specifies how to run @command{grep}. Use the same arguments you +would give @command{grep} when running it normally: a @command{grep}-style regexp (usually in single-quotes to quote the shell's special characters) followed by file names, which may use wildcards. If you specify a prefix argument for @kbd{M-x grep}, it finds the tag (@pxref{Tags}) in the buffer around point, and puts that into the -default @code{grep} command. +default @command{grep} command. - Your command need not simply run @code{grep}; you can use any shell + Your command need not simply run @command{grep}; you can use any shell command that produces output in the same format. For instance, you -can chain @code{grep} commands, like this: +can chain @command{grep} commands, like this: @example grep -nH -e foo *.el | grep bar | grep toto @end example - The output from @code{grep} goes in the @samp{*grep*} buffer. You + The output from @command{grep} goes in the @samp{*grep*} buffer. You can find the corresponding lines in the original files using @w{@kbd{C-x `}}, @key{RET}, and so forth, just like compilation errors. @@ -397,30 +385,31 @@ match will be highlighted, instead of the entire source line. The command @kbd{M-x grep-find} (also available as @kbd{M-x find-grep}) is similar to @kbd{M-x grep}, but it supplies a different initial default for the command---one that runs both @code{find} and -@code{grep}, so as to search every file in a directory tree. See also +@command{grep}, so as to search every file in a directory tree. See also the @code{find-grep-dired} command, in @ref{Dired and Find}. @findex lgrep @findex rgrep @findex zrgrep The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} -(recursive grep) are more user-friendly versions of @code{grep} and +(recursive grep) are more user-friendly versions of @command{grep} and @code{grep-find}, which prompt separately for the regular expression to match, the files to search, and the base directory for the search. Case sensitivity of the search is controlled by the current value of @code{case-fold-search}. The command @kbd{M-x zrgrep} is similar to -@code{rgrep}, but it calls @code{zgrep} instead of @code{grep} to -search the contents of gzipped files. +@kbd{M-x rgrep}, but it calls @command{zgrep} instead of +@command{grep} to search the contents of gzipped files. These commands build the shell commands based on the variables @code{grep-template} (for @code{lgrep}) and @code{grep-find-template} (for @code{rgrep}). The files to search can use aliases defined in the variable @code{grep-files-aliases}. - Subdirectories listed in the variable -@code{grep-find-ignored-directories} such as those typically used by -various version control systems, like CVS and arch, are automatically -skipped by @code{rgrep}. +@vindex grep-find-ignored-directories + Directories listed in the variable +@code{grep-find-ignored-directories} are automatically skipped by +@kbd{M-x rgrep}. The default value includes the data directories used +by various version control systems. @node Flymake @section Finding Syntax Errors On The Fly @@ -444,8 +433,13 @@ flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To display any error messages associated with the current line, use @kbd{M-x flymake-display-err-menu-for-current-line}. - For more details about using Flymake, see @ref{Top, Flymake, -Flymake, flymake, The Flymake Manual}. + For more details about using Flymake, +@ifnottex +see @ref{Top, Flymake, Flymake, flymake, The Flymake Manual}. +@end ifnottex +@iftex +see the Flymake Info manual, which is distributed with Emacs. +@end iftex @node Debuggers @section Running Debuggers Under Emacs @@ -459,16 +453,18 @@ Flymake, flymake, The Flymake Manual}. @cindex JDB @cindex PDB -@c Do you believe in GUD? The GUD (Grand Unified Debugger) library provides an Emacs interface -to a wide variety of symbolic debuggers. Unlike the GDB graphical -interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD -can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger -PDB, or the Java Debugger JDB. +to a wide variety of symbolic debuggers. It can run the GNU Debugger +(GDB), as well as DBX, SDB, XDB, Perl's debugging mode, the Python +debugger PDB, and the Java Debugger JDB. - In addition, Emacs contains a built-in system for debugging Emacs -Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs -Lisp Reference Manual}, for information on the Emacs Lisp debugger. + Emacs provides a special interface to GDB, which uses extra Emacs +windows to display the state of the debugged program. @xref{GDB +Graphical Interface}. + + Emacs also has a built-in debugger for Emacs Lisp programs. +@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference +Manual}. @menu * Starting GUD:: How to start a debugger subprocess. @@ -483,146 +479,136 @@ Lisp Reference Manual}, for information on the Emacs Lisp debugger. @node Starting GUD @subsection Starting GUD - There are several commands for starting a debugger under GUD, each + There are several commands for starting a debugger subprocess, each corresponding to a particular debugger program. @table @kbd -@item M-x gdb @key{RET} @var{file} @key{RET} +@item M-x gdb @findex gdb -Run GDB as a subprocess of Emacs. This uses an IDE-like graphical -interface; see @ref{GDB Graphical Interface}. Only GDB works with the -graphical interface. +Run GDB as a subprocess, and interact with it via an IDE-like Emacs +interface. @xref{GDB Graphical Interface}, for more information about +this command. -@item M-x gud-gdb @key{RET} @var{file} @key{RET} +@item M-x gud-gdb @findex gud-gdb -Run GDB as a subprocess of Emacs. This command creates a buffer for -input and output to GDB, and switches to it. If a GDB buffer already -exists, it just switches to that buffer. - -@item M-x dbx @key{RET} @var{file} @key{RET} -@findex dbx -Run DBX as a subprocess of Emacs. Since Emacs does not implement a -graphical interface for DBX, communication with DBX works by typing -commands in the GUD interaction buffer. The same is true for all -the other supported debuggers. +Run GDB, using a GUD interaction buffer for input and output to the +GDB subprocess (@pxref{Debugger Operation}). If such a buffer already +exists, switch to it; otherwise, create the buffer and switch to it. -@item M-x xdb @key{RET} @var{file} @key{RET} -@findex xdb -@vindex gud-xdb-directories -Run XDB as a subprocess of Emacs. Use the variable -@code{gud-xdb-directories} to specify directories to search for source -files. +The other commands in this list do the same, for other debugger +programs. -@item M-x sdb @key{RET} @var{file} @key{RET} -@findex sdb -Run SDB as a subprocess of Emacs. - -Some versions of SDB do not mention source file names in their -messages. When you use them, you need to have a valid tags table -(@pxref{Tags}) in order for GUD to find functions in the source code. -If you have not visited a tags table or the tags table doesn't list -one of the functions, you get a message saying @samp{The sdb support -requires a valid tags table to work}. If this happens, generate a -valid tags table in the working directory and try again. - -@item M-x perldb @key{RET} @var{file} @key{RET} +@item M-x perldb @findex perldb -Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. +Run the Perl interpreter in debug mode. -@item M-x jdb @key{RET} @var{file} @key{RET} +@item M-x jdb @findex jdb -Run the Java debugger to debug @var{file}. +Run the Java debugger. -@item M-x pdb @key{RET} @var{file} @key{RET} +@item M-x pdb @findex pdb -Run the Python debugger to debug @var{file}. +Run the Python debugger. + +@item M-x dbx +@findex dbx +Run the DBX debugger. + +@item M-x xdb +@findex xdb +@vindex gud-xdb-directories +Run the XDB debugger. + +@item M-x sdb +@findex sdb +Run the SDB debugger. @end table - Each of these commands takes one argument: a command line to invoke -the debugger. In the simplest case, specify just the name of the -executable file you want to debug. You may also use options that the -debugger supports. However, shell wildcards and variables are not -allowed. GUD assumes that the first argument not starting with a -@samp{-} is the executable file name. + Each of these commands reads a command line to invoke the debugger, +using the minibuffer. The minibuffer's initial contents contain the +standard executable name and options for the debugger, and sometimes +also a guess for the name of the executable file you want to debug. +Shell wildcards and variables are not allowed in this command line. +Emacs assumes that the first command argument which does not start +with a @samp{-} is the executable file name. @cindex remote host, debugging on -Tramp provides a facility to debug programs on remote hosts -(@pxref{Running a debugger on a remote host, Running a debugger on a -remote host,, tramp, The Tramp Manual}), whereby both the debugger and -the program being debugged are on the same remote host. This should -not be confused with debugging programs remotely, where the program -and the debugger run on different machines, as can be done using the -GDB remote debugging feature, for example (@pxref{Remote Debugging,, -Debugging Remote Programs, gdb, The GNU debugger}). + Tramp provides a facility for remote debugging, whereby both the +debugger and the program being debugged are on the same remote host. +@xref{Running a debugger on a remote host,,, tramp, The Tramp Manual}, +for details. This is separate from GDB's remote debugging feature, +where the program and the debugger run on different machines +(@pxref{Remote Debugging,, Debugging Remote Programs, gdb, The GNU +debugger}). @node Debugger Operation @subsection Debugger Operation +@cindex GUD interaction buffer + + The @dfn{GUD interaction buffer} is an Emacs buffer which is used to +send text commands to a debugger subprocess, and record its output. +This is the basic interface for interacting with a debugger, used by +@kbd{M-x gud-gdb} and other commands listed in +@iftex +the preceding section. +@end iftext +@ifnottex +@ref{Starting GUD}. +@end ifnottex +The @kbd{M-x gdb} command extends this interface with additional +specialized buffers for controlling breakpoints, stack frames, and +other aspects of the debugger state (@pxref{GDB Graphical Interface}). -@cindex fringes, and current execution line in GUD - Generally when you run a debugger with GUD, the debugger uses an Emacs -buffer for its ordinary input and output. This is called the GUD -buffer. Input and output from the program you are debugging also use -this buffer. We call this @dfn{text command mode}. The GDB Graphical -Interface can use further buffers (@pxref{GDB Graphical Interface}). - - The debugger displays the source files of the program by visiting -them in Emacs buffers. An arrow in the left fringe indicates the -current execution line.@footnote{On a text-only terminal, the arrow -appears as @samp{=>} and overlays the first two text columns.} Moving -point in this buffer does not move the arrow. The arrow is not part -of the file's text; it appears only on the screen. - - You can start editing these source files at any time in the buffers -that display them. If you do modify a source file, keep in mind that -inserting or deleting lines will throw off the arrow's positioning; -GUD has no way of figuring out which line corresponded before your -changes to the line number in a debugger message. Also, you'll -typically have to recompile and restart the program for your changes -to be reflected in the debugger's tables. - -@cindex tooltips with GUD -@vindex tooltip-gud-modes -@vindex gud-tooltip-mode + The GUD interaction buffer uses a variant of Shell mode, so the +Emacs commands defined by Shell mode are available (@pxref{Shell +Mode}). Completion is available for most debugger commands +(@pxref{Completion}), and you can use the usual Shell mode history +commands to repeat them. +@iftex +See the next section +@end iftext +@ifnottex +@xref{Commands of GUD}, +@end ifnottex +for special commands that can be used in the GUD interaction buffer. + + As you debug a program, Emacs displays the relevant source files by +visiting them in Emacs buffers, with an arrow in the left fringe +indicating the current execution line. (On a text-only terminal, the +arrow appears as @samp{=>}, overlaid on the first two text columns.) +Moving point in such a buffer does not move the arrow. You are free +to edit these source files, but note that inserting or deleting lines +will throw off the arrow's positioning, as Emacs has no way to figure +out which edited source line corresponds to the line reported by the +debugger subprocess. To update this information, you typically have +to recompile and restart the program. + +@cindex GUD Tooltip mode +@cindex mode, GUD Tooltip +@findex gud-tooltip-mode @vindex gud-tooltip-echo-area - The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. -You activate this feature by turning on the minor mode -@code{gud-tooltip-mode}. Then you can display a variable's value in a -tooltip simply by pointing at it with the mouse. This operates in the -GUD buffer and in source buffers with major modes in the list -@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} -is non-@code{nil} then the variable's value is displayed in the echo -area. When debugging a C program using the GDB Graphical Interface, you -can also display macro definitions associated with an identifier when -the program is not executing. - - GUD tooltips are disabled when you use GDB in text command mode -(@pxref{GDB Graphical Interface}), because displaying an expression's -value in GDB can sometimes expand a macro and result in a side effect -that interferes with the program's operation. The GDB graphical -interface supports GUD tooltips and assures they will not cause side -effects. + GUD Tooltip mode is a global minor mode that adds tooltip support to +GUD. To toggle this mode, type @kbd{M-x gud-tooltip-mode}. It is +disabled by default. If enabled, you can move the mouse cursor over a +variable to show its value in a tooltip (@pxref{Tooltips}); this takes +effect in the GUD interaction buffer, and in all source buffers with +major modes listed in the variable @code{gud-tooltip-modes}. If the +variable @code{gud-tooltip-echo-area} is non-@code{nil}, values are +shown in the echo area instead of a tooltip. + + When using GUD Tooltip mode with @kbd{M-x gud-gdb}, you should note +that displaying an expression's value in GDB can sometimes expand a +macro, potentially causing side effects in the debugged program. If +you use the @kbd{M-x gdb} interface, this problem does not occur, as +there is special code to avoid side-effects; furthermore, you can +display macro definitions associated with an identifier when the +program is not executing. @node Commands of GUD @subsection Commands of GUD - The GUD interaction buffer uses a variant of Shell mode, so the -Emacs commands of Shell mode are available (@pxref{Shell Mode}). All -the usual commands for your debugger are available, and you can use -the Shell mode history commands to repeat them. If you wish, you can -control your debugger process entirely through this buffer. - - GUD mode also provides commands for setting and clearing -breakpoints, for selecting stack frames, and for stepping through the -program. These commands are available both in the GUD buffer and -globally, but with different key bindings. It also has its own tool -bar from which you can invoke the more common commands by clicking on -the appropriate icon. This is particularly useful for repetitive -commands like @code{gud-next} and @code{gud-step}, and allows you to -keep the GUD buffer hidden. - - The breakpoint commands are normally used in source file buffers, -because that is the easiest way to specify where to set or clear the -breakpoint. Here's the global command to set a breakpoint: + GUD provides commands for setting and clearing breakpoints, +selecting stack frames, and stepping through the program. @table @kbd @item C-x @key{SPC} @@ -630,35 +616,42 @@ breakpoint. Here's the global command to set a breakpoint: Set a breakpoint on the source line that point is on. @end table + @kbd{C-x @key{SPC}} (@code{gud-break}), when called in a source +buffer, sets a debugger breakpoint on the current source line. This +command is available only after starting GUD. If you call it in a +buffer that is not associated with any debugger subprocess, it signals +a error. + @kindex C-x C-a @r{(GUD)} - Here are the other special commands provided by GUD@. The keys + The following commands are available both in the GUD interaction +buffer and globally, but with different key bindings. The keys starting with @kbd{C-c} are available only in the GUD interaction -buffer. The key bindings that start with @kbd{C-x C-a} are available -in the GUD interaction buffer and also in source files. Some of these -commands are not available to all the supported debuggers. +buffer, while those starting with @kbd{C-x C-a} are available +globally. Some of these commands are also available via the tool bar; +some are not supported by certain debuggers. @table @kbd @item C-c C-l @kindex C-c C-l @r{(GUD)} @itemx C-x C-a C-l @findex gud-refresh -Display in another window the last line referred to in the GUD -buffer (that is, the line indicated in the last location message). -This runs the command @code{gud-refresh}. +Display, in another window, the last source line referred to in the +GUD interaction buffer (@code{gud-refresh}). @item C-c C-s @kindex C-c C-s @r{(GUD)} @itemx C-x C-a C-s @findex gud-step -Execute a single line of code (@code{gud-step}). If the line contains -a function call, execution stops after entering the called function. +Execute the next single line of code (@code{gud-step}). If the line +contains a function call, execution stops after entering the called +function. @item C-c C-n @kindex C-c C-n @r{(GUD)} @itemx C-x C-a C-n @findex gud-next -Execute a single line of code, stepping across entire function calls -at full speed (@code{gud-next}). +Execute the next single line of code, stepping across function calls +without stopping inside the functions (@code{gud-next}). @item C-c C-i @kindex C-c C-i @r{(GUD)} @@ -769,17 +762,17 @@ Instead, type @kbd{C-q @key{TAB}} to enter a tab. @vindex perldb-mode-hook @vindex pdb-mode-hook @vindex jdb-mode-hook - On startup, GUD runs one of the following hooks: @code{gdb-mode-hook}, -if you are using GDB; @code{dbx-mode-hook}, if you are using DBX; -@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you -are using XDB; @code{perldb-mode-hook}, for Perl debugging mode; -@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can -use these hooks to define custom key bindings for the debugger -interaction buffer. @xref{Hooks}. - - Here is a convenient way to define a command that sends a particular -command string to the debugger, and set up a key binding for it in the -debugger interaction buffer: + On startup, GUD runs one of the following hooks: +@code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if +you are using DBX; @code{sdb-mode-hook}, if you are using SDB; +@code{xdb-mode-hook}, if you are using XDB; @code{perldb-mode-hook}, +for Perl debugging mode; @code{pdb-mode-hook}, for PDB; +@code{jdb-mode-hook}, for JDB. @xref{Hooks}. + + The @code{gud-def} Lisp macro (@pxref{Defining Macros,,, elisp, the +Emacs Lisp Reference Manual}) provides a convenient way to define an +Emacs command that sends a particular command string to the debugger, +and set up a key binding for in the GUD interaction buffer: @findex gud-def @example @@ -835,21 +828,22 @@ Fully qualified class name derived from the expression surrounding point @node GDB Graphical Interface @subsection GDB Graphical Interface - The command @code{gdb} starts GDB in a graphical interface, using -Emacs windows for display program state information. With it, you do -not need to use textual GDB commands; you can control the debugging -session with the mouse. For example, you can click in the fringe of a -source buffer to set a breakpoint there, or on a stack frame in the -stack buffer to select that frame. - - This mode requires telling GDB that its ``screen size'' is -unlimited, so it sets the height and width accordingly. For correct -operation you must not change these values during the GDB session. + The command @kbd{M-x gdb} starts GDB in an IDE-like interface, with +specialized buffers for controlling breakpoints, stack frames, and +other aspects of the debugger state. It also provides additional ways +to control the debugging session with the mouse, such as clicking in +the fringe of a source buffer to set a breakpoint there. @vindex gud-gdb-command-name - To run GDB in text command mode, like the other debuggers in Emacs, -use @kbd{M-x gud-gdb}. You need to use text command mode to debug -multiple programs within one Emacs session. + To run GDB using just the GUD interaction buffer interface, without +these additional features, use @kbd{M-x gud-gdb} (@pxref{Starting +GUD}). You must use this if you want to debug multiple programs +within one Emacs session, as that is currently unsupported by @kbd{M-x +gdb}. + + Internally, @kbd{M-x gdb} informs GDB that its ``screen size'' is +unlimited; for correct operation, you must not change GDB's screen +height and width values during the debugging session. @menu * GDB User Interface Layout:: Control the number of displayed buffers. @@ -858,8 +852,7 @@ multiple programs within one Emacs session. * Breakpoints Buffer:: A breakpoint control panel. * Threads Buffer:: Displays your threads. * Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Input/output, locals, registers, - assembler, threads and memory buffers. +* Other GDB Buffers:: Other buffers for controlling the GDB state. * Watch Expressions:: Monitor variable values in the speedbar. * Multithreaded Debugging:: Debugging programs with several threads. @end menu @@ -869,12 +862,12 @@ multiple programs within one Emacs session. @cindex GDB User Interface layout @vindex gdb-many-windows - If the variable @code{gdb-many-windows} is @code{nil} (the default -value) then @kbd{M-x gdb} normally displays only the GUD buffer. + If the variable @code{gdb-many-windows} is @code{nil} (the default), +@kbd{M-x gdb} normally displays only the GUD interaction buffer. However, if the variable @code{gdb-show-main} is also non-@code{nil}, -it starts with two windows: one displaying the GUD buffer, and the -other showing the source for the @code{main} function of the program -you are debugging. +it starts with two windows: one displaying the GUD interaction buffer, +and the other showing the source for the @code{main} function of the +program you are debugging. If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} displays the following frame layout: @@ -882,7 +875,7 @@ displays the following frame layout: @smallexample @group +--------------------------------+--------------------------------+ -| GUD buffer (I/O of GDB) | Locals/Registers buffer | +| GUD interaction buffer | Locals/Registers buffer | |--------------------------------+--------------------------------+ | Primary Source buffer | I/O buffer for debugged pgm | |--------------------------------+--------------------------------+ @@ -896,264 +889,233 @@ buffer does not appear and the primary source buffer occupies the full width of the frame. @findex gdb-restore-windows - If you change the window layout, for example, while editing and -re-compiling your program, then you can restore this standard window -layout with the command @code{gdb-restore-windows}. - @findex gdb-many-windows - To switch between this standard layout and a simple layout -containing just the GUD buffer and a source file, type @kbd{M-x -gdb-many-windows}. + If you ever change the window layout, you can restore the ``many +windows'' layout by typing @kbd{M-x gdb-restore-windows}. To toggle +between the many windows layout and a simple layout with just the GUD +interaction buffer and a source file, type @kbd{M-x gdb-many-windows}. You may also specify additional GDB-related buffers to display, either in the same frame or a different one. Select the buffers you -want with the @samp{GUD->GDB-Windows} and @samp{GUD->GDB-Frames} -sub-menus. If the menu-bar is unavailable, type @code{M-x -gdb-display-@var{buffertype}-buffer} or @code{M-x -gdb-frame-@var{buffertype}-buffer} respectively, where -@var{buffertype} is the relevant buffer type, such as -@samp{breakpoints}. Most of these buffers are read-only, and typing -@kbd{q} in them kills them. - - When you finish debugging, kill the GUD buffer with @kbd{C-x k}, -which will also kill all the buffers associated with the session. -However you need not do this if, after editing and re-compiling your -source code within Emacs, you wish continue debugging. When you -restart execution, GDB will automatically find your new executable. -Keeping the GUD buffer has the advantage of keeping the shell history -as well as GDB's breakpoints. You do need to check that the -breakpoints in recently edited source files are still in the right -places. +want by typing @code{M-x gdb-display-@var{buffertype}-buffer} or +@code{M-x gdb-frame-@var{buffertype}-buffer}, where @var{buffertype} +is the relevant buffer type, such as @samp{breakpoints}. You can do +the same with the menu bar, with the @samp{GDB-Windows} and +@samp{GDB-Frames} sub-menus of the @samp{GUD} menu. + + When you finish debugging, kill the GUD interaction buffer with +@kbd{C-x k}, which will also kill all the buffers associated with the +session. However you need not do this if, after editing and +re-compiling your source code within Emacs, you wish to continue +debugging. When you restart execution, GDB automatically finds the +new executable. Keeping the GUD interaction buffer has the advantage +of keeping the shell history as well as GDB's breakpoints. You do +need to check that the breakpoints in recently edited source files are +still in the right places. @node Source Buffers @subsubsection Source Buffers -@cindex GDB commands in Fringe - -@c @findex gdb-mouse-set-clear-breakpoint -@c @findex gdb-mouse-toggle-breakpoint -Many GDB commands can be entered using key bindings or the tool bar but -sometimes it is quicker to use the fringe. These commands either -manipulate breakpoints or control program execution. When there is no -fringe, you can use the margin but this is only present when the -source file already has a breakpoint. - -You can click @kbd{Mouse-1} in the fringe or display margin of a -source buffer to set a breakpoint there and, on a graphical display, a -red bullet will appear on that line. If a breakpoint already exists -on that line, the same click will remove it. You can also enable or -disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. - -A solid arrow in the left fringe of a source buffer indicates the line -of the innermost frame where the debugged program has stopped. A -hollow arrow indicates the current execution line of higher level -frames. - -If you drag the arrow in the fringe with @kbd{Mouse-1} -(@code{gdb-mouse-until}), execution will continue to the line where -you release the button, provided it is still in the same frame. -Alternatively, you can click @kbd{Mouse-3} at some point in the fringe -of this buffer and execution will advance to there. A similar command -(@code{gdb-mouse-jump}) allows you to jump to a source line without -executing the intermediate lines by clicking @kbd{C-Mouse-3}. This -command allows you to go backwards which can be useful for running -through code that has already executed, in order to examine its -execution in more detail. +@cindex fringes, for debugging -@table @kbd -@item Mouse-1 -Set or clear a breakpoint. +@table @asis +@item @kbd{Mouse-1} (in fringe) +Set or clear a breakpoint on that line. -@item C-Mouse-1 -Enable or disable a breakpoint. +@item @kbd{C-Mouse-1} (in fringe) +Enable or disable a breakpoint on that line. -@item Mouse-3 -Continue execution to here. +@item @kbd{Mouse-3} (in fringe) +Continue execution to that line. -@item C-Mouse-3 -Jump to here. +@item @kbd{C-Mouse-3} (in fringe) +Jump to that line. @end table -If the variable @code{gdb-find-source-frame} is non-@code{nil} and -execution stops in a frame for which there is no source code e.g after -an interrupt, then Emacs finds and displays the first frame further up -stack for which there is source. If it is @code{nil} then the source -buffer continues to display the last frame which maybe more useful, -for example, when re-setting a breakpoint. + On a graphical display, you can click @kbd{Mouse-1} in the fringe of +a source buffer, to set a breakpoint on that line (@pxref{Fringes}). +A red dot appears in the fringe, where you clicked. If a breakpoint +already exists there, the click removes it. A @kbd{C-Mouse-1} click +enables or disables an existing breakpoint; a breakpoint that is +disabled, but not unset, is indicated by a gray dot. + + On a text-only terminal, or when fringes are disabled, enabled +breakpoints are indicated with a @samp{B} character in the left margin +of the window. Disabled breakpoints are indicated with @samp{b}. +(The margin is only displayed if a breakpoint is present.) + + A solid arrow in the left fringe of a source buffer indicates the +line of the innermost frame where the debugged program has stopped. A +hollow arrow indicates the current execution line of a higher-level +frame. If you drag the arrow in the fringe with @kbd{Mouse-1}, that +causes execution to advance to the line where you release the button. +Alternatively, you can click @kbd{Mouse-3} in the fringe to advance to +that line. You can click @kbd{C-Mouse-3} in the fringe to jump to +that line without executing the intermediate lines. This command +allows you to go backwards, which can be useful for running through +code that has already executed, in order to examine its execution in +more detail. @node Breakpoints Buffer @subsubsection Breakpoints Buffer - The breakpoints buffer shows the existing breakpoints, watchpoints and -catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has -these special commands, which mostly apply to the @dfn{current -breakpoint}, the breakpoint which point is on. + The GDB Breakpoints buffer shows the breakpoints, watchpoints and +catchpoints in the debugger session. @xref{Breakpoints,,, gdb, The +GNU debugger}. It provides the following commands, which mostly apply +to the @dfn{current breakpoint} (the breakpoint which point is on): @table @kbd @item @key{SPC} -@kindex SPC @r{(GDB breakpoints buffer)} +@kindex SPC @r{(GDB Breakpoints buffer)} @findex gdb-toggle-breakpoint -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 -terminals correspondingly display a @samp{B} or @samp{b}. +Enable/disable current breakpoint (@code{gdb-toggle-breakpoint}). On +a graphical display, this changes the color of the dot in the fringe +of the source buffer at that line. The dot is red when the breakpoint +is enabled, and gray when it is disabled. @item D -@kindex D @r{(GDB breakpoints buffer)} +@kindex D @r{(GDB Breakpoints buffer)} @findex gdb-delete-breakpoint Delete the current breakpoint (@code{gdb-delete-breakpoint}). @item @key{RET} -@kindex RET @r{(GDB breakpoints buffer)} +@kindex RET @r{(GDB Breakpoints buffer)} @findex gdb-goto-breakpoint Visit the source line for the current breakpoint (@code{gdb-goto-breakpoint}). @item Mouse-2 -@kindex Mouse-2 @r{(GDB breakpoints buffer)} +@kindex Mouse-2 @r{(GDB Breakpoints buffer)} Visit the source line for the breakpoint you click on. @end table @vindex gdb-show-threads-by-default -When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer -shares its window with the threads buffer. To switch from one to the -other click with @kbd{Mouse-1} on the relevant button in the header -line. If @code{gdb-show-threads-by-default} is non-@code{nil}, the -threads buffer, rather than the breakpoints buffer, is shown at start -up. + When @code{gdb-many-windows} is non-@code{nil}, the GDB Breakpoints +buffer shares its window with the GDB Threads buffer. To switch from +one to the other click with @kbd{Mouse-1} on the relevant button in +the header line. If @code{gdb-show-threads-by-default} is +non-@code{nil}, the GDB Threads buffer is the one shown by default. @node Threads Buffer @subsubsection Threads Buffer @findex gdb-select-thread -The threads buffer displays a summary of all threads currently in your -program (@pxref{Threads, Threads, Debugging programs with multiple -threads, gdb, The GNU debugger}). Move point to any thread in the list -and press @key{RET} to select it (@code{gdb-select-thread}) and -display the associated source in the primary source buffer. -Alternatively, click @kbd{Mouse-2} on a thread to select it. Contents -of all GDB buffers are updated whenever you select a thread. + The GDB Threads buffer displays a summary of the threads in the +debugged program. @xref{Threads, Threads, Debugging programs with +multiple threads, gdb, The GNU debugger}. To select a thread, move +point there and type @key{RET} (@code{gdb-select-thread}), or click on +it with @kbd{Mouse-2}. This also displays the associated source +buffer, and updates the contents of the other GDB buffers. You can customize variables under @code{gdb-buffers} group to select -fields included in threads buffer. +fields included in GDB Threads buffer. @table @code @item gdb-thread-buffer-verbose-names @vindex gdb-thread-buffer-verbose-names -Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)} in -threads buffer. +Show long thread names like @samp{Thread 0x4e2ab70 (LWP 1983)}. @item gdb-thread-buffer-arguments @vindex gdb-thread-buffer-arguments -Show arguments of thread top frames in threads buffer. +Show arguments of thread top frames. @item gdb-thread-buffer-locations @vindex gdb-thread-buffer-locations -Show file information or library names in threads buffer. +Show file information or library names. @item gdb-thread-buffer-addresses @vindex gdb-thread-buffer-addresses Show addresses for thread frames in threads buffer. @end table - It's possible to observe information for several threads -simultaneously (in addition to buffers which show information for -currently selected thread) using the following keys from the threads -buffer. + To view information for several threads simultaneously, use the +following commands from the GDB Threads buffer. @table @kbd @item d @kindex d @r{(GDB threads buffer)} @findex gdb-display-disassembly-for-thread -Display disassembly buffer for the thread at current line. -(@code{gdb-display-disassembly-for-thread}) +Display disassembly buffer for the thread at current line +(@code{gdb-display-disassembly-for-thread}). @item f @kindex f @r{(GDB threads buffer)} @findex gdb-display-stack-for-thread -Display stack buffer for the thread at current line. +Display the GDB Stack buffer for the thread at current line (@code{gdb-display-stack-for-thread}). @item l @kindex l @r{(GDB threads buffer)} @findex gdb-display-locals-for-thread -Display locals buffer for the thread at current line. +Display the GDB Locals buffer for the thread at current line (@code{gdb-display-locals-for-thread}). @item r @kindex r @r{(GDB threads buffer)} @findex gdb-display-registers-for-thread -Display registers buffer for the thread at current line. +Display the GDB Registers buffer for the thread at current line (@code{gdb-display-registers-for-thread}). @end table -Pressing their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and -@kbd{R} displays the corresponding buffer in a new frame. +@noindent +Their upper-case counterparts, @kbd{D}, @kbd{F} ,@kbd{L} and @kbd{R}, +display the corresponding buffer in a new frame. When you create a buffer showing information about some specific thread, it becomes bound to that thread and keeps showing actual -information while you debug your program. Every GDB buffer contains a -number of thread it shows information for in its mode name. Thread -number is also included in the buffer name of bound buffers to prevent -buffer names clashing. +information while you debug your program. The mode indicator for each +GDB buffer shows the number of thread it is showing information about. +The thread number is also included in the buffer name of bound +buffers. -Further commands are available in the threads buffer which depend on the -mode of GDB that is used for controlling execution of your program. -(@pxref{Multithreaded Debugging, Stopping and Starting Multi-threaded Programs}). + Further commands are available in the GDB Threads buffer which +depend on the mode of GDB that is used for controlling execution of +your program. @xref{Multithreaded Debugging}. @node Stack Buffer @subsubsection Stack Buffer - The stack buffer displays a @dfn{call stack}, with one line for each -of the nested subroutine calls (@dfn{stack frames}) now active in the -program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. + The GDB Stack buffer displays a @dfn{call stack}, with one line for +each of the nested subroutine calls (@dfn{stack frames}) in the +debugger session. @xref{Backtrace,, Backtraces, gdb, The GNU +debugger}. @findex gdb-frames-select -An arrow in the fringe points to the selected frame or, if the fringe is -not present, the number of the selected frame is displayed in reverse -contrast. To select a frame in GDB, move point in the stack buffer to -that stack frame and type @key{RET} (@code{gdb-frames-select}), or click -@kbd{Mouse-2} on a stack frame. If the locals buffer is visible, -selecting a stack frame updates it to display the local variables of the -new frame. + On graphical displays, the selected stack frame is indicated by an +arrow in the fringe. On text-only terminals, or when fringes are +disabled, the selected stack frame is displayed in reverse contrast. +To select a stack frame, move point in its line and type @key{RET} +(@code{gdb-frames-select}), or click @kbd{Mouse-2} on it. Doing so +also updates the Locals buffer +@ifnottex +(@pxref{Other GDB Buffers}). +@end ifnottex +@iftex +(described in the next section). +@end iftex @node Other GDB Buffers -@subsubsection Other Buffers +@subsubsection Other GDB Buffers @table @asis -@item Input/Output Buffer -@vindex gdb-use-separate-io-buffer -If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, -the program being debugged takes its input and displays its output -here. Otherwise it uses the GUD buffer for that. To toggle whether -GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. -This takes effect when you next restart the program you are debugging. - -The history and replay commands from Shell mode are available here, -as are the commands to send signals to the debugged program. -@xref{Shell Mode}. - @item Locals Buffer -The locals buffer displays the values of local variables of the -current frame for simple data types (@pxref{Frame Info, Frame Info, +This buffer displays the values of local variables of the current +frame for simple data types (@pxref{Frame Info, Frame Info, Information on a frame, gdb, The GNU debugger}). Press @key{RET} or click @kbd{Mouse-2} on the value if you want to edit it. Arrays and structures display their type only. With GDB 6.4 or later, -move point to their name and press @key{RET}, or alternatively click -@kbd{Mouse-2} there, to examine their values. With earlier versions -of GDB, use @kbd{Mouse-2} or @key{RET} on the type description +you can examine the value of the local variable at point by typing +@key{RET}, or with a @kbd{Mouse-2} click. With earlier versions of +GDB, use @key{RET} or @kbd{Mouse-2} on the type description (@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. @item Registers Buffer @findex toggle-gdb-all-registers -The registers buffer displays the values held by the registers +This buffer displays the values held by the registers (@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on a register if you want to edit its value. -With GDB 6.4 or later, recently changed register values display with -@code{font-lock-warning-face}. With earlier versions of GDB, you can -press @key{SPC} to toggle the display of floating point registers -(@code{toggle-gdb-all-registers}). +click @kbd{Mouse-2} on a register if you want to edit its value. With +GDB 6.4 or later, recently changed register values display with +@code{font-lock-warning-face}. @item Assembler Buffer The assembler buffer displays the current frame as machine code. An @@ -1172,8 +1134,8 @@ size for these data items. @end table When @code{gdb-many-windows} is non-@code{nil}, the locals buffer -shares its window with the registers buffer, just like breakpoints -and threads buffers. To switch from one to the other click with +shares its window with the registers buffer, just like breakpoints and +threads buffers. To switch from one to the other, click with @kbd{Mouse-1} on the relevant button in the header line. @node Watch Expressions @@ -1188,14 +1150,15 @@ in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you specify a prefix argument, you can enter the variable name in the minibuffer. - Each watch expression is displayed in the speedbar. Complex data -types, such as arrays, structures and unions are represented in a tree -format. Leaves and simple data types show the name of the expression -and its value and, when the speedbar frame is selected, display the -type as a tooltip. Higher levels show the name, type and address -value for pointers and just the name and type otherwise. Root expressions -also display the frame address as a tooltip to help identify the frame -in which they were defined. + Each watch expression is displayed in the speedbar +(@pxref{Speedbar}). Complex data types, such as arrays, structures +and unions are represented in a tree format. Leaves and simple data +types show the name of the expression and its value and, when the +speedbar frame is selected, display the type as a tooltip. Higher +levels show the name, type and address value for pointers and just the +name and type otherwise. Root expressions also display the frame +address as a tooltip to help identify the frame in which they were +defined. To expand or contract a complex data type, click @kbd{Mouse-2} or press @key{SPC} on the tag to the left of the expression. Emacs asks @@ -1243,51 +1206,43 @@ non-@code{nil}. This can be useful if you are debugging with a full screen Emacs frame. @node Multithreaded Debugging -@subsubsection Stopping and Starting Multi-threaded Programs +@subsubsection Multithreaded Debugging @cindex Multithreaded debugging in GDB - -@subsubheading All-stop Debugging - -In all-stop mode, whenever your program stops, @emph{all} threads of -execution stop. Likewise, whenever you restart the program, all -threads start executing. @xref{All-Stop Mode, , All-Stop Mode, gdb, -The GNU debugger}. You can enable this behavior in Emacs by setting -@code{gdb-non-stop-setting} to @code{nil} before starting a debugging -session. - -@subsubheading Non-stop Debugging @cindex Non-stop debugging in GDB -For some multi-threaded targets, GDB supports a further mode of -operation in which you can examine stopped program threads in the -debugger while other threads continue to execute freely. -@xref{Non-Stop Mode, , Non-Stop Mode, gdb, The GNU debugger}. -This is referred to as @dfn{non-stop} mode. - -Versions of GDB prior to 7.0 do not support non-stop mode and it does -not work on all targets. In such cases, Emacs uses all-stop mode -regardless of the value of @code{gdb-non-stop-setting}. + In GDB's @dfn{all-stop mode}, whenever your program stops, all +execution threads stop. Likewise, whenever you restart the program, +all threads start executing. @xref{All-Stop Mode, , All-Stop Mode, +gdb, The GNU debugger}. For some multi-threaded targets, GDB supports +a further mode of operation, called @dfn{non-stop mode}, in which you +can examine stopped program threads in the debugger while other +threads continue to execute freely. @xref{Non-Stop Mode, , Non-Stop +Mode, gdb, The GNU debugger}. Versions of GDB prior to 7.0 do not +support non-stop mode, and it does not work on all targets. @vindex gdb-non-stop-setting -If the variable @code{gdb-non-stop-setting} is non-@code{nil} (the -default value), Emacs tries to start GDB in non-stop mode. Note that -GDB debugging session needs to be restarted for change of this setting -to take effect. + The variable @code{gdb-non-stop-setting} determines whether Emacs +runs GDB in all-stop mode or non-stop mode. The default is @code{t}, +which means it tries to use non-stop mode if that is available. If +you change the value to @code{nil}, or if non-stop mode is +unavailable, Emacs runs GDB in all-stop mode. The variable takes +effect when Emacs begins a debugging session; if you change its value, +you should restart any active debugging session. @vindex gdb-switch-when-another-stopped -When a thread stops in non-stop mode, Emacs automatically switches to -that thread. It may be undesirable to allow switching of current -thread when some other stopped thread is already selected. Set -@code{gdb-switch-when-another-stopped} to @code{nil} to prevent this. + When a thread stops in non-stop mode, Emacs usually switches to that +thread. If you don't want Emacs to do this switch if another stopped +thread is already selected, change the variable +@code{gdb-switch-when-another-stopped} to @code{nil}. @vindex gdb-switch-reasons -Emacs can decide whether or not to switch to the stopped thread -depending on the reason which caused the stop. Customize -@code{gdb-switch-reasons} to select stop reasons which make Emacs -switch thread. + Emacs can decide whether or not to switch to the stopped thread +depending on the reason which caused the stop. Customize the variable +@code{gdb-switch-reasons} to select the stop reasons which will cause +a thread switch. @vindex gdb-stopped-hooks -The variable @code{gdb-stopped-hooks} allows you to execute your + The variable @code{gdb-stopped-hooks} allows you to execute your functions whenever some thread stops. In non-stop mode, you can switch between different modes for GUD @@ -1297,7 +1252,7 @@ execution control commands. @table @dfn @item Non-stop/A -When @code{gdb-gud-control-all-threads} is @code{t} (the default + When @code{gdb-gud-control-all-threads} is @code{t} (the default value), interruption and continuation commands apply to all threads, so you can halt or continue all your threads with one command using @code{gud-stop-subjob} and @code{gud-cont}, respectively. The @@ -1318,18 +1273,13 @@ from the tool bar or from @samp{GUD->GDB-MI} menu. Stepping commands always apply to the current thread. -@subsubheading Fine Thread Control - In non-stop mode, you can interrupt/continue your threads without selecting them. Hitting @kbd{i} in threads buffer interrupts thread under point, @kbd{c} continues it, @kbd{s} steps through. More such commands may be added in the future. -Combined with creating bound buffers for any thread, this allows you -to change and track state of many threads in the same time. - - Note that when you interrupt a thread, it stops with @samp{signal -received} reason. If that reason is included in your + Note that when you interrupt a thread, it stops with the +@samp{signal received} reason. If that reason is included in your @code{gdb-switch-reasons} (it is by default), Emacs will switch to that thread. 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..8ecf0982e46 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 @@ -624,11 +602,8 @@ Editing Text-based Tables * Table Recognition:: How to activate and deactivate tables. * Cell Commands:: Cell-oriented commands in a table. * Cell Justification:: Justifying cell contents. -* Row Commands:: Manipulating rows of table cell. -* Column Commands:: Manipulating columns of table cell. -* Fixed Width Mode:: Fixing cell width. +* Table Rows and Columns:: Inserting and deleting rows and columns. * Table Conversion:: Converting between plain text and tables. -* Measuring Tables:: Analyzing table dimension. * Table Misc:: Table miscellany. Editing Programs @@ -747,8 +722,7 @@ GDB Graphical Interface * Breakpoints Buffer:: A breakpoint control panel. * Threads Buffer:: Displays your threads. * Stack Buffer:: Select a frame from the call stack. -* Other GDB Buffers:: Input/output, locals, registers, - assembler, threads and memory buffers. +* Other GDB Buffers:: Other buffers for controlling the GDB state. * Watch Expressions:: Monitor variable values in the speedbar. * Multithreaded Debugging:: Debugging programs with several threads. @@ -1152,7 +1126,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..dec5aa771ea 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/mark.texi b/doc/emacs/mark.texi index 0eccef41711..7d65719e5f0 100644 --- a/doc/emacs/mark.texi +++ b/doc/emacs/mark.texi @@ -354,9 +354,12 @@ Positions in Registers}). @vindex global-mark-ring-max In addition to the ordinary mark ring that belongs to each buffer, Emacs has a single @dfn{global mark ring}. Each time you set a mark, -in any buffer, this is recorded in the global mark ring in addition to -the current buffer's own mark ring. The length of this ring can be -controlled by @code{global-mark-ring-max}, and is 16 by default. +this is recorded in the global mark ring in addition to the current +buffer's own mark ring, if you have switched buffers since the +previous mark setting. Hence, the global mark ring records a sequence +of buffers that you have been in, and, for each buffer, a place where +you set the mark. The length of the global mark ring is controlled by +@code{global-mark-ring-max}, and is 16 by default. @kindex C-x C-@key{SPC} @findex pop-global-mark 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/msdog.texi b/doc/emacs/msdog.texi index bbaf31ade85..547d8cbadd9 100644 --- a/doc/emacs/msdog.texi +++ b/doc/emacs/msdog.texi @@ -863,15 +863,22 @@ fontconfig library used in modern Free desktops: The old XLFD based format is also supported for backwards compatibility. - Emacs 23 supports a number of backends. Currently, the @code{gdi} -and @code{uniscribe} font backends are supported on Windows. The -@code{gdi} font backend is available on all versions of Windows, and -supports all fonts that are natively supported by Windows. The +@cindex font backend selection (MS-Windows) + Emacs 23 and later supports a number of font backends. Currently, +the @code{gdi} and @code{uniscribe} backends are supported on Windows. +The @code{gdi} font backend is available on all versions of Windows, +and supports all fonts that are natively supported by Windows. The @code{uniscribe} font backend is available on Windows 2000 and later, and supports TrueType and OpenType fonts. Some languages requiring -complex layout can only be properly supported by the uniscribe +complex layout can only be properly supported by the Uniscribe backend. By default, both backends are enabled if supported, with -@code{uniscribe} taking priority over @code{gdi}. +@code{uniscribe} taking priority over @code{gdi}. To override that +and use the GDI backend even if Uniscribe is available, invoke Emacs +with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or +add a @code{Emacs.fontBackend} resource with the value @code{gdi} in +the Registry under either the +@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the +@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}). @cindex font properties (MS Windows) @noindent @@ -914,7 +921,7 @@ as a fallback with the font family left unspecified. @vindex w32-charset-info-alist @item registry Specifies the character set registry that the font is -expected to cover. Most TrueType and OpenType fonts will be unicode fonts +expected to cover. Most TrueType and OpenType fonts will be Unicode fonts that cover several national character sets, but you can narrow down the selection of fonts to those that support a particular character set by using a specific registry from @code{w32-charset-info-alist} here. @@ -936,9 +943,9 @@ Options specific to @code{GDI} fonts: @table @code @cindex font scripts (MS Windows) -@cindex font unicode subranges (MS Windows) +@cindex font Unicode subranges (MS Windows) @item script -Specifies a unicode subrange the font should support. +Specifies a Unicode subrange the font should support. The following scripts are recognized on Windows: @code{latin}, @code{greek}, @code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic}, diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 2357902341e..bb62ad67b2a 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -8,8 +8,8 @@ @cindex C editing @cindex program editing - Emacs provides many features to facilitate editing programs. Some -of these features can + This chapter describes Emacs features for facilitating editing +programs. Some of these features can: @itemize @bullet @item @@ -25,8 +25,6 @@ Insert, kill or align comments (@pxref{Comments}). Highlight program syntax (@pxref{Font Lock}). @end itemize - This chapter describes these features and many more. - @menu * Program Modes:: Major modes for editing programs. * Defuns:: Commands to operate on major top-level parts @@ -52,21 +50,14 @@ Highlight program syntax (@pxref{Font Lock}). @section Major Modes for Programming Languages @cindex modes for programming languages - Emacs has specialized major modes for various programming languages. -@xref{Major Modes}. A programming language major mode typically + Emacs has specialized major modes (@pxref{Major Modes}) for many +programming languages. A programming language mode typically specifies the syntax of expressions, the customary rules for indentation, how to do syntax highlighting for the language, and how -to find the beginning or end of a function definition. It often -customizes or provides facilities for compiling and debugging programs -as well. - - Ideally, Emacs should provide a major mode for each programming -language that you might want to edit; if it doesn't have a mode for -your favorite language, you can contribute one. But often the mode -for one language can serve for other syntactically similar languages. -The major mode for language @var{l} is called @code{@var{l}-mode}, -and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. -@xref{Choosing Modes}. +to find the beginning or end of a function definition. It often has +features for compiling and debugging programs as well. The major mode +for each language is named after the language; for instance, the major +mode for the C programming language is @code{c-mode}. @cindex Perl mode @cindex Icon mode @@ -89,40 +80,32 @@ and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. @cindex Conf mode @cindex DNS mode @cindex Javascript mode - The existing programming language major modes include Lisp, Scheme -(a variant of Lisp) and the Scheme-based DSSSL expression language, -Ada, ASM, AWK, C, C++, Delphi (Object Pascal), Fortran, Icon, IDL -(CORBA), IDLWAVE, Java, Javascript, Metafont (@TeX{}'s companion for -font creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike, -PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL. An -alternative mode for Perl is called CPerl mode. Modes are available -for the scripting languages of the common GNU and Unix shells, VMS -DCL, and MS-DOS/MS-Windows @samp{BAT} files. There are also major -modes for editing makefiles, DNS master files, and various sorts of -configuration files. + Emacs has programming language modes for Lisp, Scheme, the +Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi, +Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont +(@TeX{}'s companion for font creation), Modula2, Objective-C, Octave, +Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and +VHDL. An alternative mode for Perl is called CPerl mode. Modes are +also available for the scripting languages of the common GNU and Unix +shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for +makefiles, DNS master files, and various sorts of configuration files. + + Ideally, Emacs should have a major mode for each programming +language that you might want to edit. If it doesn't have a mode for +your favorite language, the mode might be implemented in a package not +distributed with Emacs (@pxref{Packages}); or you can contribute one. @kindex DEL @r{(programming modes)} @findex c-electric-backspace +@findex backward-delete-char-untabify In most programming languages, indentation should vary from line to -line to illustrate the structure of the program. So the major modes -for programming languages arrange for @key{TAB} to update the -indentation of the current line (@pxref{Program Indent}). They also -rebind @key{DEL} to treat a tab as if it were the equivalent number of -spaces; this lets you delete one column of indentation without -worrying whether the whitespace consists of spaces or tabs. Use -@kbd{C-b C-d} to delete a tab character before point, in these modes. - - Separate manuals are available for the modes for Ada (@pxref{Top, , Ada -Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK -(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes -(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran -mode, see -@iftex -@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@ref{Fortran}. -@end ifnottex +line to illustrate the structure of the program. Therefore, in most +programming language modes, typing @key{TAB} updates the indentation +of the current line (@pxref{Program Indent}). Furthermore, @key{DEL} +is usually bound to @code{backward-delete-char-untabify}, which +deletes backward treating each tab as if it were the equivalent number +of spaces, so that you can delete one column of indentation without +worrying whether the whitespace consists of spaces or tabs. @cindex mode hook @vindex c-mode-hook @@ -130,13 +113,24 @@ mode, see @vindex emacs-lisp-mode-hook @vindex lisp-interaction-mode-hook @vindex scheme-mode-hook - Turning on a major mode runs a normal hook called the @dfn{mode -hook}, which is the value of a Lisp variable. Each major mode has a -mode hook, and the hook's name is always made from the mode command's -name by adding @samp{-hook}. For example, turning on C mode runs the -hook @code{c-mode-hook}, while turning on Lisp mode runs the hook -@code{lisp-mode-hook}. The purpose of the mode hook is to give you a -place to set up customizations for that major mode. @xref{Hooks}. + Entering a programming language mode runs the custom Lisp functions +specified in the hook variable @code{prog-mode-hook}, followed by +those specified in the mode's own mode hook (@pxref{Major Modes}). +For instance, entering C mode runs the hooks @code{prog-mode-hook} and +@code{c-mode-hook}. @xref{Hooks}, for information about hooks. + +@ifinfo + Separate manuals are available for the modes for Ada (@pxref{Top,, +Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba +IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE +(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}). +@end ifinfo +@ifnotinfo + The Emacs distribution contains Info manuals for the major modes for +Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE. For +Fortran mode, see the ``Fortran'' section in the Info version of the +Emacs manual, which is not included in this printed version. +@end ifnotinfo @node Defuns @section Top-Level Definitions, or Defuns @@ -328,20 +322,19 @@ The Speedbar can also use it (@pxref{Speedbar}). @subsection Which Function Mode @cindex current function name in mode line - Which Function mode is a minor mode that displays the current -function name in the mode line, updating it as you move around in a -buffer. + Which Function mode is a global minor mode (@pxref{Minor Modes}) +which displays the current function name in the mode line, updating it +as you move around in a buffer. @findex which-function-mode @vindex which-func-modes To either enable or disable Which Function mode, use the command -@kbd{M-x which-function-mode}. This command applies to all buffers, -both existing ones and those yet to be created. However, it takes -effect only in certain major modes, those listed in the value of -@code{which-func-modes}. If the value of @code{which-func-modes} is -@code{t} rather than a list of modes, then Which Function mode applies -to all major modes that know how to support it---in other words, all -the major modes that support Imenu. +@kbd{M-x which-function-mode}. Although Which Function mode is a +global minor mode, it takes effect only in certain major modes: those +listed in the variable @code{which-func-modes}. If the value of +@code{which-func-modes} is @code{t} rather than a list of modes, then +Which Function mode applies to all major modes that know how to +support it---in other words, all the major modes that support Imenu. @node Program Indent @section Indentation for Programs @@ -352,6 +345,10 @@ reindent it as you change it. Emacs has commands to indent either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping. + @xref{Indentation}, for general information about indentation. This +section describes indentation features specific to programming +language modes. + @menu * Basic Indent:: Indenting a single line. * Multi-line Indent:: Commands to reindent many lines at once. @@ -361,18 +358,15 @@ single parenthetical grouping. @end menu @cindex pretty-printer - Emacs also provides a Lisp pretty-printer in the library @code{pp}. -This program reformats a Lisp object with indentation chosen to look nice. + Emacs also provides a Lisp pretty-printer in the @code{pp} package, +which reformats Lisp objects with nice-looking indentation. @node Basic Indent @subsection Basic Program Indentation Commands - The basic indentation commands indent a single line according to the -usual conventions of the language you are editing. - @table @kbd @item @key{TAB} -Adjust indentation of current line. +Adjust indentation of current line (@code{indent-for-tab-command}). @item C-j Insert a newline, then adjust indentation of following line (@code{newline-and-indent}). @@ -382,65 +376,50 @@ Insert a newline, then adjust indentation of following line @findex c-indent-command @findex indent-line-function @findex indent-for-tab-command - The basic indentation command is @key{TAB}. In any -programming-language major mode, @key{TAB} gives the current line the -correct indentation as determined from the previous lines. It does -this by inserting or deleting whitespace at the beginning of the -current line. If point was inside the whitespace at the beginning of -the line, @key{TAB} puts it at the end of that whitespace; otherwise, -@key{TAB} keeps point fixed with respect to the characters around it. -If the region is active (@pxref{Mark}), @key{TAB} indents every line -within the region instead of just the current line. The function that -@key{TAB} runs depends on the major mode; for instance, it is -@code{c-indent-line-or-region} in C mode. Each function is aware of -the syntax and conventions for its particular language. - - Use @kbd{C-q @key{TAB}} to insert a tab character at point. - -@kindex C-j + The basic indentation command is @key{TAB} +(@code{indent-for-tab-command}), which was documented in +@ref{Indentation}. In programming language modes, @key{TAB} indents +the current line, based on the indentation and syntactic content of +the preceding lines; if the region is active, @key{TAB} indents each +line within the region, not just the current line. + +@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 -indentation after it. (It also deletes any trailing whitespace which -remains before the new newline.) For instance, @kbd{C-j} at the end -of a line creates a blank line with appropriate indentation. In -programming language modes, it is equivalent to @key{RET} @key{TAB}. - - When Emacs indents a line that starts within a parenthetical -grouping, it usually places the start of the line under the preceding -line within the group, or under the text after the parenthesis. If -you manually give one of these lines a nonstandard indentation, the -lines below will tend to follow it. This behavior is convenient in -cases where you have overridden the standard result of @key{TAB} -indentation (e.g., for aesthetic purposes). - - Many programming-language modes assume that an open-parenthesis, -open-brace or other opening delimiter at the left margin is the start -of a function. This assumption speeds up indentation commands. If -the text you are editing contains opening delimiters in column zero -that aren't the beginning of a functions---even if these delimiters -occur inside strings or comments---then you must set -@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin + The command @kbd{C-j} (@code{newline-and-indent}), which was +documented in @ref{Indentation Commands}, does the same as @key{RET} +followed by @key{TAB}: it inserts a new line, then adjusts the line's +indentation. + + When indenting a line that starts within a parenthetical grouping, +Emacs usually places the start of the line under the preceding line +within the group, or under the text after the parenthesis. If you +manually give one of these lines a nonstandard indentation (e.g.@: for +aesthetic purposes), the lines below will follow it. + + The indentation commands for most programming language modes assume +that a open-parenthesis, open-brace or other opening delimiter at the +left margin is the start of a function. If the code you are editing +violates this assumption---even if the delimiters occur in strings or +comments---you must set @code{open-paren-in-column-0-is-defun-start} +to @code{nil} for indentation to work properly. @xref{Left Margin Paren}. - Normally, Emacs indents lines using an ``optimal'' mix of tab and -space characters. If you want Emacs to use spaces only, set -@code{indent-tabs-mode} (@pxref{Just Spaces}). - @node Multi-line Indent @subsection Indenting Several Lines Sometimes, you may want to reindent several lines of code at a time. One way to do this is to use the mark; when the mark is active and the -region is non-empty, @key{TAB} indents every line within the region. -In addition, Emacs provides several other commands for indenting large -chunks of code: +region is non-empty, @key{TAB} indents every line in the region. +Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents +every line in the region, whether or not the mark is active +(@pxref{Indentation Commands}). + + In addition, Emacs provides the following commands for indenting +large chunks of code: @table @kbd @item C-M-q Reindent all the lines within one parenthetical grouping. -@item C-M-\ -Reindent all lines in the region (@code{indent-region}). @item C-u @key{TAB} Shift an entire parenthetical grouping rigidly sideways so that its first line is properly indented. @@ -454,18 +433,13 @@ lines that start inside comments and strings. To reindent the contents of a single parenthetical grouping, position point before the beginning of the grouping and type @kbd{C-M-q}. This changes the relative indentation within the -grouping, without affecting its overall indentation (i.e., the +grouping, without affecting its overall indentation (i.e.@: the indentation of the line where the grouping starts). The function that @kbd{C-M-q} runs depends on the major mode; it is @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, etc. To correct the overall indentation as well, type @key{TAB} first. - @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to the region. -This is useful when Transient Mark mode is disabled (@pxref{Disabled -Transient Mark}), because in that case @key{TAB} does not act on the -region. - @kindex C-u TAB If you like the relative indentation within a grouping but not the indentation of its first line, move point to that first line and type @@ -516,9 +490,9 @@ expression. @cindex @code{lisp-indent-function} property You can override the standard pattern in various ways for individual functions, according to the @code{lisp-indent-function} property of -the function name. Normally you would use this for macro definitions -and specify it using the @code{declare} construct (@pxref{Defining -Macros,,, elisp, the Emacs Lisp Reference Manual}). +the function name. This is normally done for macro definitions, using +the @code{declare} construct. @xref{Defining Macros,,, elisp, the +Emacs Lisp Reference Manual}. @node C Indent @subsection Commands for C Indentation @@ -664,9 +638,13 @@ parentheses and unbalanced string quotes in the buffer. @cindex sexp @cindex expression @cindex balanced expression - These commands deal with balanced expressions, also called -@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an -expression in Lisp.}. + Each programming language mode has its own definition of a +@dfn{balanced expression}. Balanced expressions typically include +individual symbols, numbers, and string constants, as well as pieces +of code enclosed in a matching pair of delimiters. The following +commands deal with balanced expressions (in Emacs, such expressions +are referred to internally as @dfn{sexps}@footnote{The word ``sexp'' +is used to refer to an expression in Lisp.}). @table @kbd @item C-M-f @@ -682,90 +660,71 @@ Transpose expressions (@code{transpose-sexps}). Put mark after following expression (@code{mark-sexp}). @end table - Each programming language major mode customizes the definition of -balanced expressions to suit that language. Balanced expressions -typically include symbols, numbers, and string constants, as well as -any pair of matching delimiters and their contents. Some languages -have obscure forms of expression syntax that nobody has bothered to -implement in Emacs. - -@cindex Control-Meta - By convention, the keys for these commands are all Control-Meta -characters. They usually act on expressions just as the corresponding -Meta characters act on words. For instance, the command @kbd{C-M-b} -moves backward over a balanced expression, just as @kbd{M-b} moves -back over a word. - @kindex C-M-f @kindex C-M-b @findex forward-sexp @findex backward-sexp To move forward over a balanced expression, use @kbd{C-M-f} (@code{forward-sexp}). If the first significant character after point -is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or -@samp{@{} in C), @kbd{C-M-f} moves past the matching closing -delimiter. If the character begins a symbol, string, or number, -@kbd{C-M-f} moves over that. +is an opening delimiter (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C), +this command moves past the matching closing delimiter. If the +character begins a symbol, string, or number, the command moves over +that. The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a -balanced expression. The detailed rules are like those above for -@kbd{C-M-f}, but with directions reversed. If there are prefix -characters (single-quote, backquote and comma, in Lisp) preceding the -expression, @kbd{C-M-b} moves back over them as well. The balanced -expression commands move across comments as if they were whitespace, -in most modes. - - @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the -specified number of times; with a negative argument, it moves in the -opposite direction. +balanced expression---like @kbd{C-M-f}, but in the reverse direction. +If the expression is preceded by any prefix characters (single-quote, +backquote and comma, in Lisp), the command moves back over them as +well. + + @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation +the specified number of times; with a negative argument means to move +in the opposite direction. In most modes, these two commands move +across comments as if they were whitespace. Note that their keys, +@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b}, +which move by characters (@pxref{Moving Point}), and @kbd{M-f} and +@kbd{M-b}, which move by words (@pxref{Words}). @cindex killing expressions @kindex C-M-k @findex kill-sexp - Killing a whole balanced expression can be done with @kbd{C-M-k} -(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} -would move over. + To kill a whole balanced expression, type @kbd{C-M-k} +(@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move +over. @cindex transposition of expressions @kindex C-M-t @findex transpose-sexps - A somewhat random-sounding command which is nevertheless handy is -@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous -balanced expression across the next one. An argument serves as a -repeat count, moving the previous expression over that many following -ones. A negative argument drags the previous balanced expression -backwards across those before it (thus canceling out the effect of -@kbd{C-M-t} with a positive argument). An argument of zero, rather -than doing nothing, transposes the balanced expressions ending at or -after point and the mark. + @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the +previous balanced expression and the next one. It is analogous to the +@kbd{C-t} command, which transposes characters (@pxref{Transpose}). +An argument to @kbd{C-M-t} serves as a repeat count, moving the +previous expression over that many following ones. A negative +argument moves the previous balanced expression backwards across those +before it. An argument of zero, rather than doing nothing, transposes +the balanced expressions ending at or after point and the mark. @kindex C-M-@@ @kindex C-M-@key{SPC} @findex mark-sexp - To operate on balanced expressions with an operation which acts on -the region, use the command @kbd{C-M-@key{SPC}} (@code{mark-sexp}). -This sets the mark at the same place that @kbd{C-M-f} would move to. -@xref{Marking Objects}, for more information about this command. - -@kbd{C-M-@key{SPC}} treats -numeric arguments in the same way as @kbd{C-M-f}; in particular, a -negative argument puts the mark at the beginning of the previous -balanced expression. The alias @kbd{C-M-@@} is equivalent to -@kbd{C-M-@key{SPC}}. While the mark is active, each successive use of -@kbd{C-M-@key{SPC}} extends the region by shifting the mark by one -sexp. + To operate on balanced expressions with a command which acts on the +region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the +mark where @kbd{C-M-f} would move to. While the mark is active, each +successive call to this command extends the region by shifting the +mark by one expression. Positive or negative numeric arguments move +the mark forward or backward by the specified number of expressions. +The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}. +@xref{Marking Objects}, for more information about this and related +commands. In languages that use infix operators, such as C, it is not possible -to recognize all balanced expressions as such because there can be -multiple possibilities at a given position. For example, C mode does -not treat @samp{foo + bar} as a single expression, even though it -@emph{is} one C expression; instead, it recognizes @samp{foo} as one -expression and @samp{bar} as another, with the @samp{+} as punctuation -between them. Both @samp{foo + bar} and @samp{foo} are legitimate -choices for ``the expression following point'' when point is at the -@samp{f}, so the expression commands must perforce choose one or the -other to operate on. Note that @samp{(foo + bar)} is recognized as a -single expression in C mode, because of the parentheses. +to recognize all balanced expressions because there can be multiple +possibilities at a given position. For example, C mode does not treat +@samp{foo + bar} as a single expression, even though it @emph{is} one +C expression; instead, it recognizes @samp{foo} as one expression and +@samp{bar} as another, with the @samp{+} as punctuation between them. +However, C mode recognizes @samp{(foo + bar)} as a single expression, +because of the parentheses. @node Moving by Parens @subsection Moving in the Parenthesis Structure @@ -776,19 +735,18 @@ single expression in C mode, because of the parentheses. @cindex braces, moving across @cindex list commands - The Emacs commands for handling parenthetical groupings see nothing -except parentheses (or whatever characters must balance in the -language you are working with). They ignore strings and comments -(including any parentheses within them) and ignore parentheses quoted -by an escape character. They are mainly intended for editing -programs, but can be useful for editing any text that has parentheses. -They are sometimes called ``list'' commands because in Lisp these -groupings are lists. + The following commands move over groupings delimited by parentheses +(or whatever else serves as delimiters in the language you are working +with). They ignore strings and comments, including any parentheses +within them, and also ignore parentheses that are ``quoted'' with an +escape character. These commands are mainly intended for editing +programs, but can be useful for editing any text containing +parentheses. They are referred to internally as ``list'' commands +because in Lisp these groupings are lists. -These commands assume that the starting point is not inside a string -or a comment. Sometimes you can invoke them usefully from one of -these places (for example, when you have a parenthesised clause in a -comment) but this is unreliable. + These commands assume that the starting point is not inside a string +or a comment. If you invoke them from inside a string or comment, the +results are unreliable. @table @kbd @item C-M-n @@ -826,52 +784,62 @@ delimiter, this is nearly the same as searching for a @samp{(}. An argument specifies the number of levels to go down. @node Matching -@subsection Automatic Display Of Matching Parentheses +@subsection Matching Parentheses @cindex matching parentheses @cindex parentheses, displaying matches - The Emacs parenthesis-matching feature is designed to show -automatically how parentheses (and other matching delimiters) match in -the text. Whenever you type a self-inserting character that is a -closing delimiter, the cursor moves momentarily to the location of the + Emacs has a number of @dfn{parenthesis matching} features, which +make it easy to see how and whether parentheses (or other delimiters) +match up. + + Whenever you type a self-inserting character that is a closing +delimiter, the cursor moves momentarily to the location of the matching opening delimiter, provided that is on the screen. If it is not on the screen, Emacs displays some of the text near it in the echo area. Either way, you can tell which grouping you are closing off. - - If the opening delimiter and closing delimiter are mismatched---such +If the opening delimiter and closing delimiter are mismatched---such as in @samp{[x)}---a warning message is displayed in the echo area. @vindex blink-matching-paren @vindex blink-matching-paren-distance @vindex blink-matching-delay - Three variables control parenthesis match display: + Three variables control the display of matching parentheses: - @code{blink-matching-paren} turns the feature on or off: @code{nil} -disables it, but the default is @code{t} to enable match display. +@itemize @bullet +@item +@code{blink-matching-paren} turns the feature on or off: @code{nil} +disables it, but the default is @code{t} to enable it. - @code{blink-matching-delay} says how many seconds to leave the -cursor on the matching opening delimiter, before bringing it back to -the real location of point; the default is 1, but on some systems it -is useful to specify a fraction of a second. +@item +@code{blink-matching-delay} says how many seconds to leave the cursor +on the matching opening delimiter, before bringing it back to the real +location of point. This may be an integer or floating-point number; +the default is 1. - @code{blink-matching-paren-distance} specifies how many characters +@item +@code{blink-matching-paren-distance} specifies how many characters back to search to find the matching opening delimiter. If the match -is not found in that distance, scanning stops, and nothing is displayed. -This is to prevent the scan for the matching delimiter from wasting -lots of time when there is no match. The default is 102400. +is not found in that distance, Emacs stops scanning and nothing is +displayed. The default is 102400. +@end itemize @cindex Show Paren mode @cindex highlighting matching parentheses @findex show-paren-mode - Show Paren mode provides a more powerful kind of automatic matching. -Whenever point is before an opening delimiter or after a closing -delimiter, both that delimiter and its opposite delimiter are -highlighted. Use the command @kbd{M-x show-paren-mode} to enable or -disable this mode. - - Show Paren mode uses the faces @code{show-paren-match} and -@code{show-paren-mismatch} to highlight parentheses; you can customize -them to control how highlighting looks. @xref{Face Customization}. + Show Paren mode, a global minor mode, provides a more powerful kind +of automatic matching. Whenever point is before an opening delimiter +or after a closing delimiter, both that delimiter and its opposite +delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x +show-paren-mode}. + +@cindex Electric Pair mode +@cindex inserting matching parentheses +@findex electric-pair-mode + Electric Pair mode, a global minor mode, provides a way to easily +insert matching delimiters. Whenever you insert an opening delimiter, +the matching closing delimiter is automatically inserted as well, +leaving point between the two. To toggle Electric Pair mode, type +@kbd{M-x electric-pair-mode}. @node Comments @section Manipulating Comments @@ -882,6 +850,23 @@ provides special commands for editing and inserting comments. It can also do spell checking on comments with Flyspell Prog mode (@pxref{Spelling}). + Some major modes have special rules for indenting different kinds of +comments. For example, in Lisp code, comments starting with two +semicolons are indented as if they were lines of code, while those +starting with three semicolons are supposed to be aligned to the left +margin and are often used for sectioning purposes. Emacs understand +these conventions; for instance, typing @key{TAB} on a comment line +will indent the comment to the appropriate position. + +@example +;; This function is just an example. +;;; Here either two or three semicolons are appropriate. +(defun foo (x) +;;; And now, the first part of the function: + ;; The following line adds one. + (1+ x)) ; This line adds one. +@end example + @menu * Comment Commands:: Inserting, killing, and aligning comments. * Multi-Line Comments:: Commands for adding and editing multi-line comments. @@ -893,12 +878,12 @@ also do spell checking on comments with Flyspell Prog mode @cindex indentation for comments @cindex alignment for comments - The commands in this table insert, kill and align comments: + The following commands operate on comments: @table @asis @item @kbd{M-;} -Insert or realign comment on current line; alternatively, comment or -uncomment the region (@code{comment-dwim}). +Insert or realign comment on current line; if the region is active, +comment or uncomment the region instead (@code{comment-dwim}). @item @kbd{C-u M-;} Kill comment on current line (@code{comment-kill}). @item @kbd{C-x ;} @@ -909,7 +894,7 @@ Like @key{RET} followed by inserting and aligning a comment (@code{comment-indent-new-line}). @xref{Multi-Line Comments}. @item @kbd{M-x comment-region} @itemx @kbd{C-c C-c} (in C-like modes) -Add or remove comment delimiters on all the lines in the region. +Add comment delimiters to all the lines in the region. @end table @kindex M-; @@ -920,65 +905,61 @@ I Mean''; it indicates that this command can be used for many different jobs relating to comments, depending on the situation where you use it. - When a region is active, @kbd{M-;} either adds or removes comment -delimiters on each line of the region. @xref{Mark}. If every line in -the region is a comment, it removes comment delimiters from each; -otherwise, it adds comment delimiters to each. You can also use the -commands @code{comment-region} and @code{uncomment-region} to -explicitly comment or uncomment the text in the region -(@pxref{Multi-Line Comments}). If you supply a prefix argument to -@kbd{M-;} when a region is active, that specifies how many comment -delimiters to add or how many to delete. - - If the region is not active, @kbd{M-;} inserts a new comment if -there is no comment already on the line. The new comment is normally -aligned at a specific column called the @dfn{comment column}; if the -text of the line extends past the comment column, @kbd{M-;} aligns the -comment start string to a suitable boundary (usually, at least one -space is inserted). The comment begins with the string Emacs thinks -comments should start with (the value of @code{comment-start}; see -below). Emacs places point after that string, so you can insert the -text of the comment right away. If the major mode has specified a -string to terminate comments, @kbd{M-;} inserts that string after -point, to keep the syntax valid. + When a region is active (@pxref{Mark}), @kbd{M-;} either adds +comment delimiters to the region, or removes them. If every line in +the region is already a comment, it ``uncomments'' each of those lines +by removing their comment delimiters. Otherwise, it adds comment +delimiters to enclose the text in the region. + + If you supply a prefix argument to @kbd{M-;} when a region is +active, that specifies the number of comment delimiters to add or +delete. A positive argument @var{n} adds @var{n} delimiters, while a +negative argument @var{-n} removes @var{n} delimiters. + + If the region is not active, and there is no existing comment on the +current line, @kbd{M-;} adds a new comment to the current line. If +the line is blank (i.e.@: empty or containing only whitespace +characters), the comment is indented to the same position where +@key{TAB} would indent to (@pxref{Basic Indent}). If the line is +non-blank, the comment is placed after the last non-whitespace +character on the line; normally, Emacs tries putting it at the column +specified by the variable @code{comment-column} (@pxref{Options for +Comments}), but if the line already extends past that column, it puts +the comment at some suitable position, usually separated from the +non-comment text by at least one space. In each case, Emacs places +point after the comment's starting delimiter, so that you can start +typing the comment text right away. You can also use @kbd{M-;} to align an existing comment. If a line already contains the comment-start string, @kbd{M-;} realigns it to -the conventional alignment and moves point after it. (Exception: -comments starting in column 0 are not moved.) Even when an existing -comment is properly aligned, @kbd{M-;} is still useful for moving -directly to the start of the text inside the comment. +the conventional alignment and moves point after the comment's +starting delimiter. As an exception, comments starting in column 0 +are not moved. Even when an existing comment is properly aligned, +@kbd{M-;} is still useful for moving directly to the start of the +comment text. @findex comment-kill @kindex C-u M-; - @kbd{C-u M-;} kills any comment on the current line, along with the -whitespace before it. To reinsert the comment on another line, move -to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to -realign it. - - Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} -(@code{comment-dwim}) with a prefix argument. That command is -programmed so that when it receives a prefix argument it calls -@code{comment-kill}. However, @code{comment-kill} is a valid command -in its own right, and you can bind it directly to a key if you wish. - - Some major modes have special rules for aligning certain kinds of -comments in certain contexts. For example, in Lisp code, comments which -start with two semicolons are indented as if they were lines of code, -instead of at the comment column. Comments which start with three -semicolons are supposed to start at the left margin and are often used -for sectioning purposes. Emacs understands -these conventions by indenting a double-semicolon comment using @key{TAB}, -and by not changing the indentation of a triple-semicolon comment at all. + @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any +comment on the current line, along with the whitespace before it. +Since the comment is saved to the kill ring, you can reinsert it on +another line by moving to the end of that line, doing @kbd{C-y}, and +then @kbd{M-;} to realign the command. You can achieve the same +effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill} +(@code{comment-dwim} actually calls @code{comment-kill} as a +subroutine when it is given a prefix argument). -@example -;; This function is just an example. -;;; Here either two or three semicolons are appropriate. -(defun foo (x) -;;; And now, the first part of the function: - ;; The following line adds one. - (1+ x)) ; This line adds one. -@end example +@kindex C-c C-c (C mode) +@findex comment-region +@findex uncomment-region + The command @kbd{M-x comment-region} is equivalent to calling +@kbd{M-;} on an active region, except that it always acts on the +region, even if the mark is inactive. In C mode and related modes, +this command is bound to @kbd{C-c C-c}. The command @kbd{M-x +uncomment-region} uncomments each line in the region; a numeric prefix +argument specifies the number of comment delimiters to remove +(negative arguments specify the number of comment to delimiters to +add). For C-like modes, you can configure the exact effect of @kbd{M-;} by setting the variables @code{c-indent-comment-alist} and @@ -994,32 +975,31 @@ the brace rather than at @code{comment-column}. For full details see @kindex M-j @cindex blank lines in programs @findex comment-indent-new-line - - If you are typing a comment and wish to continue it on another line, -you can use the command @kbd{C-M-j} or @kbd{M-j} -(@code{comment-indent-new-line}). If @code{comment-multi-line} -(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new -line within the comment. Otherwise it closes the comment and starts a -new comment on a new line. When Auto Fill mode is on, going past the -fill column while typing a comment causes the comment to be continued -in just this fashion. - -@kindex C-c C-c (C mode) -@findex comment-region - To turn existing lines into comment lines, use the @kbd{M-x -comment-region} command (or type @kbd{C-c C-c} in C-like modes). It -adds comment delimiters to the lines that start in the region, thus -commenting them out. With a negative argument, it does the -opposite---it deletes comment delimiters from the lines in the region. - - With a positive argument, @code{comment-region} duplicates the last -character of the comment start sequence it adds; the argument -specifies how many copies of the character to insert. Thus, in Lisp -mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. -Duplicating the comment delimiter is a way of calling attention to the -comment. It can also affect how the comment is aligned or indented. -In Lisp, for proper indentation, you should use an argument of two or -three, if between defuns; if within a defun, it must be three. +@vindex comment-multi-line + If you are typing a comment and wish to continue it to another line, +type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This +breaks the current line, and inserts the necessary comment delimiters +and indentation to continue the comment. + + For languages with closing comment delimiters (e.g.@: @samp{*/} in +C), the exact behavior of @kbd{M-j} depends on the value of the +variable @code{comment-multi-line}. If the value is @code{nil}, the +command closes the comment on the old line and starts a new comment on +the new line. Otherwise, it opens a new line within the current +comment delimiters. + + When Auto Fill mode is on, going past the fill column while typing a +comment also continues the comment, in the same way as an explicit +invocation of @kbd{M-j}. + + To turn existing lines into comment lines, use @kbd{M-;} with the +region active, or use @kbd{M-x comment-region} +@ifinfo +(@pxref{Comment Commands}). +@end ifinfo +@ifnotinfo +as described in the preceding section. +@end ifnotinfo You can configure C Mode such that when you type a @samp{/} at the start of a line in a multi-line block comment, this closes the @@ -1032,19 +1012,16 @@ comment. Enable the @code{comment-close-slash} clean-up for this. @vindex comment-column @kindex C-x ; @findex comment-set-column - The @dfn{comment column}, the column at which Emacs tries to place -comments, is stored in the variable @code{comment-column}. You can -set it to a number explicitly. Alternatively, the command @kbd{C-x ;} -(@code{comment-set-column}) sets the comment column to the column -point is at. @kbd{C-u C-x ;} sets the comment column to match the -last comment before point in the buffer, and then does a @kbd{M-;} to -align the current line's comment under the previous one. - - The variable @code{comment-column} is per-buffer: setting the variable -in the normal fashion affects only the current buffer, but there is a -default value which you can change with @code{setq-default}. -@xref{Locals}. Many major modes initialize this variable for the -current buffer. + As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command +adds a comment to a line, it tries to place the comment at the column +specified by the buffer-local variable @code{comment-column}. You can +set either the local value or the default value of this buffer-local +variable in the usual way (@pxref{Locals}). Alternatively, you can +type @kbd{C-x ;} (@code{comment-set-column}) to set the value of +@code{comment-column} in the current buffer to the column where point +is currently located. @kbd{C-u C-x ;} sets the comment column to +match the last comment before point in the buffer, and then does a +@kbd{M-;} to align the current line's comment under the previous one. @vindex comment-start-skip The comment commands recognize comments based on the regular @@ -1053,39 +1030,32 @@ Make sure this regexp does not match the null string. It may match more than the comment starting delimiter in the strictest sense of the word; for example, in C mode the value of the variable is @c This stops M-q from breaking the line inside that @code. -@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces -after the @samp{/*} itself, and accepts C++ style comments also. -(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in -the string, which is needed to deny the first star its special meaning -in regexp syntax. @xref{Regexp Backslash}.) +@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and +spaces after the @samp{/*} itself, and accepts C++ style comments +also. (Note that @samp{\\} is needed in Lisp syntax to include a +@samp{\} in the string, which is needed to deny the first star its +special meaning in regexp syntax. @xref{Regexp Backslash}.) @vindex comment-start @vindex comment-end When a comment command makes a new comment, it inserts the value of -@code{comment-start} to begin it. The value of @code{comment-end} is -inserted after point, so that it will follow the text that you will -insert into the comment. When @code{comment-end} is non-empty, it -should start with a space. For example, in C mode, -@code{comment-start} has the value @w{@code{"/* "}} and -@code{comment-end} has the value @w{@code{" */"}}. +@code{comment-start} as an opening comment delimiter. It also inserts +the value of @code{comment-end} after point, as a closing comment +delimiter. For example, in Lisp mode, @code{comment-start} is +@samp{";"} and @code{comment-end} is @code{""} (the empty string). In +C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is +@code{" */"}. @vindex comment-padding - The variable @code{comment-padding} specifies how many spaces -@code{comment-region} should insert on each line between the comment -delimiter and the line's original text. The default is 1, to insert -one space. @code{nil} means 0. Alternatively, @code{comment-padding} -can hold the actual string to insert. + The variable @code{comment-padding} specifies a string that the +commenting commands should insert between the comment delimiter(s) and +the comment text. The default, @samp{" "}, specifies a single space. +Alternatively, the value can be a number, which specifies that number +of spaces, or @code{nil}, which means no spaces at all. -@vindex comment-multi-line - The variable @code{comment-multi-line} controls how @kbd{C-M-j} -(@code{indent-new-comment-line}) behaves when used inside a comment. -Specifically, when @code{comment-multi-line} is @code{nil}, the -command inserts a comment terminator, begins a new line, and finally -inserts a comment starter. Otherwise it does not insert the -terminator and starter, so it effectively continues the current -comment across multiple lines. In languages that allow multi-line -comments, the choice of value for this variable is a matter of taste. -The default for this variable depends on the major mode. + The variable @code{comment-multi-line} controls how @kbd{M-j} and +Auto Fill mode continue comments over multiple lines. +@xref{Multi-Line Comments}. @vindex comment-indent-function The variable @code{comment-indent-function} should contain a function @@ -1139,7 +1109,7 @@ mode which @kbd{C-h S} does support. @node Man Page @subsection Man Page Lookup -@cindex manual page +@cindex man page On Unix, the main form of on-line documentation was the @dfn{manual page} or @dfn{man page}. In the GNU operating system, we aim to replace man pages with better-organized manuals that you can browse @@ -1148,71 +1118,51 @@ still useful to read manual pages. @findex manual-entry You can read the man page for an operating system command, library -function, or system call, with the @kbd{M-x man} command. It -runs the @code{man} program to format the man page; if the system -permits, it runs @code{man} asynchronously, so that you can keep on -editing while the page is being formatted. (On MS-DOS and MS-Windows -3, you cannot edit while Emacs waits for @code{man} to finish.) The -result goes in a buffer named @samp{*Man @var{topic}*}. These buffers -use a special major mode, Man mode, that facilitates scrolling and -jumping to other manual pages. For details, type @kbd{C-h m} while in -a man page buffer. +function, or system call, with the @kbd{M-x man} command. This +prompts for a topic, with completion (@pxref{Completion}), and runs +the @command{man} program to format the corresponding man page. If +the system permits, it runs @command{man} asynchronously, so that you +can keep on editing while the page is being formatted. The result +goes in a buffer named @samp{*Man @var{topic}*}. These buffers use a +special major mode, Man mode, that facilitates scrolling and jumping +to other manual pages. For details, type @kbd{C-h m} while in a Man +mode buffer. @cindex sections of manual pages Each man page belongs to one of ten or more @dfn{sections}, each -named by a digit or by a digit and a letter. Sometimes there are -multiple man pages with the same name in different sections. To read -a man page from a specific section, type -@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} -when @kbd{M-x manual-entry} prompts for the topic. For example, to -read the man page for the C library function @code{chmod} (as opposed -to a command of the same name), type @kbd{M-x manual-entry @key{RET} -chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in -section @samp{2}.) +named by a digit or by a digit and a letter. Sometimes there are man +pages with the same name in different sections. To read a man page +from a specific section, type @samp{@var{topic}(@var{section})} or +@samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts +for the topic. For example, the man page for the C library function +@code{chmod} is in section 2, but there is a shell command of the same +name, whose man page is in section 1; to view the former, type +@kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}. @vindex Man-switches - If you do not specify a section, the results depend on how the -@code{man} program works on your system. Some of them display only -the first man page they find. Others display all man pages that have -the specified name, so you can move between them with the @kbd{M-n} -and @kbd{M-p} keys@footnote{On some systems, the @code{man} program -accepts a @samp{-a} command-line option which tells it to display all -the man pages for the specified topic. If you want this behavior, you -can add this option to the value of the variable @code{Man-switches}.}. -The mode line shows how many manual pages are present in the Man buffer. - -@vindex Man-fontify-manpage-flag - By default, Emacs highlights the text in man pages. For a long man -page, highlighting can take substantial time. You can turn off -highlighting of man pages by setting the variable -@code{Man-fontify-manpage-flag} to @code{nil}. - -@findex Man-fontify-manpage - If you insert the text of a man page into an Emacs buffer in some -other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to -perform the same conversions that @kbd{M-x manual-entry} does. +@kindex M-n @r{(Man mode)} +@kindex M-p @r{(Man mode)} + If you do not specify a section, @kbd{M-x man} normally displays +only the first man page found. On some systems, the @code{man} +program accepts a @samp{-a} command-line option, which tells it to +display all the man pages for the specified topic. To make use of +this, change the value of the variable @code{Man-switches} to +@samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and +@kbd{M-p} to switch between man pages in different sections. The mode +line shows how many manual pages are available. @findex woman @cindex manual pages, on MS-DOS/MS-Windows An alternative way of reading manual pages is the @kbd{M-x woman} -command@footnote{The name of the command, @code{woman}, is an acronym -for ``w/o (without) man,'' since it doesn't use the @code{man} -program.}. Unlike @kbd{M-x man}, it does not run any external -programs to format and display the man pages; instead it does the job -in Emacs Lisp, so it works on systems such as MS-Windows, where the -@code{man} program (and other programs it uses) are not generally -available. - - @kbd{M-x woman} prompts for a name of a manual page, and provides -completion based on the list of manual pages that are installed on -your machine; the list of available manual pages is computed -automatically the first time you invoke @code{woman}. The word at -point in the current buffer is used to suggest the default for the -name of the manual page. - - With a numeric argument, @kbd{M-x woman} recomputes the list of the -manual pages used for completion. This is useful if you add or delete -manual pages. +command. Unlike @kbd{M-x man}, it does not run any external programs +to format and display the man pages; the formatting is done by Emacs, +so it works on systems such as MS-Windows where the @command{man} +program may be unavailable. It prompts for a man page, and displays +it in a buffer named @samp{*WoMan @var{section} @var{topic}}. + + @kbd{M-x woman} computes the completion list for manpages the first +time you invoke the command. With a numeric argument, it recomputes +this list; this is useful if you add or delete manual pages. If you type a name of a manual page and @kbd{M-x woman} finds that several manual pages by the same name exist in different sections, it @@ -1220,48 +1170,51 @@ pops up a window with possible candidates asking you to choose one of them. For more information about setting up and using @kbd{M-x woman}, see -@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan -Manual}. +@ifinfo +@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The +WoMan Manual}. +@end ifinfo +@ifnotinfo +the WoMan Info manual, which is distributed with Emacs. +@end ifnotinfo @node Lisp Doc @subsection Emacs Lisp Documentation Lookup - As you edit Lisp code to be run in Emacs, you can use the commands -@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} -(@code{describe-variable}) to view documentation of functions and -variables that you want to use. These commands use the minibuffer to -read the name of a function or variable to document, and display the -documentation in a window. Their default arguments are based on the -code in the neighborhood of point. For @kbd{C-h f}, the default is -the function called in the innermost list containing point. @kbd{C-h -v} uses the symbol name around or adjacent to point as its default. + When editing Emacs Lisp code, you can use the commands @kbd{C-h f} +(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) +to view the built-in documentation for the Lisp functions and +variables that you want to use. @xref{Name Help}. @cindex Eldoc mode @findex eldoc-mode - A more automatic but less powerful method is Eldoc mode. This minor -mode constantly displays in the echo area the argument list for the -function being called at point. (In other words, it finds the -function call that point is contained in, and displays the argument -list of that function.) If point is over a documented variable, it -shows the first line of the variable's docstring. Eldoc mode applies -in Emacs Lisp and Lisp Interaction modes, and perhaps a few others -that provide special support for looking up doc strings. Use the -command @kbd{M-x eldoc-mode} to enable or disable this feature. + Eldoc is a buffer-local minor mode that helps with looking up Lisp +documention. When it is enabled, the echo area displays some useful +information whenever there is a Lisp function or variable at point; +for a function, it shows the argument list, and for a variable it +shows the first line of the variable's documentation string. To +toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used +with the Emacs Lisp and Lisp Interaction major modes. @node Hideshow @section Hideshow minor mode +@cindex Hideshow mode +@cindex mode, Hideshow @findex hs-minor-mode - Hideshow minor mode provides selective display of portions of a -program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} -to enable or disable this mode, or add @code{hs-minor-mode} to the -mode hook for certain major modes in order to enable it automatically -for those modes. + Hideshow mode is a buffer-local minor mode that allows you to +selectively display portions of a program, which are referred to as +@dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode +(@pxref{Minor Modes}). - Just what constitutes a block depends on the major mode. In C mode -or C++ mode, they are delimited by braces, while in Lisp mode and -similar modes they are delimited by parentheses. Multi-line comments -also count as blocks. + When you use Hideshow mode to hide a block, the block disappears +from the screen, to be replaced by an ellipsis (three periods in a +row). Just what constitutes a block depends on the major mode. In C +mode and related modes, blocks are delimited by braces, while in Lisp +mode they are delimited by parentheses. Multi-line comments also +count as blocks. + + Hideshow mode provides the following commands: @findex hs-hide-all @findex hs-hide-block @@ -1285,11 +1238,11 @@ Show the current block (@code{hs-show-block}). @item C-c @@ C-c Either hide or show the current block (@code{hs-toggle-hiding}). @item S-Mouse-2 -Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). +Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}). @item C-c @@ C-M-h Hide all top-level blocks (@code{hs-hide-all}). @item C-c @@ C-M-s -Show everything in the buffer (@code{hs-show-all}). +Show all blocks in the buffer (@code{hs-show-all}). @item C-c @@ C-l Hide all blocks @var{n} levels below this block (@code{hs-hide-level}). @@ -1298,80 +1251,55 @@ Hide all blocks @var{n} levels below this block @vindex hs-hide-comments-when-hiding-all @vindex hs-isearch-open @vindex hs-special-modes-alist - These variables exist for customizing Hideshow mode. + These variables can be used to customize Hideshow mode: @table @code @item hs-hide-comments-when-hiding-all -Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. +If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides +comments too. @item hs-isearch-open -Specifies what kind of hidden blocks incremental search should make -visible. The value should be one of these four symbols: - -@table @code -@item code -Open only code blocks. -@item comment -Open only comments. -@item t -Open both code blocks and comments. -@item nil -Open neither code blocks nor comments. -@end table - -@item hs-special-modes-alist -A list of elements, each specifying how to initialize Hideshow -variables for one major mode. See the variable's documentation string -for more information. +This variable specifies the conditions under which incremental search +should unhide a hidden block when matching text occurs within the +block. Its value should be either @code{code} (unhide only code +blocks), @code{comment} (unhide only comments), @code{t} (unhide both +code blocks and comments), or @code{nil} (unhide neither code blocks +nor comments). The default value is @code{code}. @end table @node Symbol Completion @section Completion for Symbol Names @cindex completion (symbol names) - In Emacs, completion is something you normally do in the minibuffer -(@pxref{Completion}). But one kind of completion is available in all -buffers: completion for symbol names. + Completion is normally done in the minibuffer (@pxref{Completion}), +but you can also complete symbol names in ordinary Emacs buffers. @kindex M-TAB - The character @kbd{M-@key{TAB}} runs a command to complete the -partial symbol before point against the set of meaningful symbol -names. This command inserts at point any additional characters that -it can determine from the partial name. - - If your window manager defines @kbd{M-@key{TAB}} to switch windows, -you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. -However, most window managers let you customize these shortcuts, so -you can change any that interfere with the way you use Emacs. - - If the partial name in the buffer has multiple possible completions -that differ in the very next character, so that it is impossible to -complete even one more character, @kbd{M-@key{TAB}} displays a list of -all possible completions in another window. +@kindex C-M-i + In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}} +to complete the partial symbol before point. On graphical displays, +the @kbd{M-@key{TAB}} key is usually reserved by the window manager +for switching graphical windows, so you should type @kbd{C-M-i} or +@kbd{@key{ESC} @key{TAB}} instead. @cindex tags-based completion -@cindex Info index completion -@findex complete-symbol - In most programming language major modes, @kbd{M-@key{TAB}} runs the -command @code{complete-symbol}, which provides two kinds of completion. -Normally it does completion based on a tags table (@pxref{Tags}); with a -numeric argument (regardless of the value), it does completion based on -the names listed in the Info file indexes for your language. Thus, to -complete the name of a symbol defined in your own program, use -@kbd{M-@key{TAB}} with no argument; to complete the name of a standard -library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based -completion works only if there is an Info file for the standard library -functions of your language, and only if it is installed at your site. + In-buffer symbol completion generates its completion list in a +number of different ways. If Semantic mode is enabled, Emacs tries to +use the Semantic parser data for completion (@pxref{Semantic}). If +Semantic mode is not enabled or it fails at performing completion, +Emacs normally tries to complete using a tags table (@pxref{Tags}). @cindex Lisp symbol completion @cindex completion (Lisp symbols) -@findex lisp-complete-symbol - In Emacs-Lisp mode, the name space for completion normally consists of -nontrivial symbols present in Emacs---those that have function -definitions, values or properties. However, if there is an -open-parenthesis immediately before the beginning of the partial symbol, -only symbols with function definitions are considered as completions. -The command which implements this is @code{lisp-complete-symbol}. + In Emacs Lisp mode, completion is performed using the function, +variable, and property names defined in the current Emacs session. If +there is an open parenthesis immediately before the beginning of the +partial symbol, only symbols with function definitions are considered. + + In all other respects, in-buffer symbol completion behaves like +minibuffer completion. For instance, if Emacs cannot complete to a +unique symbol, it displays a list of completion alternatives in +another window. @xref{Completion}. In Text mode and related modes, @kbd{M-@key{TAB}} completes words based on the spell-checker's dictionary. @xref{Spelling}. @@ -1379,20 +1307,20 @@ based on the spell-checker's dictionary. @xref{Spelling}. @node Glasses @section Glasses minor mode @cindex Glasses mode -@cindex identifiers, making long ones readable -@cindex StudlyCaps, making them readable -@findex glasses-mode - - Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} -readable by altering the way they display. It knows two different -ways to do this: by displaying underscores between a lower-case letter -and the following capital letter, and by emboldening the capital -letters. It does not alter the buffer text, only the way they -display, so you can use it even on read-only buffers. You can use the -command @kbd{M-x glasses-mode} to enable or disable the mode in the -current buffer; you can also add @code{glasses-mode} to the mode hook -of the programming language major modes in which you normally want -to use Glasses mode. +@cindex camel case +@findex mode, Glasses + + Glasses mode is a buffer-local minor mode that makes it easier to +read mixed-case (or ``CamelCase'') symbols like +@samp{unReadableSymbol}, by altering how they are displayed. By +default, it displays extra underscores between each lower-case letter +and the following capital letter. This does not alter the buffer +text, only how it is displayed. + + To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor +Modes}). When Glasses mode is enabled, the minor mode indicator +@samp{o^o} appears in the mode line. For more information about +Glasses mode, type @kbd{C-h P glasses @key{RET}}. @node Semantic @section Semantic @@ -1400,23 +1328,24 @@ to use Glasses mode. Semantic is a package that provides language-aware editing commands based on @code{source code parsers}. This section provides a brief -description of Semantic; +description of Semantic; for full details, @ifnottex -for full details, see @ref{Top, Semantic,, semantic, Semantic}. +see @ref{Top, Semantic,, semantic, Semantic}. @end ifnottex @iftex -for full details, type @kbd{C-h i} (@code{info}) and then select the -Semantic manual. +see the Semantic Info manual, which is distributed with Emacs. @end iftex - Most of the ``language aware'' features in Emacs, such as font lock -(@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular + Most of the ``language aware'' features in Emacs, such as Font Lock +mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular expressions and syntax tables.} that usually give good results but are never completely exact. In contrast, the parsers used by Semantic have an exact understanding of programming language syntax. This allows Semantic to provide search, navigation, and completion commands that are powerful and precise. +@cindex Semantic mode +@cindex mode, Semantic To begin using Semantic, type @kbd{M-x semantic-mode} or click on the menu item named @samp{Source Code Parsers (Semantic)} in the @samp{Tools} menu. This enables Semantic mode, a global minor mode. @@ -1464,30 +1393,30 @@ is idle. @node Misc for Programs @section Other Features Useful for Editing Programs - A number of Emacs commands that aren't designed specifically for -editing programs are useful for that nonetheless. + Some Emacs commands that aren't designed specifically for editing +programs are useful for that nonetheless. The Emacs commands that operate on words, sentences and paragraphs are useful for editing code. Most symbols names contain words -(@pxref{Words}); sentences can be found in strings and comments -(@pxref{Sentences}). Paragraphs in the strict sense can be found in -program code (in long comments), but the paragraph commands are useful -in other places too, because programming language major modes define -paragraphs to begin and end at blank lines (@pxref{Paragraphs}). -Judicious use of blank lines to make the program clearer will also -provide useful chunks of text for the paragraph commands to work on. -Auto Fill mode, if enabled in a programming language major mode, -indents the new lines which it creates. - - The selective display feature is useful for looking at the overall -structure of a function (@pxref{Selective Display}). This feature -hides the lines that are indented more than a specified amount. -Programming modes often support Outline minor mode (@pxref{Outline -Mode}). The Foldout package provides folding-editor features -(@pxref{Foldout}). - +(@pxref{Words}), while sentences can be found in strings and comments +(@pxref{Sentences}). As for paragraphs, they are defined in most +programming language modes to begin and end at blank lines +(@pxref{Paragraphs}). Therefore, judicious use of blank lines to make +the program clearer will also provide useful chunks of text for the +paragraph commands to work on. Auto Fill mode, if enabled in a +programming language major mode, indents the new lines which it +creates. + + Apart from Hideshow mode (@pxref{Hideshow}), another way to +selectively display parts of a program is to use the selective display +feature (@pxref{Selective Display}). Programming modes often also +support Outline minor mode (@pxref{Outline Mode}), which can be used +with the Foldout package (@pxref{Foldout}). + +@ifinfo The ``automatic typing'' features may be useful for writing programs. @xref{Top,,Autotyping, autotype, Autotyping}. +@end ifinfo @node C Modes @section C and Related Modes @@ -1509,9 +1438,14 @@ Mode}). The Foldout package provides folding-editor features This section gives a brief description of the special features available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. -(These are called ``C mode and related modes.'') @xref{Top, , CC Mode, -ccmode, CC Mode}, for a more extensive description of these modes -and their special features. +(These are called ``C mode and related modes.'') +@ifinfo +@xref{Top,, CC Mode, ccmode, CC Mode}, for more details. +@end ifinfo +@ifnotinfo +For more details, see the CC mode Info manual, which is distributed +with Emacs. +@end ifnotinfo @menu * Motion in C:: Commands to move by C statements, etc. diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index 71c23655608..d05af468fa1 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) @@ -1324,17 +1340,18 @@ included in GNU mailutils (the ``mailutils version,'' command line syntax and the same basic subset of options. However, the Mailutils version offers additional features. - The Emacs version of @code{movemail} is able to retrieve mail from the -usual UNIX mailbox formats and from remote mailboxes using the POP3 -protocol. + The Emacs version of @code{movemail} is able to retrieve mail from +the usual Unix mailbox formats and from remote mailboxes using the +POP3 protocol. The Mailutils version is able to handle a wide set of mailbox -formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH} -mailboxes, etc. It is able to access remote mailboxes using the POP3 or -IMAP4 protocol, and can retrieve mail from them using a TLS encrypted -channel. It also accepts mailbox arguments in @acronym{URL} form. -The detailed description of mailbox @acronym{URL}s can be found in -@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL} is: +formats, such as plain Unix mailboxes, @code{maildir} and @code{MH} +mailboxes, etc. It is able to access remote mailboxes using the POP3 +or IMAP4 protocol, and can retrieve mail from them using a TLS +encrypted channel. It also accepts mailbox arguments in @acronym{URL} +form. The detailed description of mailbox @acronym{URL}s can be found +in @ref{URL,,,mailutils,Mailbox URL Formats}. In short, a +@acronym{URL} is: @smallexample @var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name} @@ -1365,9 +1382,9 @@ local mailbox. @table @code @item mbox -Usual UNIX mailbox format. In this case, neither @var{user} nor -@var{pass} are used, and @var{host-or-file-name} denotes the file name of -the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. +Usual Unix mailbox format. In this case, neither @var{user} nor +@var{pass} are used, and @var{host-or-file-name} denotes the file name +of the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. @item mh A local mailbox in the @acronym{MH} format. @var{User} and @@ -1508,7 +1525,7 @@ use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}. @section Retrieving Mail from Local Mailboxes in Various Formats If your incoming mail is stored on a local machine in a format other -than UNIX mailbox, you will need the Mailutils @code{movemail} to +than Unix mailbox, you will need the Mailutils @code{movemail} to retrieve it. @xref{Movemail}, for the detailed description of @code{movemail} versions. For example, to access mail from a inbox in @code{maildir} format located in @file{/var/spool/mail/in}, you would diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 562ce92d427..c27a2c2936d 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -32,10 +32,14 @@ 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 +@ifinfo +(@pxref{Top,The nXML Mode Manual,,nxml-mode, nXML Mode}); +@end ifinfo +@ifnotinfo +(see the nXML mode Info manual, which is distributed with Emacs); +@end ifnotinfo +and Groff and Nroff (@pxref{Nroff Mode}). @cindex ASCII art If you need to edit pictures made out of text characters (commonly @@ -48,13 +52,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 +73,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 +83,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 +162,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 +189,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 +216,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 +233,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 +245,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 +265,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 +282,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 +364,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 +408,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 +422,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 +435,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 +490,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 +516,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 +538,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 +567,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 +595,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 +656,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 +754,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 +797,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 +808,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 +861,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 +897,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 +912,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 +1000,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 +1011,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 +1067,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 +1244,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 +1291,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 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 +1357,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 +1368,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 +1392,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 +1411,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 +1425,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 +1485,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 +1539,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 +1552,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 +1657,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,35 +1759,50 @@ 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}). +@ifinfo +nXML mode is described in its own manual: @xref{Top, nXML +Mode,,nxml-mode, nXML Mode}. +@end ifinfo +@ifnotinfo +nXML mode is described in an Info manual, which is distributed with +Emacs. +@end ifnotinfo @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 @cindex nroff @findex nroff-mode - Nroff mode is a mode like Text mode but modified to handle nroff commands -present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It -differs from Text mode in only a few ways. All nroff command lines are -considered paragraph separators, so that filling will never garble the -nroff commands. Pages are separated by @samp{.bp} commands. Comments -start with backslash-doublequote. Also, three special commands are -provided that are not in Text mode: +@vindex nroff-mode-hook + Nroff mode is a major mode derived from Text mode, which is +specialized for editing nroff files (e.g.@: Unix man pages). Type +@kbd{M-x nroff-mode} to enter this mode. Entering Nroff mode runs the +hook @code{text-mode-hook}, followed by @code{nroff-mode-hook} +(@pxref{Hooks}). + + In Nroff mode, nroff command lines are treated as paragraph +separators, pages are separated by @samp{.bp} commands, and comments +start with backslash-doublequote. It also defines these commands: @findex forward-text-line @findex backward-text-line @@ -1812,104 +1822,95 @@ nroff commands) in the region (@code{count-text-lines}). @end table @findex electric-nroff-mode - The other feature of Nroff mode is that you can turn on Electric Nroff -mode. This is a minor mode that you can turn on or off with @kbd{M-x + Electric Nroff mode is a buffer-local minor mode that can be used +with Nroff mode. To toggle this minor mode, type @kbd{M-x electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each -time you use @key{RET} to end a line that contains an nroff command that -opens a kind of grouping, the matching nroff command to close that -grouping is automatically inserted on the following line. For example, -if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}}, -this inserts the matching command @samp{.)b} on a new line following -point. +time you type @key{RET} to end a line containing an nroff command that +opens a kind of grouping, the nroff command to close that grouping is +automatically inserted on the following line. - If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}), -heading lines are lines of the form @samp{.H} followed by a number (the -header level). - -@vindex nroff-mode-hook - 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 + If you use Outline minor mode with Nroff mode (@pxref{Outline +Mode}), heading lines are lines of the form @samp{.H} followed by a +number (the header level). +@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 +1919,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 +1965,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 +2077,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,149 +2098,75 @@ 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. - - 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 + 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}. - 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 not saved +in the @samp{text/enriched} format. @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 -text-based tables. Here is an example of such a table: + The @code{table} package provides commands to easily edit text-based +tables. Here is an example of what such a table looks like: @smallexample @group @@ -2355,27 +2176,23 @@ text-based tables. Here is an example of such a table: | forward-char |Move point right N characters | C-f | | |(left if N is negative). | | | | | | -| |On reaching end of buffer, stop | | -| |and signal error. | | +-----------------+--------------------------------+-----------------+ | backward-char |Move point left N characters | C-b | | |(right if N is negative). | | | | | | -| |On attempt to pass beginning or | | -| |end of buffer, stop and signal | | -| |error. | | +-----------------+--------------------------------+-----------------+ @end group @end smallexample - Table mode allows the contents of the table such as this one to be -easily manipulated by inserting or deleting characters inside a cell. -A cell is effectively a localized rectangular edit region and edits to -a cell do not affect the contents of the surrounding cells. If the -contents do not fit into a cell, then the cell is automatically -expanded in the vertical and/or horizontal directions and the rest of -the table is restructured and reformatted in accordance with the -growth of the cell. + When Emacs recognizes such a stretch of text as a table +(@pxref{Table Recognition}), editing the contents of each table cell +will automatically resize the table, whenever the contents become too +large to fit in the cell. You can use the commands defined in the +following sections for navigating and editing the table layout. + +@findex table-fixed-width-mode + To toggle the automatic table resizing feature, type @kbd{M-x +table-fixed-width-mode}. @menu * Table Definition:: What is a text based table. @@ -2383,102 +2200,87 @@ growth of the cell. * Table Recognition:: How to activate and deactivate tables. * Cell Commands:: Cell-oriented commands in a table. * Cell Justification:: Justifying cell contents. -* Row Commands:: Manipulating rows of table cell. -* Column Commands:: Manipulating columns of table cell. -* Fixed Width Mode:: Fixing cell width. +* Table Rows and Columns:: Inserting and deleting rows and columns. * Table Conversion:: Converting between plain text and tables. -* Measuring Tables:: Analyzing table dimension. * Table Misc:: Table miscellany. @end menu @node Table Definition @subsection What is a Text-based Table? +@cindex cells, for text-based tables - Keep the following examples of valid tables in mind as a reference -while you read this section: - -@example - +--+----+---+ +-+ +--+-----+ - | | | | | | | | | - +--+----+---+ +-+ | +--+--+ - | | | | | | | | - +--+----+---+ +--+--+ | - | | | - +-----+--+ -@end example - - A table consists of a rectangular frame whose inside is divided into -cells. Each cell must be at least one character wide and one -character high, not counting its border lines. A cell can be -subdivided into multiple rectangular cells, but cells cannot overlap. + A @dfn{table} consists of a rectangular text area which is divided +into @dfn{cells}. Each cell must be at least one character wide and +one character high, not counting its border lines. A cell can be +subdivided into more cells, but they cannot overlap. - The table frame and cell border lines are made of three special -characters. These variables specify those characters: + Cell border lines are drawn with three special characters, specified +by the following variables: @table @code @vindex table-cell-vertical-char @item table-cell-vertical-char -Holds the character used for vertical lines. The default value is -@samp{|}. +The character used for vertical lines. The default is @samp{|}. @vindex table-cell-horizontal-chars @item table-cell-horizontal-chars -Holds the characters used for horizontal lines. The default value is -@samp{"-="}. +The characters used for horizontal lines. The default is @samp{"-="}. @vindex table-cell-intersection-char @item table-cell-intersection-char -Holds the character used at where horizontal line and vertical line -meet. The default value is @samp{+}. +The character used for the intersection of horizontal and vertical +lines. The default is @samp{+}. @end table @noindent -Based on this definition, the following five tables are examples of invalid -tables: +The following are examples of @emph{invalid} tables: @example - +-----+ +-----+ +--+ +-++--+ ++ - | | | | | | | || | ++ - | +-+ | | | | | | || | - | | | | +--+ | +--+--+ +-++--+ - | +-+ | | | | | | | +-++--+ - | | | | | | | | | || | - +-----+ +--+--+ +--+--+ +-++--+ - a b c d e + +-----+ +--+ +-++--+ + | | | | | || | + | | | | | || | + +--+ | +--+--+ +-++--+ + | | | | | | +-++--+ + | | | | | | | || | + +--+--+ +--+--+ +-++--+ + a b c @end example +@noindent From left to right: @enumerate a @item Overlapped cells or non-rectangular cells are not allowed. @item -Same as a. -@item The border must be rectangular. @item Cells must have a minimum width/height of one character. -@item -Same as d. @end enumerate @node Table Creation -@subsection How to Create a Table? +@subsection Creating a Table @cindex create a text-based table @cindex table creation @findex table-insert - The command to create a table is @code{table-insert}. When called -interactively, it asks for the number of columns, number of rows, cell -width and cell height. The number of columns is the number of cells -horizontally side by side. The number of rows is the number of cells -vertically within the table's height. The cell width is a number of -characters that each cell holds, left to right. The cell height is a -number of lines each cell holds. The cell width and the cell height -can be either an integer (when the value is constant across the table) -or a series of integer, separated by spaces or commas, where each -number corresponds to the next cell within a row from left to right, -or the next cell within a column from top to bottom. + To create a text-based table from scratch, type @kbd{M-x +table-insert}. This command prompts for the number of table columns, +the number of table rows, cell width and cell height. The cell width +and cell height do not include the cell borders; each can be specified +as a single integer (which means each cell is given the same +width/height), or as a sequence of integers separated by spaces or +commas (which specify the width/height of the individual table +columns/rows, counting from left to right for table columns and from +top to bottom for table rows). The specified table is then inserted +at point. + + The table inserted by @kbd{M-x table-insert} contains special text +properties, which tell Emacs to treat it specially as a text-based +table. If you save the buffer to a file and visit it again later, +those properties are lost, and the table appears to Emacs as an +ordinary piece of text. See the next section, for how to convert it +back into a table. @node Table Recognition @subsection Table Recognition @@ -2486,103 +2288,97 @@ or the next cell within a column from top to bottom. @findex table-recognize @findex table-unrecognize - Table mode maintains special text properties in the buffer to allow -editing in a convenient fashion. When a buffer with tables is saved -to its file, these text properties are lost, so when you visit this -file again later, Emacs does not see a table, but just formatted text. -To resurrect the table text properties, issue the @kbd{M-x -table-recognize} command. It scans the current buffer, recognizes -valid table cells, and attaches appropriate text properties to allow -for table editing. The converse command, @code{table-unrecognize}, is -used to remove the special text properties and convert the buffer back -to plain text. - - Special commands exist to enable or disable tables within a region, -enable or disable individual tables, and enable/disable individual -cells. These commands are: + Existing text-based tables in a buffer, which lack the special text +properties applied by @kbd{M-x table-insert}, are not treated +specially as tables. To apply those text properties, type @kbd{M-x +table-recognize}. This command scans the current buffer, +@dfn{recognizes} valid table cells, and applies the relevant text +properties. Conversely, type @kbd{M-x table-unrecognize} to +@dfn{unrecognize} all tables in the current buffer, removing the +special text properties and converting tables back to plain text. + + You can also use the following commands to selectively recognize or +unrecognize tables: @table @kbd @findex table-recognize-region @item M-x table-recognize-region -Recognize tables within the current region and activate them. +Recognize tables within the current region. + @findex table-unrecognize-region @item M-x table-unrecognize-region -Deactivate tables within the current region. +Unrecognize tables within the current region. + @findex table-recognize-table @item M-x table-recognize-table Recognize the table at point and activate it. + @findex table-unrecognize-table @item M-x table-unrecognize-table Deactivate the table at point. + @findex table-recognize-cell @item M-x table-recognize-cell Recognize the cell at point and activate it. + @findex table-unrecognize-cell @item M-x table-unrecognize-cell Deactivate the cell at point. @end table - For another way of converting text into tables, see @ref{Table -Conversion}. + @xref{Table Conversion}, for another way to recognize a table. @node Cell Commands @subsection Commands for Table Cells @findex table-forward-cell @findex table-backward-cell - The commands @code{table-forward-cell} and -@code{table-backward-cell} move point from the current cell to an -adjacent cell forward and backward respectively. The order of the -cells is cyclic: when point is in the last cell of a table, typing -@kbd{M-x table-forward-cell} moves to the first cell in the table. -Likewise @kbd{M-x table-backward-cell} from the first cell in a table -moves to the last cell. + The commands @kbd{M-x table-forward-cell} and @kbd{M-x +table-backward-cell} move point from the current cell to an adjacent +cell. The order is cyclic: when point is in the last cell of a table, +@kbd{M-x table-forward-cell} moves to the first cell. Likewise, when +point is on the first cell, @kbd{M-x table-backward-cell} moves to the +last cell. @findex table-span-cell - The command @code{table-span-cell} merges the current cell with the -adjacent cell in a specified direction---right, left, above or below. -You specify the direction with the minibuffer. It does not allow -merges which don't result in a legitimate cell layout. + @kbd{M-x table-span-cell} prompts for a direction---right, left, +above, or below---and merges the current cell with the adjacent cell +in that direction. This command signals an error if the merge would +result in an illegitimate cell layout. @findex table-split-cell -@cindex text-based tables, split a cell -@cindex split table cell - The command @code{table-split-cell} splits the current cell -vertically or horizontally. This command is a wrapper to the -direction specific commands @code{table-split-cell-vertically} and -@code{table-split-cell-horizontally}. You specify the direction with -a minibuffer argument. - @findex table-split-cell-vertically - The command @code{table-split-cell-vertically} splits the current -cell vertically and creates a pair of cells above and below where -point is located. The content in the original cell is split as well. - @findex table-split-cell-horizontally - The command @code{table-split-cell-horizontally} splits the current -cell horizontally and creates a pair of cells right and left of where -point is located. If the cell being split is not empty, this asks you -how to handle the cell contents. The three options are: @code{split}, -@code{left}, or @code{right}. @code{split} splits the contents at -point literally, while the @code{left} and @code{right} options move -the entire contents into the left or right cell respectively. - -@cindex enlarge a table cell -@cindex shrink a table cell - The next four commands enlarge or shrink a cell. They use numeric -arguments (@pxref{Arguments}) to specify how many columns or rows to -enlarge or shrink a particular table. +@cindex text-based tables, splitting cells +@cindex splitting table cells + @kbd{M-x table-split-cell} splits the current cell vertically or +horizontally, prompting for the direction with the minibuffer. The +commands @kbd{M-x table-split-cell-vertically} and @kbd{M-x +table-split-cell-horizontally} split in a specific direction. When +splitting vertically, the old cell contents are automatically split +between the two new cells. When splitting horizontally, you are +prompted for how to divide the cell contents, if the cell is +non-empty; the options are @samp{split} (divide the contents at +point), @samp{left} (put all the contents in the left cell), and +@samp{right} (put all the contents in the right cell). + + The following commands enlarge or shrink a cell. By default, they +resize by one row or column; if a numeric argument is supplied, that +specifies the number of rows or columns to resize by. @table @kbd @findex table-heighten-cell @item M-x table-heighten-cell Enlarge the current cell vertically. + @findex table-shorten-cell @item M-x table-shorten-cell Shrink the current cell vertically. + @findex table-widen-cell @item M-x table-widen-cell Enlarge the current cell horizontally. + @findex table-narrow-cell @item M-x table-narrow-cell Shrink the current cell horizontally. @@ -2590,107 +2386,76 @@ Shrink the current cell horizontally. @node Cell Justification @subsection Cell Justification -@cindex cell text justification +@cindex justification in text-based tables - You can specify text justification for each cell. The justification -is remembered independently for each cell and the subsequent editing -of cell contents is subject to the specified justification. + The command @kbd{M-x table-justify} imposes @dfn{justification} on +one or more cells in a text-based table. Justification determines how +the text in the cell is aligned, relative to the edges of the cell. +Each cell in a table can be separately justified. @findex table-justify - The command @code{table-justify} ask you to specify what to justify: -a cell, a column, or a row. If you select cell justification, this -command sets the justification only for the current cell. Selecting -column or row justification sets the justification for all the cells -within a column or row respectively. The command then ask you which -kind of justification to apply: @code{left}, @code{center}, -@code{right}, @code{top}, @code{middle}, @code{bottom}, or -@code{none}. Horizontal justification and vertical justification are -specified independently. The options @code{left}, @code{center}, and -@code{right} specify horizontal justification while the options -@code{top}, @code{middle}, @code{bottom}, and @code{none} specify -vertical justification. The vertical justification @code{none} -effectively removes vertical justification. Horizontal justification -must be one of @code{left}, @code{center}, or @code{right}. + @kbd{M-x table-justify} first prompts for what to justify; the +options are @samp{cell} (just the current cell), @samp{column} (all +cells in the current table column) and @samp{row} (all cells in the +current table row). The command then prompts for the justification +style; the options are @code{left}, @code{center}, @code{right}, +@code{top}, @code{middle}, @code{bottom}, or @code{none} (meaning no +vertical justification). + + Horizontal and vertical justification styles are specified +independently, and both types can be in effect simultaneously; for +instance, you can call @kbd{M-x table-justify} twice, once to specify +@code{right} justification and once to specify @code{bottom} +justification, to align the contents of a cell to the bottom right. @vindex table-detect-cell-alignment - Justification information is stored in the buffer as a part of text -property. Therefore, this information is ephemeral and does not -survive through the loss of the buffer (closing the buffer and -revisiting the buffer erase any previous text properties). To -countermand for this, the command @code{table-recognize} and other -recognition commands (@pxref{Table Recognition}) are equipped with a -convenience feature (turned on by default). During table recognition, -the contents of a cell are examined to determine which justification -was originally applied to the cell and then applies this justification -to the cell. This is a speculative algorithm and is therefore not -perfect, however, the justification is deduced correctly most of the -time. To disable this feature, customize the variable -@code{table-detect-cell-alignment} and set it to @code{nil}. - -@node Row Commands -@subsection Commands for Table Rows -@cindex table row commands - -@cindex insert row in table + The justification style is stored in the buffer as a text property, +and is lost when you kill the buffer or exit Emacs. However, the +table recognition commands, such as @kbd{M-x table-recognize} +(@pxref{Table Recognition}), attempt to determine and re-apply each +cell's justification style, by examining its contents. To disable +this feature, change the variable @code{table-detect-cell-alignment} +to @code{nil}. + +@node Table Rows and Columns +@subsection Table Rows and Columns +@cindex inserting rows and columns in text-based tables + @findex table-insert-row - The command @code{table-insert-row} inserts a row of cells before -the current row in a table. The current row where point is located is -pushed down after the newly inserted row. A numeric prefix argument -specifies the number of rows to insert. Note that in order to insert -rows @emph{after} the last row at the bottom of a table, you must -place point below the table---that is, outside the table---prior to -invoking this command. - -@cindex delete row in table -@findex table-delete-row - The command @code{table-delete-row} deletes a row of cells at point. -A numeric prefix argument specifies the number of rows to delete. - -@node Column Commands -@subsection Commands for Table Columns -@cindex table column commands - -@cindex insert column in table -@findex table-insert-column - The command @code{table-insert-column} inserts a column of cells to -the left of the current row in a table. This pushes the current -column to the right. To insert a column to the right side of the -rightmost column, place point to the right of the rightmost column, -which is outside of the table, prior to invoking this command. A -numeric prefix argument specifies the number of columns to insert. - -@cindex delete column in table - A command @code{table-delete-column} deletes a column of cells at -point. A numeric prefix argument specifies the number of columns to -delete. - -@node Fixed Width Mode -@subsection Fix Width of Cells -@cindex fix width of table cells + @kbd{M-x table-insert-row} inserts a row of cells before the current +table row. The current row, together with point, is pushed down past +the new row. To insert rows after the last row at the bottom of a +table, invoke this command with point below the table, just below the +bottom edge. A numeric prefix argument specifies the number of rows +to insert. -@findex table-fixed-width-mode - The command @code{table-fixed-width-mode} toggles fixed width mode -on and off. When fixed width mode is turned on, editing inside a -cell never changes the cell width; when it is off, the cell width -expands automatically in order to prevent a word from being folded -into multiple lines. By default, fixed width mode is disabled. +@findex table-insert-column + Similarly, @kbd{M-x table-insert-column} inserts a column of cells +to the left of the current table column. To insert a column to the +right side of the rightmost column, invoke this command with point to +the right of the rightmost column, outside the table. A numeric +prefix argument specifies the number of columns to insert. + +@cindex deleting rows and column in text-based tables + @kbd{M-x table-delete-column} deletes the column of cells at point. +Similarly, @kbd{M-x table-delete-row} deletes the row of cells at +point. A numeric prefix argument to either command specifies the +number of columns or rows to delete. @node Table Conversion -@subsection Conversion Between Plain Text and Tables +@subsection Converting Between Plain Text and Tables @cindex text to table @cindex table to text @findex table-capture - The command @code{table-capture} captures plain text in a region and -turns it into a table. Unlike @code{table-recognize} (@pxref{Table -Recognition}), the original text does not have a table appearance but -may hold a logical table structure. For example, some elements -separated by known patterns form a two dimensional structure which can -be turned into a table. + The command @kbd{M-x table-capture} captures plain text in a region +and turns it into a table. Unlike @kbd{M-x table-recognize} +(@pxref{Table Recognition}), the original text does not need to have a +table appearance; it only needs to have a logical table-like +structure. - Here's an example of data that @code{table-capture} can operate on. -The numbers are horizontally separated by a comma and vertically -separated by a newline character. + For example, suppose we have the following numbers, which are +divided into three lines and separated horizontally by commas: @example 1, 2, 3, 4 @@ -2711,136 +2476,92 @@ Invoking @kbd{M-x table-capture} on that text produces this table: +-----+-----+-----+-----+ @end example -@noindent -The conversion uses @samp{,} for the column delimiter and newline for -a row delimiter, cells are left justified, and minimum cell width is -5. - @findex table-release - The command @code{table-release} does the opposite of -@code{table-capture}. It releases a table by removing the table frame -and cell borders. This leaves the table contents as plain text. One -of the useful applications of @code{table-capture} and -@code{table-release} is to edit a text in layout. Look at the -following three paragraphs (the latter two are indented with header -lines): + @kbd{M-x table-release} does the opposite: it converts a table back +to plain text, removing its cell borders. + + One application of this pair of commands is to edit a text in +layout. Look at the following three paragraphs (the latter two are +indented with header lines): @example table-capture is a powerful command. Here are some things it can do: -Parse Cell Items By using column delimiter regular - expression and raw delimiter regular - expression, it parses the specified text - area and extracts cell items from - non-table text and then forms a table out - of them. - -Capture Text Area When no delimiters are specified it - creates a single cell table. The text in - the specified region is placed in that - cell. +Parse Cell Items Using row and column delimiter regexps, + it parses the specified text area and + extracts cell items into a table. @end example @noindent -Applying @code{table-capture} to a region containing the above three -paragraphs, with empty strings for column delimiter regexp and row -delimiter regexp, creates a table with a single cell like the -following one. - -@c The first line's right-hand frame in the following two examples -@c sticks out to accommodate for the removal of @samp in the -@c produced output!! +Applying @code{table-capture} to a region containing the above text, +with empty strings for the column and row delimiter regexps, creates a +table with a single cell like the following one. + @smallexample @group -+-------------------------------------------------------------+ -|table-capture is a powerful command. | -|Here are some things it can do: | -| | -|Parse Cell Items By using column delimiter regular | -| expression and raw delimiter regular | -| expression, it parses the specified text | -| area and extracts cell items from | -| non-table text and then forms a table out | -| of them. | -| | -|Capture Text Area When no delimiters are specified it | -| creates a single cell table. The text in | -| the specified region is placed in that | -| cell. | -+-------------------------------------------------------------+ ++----------------------------------------------------------+ +|table-capture is a powerful command. | +|Here are some things it can do: | +| | +|Parse Cell Items Using row and column delimiter regexps,| +| it parses the specified text area and | +| extracts cell items into a table. | ++----------------------------------------------------------+ @end group @end smallexample @noindent -By splitting the cell appropriately we now have a table consisting of -paragraphs occupying its own cell. Each cell can now be edited -independently without affecting the layout of other cells. +We can then use the cell splitting commands (@pxref{Cell Commands}) to +subdivide the table so that each paragraph occupies a cell: @smallexample -+--------------------------------------------------------------+ -|table-capture is a powerful command. | -|Here are some things it can do: | -+------------------+-------------------------------------------+ -|Parse Cell Items |By using column delimiter regular | -| |expression and raw delimiter regular | -| |expression, it parses the specified text | -| |area and extracts cell items from | -| |non-table text and then forms a table out | -| |of them. | -+------------------+-------------------------------------------+ -|Capture Text Area |When no delimiters are specified it | -| |creates a single cell table. The text in | -| |the specified region is placed in that | -| |cell. | -+------------------+-------------------------------------------+ ++----------------------------------------------------------+ +|table-capture is a powerful command. | +|Here are some things it can do: | ++-----------------+----------------------------------------+ +|Parse Cell Items | Using row and column delimiter regexps,| +| | it parses the specified text area and | +| | extracts cell items into a table. | ++-----------------+----------------------------------------+ @end smallexample @noindent -By applying @code{table-release}, which does the opposite process, the -contents become once again plain text. @code{table-release} works as -a companion command to @code{table-capture}. +Each cell can now be edited independently without affecting the layout +of other cells. When finished, we can invoke @kbd{M-x table-release} +to convert the table back to plain text. -@node Measuring Tables -@subsection Analyzing Table Dimensions -@cindex table dimensions +@node Table Misc +@subsection Table Miscellany +@cindex table dimensions @findex table-query-dimension - The command @code{table-query-dimension} analyzes a table structure -and reports information regarding its dimensions. In case of the -above example table, the @code{table-query-dimension} command displays -in echo area: + The command @code{table-query-dimension} reports the layout of the +table and table cell at point. Here is an example of its output: @smallexample Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5 @end smallexample @noindent -This indicates that the current cell is 21 character wide and 6 lines -high, the entire table is 67 characters wide and 16 lines high. The -table has 2 columns and 3 rows. It has a total of 5 cells, since the -first row has a spanned cell. - -@node Table Misc -@subsection Table Miscellany +This indicates that the current cell is 21 characters wide and 6 lines +high, the table is 67 characters wide and 16 lines high with 2 columns +and 3 rows, and a total of 5 cells. -@cindex insert string into table cells @findex table-insert-sequence - The command @code{table-insert-sequence} inserts a string into each -cell. Each string is a part of a sequence i.e.@: a series of -increasing integer numbers. + @kbd{M-x table-insert-sequence} inserts a string into each cell. +Each string is a part of a sequence i.e.@: a series of increasing +integer numbers. -@cindex table in language format @cindex table for HTML and LaTeX @findex table-generate-source - The command @code{table-generate-source} generates a table formatted -for a specific markup language. It asks for a language (which must be -one of @code{html}, @code{latex}, or @code{cals}), a destination -buffer where to put the result, and the table caption (a string), and -then inserts the generated table in the proper syntax into the -destination buffer. The default destination buffer is -@code{table.@var{lang}}, where @var{lang} is the language you -specified. + @kbd{M-x table-generate-source} generates a table formatted for a +specific markup language. It asks for a language (which must be one +of @code{html}, @code{latex}, or @code{cals}), a destination buffer in +which to put the result, and a table caption, and then inserts the +generated table into the specified buffer. The default destination +buffer is @code{table.@var{lang}}, where @var{lang} is the language +you specified. @node Two-Column @section Two-Column Editing @@ -2848,11 +2569,9 @@ specified. @cindex splitting columns @cindex columns, splitting - Two-column mode lets you conveniently edit two side-by-side columns of -text. It uses two side-by-side windows, each showing its own -buffer. - - There are three ways to enter two-column mode: + Two-column mode lets you conveniently edit two side-by-side columns +of text. It uses two side-by-side windows, each showing its own +buffer. There are three ways to enter two-column mode: @table @asis @item @kbd{@key{F2} 2} or @kbd{C-x 6 2} diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index ad2040c9047..6a6f7b1a4d7 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -34,11 +34,11 @@ has its own value of point. @cindex selected window At any time, one Emacs window is the @dfn{selected window}; the -buffer this window is displaying is the current buffer. Each window -has its own value of point. On graphical displays, the point is -indicated by a solid blinking cursor in the selected window, and by a -hollow box in non-selected windows. On text-only terminals, the -cursor is drawn only in the selected window. @xref{Cursor Display}. +buffer this window is displaying is the current buffer. On graphical +displays, the point is indicated by a solid blinking cursor in the +selected window, and by a hollow box in non-selected windows. On +text-only terminals, the cursor is drawn only in the selected window. +@xref{Cursor Display}. Commands to move point affect the value of point for the selected Emacs window only. They do not change the value of point in other @@ -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. diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog index bdcd9e9aea8..6cede6375f2 100644 --- a/doc/lispintro/ChangeLog +++ b/doc/lispintro/ChangeLog @@ -1,3 +1,7 @@ +2011-11-24 Juanma Barranquero <lekktu@gmail.com> + + * makefile.w32-in: Update dependencies. + 2011-11-16 Juanma Barranquero <lekktu@gmail.com> * emacs-lisp-intro.texi (etags): Fix typo. diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index ef04626e95f..23d0d5a8f34 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -887,7 +887,7 @@ but in this case, it is best to treat it as a novel or as a travel guide to a country not yet visited: interesting, but not the same as being there. -Much of this introduction is dedicated to walk-throughs or guided tours +Much of this introduction is dedicated to walkthroughs or guided tours of code used in GNU Emacs. These tours are designed for two purposes: first, to give you familiarity with real, working code (code you use every day); and, second, to give you familiarity with the way Emacs @@ -1401,7 +1401,7 @@ This is a harmless activity; and indeed, we will often try to generate error messages intentionally. Once you understand the jargon, error messages can be informative. Instead of being called ``error'' messages, they should be called ``help'' messages. They are like -signposts to a traveller in a strange country; deciphering them can be +signposts to a traveler in a strange country; deciphering them can be hard, but once understood, they can point the way. The error message is generated by a built-in GNU Emacs debugger. We @@ -2040,7 +2040,7 @@ the first argument. This function takes three arguments. Its first argument is the string of characters, the second and third arguments are numbers that indicate the beginning and end of the substring. The numbers are a count of the number of characters (including spaces and -punctuations) from the beginning of the string. +punctuation) from the beginning of the string. @need 800 For example, if you evaluate the following: diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in index 7294d46b693..06641cc2222 100644 --- a/doc/lispintro/makefile.w32-in +++ b/doc/lispintro/makefile.w32-in @@ -24,7 +24,7 @@ infodir = $(srcdir)/../../info # Directory with the (customized) texinfo.tex file. texinfodir = $(srcdir)/../misc -INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi +INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi $(srcdir)/doclicense.texi # The file name eintr must fit within 5 characters, to allow for # -NN extensions to fit into DOS 8+3 limits without clashing INFO_TARGETS = $(infodir)/eintr diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 0fa50492481..d620c9e3c4c 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,71 @@ +2011-12-05 Stefan Monnier <monnier@iro.umontreal.ca> + + * text.texi (Special Properties): Warn against `intangible' properties + (bug#10222). + +2011-11-26 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Truncation): + * text.texi (Special Properties): Describe what a stretch-glyph is + instead of using that term without explanation. Make the + cross-references more accurate. + + * display.texi (Usual Display): Update the description, + cross-references, and indexing related to display of control + characters and raw bytes. + +2011-11-25 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Splitting Windows): Fix description of + window-combination-limit. Suggested by Eli Zaretskii. + +2011-11-23 Chong Yidong <cyd@gnu.org> + + * windows.texi (Window Sizes): Move window-top-line, + window-left-column, and window-*-pixel-edges to Coordinates and + Windows node. + (Coordinates and Windows): Restore window-edges doc. + +2011-11-21 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Windows and Frames, Splitting Windows): + Fix typos. + +2011-11-21 Chong Yidong <cyd@gnu.org> + + * windows.texi (Splitting Windows): Fix error in documentation of + window-combination-limit. + (Cyclic Window Ordering): Minor fixes to next-window, + one-window-p, and get-lru-window docs. Don't document + window-list-1. + (Buffers and Windows): Copyedits. + (Choosing Window): Document special handling of special-display-*. + (Choosing Window Options): Fix display-buffer-reuse-frames doc. + Don't document even-window-heights, which is going away. + Clarify which options are obeyed by which action functions. + +2011-11-20 Stefan Monnier <monnier@iro.umontreal.ca> + + * display.texi (Invisible Text): Clarify point adjustment (bug#10072). + +2011-11-20 Martin Rudalics <rudalics@gmx.at> + + * windows.texi (Resizing Windows, Splitting Windows): + Remove term "status" when talking about combination limits. + +2011-11-20 Juanma Barranquero <lekktu@gmail.com> + + * compile.texi (Compiler Errors): + * help.texi (Help Functions): Fix typos. + +2011-11-19 Chong Yidong <cyd@gnu.org> + + * windows.texi (Splitting Windows): Clarify role of window + parameters in split-window. Shorten the example. + (Deleting Windows): Rewrite intro to handle internal windows. + Fix delete-windows-on doc. + (Selecting Windows): Copyedits. + 2011-11-17 Martin Rudalics <rudalics@gmx.at> * windows.texi (Resizing Windows, Splitting Windows) @@ -6,8 +74,8 @@ 2011-11-16 Martin Rudalics <rudalics@gmx.at> - * windows.texi (Resizing Windows, Splitting Windows): Rename - occurrences of window-nest to window-combination-limit. + * windows.texi (Resizing Windows, Splitting Windows): + Rename occurrences of window-nest to window-combination-limit. 2011-11-14 Juanma Barranquero <lekktu@gmail.com> @@ -15,8 +83,8 @@ 2011-11-12 Martin Rudalics <rudalics@gmx.at> - * windows.texi (Splitting Windows, Deleting Windows): Remove - references to splits status of windows. + * windows.texi (Splitting Windows, Deleting Windows): + Remove references to splits status of windows. 2011-11-10 Glenn Morris <rgm@gnu.org> @@ -68,8 +136,8 @@ (Windows and Frames): Various clarifications, e.g. non-live windows also belong to frames. Fix window-list description. Simplify window nesting example. - (Splitting Windows, Window Configurations): Use - split-window-below. + (Splitting Windows, Window Configurations): + Use split-window-below. 2011-11-04 Eli Zaretskii <eliz@gnu.org> @@ -119,8 +187,8 @@ 2011-10-05 Chong Yidong <cyd@stupidchicken.com> - * display.texi (Low-Level Font, Face Attributes, Font Lookup): Fix - Emacs manual xref (Bug#9675). + * display.texi (Low-Level Font, Face Attributes, Font Lookup): + Fix Emacs manual xref (Bug#9675). 2011-10-01 Chong Yidong <cyd@stupidchicken.com> @@ -159,8 +227,8 @@ * windows.texi (Window History): New node. Move text here from Buffers and Windows. (Switching Buffers): Rename from Displaying Buffers, since we - don't document display-buffer here; callers changed. Document - FORCE-SAME-WINDOW arg to switch-to-buffer and + don't document display-buffer here; callers changed. + Document FORCE-SAME-WINDOW arg to switch-to-buffer and switch-to-buffer-other-frame. Delete duplicate replace-buffer-in-windows doc. (Choosing Window): Document display actions. @@ -191,10 +259,10 @@ Provide examples. Describe window-nest and window-splits options. (Deleting Windows): Minor rewrite. - (Selecting Windows): Minor rewrite. Describe - frame-selected-window and set-frame-selected-window here. - (Cyclic Window Ordering): Minor rewrite. Describe - window-list-1. + (Selecting Windows): Minor rewrite. + Describe frame-selected-window and set-frame-selected-window here. + (Cyclic Window Ordering): Minor rewrite. + Describe window-list-1. (Buffers and Windows): Rewrite. Explain a window's previous and next buffers and the corresponding functions. (Window Tree): Merge into Windows and Frames section. @@ -296,8 +364,8 @@ * display.texi (Bidirectional Display): Document the pitfalls of concatenating strings with bidirectional content, with possible - solutions. Document bidi-string-mark-left-to-right. Mention - paragraph direction in modes that inherit from prog-mode. + solutions. Document bidi-string-mark-left-to-right. + Mention paragraph direction in modes that inherit from prog-mode. Document use of `bidi-class' and `mirroring' properties as part of reordering. @@ -353,8 +421,8 @@ the next character, and doesn't affect longer sequences in particular (bug#8935). - * debugging.texi (Using Debugger): Mention - @code{eval-expression-debug-on-error} (bug#8549). + * debugging.texi (Using Debugger): + Mention @code{eval-expression-debug-on-error} (bug#8549). 2011-07-14 Eli Zaretskii <eliz@gnu.org> @@ -503,7 +571,7 @@ 2011-06-15 Lars Magne Ingebrigtsen <larsi@gnus.org> - * processes.texi (Process Information): Renamed `process-alive-p' + * processes.texi (Process Information): Rename `process-alive-p' to `process-live-p' for consistency with other `-live-p' functions. 2011-06-03 Paul Eggert <eggert@cs.ucla.edu> @@ -520,8 +588,8 @@ 2011-05-31 Lars Magne Ingebrigtsen <larsi@gnus.org> - * processes.texi (Process Information): Document - `process-alive-p'. + * processes.texi (Process Information): + Document `process-alive-p'. 2011-05-29 Chong Yidong <cyd@stupidchicken.com> @@ -1919,8 +1987,8 @@ 2009-05-09 Eli Zaretskii <eliz@gnu.org> - * nonascii.texi (Default Coding Systems): Document - find-auto-coding, set-auto-coding, and auto-coding-alist. + * nonascii.texi (Default Coding Systems): + Document find-auto-coding, set-auto-coding, and auto-coding-alist. Add indexing. (Lisp and Coding Systems): Add index entries. @@ -2237,7 +2305,7 @@ (Future Local Variables): Node deleted. * objects.texi (General Escape Syntax): Update explanation of - unicode escape syntax. + Unicode escape syntax. 2009-02-23 Chong Yidong <cyd@stupidchicken.com> @@ -5151,8 +5219,8 @@ (Saving Buffers): Mention code and EOL conversions by file I/O primitives and subroutines. - * nonascii.texi (Lisp and Coding Systems): Document - coding-system-eol-type. Add index entries for eol conversion. + * nonascii.texi (Lisp and Coding Systems): + Document coding-system-eol-type. Add index entries for eol conversion. * display.texi (Defining Faces): Mention `mac', and add an xref to where window-system is described. @@ -9102,7 +9170,7 @@ * functions.texi (Defining Functions): Explain about redefining primitives. - (Function Safety): Renamed. Minor changes. + (Function Safety): Rename. Minor changes. Comment out the detailed criteria for what is safe. 2003-06-22 Andreas Schwab <schwab@suse.de> @@ -9603,7 +9671,7 @@ * Makefile (infodir, prefix): New vars. (install): Use infodir. - (emacsinfodir): Deleted. + (emacsinfodir): Delete. 1993-05-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) @@ -9614,7 +9682,7 @@ 1993-05-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - * Makefile (dist): Changed to use Gzip instead of compress. + * Makefile (dist): Change to use Gzip instead of compress. 1993-04-23 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index e76b2bafd79..41392273fbd 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -946,10 +946,9 @@ If the last event came from a keyboard macro, the value is @code{macro}. It is not easy to display a value of point in the middle of a sequence of text that has the @code{display}, @code{composition} or -@code{intangible} property, or is invisible. Therefore, after a -command finishes and returns to the command loop, if point is within -such a sequence, the command loop normally moves point to the edge of -the sequence. +is invisible. Therefore, after a command finishes and returns to the +command loop, if point is within such a sequence, the command loop +normally moves point to the edge of the sequence. A command can inhibit this feature by setting the variable @code{disable-point-adjustment}: diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index fe5563370c4..372c041ab7a 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -528,7 +528,7 @@ but the compiler does not issue warnings for anything that occurs inside @var{body}. We recommend that you use this construct around the smallest -possible piece of code, to avoid missing possible warnings other than one +possible piece of code, to avoid missing possible warnings other than one you intend to suppress. @end defspec diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 034d92f78c3..a9921d7443d 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -193,10 +193,12 @@ a window, that forces truncation. @defvar wrap-prefix If this buffer-local variable is non-@code{nil}, it defines a ``prefix'' that is prepended to every continuation line at -display-time. (If lines are truncated, the wrap-prefix is never -used.) It may be a string, an image, or a stretch-glyph; the value is -interpreted in the same way as a @code{display} text property. -@xref{Display Property}. +display time. (If lines are truncated, the wrap-prefix is never +used.) It may be a string or an image (@pxref{Other Display Specs}), +or a stretch of whitespace such as specified by the @code{:width} or +@code{:align-to} display properties (@pxref{Specified Space}). The +value is interpreted in the same way as a @code{display} text +property. @xref{Display Property}. A wrap-prefix may also be specified for regions of text, using the @code{wrap-prefix} text or overlay property. This takes precedence @@ -206,9 +208,11 @@ over the @code{wrap-prefix} variable. @xref{Special Properties}. @defvar line-prefix If this buffer-local variable is non-@code{nil}, it defines a ``prefix'' that is prepended to every non-continuation line at -display-time. It may be a string, an image, or a stretch-glyph; the -value is interpreted in the same way as a @code{display} text -property. @xref{Display Property}. +display time. It may be a string or an image (@pxref{Other Display +Specs}), or a stretch of whitespace such as specified by the +@code{:width} or @code{:align-to} display properties (@pxref{Specified +Space}). The value is interpreted in the same way as a @code{display} +text property. @xref{Display Property}. A line-prefix may also be specified for regions of text using the @code{line-prefix} text or overlay property. This takes precedence @@ -870,15 +874,21 @@ ignore invisible newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the default), but only because they are explicitly programmed to do so. - However, if a command ends with point inside or immediately before -invisible text, the main editing loop moves point further forward or -further backward (in the same direction that the command already moved -it) until that condition is no longer true. Thus, if the command -moved point back into an invisible range, Emacs moves point back to -the beginning of that range, and then back one more character. If the -command moved point forward into an invisible range, Emacs moves point -forward up to the first visible character that follows the invisible -text. + However, if a command ends with point inside or at the boundary of invisible +text, the main editing loop moves point to one of the two ends of the invisible +text. Which end to move to is chosen based on the following factors: make sure +that the overall movement of the command is still in the same direction, and +prefer a position where an inserted char would not inherit the @code{invisible} +property. Additionally, if the text is not replaced by an ellipsis and the +command only moved within the invisible text, then point is moved one extra +character so as to try and reflect the command's movement by a visible movement +of the cursor. + + Thus, if the command moved point back to an invisible range (with the usual +stickiness), Emacs moves point back to the beginning of that range. If the +command moved point forward into an invisible range, Emacs moves point forward +to the first visible character that follows the invisible text and then forward +one more character. Incremental search can make invisible overlays visible temporarily and/or permanently when a match includes invisible text. To enable @@ -4546,7 +4556,7 @@ you may prefer to use a different one for a given image type (which @c FIXME how is this priority determined? loader will be used in practice depends on the priority of the loaders). @c FIXME why are these uppercase when image-types is lower-case? -@c FIXME what are the possibe options? Are these actually file extensions? +@c FIXME what are the possible options? Are these actually file extensions? For example, if you never want to use the ImageMagick loader to use JPEG files, add @code{JPG} to this list. @@ -5632,39 +5642,45 @@ code. You can override these conventions by setting up a display table @itemize @bullet @item Character codes 32 through 126 map to glyph codes 32 through 126. -Normally this means they display as themselves. +Normally this means they display as themselves, but a display table +can change that. @item Character code 9 is a horizontal tab. It displays as whitespace up to a position determined by @code{tab-width}. @item -Character code 10 is a newline. +Character code 10 is a newline. It is normally invisible on display, +and has the effect of ending the preceding line and starting a new +line. @item -All other codes in the range 0 through 31, and code 127, display in one -of two ways according to the value of @code{ctl-arrow}. If it is -non-@code{nil}, these codes map to sequences of two glyphs, where the -first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can -specify a glyph to use instead of @samp{^}.) Otherwise, these codes map -just like the codes in the range 128 to 255. - -On MS-DOS terminals, Emacs arranges by default for the character code -127 to be mapped to the glyph code 127, which normally displays as an -empty polygon. This glyph is used to display non-@acronym{ASCII} characters -that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,, -emacs, The GNU Emacs Manual}. - +All other codes in the range 0 through 31 display in one of two ways +according to the value of @code{ctl-arrow}. If it is non-@code{nil}, +these codes map to sequences of two glyphs, where the first glyph is +the @acronym{ASCII} code for @samp{^}. (A display table can specify a +glyph to use instead of @samp{^}.) Otherwise, these codes map just +like the raw bytes in the range 128 to 255 (described below). + +@cindex octal escapes @item -Character codes 128 through 255 map to sequences of four glyphs, where -the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are -digit characters representing the character code in octal. (A display -table can specify a glyph to use instead of @samp{\}.) +Raw bytes (@pxref{Text Representations}) with codes 128 through 255, +and the @acronym{ASCII} control character with code 127, display as +sequences of four glyphs, where the first glyph is the @acronym{ASCII} +code for @samp{\}, and the others are digit characters representing +the character code in octal. (A display table can specify a glyph to +use instead of @samp{\}.) This is known as the @dfn{octal escape} +display. @item -Multibyte character codes above 256 are displayed as themselves, or as -a question mark or a hex code or an empty box if the terminal cannot -display that character. +Non-@acronym{ASCII} character codes above 127 are displayed as +themselves, if the terminal and the available fonts support them. +Characters that are not supported by the terminal, or (on window +systems) have no fonts available for them, are displayed as a question +mark or a hex code or an empty box. @xref{Glyphless Chars}, for how +to control display of the characters not supported by the terminal or +fonts. Display tables can change how a character is displayed, even +if it is supported. @end itemize The usual display conventions apply even when there is a display @@ -5689,7 +5705,8 @@ mode line using the new values, call the function This buffer-local variable controls how control characters are displayed. If it is non-@code{nil}, they are displayed as a caret followed by the character: @samp{^A}. If it is @code{nil}, they are -displayed as a backslash followed by three octal digits: @samp{\001}. +displayed as octal escapes: a backslash followed by three octal +digits, as in @samp{\001}. @end defopt @defopt tab-width diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index d2e86a77112..dad1f28026e 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -953,7 +953,7 @@ variable, Emacs uses the latter. By default, The @code{alpha} frame parameter can also be a cons cell @code{(@samp{active} . @samp{inactive})}, where @samp{active} is the opacity of the frame when it is selected, and @samp{inactive} is the -opactity when it is not selected. +opacity when it is not selected. @end table The following frame parameters are semi-obsolete in that they are diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 0ce05d55a07..3426e81cdb3 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -653,7 +653,7 @@ buffer, which is used to regenerate the help information when the user clicks on the @samp{Back} or @samp{Forward} buttons. Most commands that use the @samp{*Help*} buffer should invoke this function before clearing the buffer. The @var{item} argument should have the form -@code{(@var{funtion} . @var{args})}, where @var{funtion} is a function +@code{(@var{function} . @var{args})}, where @var{function} is a function to call, with argument list @var{args}, to regenerate the help buffer. The @var{interactive-p} argument is non-@code{nil} if the calling command was invoked interactively; in that case, the stack of items diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index fe7c805c6f7..a601ed0c2c0 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1213,7 +1213,7 @@ match data around it, to prevent it from being overwritten. Notice that all functions are allowed to overwrite the match data unless they're explicitly documented not to do so. A consequence is -that functions that are run implictly in the background +that functions that are run implicitly in the background (@pxref{Timers}, and @ref{Idle Timers}) should likely save and restore the match data explicitly. diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile index e66dcc88f71..e0d77ee0541 100644 --- a/doc/lispref/spellfile +++ b/doc/lispref/spellfile @@ -253,7 +253,6 @@ deletable deletion' delq depiction -descendents deselecting destructive' destructively' @@ -299,7 +298,6 @@ excess' exec exitcode expression' -extendible extra' fails' fascist @@ -376,7 +374,6 @@ inserting' integerp intermixed ints -inturned irreversibly jum keymapp @@ -530,7 +527,6 @@ pointer' pointm pos preallocate -predicale preload prepend prepended @@ -641,7 +637,7 @@ suspension' symbolp symlink syms -syntatic +syntactic tabname temacs temporarily' @@ -662,7 +658,7 @@ the' tildes time's to' -towars +towards transportable txt types' @@ -676,7 +672,6 @@ undefine undefines underfull undo's -undodata unevaluated' unexec unexpand diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 3a081dddc61..f7f9c716162 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3145,6 +3145,12 @@ group is separately treated as described above. When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, the @code{intangible} property is ignored. +Beware: this property operates at a very low level, and affects a lot of code +in unexpected ways. So use it with extreme caution. A common misuse is to put +an intangible property on invisible text, which is actually unnecessary since +the command loop will move point outside of the invisible text at the end of +each command anyway. @xref{Adjusting Point}. + @item field @kindex field @r{(text property)} Consecutive characters with the same @code{field} property constitute a @@ -3191,10 +3197,12 @@ controls the total height of the display line ending in that newline. @item wrap-prefix If text has a @code{wrap-prefix} property, the prefix it defines will -be added at display-time to the beginning of every continuation line +be added at display time to the beginning of every continuation line due to text wrapping (so if lines are truncated, the wrap-prefix is -never used). It may be a string, an image, or a stretch-glyph such as -used by the @code{display} text-property. @xref{Display Property}. +never used). It may be a string or an image (@pxref{Other Display +Specs}), or a stretch of whitespace such as specified by the +@code{:width} or @code{:align-to} display properties (@pxref{Specified +Space}). A wrap-prefix may also be specified for an entire buffer using the @code{wrap-prefix} buffer-local variable (however, a @@ -3203,9 +3211,11 @@ the @code{wrap-prefix} variable). @xref{Truncation}. @item line-prefix If text has a @code{line-prefix} property, the prefix it defines will -be added at display-time to the beginning of every non-continuation -line. It may be a string, an image, or a stretch-glyph such as used -by the @code{display} text-property. @xref{Display Property}. +be added at display time to the beginning of every non-continuation +line. It may be a string or an image (@pxref{Other Display +Specs}), or a stretch of whitespace such as specified by the +@code{:width} or @code{:align-to} display properties (@pxref{Specified +Space}). A line-prefix may also be specified for an entire buffer using the @code{line-prefix} buffer-local variable (however, a @@ -3762,7 +3772,7 @@ Additionally, if two fields are separated by another field with the special value @code{boundary}, then any point within this special field is also considered to be ``on the boundary.'' -Commands like @kbd{C-a} with no argumemt, that normally move backward +Commands like @kbd{C-a} with no argument, that normally move backward to a specific kind of location and stay there once there, probably should specify @code{nil} for @var{escape-from-edge}. Other motion commands that check fields should probably pass @code{t}. @@ -4322,5 +4332,3 @@ If you do want modification hooks to be run in a particular piece of code that is itself run from a modification hook, then rebind locally @code{inhibit-modification-hooks} to @code{nil}. @end defvar - - diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt index 53a9f58cd01..6eb11a92f47 100644 --- a/doc/lispref/two-volume-cross-refs.txt +++ b/doc/lispref/two-volume-cross-refs.txt @@ -34,7 +34,7 @@ where each volume starts with a higher page number since I find it harder to go to the right place in the volume.) References to the same volume are just the page number; references to -the other volume are a volumne number (in Roman numerals) preceding +the other volume are a volume number (in Roman numerals) preceding the page number. For example, in Volume I: diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 8c99a06909b..437b6db8d58 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -110,6 +110,7 @@ including for the case where @var{object} is a deleted window. @end defun @cindex selected window +@cindex window selected within a frame In each frame, at any time, exactly one Emacs window is designated as @dfn{selected within the frame}. For the selected frame, that window is called the @dfn{selected window}---the one in which most @@ -148,10 +149,10 @@ the minibuffer window in the returned list. If @var{minibuffer} is active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the minibuffer window is never included. -The optional argument @var{window}, if non-@code{nil}, should be a -live window on the specified frame; then @var{window} will be the -first element in the returned list. If @var{window} is omitted or -@code{nil}, the window selected within the frame is first element. +The optional argument @var{window}, if non-@code{nil}, should be a live +window on the specified frame; then @var{window} will be the first +element in the returned list. If @var{window} is omitted or @code{nil}, +the window selected within the frame is the first element. @end defun @cindex window tree @@ -375,7 +376,7 @@ Bars}). At the top of the window is an optional header line line (@pxref{Mode Line Format}). Emacs provides several functions for finding the height and width of -a window. Except where noted, these heights and widths are reported +a window. Except where noted, Emacs reports window heights and widths as integer numbers of lines and columns respectively. On a graphical display, each ``line'' and ``column'' actually corresponds to the height and width of a ``default'' character specified by the frame's @@ -438,26 +439,6 @@ that of the root window on that frame. If @var{window} is omitted or @code{nil}, it defaults to the selected window. @end defun -@cindex window position - The following functions can be used to determine the position of a -window relative to the window area of its frame: - -@defun window-top-line &optional window -This function returns the distance, in lines, between the top of -@var{window} and the top of the frame's window area. For instance, -the return value is 0 if there is no window above @var{window}. If -@var{window} is omitted or @code{nil}, it defaults to the selected -window. -@end defun - -@defun window-left-column &optional window -This function returns the distance, in columns, between the left edge -of @var{window} and the left edge of the frame's window area. For -instance, the return value is 0 if there is no window to the left of -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. -@end defun - @cindex window body height @cindex body height of a window @cindex window body width @@ -534,45 +515,12 @@ can be resized in the desired direction. To determine that, use the function @code{window-resizable}. @xref{Resizing Windows}. @end defun - The following functions can be used to find a window's size and -position in pixels. Though mostly useful on graphical displays, they -can also be called on text-only terminals, where the screen area of -each text character is taken to be ``one pixel''. - -@defun window-pixel-edges &optional window -This function return a list of pixel coordinates for the edges of -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. - -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. The list elements are, respectively, the X coordinate -of the left window edge, the Y coordinate of the top edge, one more -than the X coordinate of the right edge, and one more than the Y -coordinate of the bottom edge. The origin coordinate @samp{(0,0)} is -taken to be the top left corner of the frame's window area. - -These edge values include the space used by the window's scroll bar, -margins, fringes, header line, and mode line, if any. -@end defun - -@defun window-inside-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the edge coordinates for the window's text area, rather than -the edge coordinates for the window itself. @var{window} must specify -a live window. -@end defun - -@defun window-absolute-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the edge coordinates relative to the top left corner of the -display screen. -@end defun - -@defun window-inside-absolute-pixel-edges &optional window -This function is like @code{window-inside-pixel-edges}, except that it -returns the edge coordinates relative to the top left corner of the -display screen. @var{window} must specify a live window. -@end defun + @xref{Coordinates and Windows}, for more functions that report the +positions of various parts of a window relative to the frame, from +which you can calculate its size. In particular, you can use the +functions @code{window-pixel-edges} and +@code{window-inside-pixel-edges} to find the size in pixels, for +graphical displays. @node Resizing Windows @section Resizing Windows @@ -634,9 +582,9 @@ function @code{window-resizable} above. The choice of which window edges this function alters depends on the values of the option @code{window-combination-resize} and the -combination-limit status of the involved windows; in some cases, it may -alter both edges. @xref{Splitting Windows}. To resize by moving only -the bottom or right edge of a window, use the function +combination limits of the involved windows; in some cases, it may alter +both edges. @xref{Splitting Windows}. To resize by moving only the +bottom or right edge of a window, use the function @code{adjust-window-trailing-edge}, below. @end defun @@ -774,22 +722,24 @@ properties from it, including margins and scroll bars. If @var{window} is an internal window, the new window inherits the properties of the window selected within @var{window}'s frame. -If the variable @code{ignore-window-parameters} is non-@code{nil} -(@pxref{Window Parameters}), this function ignores window parameters. -Otherwise, it consults the @code{split-window} parameter of -@var{window}; if this is @code{t}, it splits the window disregarding -any other window parameters. If the @code{split-window} parameter -specifies a function, that function is called with the arguments -@var{window}, @var{size}, and @var{side} to split @var{window}, in -lieu of the usual action of @code{split-window}. +The behavior of this function may be altered by the window parameters +of @var{window}, so long as the variable +@code{ignore-window-parameters} is non-@code{nil}. If the value of +the @code{split-window} window parameter is @code{t}, this function +ignores all other window parameters. Otherwise, if the value of the +@code{split-window} window parameter is a function, that function is +called with the arguments @var{window}, @var{size}, and @var{side}, in +lieu of the usual action of @code{split-window}. Otherwise, this +function obeys the @code{window-atom} or @code{window-side} window +parameter, if any. @xref{Window Parameters}. @end deffn - As an example, we show a combination of @code{split-window} calls -that yields the window configuration discussed in @ref{Windows and -Frames}. This example demonstrates splitting a live window as well as -splitting an internal window. We begin with a frame containing a -single window (a live root window), which we denote by @var{W4}. -Calling @code{(split-window W3)} yields this window configuration: + As an example, here is a sequence of @code{split-window} calls that +yields the window configuration discussed in @ref{Windows and Frames}. +This example demonstrates splitting a live window as well as splitting +an internal window. We begin with a frame containing a single window +(a live root window), which we denote by @var{W4}. Calling +@code{(split-window W4)} yields this window configuration: @smallexample @group @@ -841,9 +791,6 @@ A new live window @var{W2} is created, to the left of the internal window @var{W3}. A new internal window @var{W1} is created, becoming the new root window. - The following two options can be used to modify the operation of -@code{split-window}. - @defopt window-combination-resize If this variable is @code{nil}, @code{split-window} can only split a window (denoted by @var{window}) if @var{window}'s screen area is @@ -854,18 +801,17 @@ If this variable is non-@code{nil}, @code{split-window} tries to resize all windows that are part of the same combination as @var{window}, in order to accommodate the new window. In particular, this may allow @code{split-window} to succeed even if @var{window} is -a fixed-size window or too small to ordinarily split. - -Also if this variable is non-@code{nil}, subsequent resizing and -deleting @var{window} will usually affect @emph{all} windows in -@var{window}'s combination. +a fixed-size window or too small to ordinarily split. Furthermore, +subsequently resizing or deleting @var{window} may resize all other +windows in its combination. -The setting of this variable has no effect if -@code{window-combination-limit} (see below) is non-@code{nil}. +This variable has no effect if @code{window-combination-limit} is +non-@code{nil} (see below). @end defopt -To illustrate the use of @code{window-combination-resize} consider the -following window configuration: + To illustrate the effect of @code{window-combination-resize}, +consider the following window configuration: + @smallexample @group ______________________________________ @@ -886,9 +832,10 @@ following window configuration: @end group @end smallexample -Splitting window @code{W3} with @code{window-combination-resize} -@code{nil} produces a configuration where the size of @code{W2} remains -unchanged: +@noindent +If @code{window-combination-resize} is @code{nil}, splitting window +@code{W3} leaves the size of @code{W2} unchanged: + @smallexample @group ______________________________________ @@ -909,8 +856,11 @@ unchanged: @end group @end smallexample -Splitting @code{W3} with @code{window-combination-resize} non-@code{nil} -instead steals the space for @code{W4} from both @code{W2} and @code{W3}: +@noindent +If @code{window-combination-resize} is non-@code{nil}, splitting +@code{W3} instead leaves all three live windows with approximately the +same height: + @smallexample @group ______________________________________ @@ -932,53 +882,52 @@ instead steals the space for @code{W4} from both @code{W2} and @code{W3}: @end smallexample @defopt window-combination-limit -If this variable is @code{nil}, @code{split-window} creates a new parent -window if and only if the old window has no parent window or shall be -split orthogonally to the combination it is part of. If this variable -is @code{t}, @code{split-window} always creates a new parent window. If -this variable is always @code{t}, a frame's window tree is a binary tree -so every window but the frame's root window has exactly one sibling. -Other values are reserved for future use. - -The value of this variable is also assigned to the combination-limit -status of the new parent window. The combination-limit status of any -window can be retrieved via the function @code{window-combination-limit} -and altered by the function @code{set-window-combination-limit}, see -below. +If the value of this variable is @code{t}, the @code{split-window} +function always creates a new internal window. If the value is +@code{nil}, the new live window is allowed to share the existing +parent window, if one exists, provided the split occurs in the same +direction as the existing window combination (otherwise, a new +internal window is created anyway). The default is @code{nil}. Other +values are reserved for future use. + +Thus, if the value of this variable is at all times @code{t}, then at +all times every window tree is a binary tree (a tree where each window +except the root window has exactly one sibling). + +Furthermore, @code{split-window} calls +@code{set-window-combination-limit} on the newly-created internal +window, recording the current value of this variable. This affects +how the window tree is rearranged when the child windows are deleted +(see below). @end defopt -@defun window-combination-limit &optional window -This function returns the combination-limit status of @var{window}. The -argument @var{window} can be any window and defaults to the selected -one. Note, however, that the combination-limit status is currently -meaningful for internal windows only. - -@cindex combination-limit status -The @dfn{combination-limit status} of a window specifies whether that -window may be removed and its child windows recombined with that -window's siblings when such a sibling's child window is deleted. The -combination-limit status is initially assigned by @code{split-window} -from the current value of the variable @code{window-combination-limit} -(see above) and can be reset by the function -@code{set-window-combination-limit} (see below). - -If the return value is @code{nil}, child windows of @var{window} may be -recombined with @var{window}'s siblings when a window gets deleted. A -return value of @code{nil} means that child windows of @var{window} are -never (re-)combined with @var{window}'s siblings in such a case. -@end defun - -@defun set-window-combination-limit window &optional status -This functions sets the combination-limit status (see above) of -@var{window} to @var{status}. The argument @var{window} can be any -window and defaults to the selected one. Note that setting the -combination-limit status is meaningful for internal windows only. The -return value is @var{status}. -@end defun - -To illustrate the use of @code{window-combination-limit} consider the -following configuration (throughout the following examples we shall -assume that @code{window-combination-resize} invariantly is @code{nil}). +@cindex window combination limit +@defun set-window-combination-limit window limit +This functions sets the @dfn{combination limit} of the window +@var{window} to @var{limit}. This value can be retrieved via the +function @code{window-combination-limit}. See below for its effects; +note that it is only meaningful for internal windows. The +@code{split-window} function automatically calls this function, passing +the value of the variable @code{window-combination-limit} as +@var{limit}. +@end defun + +@defun window-combination-limit window +This function returns the combination limit for @var{window}. + +The combination limit is meaningful only for an internal window. If +it is @code{nil}, then Emacs is allowed to automatically delete +@var{window}, in response to a window deletion, in order to group the +child windows of @var{window} with its sibling windows to form a new +window combination. If the combination limit is @code{t}, the child +windows of @var{window} are never automatically re-combined with its +siblings. +@end defun + + To illustrate the effect of @code{window-combination-limit}, +consider the following configuration (throughout this example, we will +assume that @code{window-combination-resize} is @code{nil}): + @smallexample @group ______________________________________ @@ -999,31 +948,10 @@ assume that @code{window-combination-resize} invariantly is @code{nil}). @end group @end smallexample -Splitting @code{W2} into two windows above each other with -@code{window-combination-limit} equal @code{nil} will get you a -configuration like: -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - || || - ||_________________W4_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample +@noindent +If @code{window-combination-limit} is @code{nil}, splitting @code{W2} +into two windows, one above the other, yields -If you now enlarge window @code{W4}, Emacs steals the necessary space -from window @code{W3} resulting in a configuration like: @smallexample @group ______________________________________ @@ -1034,43 +962,24 @@ from window @code{W3} resulting in a configuration like: | ____________________________________ | || || || || - || || ||_________________W4_________________|| | ____________________________________ | || || + || || ||_________________W3_________________|| |__________________W1__________________| @end group @end smallexample -Deleting window @code{W4}, will return its space to @code{W2} as -follows: -@smallexample -@group - ______________________________________ - | ____________________________________ | - || || - || || - || || - || || - || || - || || - || || - ||_________________W2_________________|| - | ____________________________________ | - || || - ||_________________W3_________________|| - |__________________W1__________________| +@noindent +The newly-created window, @code{W4}, shares the same internal window +@code{W1}. If @code{W4} is resized, it is allowed to resize the other +live window, @code{W3}. -@end group -@end smallexample + If @code{window-combination-limit} is @code{t}, splitting @code{W2} +in the initial configuration would instead have produced this: -Hence, with respect to the initial configuration, window @code{W2} has -grown at the expense of window @code{W3}. If, however, in the initial -configuration you had split @code{W2} with -@code{window-combination-limit} bound to @code{t}, a new internal window -@code{W5} would have been created as depicted below. @smallexample @group ______________________________________ @@ -1091,143 +1000,110 @@ configuration you had split @code{W2} with @end group @end smallexample -Enlarging @code{W4} would now have stolen the necessary space from -@code{W2} instead of @code{W3} as -@smallexample -@group - ______________________________________ - | ____________________________________ | - || __________________________________ || - |||________________W2________________||| - || __________________________________ || - ||| ||| - ||| ||| - |||________________W4________________||| - ||_________________W5_________________|| - | ____________________________________ | - || || - || || - ||_________________W3_________________|| - |__________________W1__________________| - -@end group -@end smallexample +@noindent +A new internal window @code{W5} has been created; its children are +@code{W2} and the new live window @code{W4}. Now, @code{W2} is the +only sibling of @code{W4}, so resizing @code{W4} will resize +@code{W2}, leaving @code{W3} unaffected. -and the subsequent deletion of @code{W4} would have restored the initial -configuration. + For interactive use, Emacs provides two commands which always split +the selected window. These call @code{split-window} internally. -For interactive use, Emacs provides two commands which always split the -selected window. +@deffn Command split-window-right &optional size +This function splits the selected window into two side-by-side +windows, putting the selected window on the left. If @var{size} is +positive, the left window gets @var{size} columns; if @var{size} is +negative, the right window gets @minus{}@var{size} columns. +@end deffn @deffn Command split-window-below &optional size -This function splits the selected window into two windows, one above the -other, leaving the upper of the two windows selected, with @var{size} -lines. (If @var{size} is negative, then the lower of the two windows -gets @minus{}@var{size} lines and the upper window gets the rest, but -the upper window is still the one selected.) However, if -@code{split-window-keep-point} (see below) is @code{nil}, then either -window can be selected. - - In other respects, this function is similar to @code{split-window}. -In particular, the upper window is the original one and the return value -is the new, lower window. +This function splits the selected window into two windows, one above +the other, leaving the upper window selected. If @var{size} is +positive, the upper window gets @var{size} lines; if @var{size} is +negative, the lower window gets @minus{}@var{size} lines. @end deffn @defopt split-window-keep-point -If this variable is non-@code{nil} (the default), then +If the value of this variable is non-@code{nil} (the default), @code{split-window-below} behaves as described above. - If it is @code{nil}, then @code{split-window-below} adjusts point -in each of the two windows to avoid scrolling. (This is useful on -slow terminals.) It selects whichever window contains the screen line -that point was previously on. Other functions are not affected by -this variable. +If it is @code{nil}, @code{split-window-below} adjusts point in each +of the two windows to minimize redisplay. (This is useful on slow +terminals.) It selects whichever window contains the screen line that +point was previously on. Note that this only affects +@code{split-window-below}, not the lower-level @code{split-window} +function. @end defopt -@deffn Command split-window-right &optional size -This function splits the selected window into two windows -side-by-side, leaving the selected window on the left with @var{size} -columns. If @var{size} is negative, the rightmost window gets -@minus{}@var{size} columns, but the leftmost window still remains -selected. -@end deffn - - @node Deleting Windows @section Deleting Windows @cindex deleting windows -A window remains visible on its frame unless you @dfn{delete} it by -calling certain functions that delete windows. A deleted window cannot -appear on the screen, but continues to exist as a Lisp object until -there are no references to it. There is no way to cancel the deletion -of a window aside from restoring a saved window configuration -(@pxref{Window Configurations}). Restoring a window configuration also -deletes any windows that aren't part of that configuration. Erroneous -information may result from using a deleted window as if it were live. + @dfn{Deleting} a window removes it from the frame's window tree. If +the window is a live window, it disappears from the screen. If the +window is an internal window, its child windows are deleted too. -@deffn Command delete-window &optional window -This function removes @var{window} from display and returns @code{nil}. -The argument @var{window} can denote any window and defaults to the -selected one. An error is signaled if @var{window} is the only window -on its frame. Hence @var{window} must have at least one sibling window -(@pxref{Windows and Frames}) in order to get deleted. If @var{window} -is the selected window on its frame, this function selects the most -recently selected live window on that frame instead. - -If the variable @code{ignore-window-parameters} (@pxref{Window -Parameters}) is non-@code{nil}, this function ignores all parameters of -@var{window}. Otherwise, if the @code{delete-window} parameter of -@var{window} is @code{t}, it deletes the window disregarding other -window parameters. If the @code{delete-window} parameter specifies a -function, that function is called with @var{window} as its sole -argument. + Even after a window is deleted, it continues to exist as a Lisp +object, until there are no more references to it. Window deletion can +be reversed, by restoring a saved window configuration (@pxref{Window +Configurations}). -If @code{window-combination-resize} (@pxref{Splitting Windows}) is -@code{nil}, the space @var{window} took up is given to its left sibling -if such a window exists and to its right sibling otherwise. If -@code{window-combination-resize} is non-@code{nil}, the space of -@var{window} is proportionally distributed among the remaining windows -in the same combination. +@deffn Command delete-window &optional window +This function removes @var{window} from display and returns +@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. If deleting the window would leave no more +windows in the window tree (e.g. if it is the only live window in the +frame), an error is signaled. + +By default, the space taken up by @var{window} is given to one of its +adjacent sibling windows, if any. However, if the variable +@code{window-combination-resize} is non-@code{nil}, the space is +proportionally distributed among any remaining windows in the window +combination. @xref{Splitting Windows}. + +The behavior of this function may be altered by the window parameters +of @var{window}, so long as the variable +@code{ignore-window-parameters} is non-@code{nil}. If the value of +the @code{delete-window} window parameter is @code{t}, this function +ignores all other window parameters. Otherwise, if the value of the +@code{delete-window} window parameter is a function, that function is +called with the argument @var{window}, in lieu of the usual action of +@code{delete-window}. Otherwise, this function obeys the +@code{window-atom} or @code{window-side} window parameter, if any. +@xref{Window Parameters}. @end deffn @deffn Command delete-other-windows &optional window -This function makes @var{window} fill its frame and returns @code{nil}. -The argument @var{window} can denote an arbitrary window and defaults to -the selected one. Upon exit, @var{window} will be the selected window -on its frame. - -If the variable @code{ignore-window-parameters} (@pxref{Window -Parameters}) is non-@code{nil}, this function ignores all parameters of -@var{window}. Otherwise, if the @code{delete-other-windows} parameter -of @var{window} equals @code{t}, it deletes all other windows -disregarding any remaining window parameters. If the -@code{delete-other-windows} parameter of @var{window} specifies a -function, it calls that function with @var{window} as its sole argument. +This function makes @var{window} fill its frame, by deleting other +windows as necessary. If @var{window} is omitted or @code{nil}, it +defaults to the selected window. The return value is @code{nil}. + +The behavior of this function may be altered by the window parameters +of @var{window}, so long as the variable +@code{ignore-window-parameters} is non-@code{nil}. If the value of +the @code{delete-other-windows} window parameter is @code{t}, this +function ignores all other window parameters. Otherwise, if the value +of the @code{delete-other-windows} window parameter is a function, +that function is called with the argument @var{window}, in lieu of the +usual action of @code{delete-other-windows}. Otherwise, this function +obeys the @code{window-atom} or @code{window-side} window parameter, +if any. @xref{Window Parameters}. @end deffn @deffn Command delete-windows-on &optional buffer-or-name frame -This function deletes all windows showing @var{buffer-or-name}. If -there are no windows showing @var{buffer-or-name}, it does nothing. -The optional argument @var{buffer-or-name} may be a buffer or the name -of an existing buffer and defaults to the current buffer. Invoking -this command on a minibuffer signals an error. - -The function @code{delete-windows-on} operates by calling -@code{delete-window} for each window showing @var{buffer-or-name}. If a -frame has several windows showing different buffers, then those showing -@var{buffer-or-name} are removed, and the other windows expand to fill -the space. - -If all windows in some frame are showing @var{buffer-or-name} (including -the case where there is only one window), then that frame is deleted -provided there are other frames left. - -The optional argument @var{frame} specifies which frames to operate on. -This function does not use it in quite the same way as the other -functions which scan all live windows (@pxref{Cyclic Window Ordering}); -specifically, the values @code{t} and @code{nil} have the opposite of -their meanings in the other functions. Here are the full details: +This function deletes all windows showing @var{buffer-or-name}, by +calling @code{delete-window} on those windows. @var{buffer-or-name} +should be a buffer, or the name of a buffer; if omitted or @code{nil}, +it defaults to the current buffer. If there are no windows showing +the specified buffer, this function does nothing. If the specified +buffer is a minibuffer, an error is signaled. + +If there is a dedicated window showing the buffer, and that window is +the only one on its frame, this function also deletes that frame if it +is not the only frame on the terminal. + +The optional argument @var{frame} specifies which frames to operate +on: @itemize @bullet @item @code{nil} @@ -1241,34 +1117,37 @@ means operate on all visible or iconified frames. @item A frame means operate on that frame. @end itemize -@end deffn +Note that this argument does not have the same meaning as in other +functions which scan all live windows (@pxref{Cyclic Window +Ordering}). Specifically, the values @code{t} and @code{nil} have the +opposite of their meanings in those other functions. +@end deffn @node Selecting Windows @section Selecting Windows @cindex selecting a window @defun select-window window &optional norecord -This function makes @var{window} the selected window, see @ref{Basic -Windows}. Unless @var{window} already is the selected window, this also -makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current -buffer. Moreover, the cursor for selected windows will be displayed in -@var{window} after the next redisplay. This function returns -@var{window}. +This function makes @var{window} the selected window, as well as the +window selected within its frame (@pxref{Basic Windows}). +@var{window} must be a live window. Unless @var{window} already is the +selected window, its buffer becomes the current buffer (@pxref{Buffers +and Windows}). The return value is @var{window}. -Normally, @var{window}'s selected buffer is moved to the front of the -buffer list (@pxref{The Buffer List}) and @var{window} becomes the most -recently selected window. But if the optional argument @var{norecord} -is non-@code{nil}, the buffer list remains unchanged and @var{window} -does not become the most recently selected one. +By default, this function also moves @var{window}'s selected buffer to +the front of the buffer list (@pxref{The Buffer List}), and makes +@var{window} the most recently selected window. However, if the +optional argument @var{norecord} is non-@code{nil}, these additional +actions are omitted. @end defun @cindex most recently selected windows -The sequence of calls to @code{select-window} with a non-@code{nil} + The sequence of calls to @code{select-window} with a non-@code{nil} @var{norecord} argument determines an ordering of windows by their selection time. The function @code{get-lru-window} can be used to -retrieve the least recently selected live window in this ordering, see -@ref{Cyclic Window Ordering}. +retrieve the least recently selected live window (@pxref{Cyclic Window +Ordering}). @defmac save-selected-window forms@dots{} This macro records the selected frame, as well as the selected window @@ -1300,33 +1179,26 @@ The order of recently selected windows and the buffer list are not changed by this macro. @end defmac -@cindex frame selected window -@cindex window selected within frame -Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly -one window on any frame is selected within the frame. The significance -of this designation is that selecting the frame also selects this -window. Conversely, selecting a window for Emacs with -@code{select-window} also makes that window selected within its frame. - -@defun frame-selected-window &optional frame -This function returns the window on @var{frame} that is selected within -@var{frame}. The optional argument @var{frame} must denote a live frame -and defaults to the selected one. +@defun frame-selected-window &optional frame +This function returns the window on @var{frame} that is selected +within that frame. @var{frame} should be a live frame; if omitted or +@code{nil}, it defaults to the selected frame. @end defun @defun set-frame-selected-window frame window &optional norecord -This function sets the selected window of frame @var{frame} to -@var{window}. The argument @var{frame} must denote a live frame and -defaults to the selected one. If @var{frame} is the selected frame, -this also makes @var{window} the selected window. The argument -@var{window} must denote a live window. This function returns -@var{window}. +This function makes @code{window} the window selected within the frame +@var{frame}. @var{frame} should be a live frame; if omitted or +@code{nil}, it defaults to the selected frame. @var{window} should be +a live window; if omitted or @code{nil}, it defaults to the selected +window. -Optional argument @var{norecord} non-@code{nil} means to neither change -the list of most recently selected windows (@pxref{Selecting Windows}) -nor the buffer list (@pxref{The Buffer List}). -@end defun +If @var{frame} is the selected frame, this makes @var{window} the +selected window. +If the optional argument @var{norecord} is non-@code{nil}, this +function does not alter the list of most recently selected windows, +nor the buffer list. +@end defun @node Cyclic Window Ordering @section Cyclic Ordering of Windows @@ -1334,28 +1206,22 @@ nor the buffer list (@pxref{The Buffer List}). @cindex ordering of windows, cyclic @cindex window ordering, cyclic -When you use the command @kbd{C-x o} (@code{other-window}) to select + When you use the command @kbd{C-x o} (@code{other-window}) to select some other window, it moves through live windows in a specific order. -For any given configuration of windows, this order never varies. It is -called the @dfn{cyclic ordering of windows}. - - For a particular frame, this ordering is determined by the window -tree of that frame, see @ref{Windows and Frames}. More precisely, the -ordering is obtained by a depth-first traversal of the frame's window -tree supplemented, if requested, by the frame's minibuffer window. +For any given configuration of windows, this order never varies. It +is called the @dfn{cyclic ordering of windows}. - If there's just one live frame, the cyclic ordering is the ordering -for that frame. Otherwise, the cyclic ordering is obtained by appending -the orderings for individual frames in order of the list of all live -frames, @ref{Finding All Frames}. In any case, the ordering is made -``cyclic'' by having the last window precede the first window in the -ordering. + The ordering is determined by a depth-first traversal of the frame's +window tree, retrieving the live windows which are the leaf nodes of +the tree (@pxref{Windows and Frames}). If the minibuffer is active, +the minibuffer window is included too. The ordering is cyclic, so the +last window in the sequence is followed by the first one. @defun next-window &optional window minibuf all-frames @cindex minibuffer window, and @code{next-window} -This function returns the window following @var{window} in the cyclic -ordering of windows. The argument @var{window} must specify a live -window and defaults to the selected one. +This function returns a live window, the one following @var{window} in +the cyclic ordering of windows. @var{window} should be a live window; +if omitted or @code{nil}, it defaults to the selected window. The optional argument @var{minibuf} specifies whether minibuffer windows shall be included in the cyclic ordering. Normally, when @var{minibuf} @@ -1369,139 +1235,100 @@ minibuffer windows. If @var{minibuf} is neither @code{t} nor @code{nil}, minibuffer windows are not included even if they are active. The optional argument @var{all-frames} specifies which frames to -consider. Here are the possible values and their meanings: +consider: @itemize @bullet @item @code{nil} -means consider all windows on @var{window}'s frame, plus the minibuffer -window used by that frame even if it lies in some other frame. If the -minibuffer counts (as determined by @var{minibuf}), then all windows on -all frames that share that minibuffer count too. +means to consider windows on @var{window}'s frame. If the minibuffer +window is considered (as specified by the @var{minibuf} argument), +then frames that share the minibuffer window are considered too. @item @code{t} -means consider all windows on all existing frames. +means to consider windows on all existing frames. @item @code{visible} -means consider all windows on all visible frames. (To get useful -results, ensure that @var{window} is on a visible frame.) +means to consider windows on all visible frames. @item 0 -means consider all windows on all visible or iconified frames. +means to consider windows on all visible or iconified frames. @item A frame -means consider all windows on that frame. +means to consider windows on that specific frame. @item Anything else -means consider the windows on @var{window}'s frame, and no others. +means to consider windows on @var{window}'s frame, and no others. @end itemize -This example assumes there are two windows, both displaying the -buffer @samp{windows.texi}: - -@example -@group -(selected-window) - @result{} #<window 56 on windows.texi> -@end group -@group -(next-window (selected-window)) - @result{} #<window 52 on windows.texi> -@end group -@group -(next-window (next-window (selected-window))) - @result{} #<window 56 on windows.texi> -@end group -@end example +If more than one frame is considered, the cyclic ordering is obtained +by appending the orderings for those frames, in the same order as the +list of all live frames (@pxref{Finding All Frames}). @end defun @defun previous-window &optional window minibuf all-frames -This function returns the window preceding @var{window} in the cyclic -ordering of windows. The other arguments specify which windows to -consider as in @code{next-window}. +This function returns a live window, the one preceding @var{window} in +the cyclic ordering of windows. The other arguments are handled like +in @code{next-window}. @end defun @deffn Command other-window count &optional all-frames -This function selects another window in the cyclic ordering of windows. -@var{count} specifies the number of windows to skip in the ordering, -starting with the selected window, before making the selection. If -@var{count} is a positive number, it skips @var{count} windows forwards. -@var{count} negative means skip @minus{}@var{count} windows backwards. -If @var{count} is zero, it does not skip any window, thus re-selecting -the selected window. In an interactive call, @var{count} is the numeric -prefix argument. +This function selects a live window, one @var{count} places from the +selected window in the cyclic ordering of windows. If @var{count} is +a positive number, it skips @var{count} windows forwards; if +@var{count} is negative, it skips @minus{}@var{count} windows +backwards; if @var{count} is zero, that simply re-selects the selected +window. When called interactively, @var{count} is the numeric prefix +argument. The optional argument @var{all-frames} has the same meaning as in -@code{next-window}, but the @var{minibuf} argument of @code{next-window} -is always effectively @code{nil}. This function returns @code{nil}. +@code{next-window}, like a @code{nil} @var{minibuf} argument to +@code{next-window}. This function does not select a window that has a non-@code{nil} @code{no-other-window} window parameter (@pxref{Window Parameters}). @end deffn -The following function returns a copy of the list of windows in the -cyclic ordering. - -@defun window-list-1 &optional window &optional minibuf &optional all_frames -This function returns a list of live windows. The optional arguments -@var{minibuf} and @var{all-frames} specify the set of windows to include -in the list. See the description of @code{next-window} for details. - -The optional argument @var{window} specifies the first window to list -and defaults to the selected window. If @var{window} is not on the list -of windows returned, some other window will be listed first but no error -is signaled. -@end defun - -The functions described below use @code{window-list-1} for generating a -copy of the list of all relevant windows. Hence, any change of the -window configuration that occurs while one of these functions is -executed is @emph{not} reflected in the list of windows investigated. +@defun walk-windows fun &optional minibuf all-frames +This function calls the function @var{fun} once for each live window, +with the window as the argument. -@defun walk-windows proc &optional minibuf all-frames -This function cycles through live windows. It calls the function -@var{proc} once for each window, with the window as its sole argument. - -The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the walk, see @code{next-window} above. If -@var{all-frames} specifies a frame, the first window walked is the first -window on that frame as returned by @code{frame-first-window} and not -necessarily the selected window. +It follows the cyclic ordering of windows. The optional arguments +@var{minibuf} and @var{all-frames} specify the set of windows +included; these have the same arguments as in @code{next-window}. If +@var{all-frames} specifies a frame, the first window walked is the +first window on that frame (the one returned by +@code{frame-first-window}), not necessarily the selected window. -If @var{proc} changes the window configuration by splitting or deleting -windows, that change is not reflected in the set of windows walked. -That set is determined entirely by the set of live windows at the time -this function was invoked. +If @var{fun} changes the window configuration by splitting or deleting +windows, that does not alter the set of windows walked, which is +determined prior to calling @var{fun} for the first time. @end defun -The following function allows to determine whether a specific window is -the only live window. - @defun one-window-p &optional no-mini all-frames -This function returns non-@code{nil} if the selected window is the only -window. +This function returns @code{t} if the selected window is the only live +window, and @code{nil} otherwise. -The optional argument @var{no-mini}, if non-@code{nil}, means don't -count the minibuffer even if it is active; otherwise, the minibuffer -window is counted when it is active. The optional argument -@var{all-frames} has the same meaning as for @code{next-window}, see -above. +If the minibuffer window is active, it is normally considered (so that +this function returns @code{nil}). However, if the optional argument +@var{no-mini} is non-@code{nil}, the minibuffer window is ignored even +if active. The optional argument @var{all-frames} has the same +meaning as for @code{next-window}. @end defun @cindex finding windows - The following functions choose (but do not select) one of the windows -on the screen, offering various criteria for the choice. + The following functions return a window which satisfies some +criterion, without selecting it: @cindex least recently used window @defun get-lru-window &optional all-frames dedicated -This function returns the window least recently ``used'' (that is, -selected). If any full-width windows are present, it only considers -these. The optional argument @var{all-frames} has the same meaning as -in @code{next-window}. +This function returns a live window which is heuristically the ``least +recently used'' window. The optional argument @var{all-frames} has +the same meaning as in @code{next-window}. -The selected window is returned if it is the only candidate. A -minibuffer window is never a candidate. A dedicated window -(@pxref{Dedicated Windows}) is never a candidate unless the optional -argument @var{dedicated} is non-@code{nil}. +If any full-width windows are present, only those windows are +considered. The selected window is never returned, unless it is the +only candidate. A minibuffer window is never a candidate. A +dedicated window (@pxref{Dedicated Windows}) is never a candidate +unless the optional argument @var{dedicated} is non-@code{nil}. @end defun @cindex largest window @@ -1515,22 +1342,23 @@ If there are two candidate windows of the same size, this function prefers the one that comes first in the cyclic ordering of windows, starting from the selected window. -The optional argument @var{all-frames} specifies which set of windows to -consider as with @code{next-window}, see above. +The optional argument @var{all-frames} specifies the windows to +search, and has the same meaning as in @code{next-window}. @end defun @cindex window that satisfies a predicate @cindex conditional selection of windows @defun get-window-with-predicate predicate &optional minibuf all-frames default -This function returns a window satisfying @var{predicate}. It cycles -through all visible windows calling @var{predicate} on each one of them -with that window as its argument. The function returns the first window -for which @var{predicate} returns a non-@code{nil} value; if that never -happens, it returns @var{default} (which defaults to @code{nil}). +This function calls the function @var{predicate} for each of the +windows in the cyclic order of windows in turn, passing it the window +as an argument. If the predicate returns non-@code{nil} for any +window, this function stops and returns that window. If no such +window is found, the return value is @var{default} (which defaults to +@code{nil}). The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to investigate. See the description of -@code{next-window} for details. +windows to search, and have the same meanings as in +@code{next-window}. @end defun @node Buffers and Windows @@ -1539,47 +1367,41 @@ set of windows to investigate. See the description of @cindex windows, controlling precisely @cindex buffers, controlled in windows -To find out which buffer is displayed in a given window the following -function is used. + This section describes low-level functions for examining and setting +the contents of windows. @xref{Switching Buffers}, for higher-level +functions for displaying a specific buffer in a window. @defun window-buffer &optional window -This function returns the buffer that @var{window} is displaying. The -argument @var{window} can be any window and defaults to the selected -one. If @var{window} is an internal window, this function returns +This function returns the buffer that @var{window} is displaying. If +@var{window} is omitted or @code{nil} it defaults to the selected +window. If @var{window} is an internal window, this function returns @code{nil}. @end defun -The basic, low-level function to associate a window with a buffer is -@code{set-window-buffer}. Higher-level functions like -@code{switch-to-buffer} and @code{display-buffer} try to obey a number -of user customizations regulating which windows are supposed to -display which buffers. @xref{Switching Buffers}. When writing an -application, you should avoid using @code{set-window-buffer} unless -you are sure you need it. - @defun set-window-buffer window buffer-or-name &optional keep-margins -This function makes @var{window} display @var{buffer-or-name} and -returns @code{nil}. The argument @var{window} has to denote a live -window and defaults to the selected one. The argument -@var{buffer-or-name} must specify a buffer or the name of an existing -buffer. An error is signaled when @var{window} is @dfn{strongly} -dedicated to its buffer (@pxref{Dedicated Windows}) and does not already -display @var{buffer-or-name}. - -Normally, displaying @var{buffer-or-name} in @var{window} resets the -window's position, display margins, fringe widths, and scroll bar -settings based on the local variables of the specified buffer. However, -if the optional argument @var{keep-margins} is non-@code{nil}, display -margins and fringe widths of @var{window} remain unchanged. -@xref{Fringes}. - -This function is the fundamental primitive for changing which buffer is -displayed in a window, and all ways of doing that call this function. -Neither the selected window nor the current buffer are changed by this -function. +This function makes @var{window} display @var{buffer-or-name}. +@var{window} should be a live window; if @code{nil}, it defaults to +the selected window. @var{buffer-or-name} should be a buffer, or the +name of an existing buffer. This function does not change which +window is selected, nor does it directly change which buffer is +current (@pxref{Current Buffer}). Its return value is @code{nil}. + +If @var{window} is @dfn{strongly dedicated} to a buffer and +@var{buffer-or-name} does not specify that buffer, this function +signals an error. @xref{Dedicated Windows}. + +By default, this function resets @var{window}'s position, display +margins, fringe widths, and scroll bar settings, based on the local +variables in the specified buffer. However, if the optional argument +@var{keep-margins} is non-@code{nil}, it leaves the display margins +and fringe widths unchanged. -This function runs @code{window-scroll-functions} before running -@code{window-configuration-change-hook}, see @ref{Window Hooks}. +When writing an application, you should normally use the higher-level +functions described in @ref{Switching Buffers}, instead of calling +@code{set-window-buffer} directly. + +This function runs @code{window-scroll-functions}, followed by +@code{window-configuration-change-hook}. @xref{Window Hooks}. @end defun @defvar buffer-display-count @@ -1589,28 +1411,26 @@ displayed in a window. It is incremented each time @end defvar @defvar buffer-display-time -This variable records the time at which a buffer was last made visible -in a window. It is always local in each buffer; each time -@code{set-window-buffer} is called, it sets this variable to -@code{(current-time)} in the specified buffer (@pxref{Time of Day}). -When a buffer is first created, @code{buffer-display-time} starts out -with the value @code{nil}. +This buffer-local variable records the time at which a buffer was last +displayed in a window. The value is @code{nil} if the buffer has +never been displayed. It is updated each time +@code{set-window-buffer} is called for the buffer, with the value +returned by @code{current-time} (@pxref{Time of Day}). @end defvar @defun get-buffer-window &optional buffer-or-name all-frames -This function returns a window displaying @var{buffer-or-name}, or -@code{nil} if there is none. If there are several such windows, then -the function returns the first one in the cyclic ordering of windows, -starting from the selected window, @xref{Cyclic Window Ordering}. +This function returns the first window displaying @var{buffer-or-name} +in the cyclic ordering of windows, starting from the selected window +(@pxref{Cyclic Window Ordering}). If no such window exists, the +return value is @code{nil}. -The argument @var{buffer-or-name} may be a buffer or a buffer name and -defaults to the current buffer. The optional argument @var{all-frames} -specifies which windows to consider: +@var{buffer-or-name} should be a buffer or the name of a buffer; if +omitted or @code{nil}, it defaults to the current buffer. The +optional argument @var{all-frames} specifies which windows to +consider: @itemize @bullet @item -@code{nil} means consider windows on the selected frame. -@item @code{t} means consider windows on all existing frames. @item @code{visible} means consider windows on all visible frames. @@ -1618,44 +1438,45 @@ specifies which windows to consider: 0 means consider windows on all visible or iconified frames. @item A frame means consider windows on that frame only. +@item +Any other value means consider windows on the selected frame. @end itemize -Observe that the behavior of @code{get-buffer-window} may differ from -that of @code{next-window} (@pxref{Cyclic Window Ordering}) when -@var{all-frames} equals @code{nil} or any value not listed here. -Perhaps we will change @code{get-buffer-window} in the future to make it -compatible with the other functions. +Note that these meanings differ slightly from those of the +@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window +Ordering}). This function may be changed in a future version of Emacs +to eliminate this discrepancy. @end defun @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames This function returns a list of all windows currently displaying -@var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer -or the name of an existing buffer and defaults to the current buffer. +@var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the +name of an existing buffer. If omitted or @code{nil}, it defaults to +the current buffer. -The two remaining arguments work like the same-named arguments of -@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} -like the optional arguments of @code{get-buffer-window}. +The arguments @var{minibuf} and @var{all-frames} have the same +meanings as in the function @code{next-window} (@pxref{Cyclic Window +Ordering}). Note that the @var{all-frames} argument does @emph{not} +behave exactly like in @code{get-buffer-window}. @end defun @deffn Command replace-buffer-in-windows &optional buffer-or-name This command replaces @var{buffer-or-name} with some other buffer, in -all windows displaying it. For each such window, it choose another -buffer using @code{switch-to-prev-buffer} (@pxref{Window History}). - -The argument @var{buffer-or-name} may be a buffer, or the name of an -existing buffer; it defaults to the current buffer. - -If a window displaying @var{buffer-or-name} is dedicated -(@pxref{Dedicated Windows}) and is not the only window on its frame, -that window is deleted. If that window is the only window on its frame -and there are other frames on the frame's terminal, that frame is dealt -with by the function specified by @code{frame-auto-hide-function} -(@pxref{Quitting Windows}). Otherwise, the buffer provided by the -function @code{switch-to-prev-buffer} (@pxref{Window History}) is -displayed in the window instead. +all windows displaying it. @var{buffer-or-name} should be a buffer, +or the name of an existing buffer; if omitted or @code{nil}, it +defaults to the current buffer. + +The replacement buffer in each window is chosen via +@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated +window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated +Windows}), unless it is the only window on its frame---if it is the +only window, and that frame is not the only frame on its terminal, the +frame is ``dismissed'' by calling the function specified by +@code{frame-auto-hide-function} (@pxref{Quitting Windows}). If the +dedicated window is the only window on the only frame on its terminal, +the buffer is replaced anyway. @end deffn - @node Switching Buffers @section Switching to a Buffer in a Window @cindex switching to a buffer @@ -1731,9 +1552,12 @@ The @var{buffer-or-name} and @var{norecord} arguments have the same meanings as in @code{switch-to-buffer}. @end deffn -The above commands use @code{pop-to-buffer}, which is the function -used by Lisp programs to flexibly display a buffer in some window and -select that window for editing: +The above commands use the function @code{pop-to-buffer}, which +flexibly displays a buffer in some window and selects that window for +editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for +displaying the buffer. Hence, all the variables affecting +@code{display-buffer} will affect it as well. @xref{Choosing Window}, +for the documentation of @code{display-buffer}. @defun pop-to-buffer buffer-or-name &optional action norecord This function makes @var{buffer-or-name} the current buffer and @@ -1743,10 +1567,6 @@ on a different graphical frame, that frame is given input focus if possible (@pxref{Input Focus}). The return value is the buffer that was switched to. -This function uses @code{display-buffer} to display the buffer, so all -the variables affecting @code{display-buffer} will affect it as well. -@xref{Choosing Window}. - If @var{buffer-or-name} is @code{nil}, it defaults to the buffer returned by @code{other-buffer} (@pxref{The Buffer List}). If @var{buffer-or-name} is a string that is not the name of any existing @@ -1775,8 +1595,8 @@ used as a subroutine by many functions and commands, including Buffers}). @cindex display action -@cindex action function, for display-buffer -@cindex action alist, for display-buffer +@cindex action function, for @code{display-buffer} +@cindex action alist, for @code{display-buffer} This command performs several complex steps to find a window to display in. These steps are described by means of @dfn{display actions}, which have the form @code{(@var{function} . @var{alist})}. @@ -1815,6 +1635,11 @@ The variable @code{display-buffer-overriding-action}. The user option @code{display-buffer-alist}. @item +A special action for handling @code{special-display-buffer-names} and +@code{special-display-regexps}, if either of those variables is +non-@code{nil}. @xref{Choosing Window Options}. + +@item The @var{action} argument. @item @@ -1886,10 +1711,9 @@ This function tries to ``display'' @var{buffer} by finding a window that is already displaying it. If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, -the selected window is not eligible for reuse. - -If @var{alist} contains a @code{reusable-frames} entry, its value -determines which frames to search for a reusable window: +the selected window is not eligible for reuse. If @var{alist} +contains a @code{reusable-frames} entry, its value determines which +frames to search for a reusable window: @itemize @bullet @item @@ -1910,17 +1734,28 @@ normally searches just the selected frame; however, if either the variable @code{display-buffer-reuse-frames} or the variable @code{pop-up-frames} is non-@code{nil}, it searches all frames on the current terminal. @xref{Choosing Window Options}. + +If this function chooses a window on another frame, it makes that +frame visible and raises it if necessary. @end defun @defun display-buffer-pop-up-frame buffer alist This function creates a new frame, and displays the buffer in that -frame's window. +frame's window. It actually performs the frame creation by calling +the function specified in @code{pop-up-frame-function} +(@pxref{Choosing Window Options}). @end defun @defun display-buffer-pop-up-window buffer alist This function tries to display @var{buffer} by splitting the largest -or least recently-used window. It uses @code{split-window-sensibly} -as a subroutine (@pxref{Choosing Window Options}). +or least recently-used window (typically one on the selected frame). +It actually performs the split by calling the function specified in +@code{split-window-preferred-function} (@pxref{Choosing Window +Options}). + +It can fail if no window splitting can be performed for some reason +(e.g. if there is just one frame and it has an @code{unsplittable} +frame parameter; @pxref{Buffer Parameters}). @end defun @defun display-buffer-use-some-window buffer alist @@ -1937,142 +1772,108 @@ The behavior of the standard display actions of @code{display-buffer} options. @defopt display-buffer-reuse-frames -If this variable is non-@code{nil}, @code{display-buffer} searches -visible and iconified frames for a window displaying -@var{buffer-or-name}. If there is such a window, @code{display-buffer} -makes that window's frame visible and raises it if necessary, and -returns the window. If there is no such window or -@code{display-buffer-reuse-frames} is @code{nil}, the behavior of -@code{display-buffer} is determined by the variables described next. +If the value of this variable is non-@code{nil}, @code{display-buffer} +may search all frames on the current terminal when looking for a +window already displaying the specified buffer. The default is +@code{nil}. This variable is consulted by the action function +@code{display-buffer-reuse-window} (@pxref{Display Action Functions}). @end defopt @defopt pop-up-windows -This variable specifies whether @code{display-buffer} is allowed to -split (@pxref{Splitting Windows}) an existing window. If this variable -is non-@code{nil}, @code{display-buffer} tries to split the largest or -least recently used window on the selected frame. (If the selected -frame is a minibuffer-only frame, @code{display-buffer} tries to split a -window on another frame instead.) If this variable is @code{nil} or the -variable @code{pop-up-frames} (see below) is non-@code{nil}, -@code{display-buffer} does not split any window. +If the value of this variable is non-@code{nil}, @code{display-buffer} +is allowed to split an existing window to make a new window for +displaying in. This is the default. + +This variable is provided mainly for backward compatibility. It is +obeyed by @code{display-buffer} via a special mechanism in +@code{display-buffer-fallback-action}, which only calls the action +function @code{display-buffer-pop-up-window} (@pxref{Display Action +Functions}) when the value is @code{nil}. It is not consulted by +@code{display-buffer-pop-up-window} itself, which the user may specify +directly in @code{display-buffer-alist} etc. @end defopt @defopt split-window-preferred-function -This variable must specify a function with one argument, which is a -window. The @code{display-buffer} routines will call this function with -one or more candidate windows when they look for a window to split. The -function is expected to split that window and return the new window. If -the function returns @code{nil}, this means that the argument window -cannot (or shall not) be split. - -The default value of @code{split-window-preferred-function} is the -function @code{split-window-sensibly} described below. If you -customize this option, bear in mind that the @code{display-buffer} -routines may call your function up to two times when trying to split a -window. The argument of the first call is the largest window on the -chosen frame (as returned by @code{get-largest-window}). If that call -fails to return a live window, your function is called a second time -with the least recently used window on that frame (as returned by -@code{get-lru-window}). - -The function specified by this option may try to split any other window -instead of the argument window. Note that the window selected at the -time @code{display-buffer} was invoked is still selected when your -function is called. Hence, you can split the selected window (instead -of the largest or least recently used one) by simply ignoring the window -argument in the body of your function. You can even choose to not split -any window as long as the return value of your function specifies a live -window or @code{nil}, but you are not encouraged to do so -unconditionally. If you want @code{display-buffer} to never split any -windows, set @code{pop-up-windows} to @code{nil}. +This variable specifies a function for splitting a window, in order to +make a new window for displaying a buffer. It is used by the +@code{display-buffer-pop-up-window} action function to actually split +the window (@pxref{Display Action Functions}). + +The default value is @code{split-window-sensibly}, which is documented +below. The value must be a function that takes one argument, a +window, and return either a new window (which is used to display the +desired buffer) or @code{nil} (which means the splitting failed). @end defopt @defun split-window-sensibly window -This function takes a window as argument and tries to split that window -in a suitable way. The two variables described next are useful for -tuning the behavior of this function. +This function tries to split @code{window}, and return the newly +created window. If @code{window} cannot be split, it returns +@code{nil}. + +This function obeys the usual rules that determine when a window may +be split (@pxref{Splitting Windows}). It first tries to split by +placing the new window below, subject to the restriction imposed by +@code{split-height-threshold} (see below) in addition to any other +restrictions. If that fails, it tries to split by placing the new +window to the right, subject to @code{split-width-threshold} (see +below). If that fails, and the window is the only window on its +frame, this function again tries to split and place the new window +below, disregarding @code{split-height-threshold}. If this fails as +well, this function gives up and returns @code{nil}. @end defun @defopt split-height-threshold -This variable specifies whether @code{split-window-sensibly} may split -windows vertically. If it is an integer, @code{split-window-sensibly} -tries to vertically split a window only if it has at least this many -lines. If the window has less lines, splitting fails, or the value of -this variable is @code{nil}, @code{split-window-sensibly} will try to -split the window horizontally, subject to restrictions of -@code{split-width-threshold} (see below). If splitting horizontally -fails too and the window is the only window on its frame, -@code{split-window-sensibly} will try to split the window vertically -disregarding the value of @code{split-height-threshold}. If this fails -as well, @code{split-window-sensibly} returns @code{nil}. - -@code{split-window-sensibly} does not split vertically a window whose -height is fixed (@pxref{Resizing Windows}). Also, it vertically splits -a window only if the space taken up by that window can accommodate two -windows one above the other that are both at least -@code{window-min-height} lines tall. Moreover, if the window that shall -be split has a mode line, @code{split-window-sensibly} does not split -the window unless the new window can accommodate a mode line too. +This variable, used by @code{split-window-sensibly}, specifies whether +to split the window placing the new window below. If it is an +integer, that means to split only if the original window has at least +that many lines. If it is @code{nil}, that means not to split this +way. @end defopt @defopt split-width-threshold -This variable specifies whether @code{split-window-sensibly} may split -windows horizontally. If it is an integer, @code{split-window-sensibly} -tries to horizontally split a window only if it has at least this many -columns. If it is @code{nil}, @code{split-window-sensibly} will not -split the window horizontally. (It still might split the window -vertically, though, see above.) - -@code{split-window-sensibly} does not split horizontally a window if -that window's width is fixed (@pxref{Resizing Windows}). Also, it -horizontally splits a window only if the space that window takes up can -accommodate two windows side by side that are both at least -@code{window-min-width} columns wide. +This variable, used by @code{split-window-sensibly}, specifies whether +to split the window placing the new window to the right. If the value +is an integer, that means to split only if the original window has at +least that many columns. If the value is @code{nil}, that means not +to split this way. @end defopt -@defopt even-window-heights -This variable specifies whether @code{display-buffer} should even out -window heights if the buffer gets displayed in an existing window, above -or beneath another window. If @code{even-window-heights} is -non-@code{nil}, the default, window heights will be evened out. If -either of the involved window has fixed height (@pxref{Resizing -Windows}) or @code{even-window-heights} is @code{nil}, the original -window heights will be left alone. -@end defopt - -@c Emacs 19 feature @defopt pop-up-frames -This variable specifies whether @code{display-buffer} should make new -frames. If it is non-@code{nil}, @code{display-buffer} looks for a -window already displaying @var{buffer-or-name} on any visible or -iconified frame. If it finds such a window, it makes that window's -frame visible and raises it if necessary, and returns the window. -Otherwise it makes a new frame, unless the variable's value is -@code{graphic-only} and the selected frame is not on a graphic display. -@xref{Frames}, for more information. - -Note that the value of @code{pop-up-windows} does not matter if -@code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is -@code{nil}, then @code{display-buffer} either splits a window or reuses -one. +If the value of this variable is non-@code{nil}, that means +@code{display-buffer} may display buffers by making new frames. The +default is @code{nil}. + +A non-@code{nil} value also means that when @code{display-buffer} is +looking for a window already displaying @var{buffer-or-name}, it can +search any visible or iconified frame, not just the selected frame. + +This variable is provided mainly for backward compatibility. It is +obeyed by @code{display-buffer} via a special mechanism in +@code{display-buffer-fallback-action}, which calls the action function +@code{display-buffer-pop-up-frame} (@pxref{Display Action Functions}) +if the value is non-@code{nil}. (This is done before attempting to +split a window.) This variable is not consulted by +@code{display-buffer-pop-up-frame} itself, which the user may specify +directly in @code{display-buffer-alist} etc. @end defopt -@c Emacs 19 feature @defopt pop-up-frame-function -This variable specifies how to make a new frame if @code{pop-up-frames} -is non-@code{nil}. - -The value of this variable must be a function of no arguments. When -@code{display-buffer} makes a new frame, it does so by calling that -function, which should return a frame. The default value of this -variable is a function that creates a frame using the parameters -specified by @code{pop-up-frame-alist} described next. +This variable specifies a function for creating a new frame, in order +to make a new window for displaying a buffer. It is used by the +@code{display-buffer-pop-up-frame} action function (@pxref{Display +Action Functions}). + +The value should be a function that takes no arguments and returns a +frame, or @code{nil} if no frame could be created. The default value +is a function that creates a frame using the parameters specified by +@code{pop-up-frame-alist} (see below). @end defopt @defopt pop-up-frame-alist -This variable holds an alist specifying frame parameters used by the -default value of @code{pop-up-frame-function} for making new frames. -@xref{Frame Parameters}, for more information about frame parameters. +This variable holds an alist of frame parameters (@pxref{Frame +Parameters}), which is used by the default function in +@code{pop-up-frame-function} to make a new frame. The default is +@code{nil}. @end defopt @defopt special-display-buffer-names @@ -2193,12 +1994,6 @@ This variable takes precedence over all the other options described above. @end defopt -If all options described above fail to produce a suitable window, -@code{display-buffer} tries to reuse an existing window. As a last -resort, it will try to display @var{buffer-or-name} on a separate frame. -In that case, the value of @code{pop-up-frames} is disregarded. - - @node Window History @section Window History @cindex window history @@ -3129,32 +2924,90 @@ is off the screen due to horizontal scrolling: @end group @end example - @node Coordinates and Windows @section Coordinates and Windows +@cindex frame-relative coordinate +@cindex coordinate, relative to frame +@cindex window position -This section describes how to relate screen coordinates to windows. + This section describes functions that report the position of a +window. Most of these functions report positions relative to the +window's frame. In this case, the coordinate origin @samp{(0,0)} lies +near the upper left corner of the frame. For technical reasons, on +graphical displays the origin is not located at the exact corner of +the graphical window as it appears on the screen. If Emacs is built +with the GTK+ toolkit, the origin is at the upper left corner of the +frame area used for displaying Emacs windows, below the title-bar, +GTK+ menu bar, and tool bar (since these are drawn by the window +manager and/or GTK+, not by Emacs). But if Emacs is not built with +GTK+, the origin is at the upper left corner of the tool bar (since in +this case Emacs itself draws the tool bar). In both cases, the X and +Y coordinates increase rightward and downward respectively. + + Except where noted, X and Y coordinates are reported in integer +character units, i.e. numbers of lines and columns respectively. On a +graphical display, each ``line'' and ``column'' corresponds to the +height and width of a default character specified by the frame's +default font. + +@defun window-edges &optional window +This function returns a list of the edge coordinates of @var{window}. +If @var{window} is omitted or @code{nil}, it defaults to the selected +window. -@defun window-at x y &optional frame -This function returns the window containing the specified cursor -position in the frame @var{frame}. The coordinates @var{x} and @var{y} -are measured in characters and count from the top left corner of the -frame. If they are out of range, @code{window-at} returns @code{nil}. +The return value has the form @code{(@var{left} @var{top} @var{right} +@var{bottom})}. These list elements are, respectively, the X +coordinate of the leftmost column occupied by the window, the Y +coordinate of the topmost row, the X coordinate one column to the +right of the rightmost column, and the Y coordinate one row down from +the bottommost row. -If you omit @var{frame}, the selected frame is used. +Note that these are the actual outer edges of the window, including +any header line, mode line, scroll bar, fringes, and display margins. +On a text-only terminal, if the window has a neighbor on its right, +its right edge includes the separator line between the window and its +neighbor. @end defun -@defun coordinates-in-window-p coordinates window -This function checks whether a particular frame position falls within -the window @var{window}. +@defun window-inside-edges &optional window +This function is similar to @code{window-edges}, but the returned edge +values are for the text area of the window. They exclude any header +line, mode line, scroll bar, fringes, display margins, and vertical +separator. +@end defun + +@defun window-top-line &optional window +This function returns the Y coordinate of the topmost row of +@var{window}, equivalent to the @var{top} entry in the list returned +by @code{window-edges}. +@end defun + +@defun window-left-column &optional window +This function returns the X coordinate of the leftmost column of +@var{window}, equivalent to the @var{left} entry in the list returned +by @code{window-edges}. +@end defun + + The following functions can be used to relate a set of +frame-relative coordinates to a window: -The argument @var{coordinates} is a cons cell of the form @code{(@var{x} -. @var{y})}. The coordinates @var{x} and @var{y} are measured in -characters, and count from the top left corner of the screen or frame. +@defun window-at x y &optional frame +This function returns the live window at the frame-relative +coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no +window at that position, the return value is @code{nil}. If +@var{frame} is omitted or @code{nil}, it defaults to the selected +frame. +@end defun + +@defun coordinates-in-window-p coordinates window +This function checks whether a window @var{window} occupies the +frame-relative coordinates @var{coordinates}, and if so which part of +the window that is. @var{window} should be a live window. +@var{coordinates} should be a cons cell of the form @code{(@var{x} +. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates. -The value returned by @code{coordinates-in-window-p} is non-@code{nil} -if the coordinates are inside @var{window}. The value also indicates -what part of the window the position is in, as follows: +If there is no window at the specified position, the return value is +@code{nil} . Otherwise, the return value is one of the following: @table @code @item (@var{relx} . @var{rely}) @@ -3191,6 +3044,44 @@ The function @code{coordinates-in-window-p} does not require a frame as argument because it always uses the frame that @var{window} is on. @end defun + The following functions return window positions in pixels, rather +than character units. Though mostly useful on graphical displays, +they can also be called on text-only terminals, where the screen area +of each text character is taken to be ``one pixel''. + +@defun window-pixel-edges &optional window +This function returns a list of pixel coordinates for the edges of +@var{window}. If @var{window} is omitted or @code{nil}, it defaults +to the selected window. + +The return value has the form @code{(@var{left} @var{top} @var{right} +@var{bottom})}. The list elements are, respectively, the X pixel +coordinate of the left window edge, the Y pixel coordinate of the top +edge, one more than the X pixel coordinate of the right edge, and one +more than the Y pixel coordinate of the bottom edge. +@end defun + +@defun window-inside-pixel-edges &optional window +This function is like @code{window-pixel-edges}, except that it +returns the pixel coordinates for the edges of the window's text area, +rather than the pixel coordinates for the edges of the window itself. +@var{window} must specify a live window. +@end defun + + The following functions return window positions in pixels, relative +to the display screen rather than the frame: + +@defun window-absolute-pixel-edges &optional window +This function is like @code{window-pixel-edges}, except that it +returns the edge pixel coordinates relative to the top left corner of +the display screen. +@end defun + +@defun window-inside-absolute-pixel-edges &optional window +This function is like @code{window-inside-pixel-edges}, except that it +returns the edge pixel coordinates relative to the top left corner of +the display screen. @var{window} must specify a live window. +@end defun @node Window Configurations @section Window Configurations diff --git a/doc/man/emacs.1 b/doc/man/emacs.1 index 91ef4189b79..1acdcf5ebd2 100644 --- a/doc/man/emacs.1 +++ b/doc/man/emacs.1 @@ -1,5 +1,5 @@ .\" See section COPYING for copyright and redistribution information. -.TH EMACS 1 "2007 April 13" "GNU Emacs 24.0.91" +.TH EMACS 1 "2007 April 13" "GNU Emacs 24.0.92" . . .SH NAME diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 924f3501bfa..5d8e05806e0 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,31 @@ +2011-12-06 Juanma Barranquero <lekktu@gmail.com> + + * gnus-faq.texi (FAQ 2-1, FAQ 3-8, FAQ 4-14, FAQ 9-1): Fix typos. + +2011-11-24 Glenn Morris <rgm@gnu.org> + + * gnus.texi, smtpmail.texi: Fix case of "GnuTLS". + +2011-11-24 Juanma Barranquero <lekktu@gmail.com> + + * makefile.w32-in: Update dependencies. + +2011-11-20 Glenn Morris <rgm@gnu.org> + + * gnus.texi (Group Information): + Remove gnus-group-fetch-faq, command deleted 2010-09-24. + +2011-11-20 Juanma Barranquero <lekktu@gmail.com> + + * gnus-coding.texi (Gnus Maintenance Guide): + Rename from "Gnus Maintainance Guide". + + * ede.texi (ede-compilation-program, ede-compiler, ede-linker): + * eieio.texi (Customizing): + * gnus.texi (Article Washing): + * gnus-news.texi: + * sem-user.texi (Smart Jump): Fix typos. + 2011-11-16 Juanma Barranquero <lekktu@gmail.com> * org.texi (Agenda commands, Exporting Agenda Views): Fix typos. @@ -2971,7 +2999,7 @@ * org.texi (Activation, Exporting, ASCII export, HTML export) (HTML Export commands, LaTeX/PDF export commands): Improve documentation about transient-mark-mode. - (References): DOcuemtn the use of special names like $LR1 to reference + (References): Document the use of special names like $LR1 to reference to fields in the last table row. 2008-12-19 Juri Linkov <juri@jurta.org> @@ -7958,7 +7986,7 @@ 2003-02-01 Michael Albinus <Michael.Albinus@alcatel.de> * tramp.texi (Frequently Asked Questions): Explain a workaround if - another package loads accidently Ange-FTP. + another package loads accidentally Ange-FTP. 2003-01-24 Michael Albinus <Michael.Albinus@alcatel.de> diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index 2e66c78a3cb..289c08eb00e 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -156,7 +156,7 @@ the point is normally left after that skeleton is inserted (@pxref{Using Skeletons}). The point (@pxref{(emacs)Point}) is left at the next interesting spot in the skeleton instead. - A negative prefix means to do something similar with that many precedingly + A negative prefix means to do something similar with that many previously marked interregions (@pxref{(emacs)Mark}). In the simplest case, if you type @kbd{M--} just before issuing the skeleton command, that will wrap the skeleton around the current region, just like a positive argument would have @@ -419,7 +419,7 @@ inserting something. When this is @code{nil}, inserting is only done with @kbd{M-x auto-insert}. When this is @code{function}, you are queried whenever @code{auto-insert} is called as a function, such as when Emacs visits an empty file and you have set the above-mentioned hook. Otherwise -you are alway queried. +you are always queried. @vindex auto-insert-prompt When querying, the variable @code{auto-insert-prompt}'s value is used as a @@ -510,7 +510,7 @@ inserting or updating the magic number. When this is @code{nil} updating is only done with @kbd{M-x executable-set-magic}. When this is @code{function} you are queried whenever @code{executable-set-magic} is called as a function, such as when Emacs puts a buffer in Shell script -mode. Otherwise you are alway queried. +mode. Otherwise you are always queried. @findex executable-self-display @kbd{M-x executable-self-display} adds a magic number to the buffer, which diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index 5a1ee872a2b..535efd86270 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -90,7 +90,7 @@ This file documents Calc, the GNU Emacs calculator. @end ifinfo @ifnotinfo -This file documents Calc, the GNU Emacs calculator, included with +This file documents Calc, the GNU Emacs calculator, included with GNU Emacs @value{EMACSVER}. @end ifnotinfo @@ -324,7 +324,7 @@ need to know. @c @cindex Marginal notes Every Calc keyboard command is listed in the Calc Summary, and also in the Key Index. Algebraic functions, @kbd{M-x} commands, and -variables also have their own indices. +variables also have their own indices. @c @texline Each @c @infoline In the printed manual, each @c paragraph that is referenced in the Key or Function Index is marked @@ -338,7 +338,7 @@ the @kbd{h i} key sequence. Outside of the Calc window, you can press command @kbd{C-x * t} will jump to the Tutorial and start Calc if necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly to the Calc Summary. Within Calc, you can also go to the part of the -manual describing any Calc key, function, or variable using +manual describing any Calc key, function, or variable using @w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}. @ifnottex @@ -437,12 +437,12 @@ Delete, and Space keys. then the command to operate on the numbers. @noindent -Type @kbd{2 @key{RET} 3 + Q} to compute +Type @kbd{2 @key{RET} 3 + Q} to compute @texline @math{\sqrt{2+3} = 2.2360679775}. @infoline the square root of 2+3, which is 2.2360679775. @noindent -Type @kbd{P 2 ^} to compute +Type @kbd{P 2 ^} to compute @texline @math{\pi^2 = 9.86960440109}. @infoline the value of `pi' squared, 9.86960440109. @@ -461,14 +461,14 @@ conventional ``algebraic'' notation. To enter an algebraic formula, use the apostrophe key. @noindent -Type @kbd{' sqrt(2+3) @key{RET}} to compute +Type @kbd{' sqrt(2+3) @key{RET}} to compute @texline @math{\sqrt{2+3}}. @infoline the square root of 2+3. @noindent -Type @kbd{' pi^2 @key{RET}} to enter +Type @kbd{' pi^2 @key{RET}} to enter @texline @math{\pi^2}. -@infoline `pi' squared. +@infoline `pi' squared. To evaluate this symbolic formula as a number, type @kbd{=}. @noindent @@ -526,10 +526,10 @@ the upper-leftmost @samp{1} and set the mark, then move to just after the lower-right @samp{8} and press @kbd{C-x * r}. @noindent -Type @kbd{v t} to transpose this +Type @kbd{v t} to transpose this @texline @math{3\times2} -@infoline 3x2 -matrix into a +@infoline 3x2 +matrix into a @texline @math{2\times3} @infoline 2x3 matrix. Type @w{@kbd{v u}} to unpack the rows into two separate @@ -605,7 +605,7 @@ there are Quick mode, Keypad mode, and Embedded mode. @noindent On most systems, you can type @kbd{C-x *} to start the Calculator. -The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch}, +The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch}, which can be rebound if convenient (@pxref{Customizing Calc}). When you press @kbd{C-x *}, Emacs waits for you to press a second key to @@ -1154,9 +1154,9 @@ its initial state: Empty stack, and initial mode settings. @noindent Calc was originally started as a two-week project to occupy a lull in the author's schedule. Basically, a friend asked if I remembered -the value of +the value of @texline @math{2^{32}}. -@infoline @expr{2^32}. +@infoline @expr{2^32}. I didn't offhand, but I said, ``that's easy, just call up an @code{xcalc}.'' @code{Xcalc} duly reported that the answer to our question was @samp{4.294967e+09}---with no way to see the full ten @@ -1213,7 +1213,7 @@ algebra system for microcomputers. Many people have contributed to Calc by reporting bugs and suggesting features, large and small. A few deserve special mention: Tim Peters, who helped develop the ideas that led to the selection commands, rewrite -rules, and many other algebra features; +rules, and many other algebra features; @texline Fran\c{c}ois @infoline Francois Pinard, who contributed an early prototype of the Calc Summary appendix @@ -1226,7 +1226,7 @@ Randal Schwartz, who suggested the @code{calc-eval} function; Juha Sarlin, who first worked out how to split Calc into quickly-loading parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and Robert J. Chassell, who suggested the Calc Tutorial and exercises as -well as many other things. +well as many other things. @cindex Bibliography @cindex Knuth, Art of Computer Programming @@ -1472,9 +1472,9 @@ Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2 multiplication.) Figure it out by hand, then try it with Calc to see if you're right. @xref{RPN Answer 1, 1}. (@bullet{}) -(@bullet{}) @strong{Exercise 2.} Compute +(@bullet{}) @strong{Exercise 2.} Compute @texline @math{(2\times4) + (7\times9.4) + {5\over4}} -@infoline @expr{2*4 + 7*9.5 + 5/4} +@infoline @expr{2*4 + 7*9.5 + 5/4} using the stack. @xref{RPN Answer 2, 2}. (@bullet{}) The @key{DEL} key is called Backspace on some keyboards. It is @@ -1889,7 +1889,7 @@ intermediate results of a calculation as you go along. You can accomplish this in Calc by performing your calculation as a series of algebraic entries, using the @kbd{$} sign to tie them together. In an algebraic formula, @kbd{$} represents the number on the top -of the stack. Here, we perform the calculation +of the stack. Here, we perform the calculation @texline @math{\sqrt{2\times4+1}}, @infoline @expr{sqrt(2*4+1)}, which on a traditional calculator would be done by pressing @@ -2149,7 +2149,7 @@ key. If you type a prefix key by accident, you can press @kbd{C-g} to cancel it. (In fact, you can press @kbd{C-g} to cancel almost anything in Emacs.) To get help on a prefix key, press that key followed by @kbd{?}. Some prefixes have several lines of help, -so you need to press @kbd{?} repeatedly to see them all. +so you need to press @kbd{?} repeatedly to see them all. You can also type @kbd{h h} to see all the help at once. Try pressing @kbd{t ?} now. You will see a line of the form, @@ -2550,13 +2550,13 @@ angle is measured in degrees. For example, @noindent The shift-@kbd{S} command computes the sine of an angle. The sine -of 45 degrees is +of 45 degrees is @texline @math{\sqrt{2}/2}; -@infoline @expr{sqrt(2)/2}; +@infoline @expr{sqrt(2)/2}; squaring this yields @expr{2/4 = 0.5}. However, there has been a slight -roundoff error because the representation of +roundoff error because the representation of @texline @math{\sqrt{2}/2} -@infoline @expr{sqrt(2)/2} +@infoline @expr{sqrt(2)/2} wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers in this case; it temporarily reduces the precision by one digit while it re-rounds the number on the top of the stack. @@ -2595,9 +2595,9 @@ either radians or degrees, depending on the current angular mode. @end smallexample @noindent -Here we compute the Inverse Sine of +Here we compute the Inverse Sine of @texline @math{\sqrt{0.5}}, -@infoline @expr{sqrt(0.5)}, +@infoline @expr{sqrt(0.5)}, first in radians, then in degrees. Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees @@ -2783,9 +2783,9 @@ logarithm). These can be modified by the @kbd{I} (inverse) and @kbd{H} (hyperbolic) prefix keys. Let's compute the sine and cosine of an angle, and verify the -identity +identity @texline @math{\sin^2x + \cos^2x = 1}. -@infoline @expr{sin(x)^2 + cos(x)^2 = 1}. +@infoline @expr{sin(x)^2 + cos(x)^2 = 1}. We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}. With the angular mode set to degrees (type @w{@kbd{m d}}), do: @@ -2806,7 +2806,7 @@ You can of course do these calculations to any precision you like.) Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum of squares, command. -Another identity is +Another identity is @texline @math{\displaystyle\tan x = {\sin x \over \cos x}}. @infoline @expr{tan(x) = sin(x) / cos(x)}. @smallexample @@ -2871,7 +2871,7 @@ the top two stack elements right after the @kbd{U U}, then a pair of A similar identity is supposed to hold for hyperbolic sines and cosines, except that it is the @emph{difference} @texline @math{\cosh^2x - \sinh^2x} -@infoline @expr{cosh(x)^2 - sinh(x)^2} +@infoline @expr{cosh(x)^2 - sinh(x)^2} that always equals one. Let's try to verify this identity. @smallexample @@ -2993,7 +2993,7 @@ factorial function defined in terms of Euler's Gamma function @end smallexample @noindent -Here we verify the identity +Here we verify the identity @texline @math{n! = \Gamma(n+1)}. @infoline @expr{@var{n}!@: = gamma(@var{n}+1)}. @@ -3283,11 +3283,11 @@ rows in the matrix is different from the number of elements in the vector. (@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows -of the above +of the above @texline @math{2\times3} -@infoline 2x3 +@infoline 2x3 matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns -to get @expr{[5, 7, 9]}. +to get @expr{[5, 7, 9]}. @xref{Matrix Answer 1, 1}. (@bullet{}) @cindex Identity matrix @@ -3432,7 +3432,7 @@ the matrix and vector. If we multiplied in the other order, Calc would assume the vector was a row vector in order to make the dimensions come out right, and the answer would be incorrect. If you don't feel safe letting Calc take either interpretation of your -vectors, use explicit +vectors, use explicit @texline @math{N\times1} @infoline Nx1 or @@ -3482,9 +3482,9 @@ on the left by the transpose of @expr{A}: @tex $A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}. @end tex -Now +Now @texline @math{A^T A} -@infoline @expr{trn(A)*A} +@infoline @expr{trn(A)*A} is a square matrix so a solution is possible. It turns out that the @expr{X} vector you compute in this way will be a ``least-squares'' solution, which can be regarded as the ``closest'' solution to the set @@ -3577,9 +3577,9 @@ other a plain number.) In the final step, we take the square root of each element. (@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two -from +from @texline @math{2^{-4}} -@infoline @expr{2^-4} +@infoline @expr{2^-4} to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{}) You can also @dfn{reduce} a binary operator across a vector. @@ -3780,9 +3780,9 @@ $$ m = {N \sum x y - \sum x \sum y \over @end tex @noindent -where +where @texline @math{\sum x} -@infoline @expr{sum(x)} +@infoline @expr{sum(x)} represents the sum of all the values of @expr{x}. While there is an actual @code{sum} function in Calc, it's easier to sum a vector using a simple reduction. First, let's compute the four different sums that @@ -3883,9 +3883,9 @@ $$ b = {\sum y - m \sum x \over N} $$ @end group @end smallexample -Let's ``plot'' this straight line approximation, +Let's ``plot'' this straight line approximation, @texline @math{y \approx m x + b}, -@infoline @expr{m x + b}, +@infoline @expr{m x + b}, and compare it with the original data. @smallexample @@ -3959,7 +3959,7 @@ Next, let's add the line we got from our least-squares fit. (If you are reading this tutorial on-line while running Calc, typing @kbd{g a} may cause the tutorial to disappear from its window and be replaced by a buffer named @samp{*Gnuplot Commands*}. The tutorial -will reappear when you terminate GNUPLOT by typing @kbd{g q}.) +will reappear when you terminate GNUPLOT by typing @kbd{g q}.) @end ifinfo @smallexample @@ -4138,7 +4138,7 @@ command to enable multi-line display of vectors.) @c [fix-ref Numerical Solutions] (@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's @texline @math{J_1(x)} -@infoline @expr{J1} +@infoline @expr{J1} function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25. Find the value of @expr{x} (from among the above set of values) for which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method, @@ -4150,7 +4150,7 @@ of thing automatically; @pxref{Numerical Solutions}.) @cindex Digits, vectors of (@bullet{}) @strong{Exercise 9.} You are given an integer in the range @texline @math{0 \le N < 10^m} -@infoline @expr{0 <= N < 10^m} +@infoline @expr{0 <= N < 10^m} for @expr{m=12} (i.e., an integer of less than twelve digits). Convert this integer into a vector of @expr{m} digits, each in the range from 0 to 9. In vector-of-digits notation, @@ -4164,12 +4164,12 @@ to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{}) happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{}) (@bullet{}) @strong{Exercise 11.} The area of a circle of radius one -is @cpi{}. The area of the +is @cpi{}. The area of the @texline @math{2\times2} @infoline 2x2 square that encloses that circle is 4. So if we throw @var{n} darts at random points in the square, about @cpiover{4} of them will land inside -the circle. This gives us an entertaining way to estimate the value of +the circle. This gives us an entertaining way to estimate the value of @cpi{}. The @w{@kbd{k r}} command picks a random number between zero and the value on the stack. We could get a random floating-point number between @mathit{-1} and 1 by typing @@ -4183,12 +4183,12 @@ points lie inside the unit circle. Hint: Use the @kbd{v b} command. another way to calculate @cpi{}. Say you have an infinite field of vertical lines with a spacing of one inch. Toss a one-inch matchstick onto the field. The probability that the matchstick will land crossing -a line turns out to be +a line turns out to be @texline @math{2/\pi}. -@infoline @expr{2/pi}. +@infoline @expr{2/pi}. Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun, the probability that the GCD (@w{@kbd{k g}}) of two large integers is -one turns out to be +one turns out to be @texline @math{6/\pi^2}. @infoline @expr{6/pi^2}. That provides yet another way to estimate @cpi{}.) @@ -4488,7 +4488,7 @@ a 60% chance that the result is correct within 0.59 degrees. @cindex Torus, volume of (@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is @texline @math{2 \pi^2 R r^2} -@infoline @w{@expr{2 pi^2 R r^2}} +@infoline @w{@expr{2 pi^2 R r^2}} where @expr{R} is the radius of the circle that defines the center of the tube and @expr{r} is the radius of the tube itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to @@ -4569,7 +4569,7 @@ In this last step, Calc has divided by 5 modulo 24; i.e., it has found a new number which, when multiplied by 5 modulo 24, produces the original number, 21. If @var{m} is prime and the divisor is not a multiple of @var{m}, it is always possible to find such a number. For non-prime -@var{m} like 24, it is only sometimes possible. +@var{m} like 24, it is only sometimes possible. @smallexample @group @@ -4587,7 +4587,7 @@ that arises in the second one. @cindex Fermat, primality test of (@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat -says that +says that @texline @w{@math{x^{n-1} \bmod n = 1}} @infoline @expr{x^(n-1) mod n = 1} if @expr{n} is a prime number and @expr{x} is an integer less than @@ -4615,9 +4615,9 @@ of day on the stack as an HMS/modulo form. This calculation tells me it is six hours and 22 minutes until midnight. (@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year -is about +is about @texline @math{\pi \times 10^7} -@infoline @w{@expr{pi * 10^7}} +@infoline @w{@expr{pi * 10^7}} seconds. What time will it be that many seconds from right now? @xref{Types Answer 11, 11}. (@bullet{}) @@ -5093,18 +5093,18 @@ One way to do it is again with vector mapping and reduction: @end smallexample (@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y} -of +of @texline @math{x \sin \pi x} -@infoline @w{@expr{x sin(pi x)}} +@infoline @w{@expr{x sin(pi x)}} (where the sine is calculated in radians). Find the values of the integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3, 3}. (@bullet{}) Calc's integrator can do many simple integrals symbolically, but many others are beyond its capabilities. Suppose we wish to find the area -under the curve +under the curve @texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} +@infoline @expr{sin(x) ln(x)} over the same range of @expr{x}. If you entered this formula and typed @kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a long time but would be unable to find a solution. In fact, there is no @@ -5242,10 +5242,10 @@ $$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots \afterdisplay @end tex -Compute the integral from 1 to 2 of +Compute the integral from 1 to 2 of @texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} -using Simpson's rule with 10 slices. +@infoline @expr{sin(x) ln(x)} +using Simpson's rule with 10 slices. @xref{Algebra Answer 4, 4}. (@bullet{}) Calc has a built-in @kbd{a I} command for doing numerical integration. @@ -5396,7 +5396,7 @@ having to retype it. To edit a variable, type @kbd{s e} and the variable name, use regular Emacs editing commands as necessary, then type @kbd{C-c C-c} to store -the edited value back into the variable. +the edited value back into the variable. You can also use @w{@kbd{s e}} to create a new variable if you wish. Notice that the first time you use each rule, Calc puts up a ``compiling'' @@ -5780,7 +5780,7 @@ in @samp{a + 1} for @samp{x} in the defining formula. @tindex Si (@bullet{}) @strong{Exercise 1.} The ``sine integral'' function @texline @math{{\rm Si}(x)} -@infoline @expr{Si(x)} +@infoline @expr{Si(x)} is defined as the integral of @samp{sin(t)/t} for @expr{t = 0} to @expr{x} in radians. (It was invented because this integral has no solution in terms of basic functions; if you give it @@ -5857,9 +5857,9 @@ the following functions: @enumerate @item -Compute +Compute @texline @math{\displaystyle{\sin x \over x}}, -@infoline @expr{sin(x) / x}, +@infoline @expr{sin(x) / x}, where @expr{x} is the number on the top of the stack. @item @@ -5923,15 +5923,15 @@ key if you have one, makes a copy of the number in level 2.) @cindex Golden ratio @cindex Phi, golden ratio A fascinating property of the Fibonacci numbers is that the @expr{n}th -Fibonacci number can be found directly by computing +Fibonacci number can be found directly by computing @texline @math{\phi^n / \sqrt{5}} @infoline @expr{phi^n / sqrt(5)} -and then rounding to the nearest integer, where +and then rounding to the nearest integer, where @texline @math{\phi} (``phi''), -@infoline @expr{phi}, -the ``golden ratio,'' is +@infoline @expr{phi}, +the ``golden ratio,'' is @texline @math{(1 + \sqrt{5}) / 2}. -@infoline @expr{(1 + sqrt(5)) / 2}. +@infoline @expr{(1 + sqrt(5)) / 2}. (For convenience, this constant is available from the @code{phi} variable, or the @kbd{I H P} command.) @@ -5946,19 +5946,19 @@ variable, or the @kbd{I H P} command.) @cindex Continued fractions (@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction} -representation of +representation of @texline @math{\phi} -@infoline @expr{phi} -is +@infoline @expr{phi} +is @texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}. @infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}. We can compute an approximate value by carrying this however far -and then replacing the innermost +and then replacing the innermost @texline @math{1/( \ldots )} -@infoline @expr{1/( ...@: )} +@infoline @expr{1/( ...@: )} by 1. Approximate @texline @math{\phi} -@infoline @expr{phi} +@infoline @expr{phi} using a twenty-term continued fraction. @xref{Programming Answer 5, 5}. (@bullet{}) @@ -6056,9 +6056,9 @@ survive past the @kbd{Z '} command. The @dfn{Bernoulli numbers} are a sequence with the interesting property that all of the odd Bernoulli numbers are zero, and the even ones, while difficult to compute, can be roughly approximated -by the formula +by the formula @texline @math{\displaystyle{2 n! \over (2 \pi)^n}}. -@infoline @expr{2 n!@: / (2 pi)^n}. +@infoline @expr{2 n!@: / (2 pi)^n}. Let's write a keyboard macro to compute (approximate) Bernoulli numbers. (Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but this command is very slow for large @expr{n} since the higher Bernoulli @@ -6166,7 +6166,7 @@ Z` ;; calc-kbd-push (Save local values) 0 ;; calc digits (Push a zero onto the stack) st ;; calc-store-into (Store it in the following variable) 1 ;; calc quick variable (Quick variable q1) -1 ;; calc digits (Initial value for the loop) +1 ;; calc digits (Initial value for the loop) TAB ;; calc-roll-down (Swap initial and final) Z( ;; calc-kbd-for (Begin the "for" loop) & ;; calc-inv (Take the reciprocal) @@ -6193,10 +6193,10 @@ Press @kbd{C-c C-c} to finish editing and return to the Calculator. The @file{edmacro} package defines a handy @code{read-kbd-macro} command which reads the current region of the current buffer as a sequence of -keystroke names, and defines that sequence on the @kbd{X} +keystroke names, and defines that sequence on the @kbd{X} (and @kbd{C-x e}) key. Because this is so useful, Calc puts this command on the @kbd{C-x * m} key. Try reading in this macro in the -following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at +following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at one end of the text below, then type @kbd{C-x * m} at the other. @example @@ -6230,12 +6230,12 @@ $$ x_{\rm new} = x - {f(x) \over f^{\prime}(x)} $$ where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x} values will quickly converge to a solution, i.e., eventually @texline @math{x_{\rm new}} -@infoline @expr{new_x} +@infoline @expr{new_x} and @expr{x} will be equal to within the limits of the current precision. Write a program which takes a formula involving the variable @expr{x}, and an initial guess @expr{x_0}, on the stack, and produces a value of @expr{x} for which the formula -is zero. Use it to find a solution of +is zero. Use it to find a solution of @texline @math{\sin(\cos x) = 0.5} @infoline @expr{sin(cos(x)) = 0.5} near @expr{x = 4.5}. (Use angles measured in radians.) Note that @@ -6245,12 +6245,12 @@ method when it is able. @xref{Programming Answer 8, 8}. (@bullet{}) @cindex Digamma function @cindex Gamma constant, Euler's @cindex Euler's gamma constant -(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function +(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function @texline @math{\psi(z) (``psi'')} @infoline @expr{psi(z)} -is defined as the derivative of +is defined as the derivative of @texline @math{\ln \Gamma(z)}. -@infoline @expr{ln(gamma(z))}. +@infoline @expr{ln(gamma(z))}. For large values of @expr{z}, it can be approximated by the infinite sum @ifnottex @@ -6267,9 +6267,9 @@ $$ @end tex @noindent -where +where @texline @math{\sum} -@infoline @expr{sum} +@infoline @expr{sum} represents the sum over @expr{n} from 1 to infinity (or to some limit high enough to give the desired accuracy), and the @code{bern} function produces (exact) Bernoulli numbers. @@ -6277,27 +6277,27 @@ While this sum is not guaranteed to converge, in practice it is safe. An interesting mathematical constant is Euler's gamma, which is equal to about 0.5772. One way to compute it is by the formula, @texline @math{\gamma = -\psi(1)}. -@infoline @expr{gamma = -psi(1)}. +@infoline @expr{gamma = -psi(1)}. Unfortunately, 1 isn't a large enough argument for the above formula to work (5 is a much safer value for @expr{z}). -Fortunately, we can compute +Fortunately, we can compute @texline @math{\psi(1)} -@infoline @expr{psi(1)} -from +@infoline @expr{psi(1)} +from @texline @math{\psi(5)} -@infoline @expr{psi(5)} -using the recurrence +@infoline @expr{psi(5)} +using the recurrence @texline @math{\psi(z+1) = \psi(z) + {1 \over z}}. -@infoline @expr{psi(z+1) = psi(z) + 1/z}. -Your task: Develop a program to compute +@infoline @expr{psi(z+1) = psi(z) + 1/z}. +Your task: Develop a program to compute @texline @math{\psi(z)}; -@infoline @expr{psi(z)}; +@infoline @expr{psi(z)}; it should ``pump up'' @expr{z} if necessary to be greater than 5, then use the above summation formula. Use looping commands to compute the sum. Use your function -to compute +to compute @texline @math{\gamma} -@infoline @expr{gamma} +@infoline @expr{gamma} to twelve decimal places. (Calc has a built-in command for Euler's constant, @kbd{I P}, which you can use to check your answer.) @xref{Programming Answer 9, 9}. (@bullet{}) @@ -6470,7 +6470,7 @@ This section includes answers to all the exercises in the Calc tutorial. @noindent @kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -} -The result is +The result is @texline @math{1 - (2 \times (3 + 4)) = -13}. @infoline @expr{1 - (2 * (3 + 4)) = -13}. @@ -6481,9 +6481,9 @@ The result is @texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75} @infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75} -After computing the intermediate term +After computing the intermediate term @texline @math{2\times4 = 8}, -@infoline @expr{2*4 = 8}, +@infoline @expr{2*4 = 8}, you can leave that result on the stack while you compute the second term. With both of these results waiting on the stack you can then compute the final term, then press @kbd{+ +} to add everything up. @@ -6790,7 +6790,7 @@ Dividing two integers that are larger than the current precision may give a floating-point result that is inaccurate even when rounded down to an integer. Consider @expr{123456789 / 2} when the current precision is 6 digits. The true answer is @expr{61728394.5}, but -with a precision of 6 this will be rounded to +with a precision of 6 this will be rounded to @texline @math{12345700.0/2.0 = 61728500.0}. @infoline @expr{12345700.@: / 2.@: = 61728500.}. The result, when converted to an integer, will be off by 106. @@ -6900,18 +6900,18 @@ Type @kbd{d N} to return to Normal display mode afterwards. @subsection Matrix Tutorial Exercise 3 @noindent -To solve +To solve @texline @math{A^T A \, X = A^T B}, -@infoline @expr{trn(A) * A * X = trn(A) * B}, +@infoline @expr{trn(A) * A * X = trn(A) * B}, first we compute @texline @math{A' = A^T A} -@infoline @expr{A2 = trn(A) * A} -and +@infoline @expr{A2 = trn(A) * A} +and @texline @math{B' = A^T B}; -@infoline @expr{B2 = trn(A) * B}; -now, we have a system +@infoline @expr{B2 = trn(A) * B}; +now, we have a system @texline @math{A' X = B'} -@infoline @expr{A2 * X = B2} +@infoline @expr{A2 * X = B2} which we can solve using Calc's @samp{/} command. @ifnottex @@ -6942,7 +6942,7 @@ $$ The first step is to enter the coefficient matrix. We'll store it in quick variable number 7 for later reference. Next, we compute the @texline @math{B'} -@infoline @expr{B2} +@infoline @expr{B2} vector. @smallexample @@ -6958,9 +6958,9 @@ vector. @end smallexample @noindent -Now we compute the matrix +Now we compute the matrix @texline @math{A'} -@infoline @expr{A2} +@infoline @expr{A2} and divide. @smallexample @@ -6979,16 +6979,16 @@ and divide. (The actual computed answer will be slightly inexact due to round-off error.) -Notice that the answers are similar to those for the +Notice that the answers are similar to those for the @texline @math{3\times3} @infoline 3x3 -system solved in the text. That's because the fourth equation that was +system solved in the text. That's because the fourth equation that was added to the system is almost identical to the first one multiplied by two. (If it were identical, we would have gotten the exact same -answer since the +answer since the @texline @math{4\times3} @infoline 4x3 -system would be equivalent to the original +system would be equivalent to the original @texline @math{3\times3} @infoline 3x3 system.) @@ -7064,7 +7064,7 @@ $$ m \times x + b \times 1 = y $$ \afterdisplay @end tex -Thus we want a +Thus we want a @texline @math{19\times2} @infoline 19x2 matrix with our @expr{x} vector as one column and @@ -7083,12 +7083,12 @@ we combine the two columns to form our @expr{A} matrix. @end smallexample @noindent -Now we compute +Now we compute @texline @math{A^T y} -@infoline @expr{trn(A) * y} -and +@infoline @expr{trn(A) * y} +and @texline @math{A^T A} -@infoline @expr{trn(A) * A} +@infoline @expr{trn(A) * A} and divide. @smallexample @@ -7114,9 +7114,9 @@ and divide. @end group @end smallexample -Since we were solving equations of the form +Since we were solving equations of the form @texline @math{m \times x + b \times 1 = y}, -@infoline @expr{m*x + b*1 = y}, +@infoline @expr{m*x + b*1 = y}, these numbers should be @expr{m} and @expr{b}, respectively. Sure enough, they agree exactly with the result computed using @kbd{V M} and @kbd{V R}! @@ -7177,9 +7177,9 @@ then raise the number to that power.) @subsection List Tutorial Exercise 4 @noindent -A number @expr{j} is a divisor of @expr{n} if +A number @expr{j} is a divisor of @expr{n} if @texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}. -@infoline @samp{n % j = 0}. +@infoline @samp{n % j = 0}. The first step is to get a vector that identifies the divisors. @smallexample @@ -7248,9 +7248,9 @@ so that the mapping operation works; no prime factor will ever be zero, so adding zeros on the left and right is safe. From then on the job is pretty straightforward. -Incidentally, Calc provides the +Incidentally, Calc provides the @texline @dfn{M@"obius} @math{\mu} -@infoline @dfn{Moebius mu} +@infoline @dfn{Moebius mu} function which is zero if and only if its argument is square-free. It would be a much more convenient way to do the above test in practice. @@ -7282,7 +7282,7 @@ exercise and type @kbd{1 -} to subtract one from all the elements. The numbers down the lefthand edge of the list we desire are called the ``triangular numbers'' (now you know why!). The @expr{n}th triangular number is the sum of the integers from 1 to @expr{n}, and -can be computed directly by the formula +can be computed directly by the formula @texline @math{n (n+1) \over 2}. @infoline @expr{n * (n+1) / 2}. @@ -7378,7 +7378,7 @@ A way to isolate the maximum value is to compute the maximum using @noindent It's a good idea to verify, as in the last step above, that only -one value is equal to the maximum. (After all, a plot of +one value is equal to the maximum. (After all, a plot of @texline @math{\sin x} @infoline @expr{sin(x)} might have many points all equal to the maximum value, 1.) @@ -7650,12 +7650,12 @@ return to full-sized display of vectors. This problem can be made a lot easier by taking advantage of some symmetries. First of all, after some thought it's clear that the @expr{y} axis can be ignored altogether. Just pick a random @expr{x} -component for one end of the match, pick a random direction +component for one end of the match, pick a random direction @texline @math{\theta}, @infoline @expr{theta}, -and see if @expr{x} and +and see if @expr{x} and @texline @math{x + \cos \theta} -@infoline @expr{x + cos(theta)} +@infoline @expr{x + cos(theta)} (which is the @expr{x} coordinate of the other endpoint) cross a line. The lines are at integer coordinates, so this happens when the two numbers surround an integer. @@ -7670,9 +7670,9 @@ In fact, since the field of lines is infinite we can choose the coordinates 0 and 1 for the lines on either side of the leftmost endpoint. The rightmost endpoint will be between 0 and 1 if the match does not cross a line, or between 1 and 2 if it does. So: -Pick random @expr{x} and +Pick random @expr{x} and @texline @math{\theta}, -@infoline @expr{theta}, +@infoline @expr{theta}, compute @texline @math{x + \cos \theta}, @infoline @expr{x + cos(theta)}, @@ -8997,7 +8997,7 @@ Each of these functions can be computed using the stack, or using algebraic entry, whichever way you prefer: @noindent -Computing +Computing @texline @math{\displaystyle{\sin x \over x}}: @infoline @expr{sin(x) / x}: @@ -9068,7 +9068,7 @@ C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x ) @noindent This program is quite efficient because Calc knows how to raise a -matrix (or other value) to the power @expr{n} in only +matrix (or other value) to the power @expr{n} in only @texline @math{\log_2 n} @infoline @expr{log(n,2)} steps. For example, this program can compute the 1000th Fibonacci @@ -9122,7 +9122,7 @@ harmonic number is 4.02. @noindent The first step is to compute the derivative @expr{f'(x)} and thus -the formula +the formula @texline @math{\displaystyle{x - {f(x) \over f'(x)}}}. @infoline @expr{x - f(x)/f'(x)}. @@ -9239,12 +9239,12 @@ method (among others) to look for numerical solutions to any equation. @noindent The first step is to adjust @expr{z} to be greater than 5. A simple ``for'' loop will do the job here. If @expr{z} is less than 5, we -reduce the problem using +reduce the problem using @texline @math{\psi(z) = \psi(z+1) - 1/z}. @infoline @expr{psi(z) = psi(z+1) - 1/z}. We go -on to compute +on to compute @texline @math{\psi(z+1)}, -@infoline @expr{psi(z+1)}, +@infoline @expr{psi(z+1)}, and remember to add back a factor of @expr{-1/z} when we're done. This step is repeated until @expr{z > 5}. @@ -9283,7 +9283,7 @@ are exactly equal, not just equal to within the current precision.) @end group @end smallexample -Now we compute the initial part of the sum: +Now we compute the initial part of the sum: @texline @math{\ln z - {1 \over 2z}} @infoline @expr{ln(z) - 1/2z} minus the adjustment factor. @@ -9326,9 +9326,9 @@ up the value of @expr{2 n}. (Calc does have a summation command, @end group @end smallexample -This is the value of +This is the value of @texline @math{-\gamma}, -@infoline @expr{- gamma}, +@infoline @expr{- gamma}, with a slight bit of roundoff error. To get a full 12 digits, let's use a higher precision: @@ -9361,9 +9361,9 @@ C-x ) @noindent Taking the derivative of a term of the form @expr{x^n} will produce -a term like +a term like @texline @math{n x^{n-1}}. -@infoline @expr{n x^(n-1)}. +@infoline @expr{n x^(n-1)}. Taking the derivative of a constant produces zero. From this it is easy to see that the @expr{n}th derivative of a polynomial, evaluated at @expr{x = 0}, will equal the @@ -9652,7 +9652,7 @@ still exists and is updated silently. @xref{Trail Commands}. @mindex @null @end ignore In most installations, the @kbd{C-x * c} key sequence is a more -convenient way to start the Calculator. Also, @kbd{C-x * *} +convenient way to start the Calculator. Also, @kbd{C-x * *} is a synonym for @kbd{C-x * c} unless you last used Calc in its Keypad mode. @@ -9908,9 +9908,9 @@ additional notes from the summary that apply to this command. The @kbd{h f} (@code{calc-describe-function}) command looks up an algebraic function or a command name in the Calc manual. Enter an algebraic function name to look up that function in the Function -Index or enter a command name beginning with @samp{calc-} to look it +Index or enter a command name beginning with @samp{calc-} to look it up in the Command Index. This command will also look up operator -symbols that can appear in algebraic formulas, like @samp{%} and +symbols that can appear in algebraic formulas, like @samp{%} and @samp{=>}. @kindex h v @@ -10038,7 +10038,7 @@ During numeric entry, the only editing key available is @key{DEL}. @cindex Formulas, entering The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter calculations in algebraic form. This is accomplished by typing the -apostrophe key, ', followed by the expression in standard format: +apostrophe key, ', followed by the expression in standard format: @example ' 2+3*4 @key{RET}. @@ -10047,7 +10047,7 @@ apostrophe key, ', followed by the expression in standard format: @noindent This will compute @texline @math{2+(3\times4) = 14} -@infoline @expr{2+(3*4) = 14} +@infoline @expr{2+(3*4) = 14} and push it on the stack. If you wish you can ignore the RPN aspect of Calc altogether and simply enter algebraic expressions in this way. You may want to use @key{DEL} every so often to @@ -10453,9 +10453,9 @@ is greater than this, it will recompute @cpi{} using a series approximation. This value will not need to be recomputed ever again unless you raise the precision still further. Many operations such as logarithms and sines make use of similarly cached values such as -@cpiover{4} and +@cpiover{4} and @texline @math{\ln 2}. -@infoline @expr{ln(2)}. +@infoline @expr{ln(2)}. The visible effect of caching is that high-precision computations may seem to do extra work the first time. Other things cached include powers of two (for the binary arithmetic @@ -10612,10 +10612,10 @@ form). The numerator and denominator always use the same radix. A floating-point number or @dfn{float} is a number stored in scientific notation. The number of significant digits in the fractional part is governed by the current floating precision (@pxref{Precision}). The -range of acceptable values is from +range of acceptable values is from @texline @math{10^{-3999999}} -@infoline @expr{10^-3999999} -(inclusive) to +@infoline @expr{10^-3999999} +(inclusive) to @texline @math{10^{4000000}} @infoline @expr{10^4000000} (exclusive), plus the corresponding negative values and zero. @@ -10666,7 +10666,7 @@ and displayed in any radix just like integers and fractions. Since a float that is entered in a radix other that 10 will be converted to decimal, the number that Calc stores may not be exactly the number that was entered, it will be the closest decimal approximation given the -current precison. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}} +current precision. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}} is a floating-point number whose digits are in the specified radix. Note that the @samp{.} is more aptly referred to as a ``radix point'' than as a decimal point in this case. The number @samp{8#123.4567} is @@ -10690,18 +10690,18 @@ polar. The default format is rectangular, displayed in the form Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i} notation; @pxref{Complex Formats}. -Polar complex numbers are displayed in the form +Polar complex numbers are displayed in the form @texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}' @infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}' -where @var{r} is the nonnegative magnitude and +where @var{r} is the nonnegative magnitude and @texline @math{\theta} -@infoline @var{theta} -is the argument or phase angle. The range of +@infoline @var{theta} +is the argument or phase angle. The range of @texline @math{\theta} -@infoline @var{theta} +@infoline @var{theta} depends on the current angular mode (@pxref{Angular Modes}); it is generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range -in radians. +in radians. Complex numbers are entered in stages using incomplete objects. @xref{Incomplete Objects}. @@ -10742,9 +10742,9 @@ really mean is that @expr{1 / x}, as @expr{x} becomes larger and larger, becomes arbitrarily close to zero. So you can imagine that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x} would go all the way to zero. Similarly, when they say that -@samp{exp(inf) = inf}, they mean that +@samp{exp(inf) = inf}, they mean that @texline @math{e^x} -@infoline @expr{exp(x)} +@infoline @expr{exp(x)} grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise stands for an infinitely negative real value; for example, we say that @samp{exp(-inf) = 0}. You can have an infinity pointing in any @@ -10839,7 +10839,7 @@ of its elements. @end ignore @tindex vec Algebraic functions for building vectors include @samp{vec(a, b, c)} -to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an +to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an @texline @math{n\times m} @infoline @var{n}x@var{m} matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers @@ -11184,9 +11184,9 @@ there is no solution to this equation (which can happen only when division is left in symbolic form. Other operations, such as square roots, are not yet supported for modulo forms. (Note that, although @w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root'' -in the sense of reducing +in the sense of reducing @texline @math{\sqrt a} -@infoline @expr{sqrt(a)} +@infoline @expr{sqrt(a)} modulo @expr{M}, this is not a useful definition from the number-theoretical point of view.) @@ -11220,11 +11220,11 @@ The algebraic function @samp{makemod(a, m)} builds the modulo form @cindex Standard deviations An @dfn{error form} is a number with an associated standard deviation, as in @samp{2.3 +/- 0.12}. The notation -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} sigma' +@texline `@var{x} @tfn{+/-} @math{\sigma}' +@infoline `@var{x} @tfn{+/-} sigma' stands for an uncertain value which follows a normal or Gaussian distribution of mean @expr{x} and standard -deviation or ``error'' +deviation or ``error'' @texline @math{\sigma}. @infoline @expr{sigma}. Both the mean and the error can be either numbers or @@ -11235,7 +11235,7 @@ regular number by the Calculator. All arithmetic and transcendental functions accept error forms as input. Operations on the mean-value part work just like operations on regular -numbers. The error part for any function @expr{f(x)} (such as +numbers. The error part for any function @expr{f(x)} (such as @texline @math{\sin x} @infoline @expr{sin(x)}) is defined by the error of @expr{x} times the derivative of @expr{f} @@ -11267,35 +11267,35 @@ Consult a good text on error analysis for a discussion of the proper use of standard deviations. Actual errors often are neither Gaussian-distributed nor uncorrelated, and the above formulas are valid only when errors are small. As an example, the error arising from -@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}' -@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}' -is -@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. -@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. +@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}' +@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}' +is +@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. +@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. When @expr{x} is close to zero, @texline @math{\cos x} -@infoline @expr{cos(x)} -is close to one so the error in the sine is close to +@infoline @expr{cos(x)} +is close to one so the error in the sine is close to @texline @math{\sigma}; @infoline @expr{sigma}; -this makes sense, since +this makes sense, since @texline @math{\sin x} -@infoline @expr{sin(x)} +@infoline @expr{sin(x)} is approximately @expr{x} near zero, so a given error in @expr{x} will produce about the same error in the sine. Likewise, near 90 degrees @texline @math{\cos x} -@infoline @expr{cos(x)} +@infoline @expr{cos(x)} is nearly zero and so the computed error is small: The sine curve is nearly flat in that region, so an error in @expr{x} -has relatively little effect on the value of +has relatively little effect on the value of @texline @math{\sin x}. -@infoline @expr{sin(x)}. +@infoline @expr{sin(x)}. However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so Calc will report zero error! We get an obviously wrong result because we have violated the small-error approximation underlying the error analysis. If the error in @expr{x} had been small, the error in @texline @math{\sin x} -@infoline @expr{sin(x)} +@infoline @expr{sin(x)} would indeed have been negligible. @ignore @@ -11402,14 +11402,14 @@ contain zero inside them Calc is forced to give the result, While it may seem that intervals and error forms are similar, they are based on entirely different concepts of inexact quantities. An error -form -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} @var{sigma}' +form +@texline `@var{x} @tfn{+/-} @math{\sigma}' +@infoline `@var{x} @tfn{+/-} @var{sigma}' means a variable is random, and its value could -be anything but is ``probably'' within one -@texline @math{\sigma} -@infoline @var{sigma} -of the mean value @expr{x}. An interval +be anything but is ``probably'' within one +@texline @math{\sigma} +@infoline @var{sigma} +of the mean value @expr{x}. An interval `@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a variable's value is unknown, but guaranteed to lie in the specified range. Error forms are statistical or ``average case'' approximations; @@ -11641,7 +11641,7 @@ the C-style ``if'' operator @samp{a?b:c} [@code{if}]; @samp{=>} [@code{evalto}]. Note that, unlike in usual computer notation, multiplication binds more -strongly than division: @samp{a*b/c*d} is equivalent to +strongly than division: @samp{a*b/c*d} is equivalent to @texline @math{a b \over c d}. @infoline @expr{(a*b)/(c*d)}. @@ -11858,13 +11858,13 @@ next higher level. For example, with @samp{10 20 30 40 50} on the stack and the point on the line containing @samp{30}, @kbd{C-x C-t} creates @samp{10 20 40 30 50}. More generally, @kbd{C-x C-t} acts on the stack objects determined by the current point (and mark) similar -to how the text-mode command @code{transpose-lines} acts on +to how the text-mode command @code{transpose-lines} acts on lines. With argument @var{n}, @kbd{C-x C-t} will move the stack object at the level above the current point and move it past N other objects; for example, with @samp{10 20 30 40 50} on the stack and the point on -the line containing @samp{30}, @kbd{C-u 2 C-x C-t} creates +the line containing @samp{30}, @kbd{C-u 2 C-x C-t} creates @samp{10 40 20 30 50}. With an argument of 0, @kbd{C-x C-t} will switch -the stack objects at the levels determined by the point and the mark. +the stack objects at the levels determined by the point and the mark. @node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail @section Editing Stack Entries @@ -12056,7 +12056,7 @@ the stack contains the arguments and the result: @samp{2 3 5}. With the exception of keyboard macros, this works for all commands that take arguments off the stack. (To avoid potentially unpleasant behavior, a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K} -prefix called @emph{within} the keyboard macro will still take effect.) +prefix called @emph{within} the keyboard macro will still take effect.) As another example, @kbd{K a s} simplifies a formula, pushing the simplified version of the formula onto the stack after the original formula (rather than replacing the original formula). Note that you @@ -12064,7 +12064,7 @@ could get the same effect by typing @kbd{@key{RET} a s}, copying the formula and then simplifying the copy. One difference is that for a very large formula the time taken to format the intermediate copy in @kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this -extra work. +extra work. Even stack manipulation commands are affected. @key{TAB} works by popping two values and pushing them back in the opposite order, @@ -12155,7 +12155,7 @@ discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}. If the file name you give is your user init file (typically @file{~/.emacs}), @kbd{m F} will not automatically load the new file. This is because your user init file may contain other things you don't want -to reread. You can give +to reread. You can give a numeric prefix argument of 1 to @kbd{m F} to force it to read the file no matter what. Conversely, an argument of @mathit{-1} tells @kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2} @@ -12274,7 +12274,7 @@ corresponding base command (@code{calc-sin} in this case). @pindex calc-option The @kbd{O} key (@code{calc-option}) sets another flag, the @dfn{Option Flag}, which also can alter the subsequent Calc command in -various ways. +various ways. The Inverse, Hyperbolic and Option flags apply only to the next Calculator command, after which they are automatically cleared. (They @@ -12366,7 +12366,7 @@ result cannot be expressed as an integer. In some cases you would rather get an exact fractional answer. One way to accomplish this is to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which divides the two integers on the top of the stack to produce a fraction: -@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though +@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though @kbd{6 @key{RET} 4 /} produces @expr{1.5}. @kindex m f @@ -12878,7 +12878,7 @@ To declare specifically that @code{x} is real and non-zero, use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the current notation to say that @code{x} is nonzero but not necessarily real.) The @kbd{a e} command does ``unsafe'' simplifications, -including cancelling @samp{x} from the equation when @samp{x} is +including canceling @samp{x} from the equation when @samp{x} is not known to be nonzero. Another set of type symbols distinguish between scalars and vectors. @@ -13155,11 +13155,11 @@ represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros}) command causes integers to be padded out with leading zeros according to the current binary word size. (@xref{Binary Functions}, for a discussion of word size.) If the absolute value of the word size is @expr{w}, all integers -are displayed with at least enough digits to represent +are displayed with at least enough digits to represent @texline @math{2^w-1} -@infoline @expr{(2^w)-1} +@infoline @expr{(2^w)-1} in the current radix. (Larger integers will still be displayed in their -entirety.) +entirety.) @cindex Two's complements Calc can display @expr{w}-bit integers using two's complement @@ -13181,7 +13181,7 @@ the integers from @expr{0} to are represented by themselves and the integers from @texline @math{-2^{w-1}} @infoline @expr{-2^(w-1)} -to @expr{-1} are represented by the integers from +to @expr{-1} are represented by the integers from @texline @math{2^{w-1}} @infoline @expr{2^(w-1)} to @expr{2^w-1} (the integer @expr{k} is represented by @expr{k+2^w}). @@ -13190,7 +13190,7 @@ Calc will display a two's complement integer by the radix (either representation (including any leading zeros necessary to include all @expr{w} bits). In a two's complement display mode, numbers that are not displayed in two's complement notation (i.e., that aren't -integers from +integers from @texline @math{-2^{w-1}} @infoline @expr{-2^(w-1)} to @@ -14095,13 +14095,13 @@ the @samp{$} sign has the same meaning it always does in algebraic formulas (a reference to an existing entry on the stack). Complex numbers are displayed as in @samp{3 + 4i}. Fractions and -quotients are written using @code{\over} in @TeX{} mode (as in +quotients are written using @code{\over} in @TeX{} mode (as in @code{@{a \over b@}}) and @code{\frac} in La@TeX{} mode (as in @code{\frac@{a@}@{b@}}); binomial coefficients are written with @code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and @code{\binom} in La@TeX{} mode (as in @code{\binom@{a@}@{b@}}). Interval forms are written with @code{\ldots}, and error forms are -written with @code{\pm}. Absolute values are written as in +written with @code{\pm}. Absolute values are written as in @samp{|x + 1|}, and the floor and ceiling functions are written with @code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and @code{\right} are ignored when reading formulas in @TeX{} and La@TeX{} @@ -14114,10 +14114,10 @@ and La@TeX{} have special names (like @code{\sin}) will use curly braces instead of parentheses for very simple arguments. During input, curly braces and parentheses work equally well for grouping, but when the document is formatted the curly braces will be invisible. Thus the -printed result is +printed result is @texline @math{\sin{2 x}} -@infoline @expr{sin 2x} -but +@infoline @expr{sin 2x} +but @texline @math{\sin(2 + x)}. @infoline @expr{sin(2 + x)}. @@ -14131,7 +14131,7 @@ italic letters in the printed document. If you invoke @kbd{d T} or @kbd{d L} with a positive numeric prefix argument, names of more than one character will instead be enclosed in a protective commands that will prevent them from being typeset in the math italics; they will be -written @samp{\hbox@{@var{name}@}} in @TeX{} mode and +written @samp{\hbox@{@var{name}@}} in @TeX{} mode and @samp{\text@{@var{name}@}} in La@TeX{} mode. The @samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during reading. If you use a negative prefix argument, such function names are @@ -14143,7 +14143,7 @@ any @TeX{} mode.) During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and -@code{\bmatrix}. In La@TeX{} mode this also applies to +@code{\bmatrix}. In La@TeX{} mode this also applies to @samp{\begin@{matrix@} ... \end@{matrix@}}, @samp{\begin@{bmatrix@} ... \end@{bmatrix@}}, @samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as @@ -14151,12 +14151,12 @@ by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and The symbol @samp{&} is interpreted as a comma, and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons. During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}} -format in @TeX{} mode and in +format in @TeX{} mode and in @samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in La@TeX{} mode; you may need to edit this afterwards to change to your preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an argument of 2 or -2, then matrices will be displayed in two-dimensional -form, such as +form, such as @example \begin@{pmatrix@} @@ -14300,25 +14300,25 @@ in Calc, @TeX{}, La@TeX{} and @dfn{eqn} (described in the next section): @example Calc TeX LaTeX eqn ---- --- ----- --- -acute \acute \acute -Acute \Acute +acute \acute \acute +Acute \Acute bar \bar \bar bar Bar \Bar -breve \breve \breve -Breve \Breve -check \check \check -Check \Check +breve \breve \breve +Breve \Breve +check \check \check +Check \Check dddot \dddot ddddot \ddddot dot \dot \dot dot Dot \Dot dotdot \ddot \ddot dotdot -DotDot \Ddot +DotDot \Ddot dyad dyad -grave \grave \grave -Grave \Grave +grave \grave \grave +Grave \Grave hat \hat \hat hat -Hat \Hat +Hat \Hat Prime prime tilde \tilde \tilde tilde Tilde \Tilde @@ -14363,7 +14363,7 @@ reading is: Note that, because these symbols are ignored, reading a @TeX{} or La@TeX{} formula into Calc and writing it back out may lose spacing and -font information. +font information. Also, the ``discretionary multiplication sign'' @samp{\*} is read the same as @samp{*}. @@ -14542,7 +14542,7 @@ are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to of quotes in @dfn{eqn}, but it is good enough for most uses. Accent codes (@samp{@var{x} dot}) are handled by treating them as -function calls (@samp{dot(@var{x})}) internally. +function calls (@samp{dot(@var{x})}) internally. @xref{TeX and LaTeX Language Modes}, for a table of these accent functions. The @code{prime} accent is treated specially if it occurs on a variable or function name: @samp{f prime prime @w{( x prime )}} is @@ -14572,7 +14572,7 @@ if the matrix justification mode so specifies. The @kbd{d Y} (@code{calc-yacas-language}) command selects the conventions of Yacas, a free computer algebra system. While the operators and functions in Yacas are similar to those of Calc, the names -of built-in functions in Yacas are capitalized. The Calc formula +of built-in functions in Yacas are capitalized. The Calc formula @samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)} in Yacas mode, and `@samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas mode. Complex numbers are written are written @samp{3 + 4 I}. @@ -14581,9 +14581,9 @@ The standard special constants are written @code{Pi}, @code{E}, represents both @code{inf} and @code{uinf}, and @code{Undefined} represents @code{nan}. -Certain operators on functions, such as @code{D} for differentiation +Certain operators on functions, such as @code{D} for differentiation and @code{Integrate} for integration, take a prefix form in Yacas. For -example, the derivative of @w{@samp{e^x sin(x)}} can be computed with +example, the derivative of @w{@samp{e^x sin(x)}} can be computed with @w{@samp{D(x) Exp(x)*Sin(x)}}. Other notable differences between Yacas and standard Calc expressions @@ -14602,7 +14602,7 @@ use square brackets. If, for example, @samp{A} represents the list The @kbd{d X} (@code{calc-maxima-language}) command selects the conventions of Maxima, another free computer algebra system. The function names in Maxima are similar, but not always identical, to Calc. -For example, instead of @samp{arcsin(x)}, Maxima will use +For example, instead of @samp{arcsin(x)}, Maxima will use @samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The standard special constants are written @code{%pi}, @code{%e}, @code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means @@ -14610,8 +14610,8 @@ the same as in Calc, but @code{infinity} represents Calc's @code{uinf}. Underscores as well as percent signs are allowed in function and variable names in Maxima mode. The underscore again is equivalent to -the @samp{#} in Normal mode, and the percent sign is equivalent to -@samp{o'o}. +the @samp{#} in Normal mode, and the percent sign is equivalent to +@samp{o'o}. Maxima uses square brackets for lists and vectors, and matrices are written as calls to the function @code{matrix}, given the row vectors of @@ -14629,7 +14629,7 @@ conventions of Giac, another free computer algebra system. The function names in Giac are similar to Maxima. Complex numbers are written @samp{3 + 4 i}. The standard special constants in Giac are the same as in Calc, except that @code{infinity} represents both Calc's @code{inf} -and @code{uinf}. +and @code{uinf}. Underscores are allowed in function and variable names in Giac mode. Brackets are used for subscripts. In Giac, indexing of lists begins at @@ -15786,9 +15786,9 @@ Command is @kbd{m p}. @item Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode, -or @var{N} for +or @var{N} for @texline @math{N\times N} -@infoline @var{N}x@var{N} +@infoline @var{N}x@var{N} Matrix mode. Command is @kbd{m v}. @item @@ -16178,7 +16178,7 @@ whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}. @mindex @null @end ignore @tindex / -The @kbd{/} (@code{calc-divide}) command divides two numbers. +The @kbd{/} (@code{calc-divide}) command divides two numbers. When combining multiplication and division in an algebraic formula, it is good style to use parentheses to distinguish between possible @@ -16187,7 +16187,7 @@ interpretations; the expression @samp{a/b*c} should be written parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since in algebraic entry Calc gives division a lower precedence than multiplication. (This is not standard across all computer languages, and -Calc may change the precedence depending on the language mode being used. +Calc may change the precedence depending on the language mode being used. @xref{Language Modes}.) This default ordering can be changed by setting the customizable variable @code{calc-multiplication-has-precedence} to @code{nil} (@pxref{Customizing Calc}); this will give multiplication and @@ -16373,7 +16373,7 @@ all the arguments.) The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X} (@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part -@expr{e}. The original number is equal to +@expr{e}. The original number is equal to @texline @math{m \times 10^e}, @infoline @expr{m * 10^e}, where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that @@ -16406,9 +16406,9 @@ floating-point numbers, the change is by one unit in the last place. For example, incrementing @samp{12.3456} when the current precision is 6 digits yields @samp{12.3457}. If the current precision had been 8 digits, the result would have been @samp{12.345601}. Incrementing -@samp{0.0} produces +@samp{0.0} produces @texline @math{10^{-p}}, -@infoline @expr{10^-p}, +@infoline @expr{10^-p}, where @expr{p} is the current precision. These operations are defined only on integers and floats. With numeric prefix arguments, they change the number by @expr{n} units. @@ -16852,7 +16852,7 @@ The last two arguments default to zero if omitted. The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts a date form into a Julian day count, which is the number of days since noon (GMT) on Jan 1, 4713 BC. A pure date is converted to an -integer Julian count representing noon of that day. A date/time form +integer Julian count representing noon of that day. A date/time form is converted to an exact floating-point Julian count, adjusted to interpret the date form in the current time zone but the Julian day count in Greenwich Mean Time. A numeric prefix argument allows @@ -17294,12 +17294,12 @@ With no arguments, @code{calc-time-zone} or @samp{tzone()} will by default get the time zone and daylight saving information from the calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary, emacs,The GNU Emacs Manual}). To use a different time zone, or if the -calendar does not give the desired result, you can set the Calc variable +calendar does not give the desired result, you can set the Calc variable @code{TimeZone} (which is by default @code{nil}) to an appropriate time zone name. (The easiest way to do this is to edit the @code{TimeZone} variable using Calc's @kbd{s T} command, then use the @kbd{s p} (@code{calc-permanent-variable}) command to save the value of -@code{TimeZone} permanently.) +@code{TimeZone} permanently.) If the time zone given by @code{TimeZone} is a generalized time zone, e.g., @code{EGT}, Calc examines the date being converted to tell whether to use standard or daylight saving time. But if the current time zone @@ -17311,12 +17311,12 @@ from the calendar. The @kbd{t J} and @code{t U} commands with no numeric prefix arguments do the same thing as @samp{tzone()}; namely, use the -information from the calendar if @code{TimeZone} is @code{nil}, +information from the calendar if @code{TimeZone} is @code{nil}, otherwise use the time zone given by @code{TimeZone}. @vindex math-daylight-savings-hook @findex math-std-daylight-savings -When Calc computes the daylight saving information itself (i.e., when +When Calc computes the daylight saving information itself (i.e., when the @code{TimeZone} variable is set), it will by default consider daylight saving time to begin at 2 a.m.@: on the second Sunday of March (for years from 2007 on) or on the last Sunday in April (for years @@ -17392,7 +17392,7 @@ falls in this hour results in a time value for the following hour, from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time form that falls in this hour results in a time value for the first -manifestation of that time (@emph{not} the one that occurs one hour +manifestation of that time (@emph{not} the one that occurs one hour later). If @code{math-daylight-savings-hook} is @code{nil}, then the @@ -17995,12 +17995,12 @@ particular, negative arguments are converted to positive integers modulo @expr{2^w} by all binary functions. If the word size is negative, binary operations produce twos-complement -integers from +integers from @texline @math{-2^{-w-1}} -@infoline @expr{-(2^(-w-1))} -to +@infoline @expr{-(2^(-w-1))} +to @texline @math{2^{-w-1}-1} -@infoline @expr{2^(-w-1)-1} +@infoline @expr{2^(-w-1)-1} inclusive. Either mode accepts inputs in any range; the sign of @expr{w} affects only the results produced. @@ -18182,13 +18182,13 @@ flag keys must be used to get some of these functions from the keyboard. One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes the value of @cpi{} (at the current precision) onto the stack. With the Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms. -With the Inverse flag, it pushes Euler's constant +With the Inverse flag, it pushes Euler's constant @texline @math{\gamma} -@infoline @expr{gamma} +@infoline @expr{gamma} (about 0.5772). With both Inverse and Hyperbolic, it -pushes the ``golden ratio'' +pushes the ``golden ratio'' @texline @math{\phi} -@infoline @expr{phi} +@infoline @expr{phi} (about 1.618). (At present, Euler's constant is not available to unlimited precision; Calc knows only the first 100 digits.) In Symbolic mode, these commands push the @@ -18266,7 +18266,7 @@ The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common (base-10) logarithm of a number. (With the Inverse flag [@code{exp10}], it raises ten to a given power.) Note that the common logarithm of a complex number is computed by taking the natural logarithm and dividing -by +by @texline @math{\ln10}. @infoline @expr{ln(10)}. @@ -18278,7 +18278,7 @@ by The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since @texline @math{2^{10} = 1024}. -@infoline @expr{2^10 = 1024}. +@infoline @expr{2^10 = 1024}. In certain cases like @samp{log(3,9)}, the result will be either @expr{1:2} or @expr{0.5} depending on the current Fraction mode setting. With the Inverse flag [@code{alog}], this command is @@ -18300,11 +18300,11 @@ integer arithmetic is used; otherwise, this is equivalent to @tindex expm1 The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes @texline @math{e^x - 1}, -@infoline @expr{exp(x)-1}, +@infoline @expr{exp(x)-1}, but using an algorithm that produces a more accurate -answer when the result is close to zero, i.e., when +answer when the result is close to zero, i.e., when @texline @math{e^x} -@infoline @expr{exp(x)} +@infoline @expr{exp(x)} is close to one. @kindex f L @@ -18312,7 +18312,7 @@ is close to one. @tindex lnp1 The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes @texline @math{\ln(x+1)}, -@infoline @expr{ln(x+1)}, +@infoline @expr{ln(x+1)}, producing a more accurate answer when @expr{x} is close to zero. @node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions @@ -18515,9 +18515,9 @@ The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler gamma function. For positive integer arguments, this is related to the factorial function: @samp{gamma(n+1) = fact(n)}. For general complex arguments the gamma function can be defined by the following definite -integral: +integral: @texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}. -@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. +@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. (The actual implementation uses far more efficient computational methods.) @kindex f G @@ -18549,7 +18549,7 @@ integral: @tindex gammaG The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by -the integral, +the integral, @texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}. @infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}. This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the @@ -18583,7 +18583,7 @@ You can obtain these using the \kbd{H f G} [\code{gammag}] and The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the Euler beta function, which is defined in terms of the gamma function as @texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)}, -@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, +@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, or by @texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}. @infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}. @@ -18606,7 +18606,7 @@ un-normalized version [@code{betaB}]. @tindex erf @tindex erfc The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the -error function +error function @texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}. @infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}. The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}] @@ -18784,9 +18784,9 @@ The @kbd{k r} (@code{calc-random}) [@code{random}] command produces random numbers of various sorts. Given a positive numeric prefix argument @expr{M}, it produces a random -integer @expr{N} in the range +integer @expr{N} in the range @texline @math{0 \le N < M}. -@infoline @expr{0 <= N < M}. +@infoline @expr{0 <= N < M}. Each possible value @expr{N} appears with equal probability. With no numeric prefix argument, the @kbd{k r} command takes its argument @@ -18794,17 +18794,17 @@ from the stack instead. Once again, if this is a positive integer @expr{M} the result is a random integer less than @expr{M}. However, note that while numeric prefix arguments are limited to six digits or so, an @expr{M} taken from the stack can be arbitrarily large. If @expr{M} is negative, -the result is a random integer in the range +the result is a random integer in the range @texline @math{M < N \le 0}. @infoline @expr{M < N <= 0}. If the value on the stack is a floating-point number @expr{M}, the result -is a random floating-point number @expr{N} in the range +is a random floating-point number @expr{N} in the range @texline @math{0 \le N < M} @infoline @expr{0 <= N < M} -or +or @texline @math{M < N \le 0}, -@infoline @expr{M < N <= 0}, +@infoline @expr{M < N <= 0}, according to the sign of @expr{M}. If @expr{M} is zero, the result is a Gaussian-distributed random real @@ -18812,14 +18812,14 @@ number; the distribution has a mean of zero and a standard deviation of one. The algorithm used generates random numbers in pairs; thus, every other call to this function will be especially fast. -If @expr{M} is an error form +If @expr{M} is an error form @texline @math{m} @code{+/-} @math{\sigma} -@infoline @samp{m +/- s} -where @var{m} and +@infoline @samp{m +/- s} +where @var{m} and @texline @math{\sigma} -@infoline @var{s} +@infoline @var{s} are both real numbers, the result uses a Gaussian distribution with mean -@var{m} and standard deviation +@var{m} and standard deviation @texline @math{\sigma}. @infoline @var{s}. @@ -18932,9 +18932,9 @@ generators that are typically used to implement @code{random}. If @code{RandSeed} contains an integer, Calc uses this integer to seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A, -computing +computing @texline @math{X_{n-55} - X_{n-24}}. -@infoline @expr{X_n-55 - X_n-24}). +@infoline @expr{X_n-55 - X_n-24}). This method expands the seed value into a large table which is maintained internally; the variable @code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]} @@ -18970,18 +18970,18 @@ value. To create a random floating-point number with precision @var{p}, Calc simply creates a random @var{p}-digit integer and multiplies by @texline @math{10^{-p}}. -@infoline @expr{10^-p}. +@infoline @expr{10^-p}. The resulting random numbers should be very clean, but note that relatively small numbers will have few significant random digits. In other words, with a precision of 12, you will occasionally get -numbers on the order of +numbers on the order of @texline @math{10^{-9}} -@infoline @expr{10^-9} -or +@infoline @expr{10^-9} +or @texline @math{10^{-10}}, -@infoline @expr{10^-10}, +@infoline @expr{10^-10}, but those numbers will only have two or three random digits since they -correspond to small integers times +correspond to small integers times @texline @math{10^{-12}}. @infoline @expr{10^-12}. @@ -19032,7 +19032,7 @@ numbers. @tindex egcd The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes the GCD of two integers @expr{x} and @expr{y} and returns a vector -@expr{[g, a, b]} where +@expr{[g, a, b]} where @texline @math{g = \gcd(x,y) = a x + b y}. @infoline @expr{g = gcd(x,y) = a x + b y}. @@ -19119,11 +19119,11 @@ functions. @tindex stir1 @tindex stir2 The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command -computes a Stirling number of the first +computes a Stirling number of the first @texline kind@tie{}@math{n \brack m}, @infoline kind, given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s} -[@code{stir2}] command computes a Stirling number of the second +[@code{stir2}] command computes a Stirling number of the second @texline kind@tie{}@math{n \brace m}. @infoline kind. These are the number of @expr{m}-cycle permutations of @expr{n} objects, @@ -19202,7 +19202,7 @@ analogously finds the next prime less than a given number. @pindex calc-totient @tindex totient The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the -Euler ``totient'' +Euler ``totient'' @texline function@tie{}@math{\phi(n)}, @infoline function, the number of integers less than @expr{n} which @@ -19277,7 +19277,7 @@ recover the original arguments but substitute a new value for @expr{x}.) @tindex ltpc The @samp{utpc(x,v)} function uses the chi-square distribution with @texline @math{\nu} -@infoline @expr{v} +@infoline @expr{v} degrees of freedom. It is the probability that a model is correct if its chi-square statistic is @expr{x}. @@ -19293,10 +19293,10 @@ correct if its chi-square statistic is @expr{x}. @end ignore @tindex ltpf The @samp{utpf(F,v1,v2)} function uses the F distribution, used in -various statistical tests. The parameters +various statistical tests. The parameters @texline @math{\nu_1} -@infoline @expr{v1} -and +@infoline @expr{v1} +and @texline @math{\nu_2} @infoline @expr{v2} are the degrees of freedom in the numerator and denominator, @@ -19314,9 +19314,9 @@ respectively, used in computing the statistic @expr{F}. @end ignore @tindex ltpn The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution -with mean @expr{m} and standard deviation +with mean @expr{m} and standard deviation @texline @math{\sigma}. -@infoline @expr{s}. +@infoline @expr{s}. It is the probability that such a normal-distributed random variable would exceed @expr{x}. @@ -19347,20 +19347,20 @@ Poisson random events will occur. @end ignore @tindex ltpt The @samp{utpt(t,v)} function uses the Student's ``t'' distribution -with +with @texline @math{\nu} -@infoline @expr{v} +@infoline @expr{v} degrees of freedom. It is the probability that a t-distributed random variable will be greater than @expr{t}. -(Note: This computes the distribution function +(Note: This computes the distribution function @texline @math{A(t|\nu)} @infoline @expr{A(t|v)} -where +where @texline @math{A(0|\nu) = 1} -@infoline @expr{A(0|v) = 1} -and +@infoline @expr{A(0|v) = 1} +and @texline @math{A(\infty|\nu) \to 0}. -@infoline @expr{A(inf|v) -> 0}. +@infoline @expr{A(inf|v) -> 0}. The @code{UTPT} operation on the HP-48 uses a different definition which returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.) @@ -19670,7 +19670,7 @@ prefix, if specified, must match the size of the vector. If the value on the stack is a scalar, it is used for each element on the diagonal, and the prefix argument is required. -To build a constant square matrix, e.g., a +To build a constant square matrix, e.g., a @texline @math{3\times3} @infoline 3x3 matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero @@ -19911,7 +19911,7 @@ command. With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector of the dimensions of a vector, matrix, or higher-order object. For example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since -its argument is a +its argument is a @texline @math{2\times3} @infoline 2x3 matrix. @@ -19945,17 +19945,17 @@ If the number of columns does not evenly divide the number of elements in the vector, the last row will be short and the result will not be suitable for use as a matrix. For example, with the matrix @samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces -@samp{[[1, 2, 3, 4]]} (a +@samp{[[1, 2, 3, 4]]} (a @texline @math{1\times4} @infoline 1x4 -matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a +matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a @texline @math{4\times1} @infoline 4x1 -matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original +matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original @texline @math{2\times2} @infoline 2x2 matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a -matrix), and @kbd{v a 0} produces the flattened list +matrix), and @kbd{v a 0} produces the flattened list @samp{[1, 2, @w{3, 4}]}. @cindex Sorting data @@ -20040,9 +20040,9 @@ If no prefix is given, then you will be prompted for a vector which will be used to determine the bins. (If a positive integer is given at this prompt, it will be still treated as if it were given as a prefix.) Each bin will consist of the interval of numbers closest to -the corresponding number of this new vector; if the vector -@expr{[a, b, c, ...]} is entered at the prompt, the bins will be -@expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of +the corresponding number of this new vector; if the vector +@expr{[a, b, c, ...]} is entered at the prompt, the bins will be +@expr{(-inf, (a+b)/2]}, @expr{((a+b)/2, (b+c)/2]}, etc. The result of this command will be a vector counting how many elements of the original vector are in each bin. @@ -20313,10 +20313,10 @@ and only if it is in both of the input sets. Thus if the input sets are disjoint, i.e., if they share no common elements, the result will be the empty vector @samp{[]}. Note that the characters @kbd{V} and @kbd{^} were chosen to be close to the conventional mathematical -notation for set +notation for set @texline union@tie{}(@math{A \cup B}) @infoline union -and +and @texline intersection@tie{}(@math{A \cap B}). @infoline intersection. @@ -20432,7 +20432,7 @@ the same set. The set may include positive infinity, but must not include any negative numbers. The input is interpreted as a set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware that a simple input like @samp{[100]} can result in a huge integer -representation +representation @texline (@math{2^{100}}, a 31-digit integer, in this case). @infoline (@expr{2^100}, a 31-digit integer, in this case). @@ -20544,10 +20544,10 @@ plus or minus infinity. @cindex Mean of data values The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command computes the average (arithmetic mean) of the data values. -If the inputs are error forms +If the inputs are error forms @texline @math{x \pm \sigma}, -@infoline @samp{x +/- s}, -this is the weighted mean of the @expr{x} values with weights +@infoline @samp{x +/- s}, +this is the weighted mean of the @expr{x} values with weights @texline @math{1 /\sigma^2}. @infoline @expr{1 / s^2}. @tex @@ -20558,9 +20558,9 @@ If the inputs are not error forms, this is simply the sum of the values divided by the count of the values. Note that a plain number can be considered an error form with -error +error @texline @math{\sigma = 0}. -@infoline @expr{s = 0}. +@infoline @expr{s = 0}. If the input to @kbd{u M} is a mixture of plain numbers and error forms, the result is the mean of the plain numbers, ignoring all values with non-zero errors. (By the @@ -20662,7 +20662,7 @@ for a vector of numbers simply by using the @kbd{A} command. @cindex Standard deviation @cindex Sample statistics The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command -computes the standard +computes the standard @texline deviation@tie{}@math{\sigma} @infoline deviation of the data values. If the values are error forms, the errors are used @@ -20677,9 +20677,9 @@ $$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$ This function also applies to distributions. The standard deviation of a single error form is simply the error part. The standard deviation of a continuous interval happens to equal the difference between the -limits, divided by +limits, divided by @texline @math{\sqrt{12}}. -@infoline @expr{sqrt(12)}. +@infoline @expr{sqrt(12)}. The standard deviation of an integer interval is the same as the standard deviation of a vector of those integers. @@ -20714,7 +20714,7 @@ population standard deviation of the equivalent vector of integers. The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and @kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}] commands compute the variance of the data values. The variance -is the +is the @texline square@tie{}@math{\sigma^2} @infoline square of the standard deviation, i.e., the sum of the @@ -20738,7 +20738,7 @@ The functions in this section take two arguments, which must be vectors of equal size. The vectors are each flattened in the same way as by the single-variable statistical functions. Given a numeric prefix argument of 1, these functions instead take one object from -the stack, which must be an +the stack, which must be an @texline @math{N\times2} @infoline Nx2 matrix of data values. Once again, variable names can be used in place @@ -20996,7 +20996,7 @@ be prompted for the number of arguments to use. If any argument to @kbd{V M} is a matrix, the operator is normally mapped across all elements of the matrix. For example, given the matrix @expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to -produce another +produce another @texline @math{3\times2} @infoline 3x2 matrix, @expr{[[1, 2, 3], [4, 5, 6]]}. @@ -21612,8 +21612,8 @@ entire four-term sum. @pindex calc-break-selections The @kbd{j b} (@code{calc-break-selections}) command controls a mode in which the ``deep structure'' of these associative formulas shows -through. Calc actually stores the above formulas as -@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain +through. Calc actually stores the above formulas as +@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain obscure reasons, by default Calc treats multiplication as right-associative.) Once you have enabled @kbd{j b} mode, selecting with the cursor on the @samp{-} sign would only select the @samp{a + b - @@ -21903,7 +21903,7 @@ of our sample formula by selecting it and pressing @kbd{n} @end smallexample Unselecting the sub-formula reveals that the minus sign, which would -normally have cancelled out with the subtraction automatically, has +normally have canceled out with the subtraction automatically, has not been able to do so because the subtraction was not part of the selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing any other mathematical operation on the whole formula will cause it @@ -22098,7 +22098,7 @@ of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may wish to eliminate the square root in the denominator by multiplying the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using -a simple @kbd{j *} command, you would get +a simple @kbd{j *} command, you would get @samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead, you would probably want to use @kbd{C-u 0 j *}, which would expand the bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More @@ -22405,7 +22405,7 @@ The most basic default simplification is the evaluation of functions. For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)} is evaluated to @expr{3}. Evaluation does not occur if the arguments to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}), -range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}), +range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}), or if the function name is not recognized (@expr{@tfn{f}(5)}), or if Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation (@expr{@tfn{sqrt}(2)}). @@ -22452,7 +22452,7 @@ Arithmetic operators like @kbd{+} and @kbd{*} always take two arguments in Calc's internal form. Sums and products of three or more terms are arranged by the associative law of algebra into a left-associative form for sums, @expr{((a + b) + c) + d}, and -(by default) a right-associative form for products, +(by default) a right-associative form for products, @expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are rearranged to left-associative form, though this rarely matters since Calc's algebra commands are designed to hide the inner structure of sums @@ -22533,7 +22533,7 @@ The product @expr{a (b + c)} is distributed over the sum only if rewritten to @expr{a (c - b)}. The distributive law of products and powers is used for adjacent -terms of the product: @expr{x^a x^b} goes to +terms of the product: @expr{x^a x^b} goes to @texline @math{x^{a+b}} @infoline @expr{x^(a+b)} where @expr{a} is a number, or an implicit 1 (as in @expr{x}), @@ -22544,9 +22544,9 @@ If the sum of the powers is zero, the product is simplified to @expr{1} or to @samp{idn(1)} if Matrix mode is enabled. The product of a negative power times anything but another negative -power is changed to use division: +power is changed to use division: @texline @math{x^{-2} y} -@infoline @expr{x^(-2) y} +@infoline @expr{x^(-2) y} goes to @expr{y / x^2} unless Matrix mode is in effect and neither @expr{x} nor @expr{y} are scalar (in which case it is considered unsafe to rearrange the order of the terms). @@ -22568,13 +22568,13 @@ The quotient @expr{x / 0} is left unsimplified or changed to an infinite quantity, as directed by the current infinite mode. @xref{Infinite Mode}. -The expression +The expression @texline @math{a / b^{-c}} -@infoline @expr{a / b^(-c)} +@infoline @expr{a / b^(-c)} is changed to @expr{a b^c}, where @expr{-c} is any negative-looking -power. Also, @expr{1 / b^c} is changed to +power. Also, @expr{1 / b^c} is changed to @texline @math{b^{-c}} -@infoline @expr{b^(-c)} +@infoline @expr{b^(-c)} for any power @expr{c}. Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)}; @@ -22590,7 +22590,7 @@ described for multiplication. Quotients of products cancel only in the leading terms of the numerator and denominator. In other words, @expr{a x b / a y b} -is cancelled to @expr{x b / y b} but not to @expr{x / y}. Once +is canceled to @expr{x b / y b} but not to @expr{x / y}. Once again this is because full cancellation can be slow; use @kbd{a s} to cancel all terms of the quotient. @@ -22614,22 +22614,22 @@ are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c} is an integer, or if either @expr{a} or @expr{b} are nonnegative real numbers. Powers of powers @expr{(a^b)^c} are simplified to @texline @math{a^{b c}} -@infoline @expr{a^(b c)} +@infoline @expr{a^(b c)} only when @expr{c} is an integer and @expr{b c} also evaluates to an integer. Without these restrictions these simplifications would not be safe because of problems with principal values. -(In other words, +(In other words, @texline @math{((-3)^{1/2})^2} -@infoline @expr{((-3)^1:2)^2} +@infoline @expr{((-3)^1:2)^2} is safe to simplify, but @texline @math{((-3)^2)^{1/2}} -@infoline @expr{((-3)^2)^1:2} +@infoline @expr{((-3)^2)^1:2} is not.) @xref{Declarations}, for ways to inform Calc that your variables satisfy these requirements. As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to @texline @math{x^{n/2}} -@infoline @expr{x^(n/2)} +@infoline @expr{x^(n/2)} only for even integers @expr{n}. If @expr{a} is known to be real, @expr{b} is an even integer, and @@ -22642,13 +22642,13 @@ for any negative-looking expression @expr{-a}. Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers @texline @math{x^{1:2}} -@infoline @expr{x^1:2} +@infoline @expr{x^1:2} for the purposes of the above-listed simplifications. -Also, note that +Also, note that @texline @math{1 / x^{1:2}} -@infoline @expr{1 / x^1:2} -is changed to +@infoline @expr{1 / x^1:2} +is changed to @texline @math{x^{-1:2}}, @infoline @expr{x^(-1:2)}, but @expr{1 / @tfn{sqrt}(x)} is left alone. @@ -22660,9 +22660,9 @@ but @expr{1 / @tfn{sqrt}(x)} is left alone. Generic identity matrices (@pxref{Matrix Mode}) are simplified by the following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b} is provably scalar, or expanded out if @expr{b} is a matrix; -@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)}; -@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to -@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b} +@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)}; +@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to +@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b} if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to @expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving @code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where @@ -22683,7 +22683,7 @@ The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}. The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to @expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or @expr{-x} if @expr{x} is provably nonnegative or nonpositive -(@pxref{Declarations}). +(@pxref{Declarations}). While most functions do not recognize the variable @code{i} as an imaginary number, the @code{arg} function does handle the two cases @@ -22693,7 +22693,7 @@ The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}. Various other expressions involving @code{conj}, @code{re}, and @code{im} are simplified, especially if some of the arguments are provably real or involve the constant @code{i}. For example, -@expr{@tfn{conj}(a + b i)} is changed to +@expr{@tfn{conj}(a + b i)} is changed to @expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a} and @expr{b} are known to be real. @@ -22810,7 +22810,7 @@ the distributive law. For example, @expr{a x^2 b / c x^3 d} will cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}. (The terms in the denominator will then be rearranged to @expr{c d x} as described above.) If there is any common integer or fractional -factor in the numerator and denominator, it is cancelled out; +factor in the numerator and denominator, it is canceled out; for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}. Non-constant common factors are not found even by @kbd{a s}. To @@ -22836,7 +22836,7 @@ several ways. (Note that these will be left unevaluated only in Symbolic mode.) First, square integer or rational factors are pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as @texline @math{2\,@tfn{sqrt}(2)}. -@infoline @expr{2 sqrt(2)}. +@infoline @expr{2 sqrt(2)}. Conceptually speaking this implies factoring the argument into primes and moving pairs of primes out of the square root, but for reasons of efficiency Calc only looks for primes up to 29. @@ -22858,7 +22858,7 @@ example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}. If the argument is multiplied by a constant, and this constant has a common integer divisor with the modulus, then this factor is -cancelled out. For example, @samp{12 x % 15} is changed to +canceled out. For example, @samp{12 x % 15} is changed to @samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15} is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may not seem ``simpler,'' they allow Calc to discover useful information @@ -22879,7 +22879,7 @@ declared to be an integer. Trigonometric functions are simplified in several ways. Whenever a products of two trigonometric functions can be replaced by a single function, the replacement is made; for example, -@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}. +@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}. Reciprocals of trigonometric functions are replaced by their reciprocal function; for example, @expr{1/@tfn{sec}(x)} is simplified to @expr{@tfn{cos}(x)}. The corresponding simplifications for the @@ -22887,7 +22887,7 @@ hyperbolic functions are also handled. Trigonometric functions of their inverse functions are simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is -simplified to @expr{x}, and similarly for @code{cos} and @code{tan}. +simplified to @expr{x}, and similarly for @code{cos} and @code{tan}. Trigonometric functions of inverses of different trigonometric functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))} to @expr{@tfn{sqrt}(1 - x^2)}. @@ -22905,30 +22905,30 @@ No simplifications for inverse trigonometric and hyperbolic functions are known, except for negative arguments of @code{arcsin}, @code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that @expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to -@expr{x}, since this only correct within an integer multiple of +@expr{x}, since this only correct within an integer multiple of @texline @math{2 \pi} -@infoline @expr{2 pi} +@infoline @expr{2 pi} radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is simplified to @expr{x} if @expr{x} is known to be real. Several simplifications that apply to logarithms and exponentials -are that @expr{@tfn{exp}(@tfn{ln}(x))}, +are that @expr{@tfn{exp}(@tfn{ln}(x))}, @texline @tfn{e}@math{^{\ln(x)}}, -@infoline @expr{e^@tfn{ln}(x)}, +@infoline @expr{e^@tfn{ln}(x)}, and @texline @math{10^{{\rm log10}(x)}} -@infoline @expr{10^@tfn{log10}(x)} +@infoline @expr{10^@tfn{log10}(x)} all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can reduce to @expr{x} if @expr{x} is provably real. The form @expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x} -is a suitable multiple of -@texline @math{\pi i} +is a suitable multiple of +@texline @math{\pi i} @infoline @expr{pi i} (as described above for the trigonometric functions), then @expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally, @expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and @code{i} where @expr{x} is provably negative, positive imaginary, or -negative imaginary. +negative imaginary. The error functions @code{erf} and @code{erfc} are simplified when their arguments are negative-looking or are calls to the @code{conj} @@ -22938,13 +22938,13 @@ function. \bigskip @end tex -Equations and inequalities are simplified by cancelling factors +Equations and inequalities are simplified by canceling factors of products, quotients, or sums on both sides. Inequalities -change sign if a negative multiplicative factor is cancelled. +change sign if a negative multiplicative factor is canceled. Non-constant multiplicative factors as in @expr{a b = a c} are -cancelled from equations only if they are provably nonzero (generally +canceled from equations only if they are provably nonzero (generally because they were declared so; @pxref{Declarations}). Factors -are cancelled from inequalities only if they are nonzero and their +are canceled from inequalities only if they are nonzero and their sign is known. Simplification also replaces an equation or inequality with @@ -23006,18 +23006,18 @@ values of @expr{x} in a certain range; outside that range, values are folded down to the 360-degree range that the inverse trigonometric functions always produce. -Powers of powers @expr{(x^a)^b} are simplified to +Powers of powers @expr{(x^a)^b} are simplified to @texline @math{x^{a b}} @infoline @expr{x^(a b)} for all @expr{a} and @expr{b}. These results will be valid only -in a restricted range of @expr{x}; for example, in +in a restricted range of @expr{x}; for example, in @texline @math{(x^2)^{1:2}} @infoline @expr{(x^2)^1:2} the powers cancel to get @expr{x}, which is valid for positive values of @expr{x} but not for negative or complex values. Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both -simplified (possibly unsafely) to +simplified (possibly unsafely) to @texline @math{x^{a/2}}. @infoline @expr{x^(a/2)}. @@ -23027,7 +23027,7 @@ Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g., Arguments of square roots are partially factored to look for squared terms that can be extracted. For example, -@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to +@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to @expr{a b @tfn{sqrt}(a+b)}. The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))}, @@ -23035,9 +23035,9 @@ The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))}, unsafe because of problems with principal values (although these simplifications are safe if @expr{x} is known to be real). -Common factors are cancelled from products on both sides of an +Common factors are canceled from products on both sides of an equation, even if those factors may be zero: @expr{a x / b x} -to @expr{a / b}. Such factors are never cancelled from +to @expr{a / b}. Such factors are never canceled from inequalities: Even @kbd{a e} is not bold enough to reduce @expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending on whether you believe @expr{x} is positive or negative). @@ -23071,7 +23071,7 @@ If units auto-ranging mode is enabled, products or quotients in which the first argument is a number which is out of range for the leading unit are modified accordingly. -When cancelling and combining units in products and quotients, +When canceling and combining units in products and quotients, Calc accounts for unit names that differ only in the prefix letter. For example, @samp{2 km m} is simplified to @samp{2000 m^2}. However, compatible but different units like @code{ft} and @code{in} @@ -23093,9 +23093,9 @@ number for an answer, then the quotient simplifies to that number. For powers and square roots, the ``unsafe'' simplifications @expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c}, -and @expr{(a^b)^c} to +and @expr{(a^b)^c} to @texline @math{a^{b c}} -@infoline @expr{a^(b c)} +@infoline @expr{a^(b c)} are done if the powers are real numbers. (These are safe in the context of units because all numbers involved can reasonably be assumed to be real.) @@ -23108,12 +23108,12 @@ according to the previous paragraph. For example, @samp{acre^1.5} is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre} is defined in terms of @samp{m^2}, and that the 2 in the power of @code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is -replaced by approximately +replaced by approximately @texline @math{(4046 m^2)^{1.5}} -@infoline @expr{(4046 m^2)^1.5}, -which is then changed to +@infoline @expr{(4046 m^2)^1.5}, +which is then changed to @texline @math{4046^{1.5} \, (m^2)^{1.5}}, -@infoline @expr{4046^1.5 (m^2)^1.5}, +@infoline @expr{4046^1.5 (m^2)^1.5}, then to @expr{257440 m^3}. The functions @code{float}, @code{frac}, @code{clean}, @code{abs}, @@ -23401,7 +23401,7 @@ answer! If you use the @code{deriv} function directly in an algebraic formula, you can write @samp{deriv(f,x,x0)} which represents the derivative -of @expr{f} with respect to @expr{x}, evaluated at the point +of @expr{f} with respect to @expr{x}, evaluated at the point @texline @math{x=x_0}. @infoline @expr{x=x0}. @@ -23441,7 +23441,7 @@ respect to a prompted-for variable. The integrator is not guaranteed to work for all integrable functions, but it is able to integrate several large classes of formulas. In particular, any polynomial or rational function (a polynomial divided by a polynomial) is acceptable. -(Rational functions don't have to be in explicit quotient form, however; +(Rational functions don't have to be in explicit quotient form, however; @texline @math{x/(1+x^{-2})} @infoline @expr{x/(1+x^-2)} is not strictly a quotient of polynomials, but it is equivalent to @@ -23472,7 +23472,7 @@ integral $\int_a^b f(x) \, dx$. Please note that the current implementation of Calc's integrator sometimes produces results that are significantly more complex than they need to -be. For example, the integral Calc finds for +be. For example, the integral Calc finds for @texline @math{1/(x+\sqrt{x^2+1})} @infoline @expr{1/(x+sqrt(x^2+1))} is several times more complicated than the answer Mathematica @@ -23480,11 +23480,11 @@ returns for the same input, although the two forms are numerically equivalent. Also, any indefinite integral should be considered to have an arbitrary constant of integration added to it, although Calc does not write an explicit constant of integration in its result. For example, -Calc's solution for +Calc's solution for @texline @math{1/(1+\tan x)} -@infoline @expr{1/(1+tan(x))} +@infoline @expr{1/(1+tan(x))} differs from the solution given in the @emph{CRC Math Tables} by a -constant factor of +constant factor of @texline @math{\pi i / 2} @infoline @expr{pi i / 2}, due to a different choice of constant of integration. @@ -23544,9 +23544,9 @@ in your @code{IntegRules}. @tindex Ei As a more serious example, the expression @samp{exp(x)/x} cannot be integrated in terms of the standard functions, so the ``exponential -integral'' function +integral'' function @texline @math{{\rm Ei}(x)} -@infoline @expr{Ei(x)} +@infoline @expr{Ei(x)} was invented to describe it. We can get Calc to do this integral in terms of a made-up @code{Ei} function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]} @@ -23717,18 +23717,18 @@ form @expr{X = 0}. This command also works for inequalities, as in @expr{y < 3x + 6}. Some inequalities cannot be solved where the analogous equation could -be; for example, solving +be; for example, solving @texline @math{a < b \, c} -@infoline @expr{a < b c} +@infoline @expr{a < b c} for @expr{b} is impossible without knowing the sign of @expr{c}. In this case, @kbd{a S} will -produce the result +produce the result @texline @math{b \mathbin{\hbox{\code{!=}}} a/c} -@infoline @expr{b != a/c} +@infoline @expr{b != a/c} (using the not-equal-to operator) to signify that the direction of the -inequality is now unknown. The inequality +inequality is now unknown. The inequality @texline @math{a \le b \, c} -@infoline @expr{a <= b c} +@infoline @expr{a <= b c} is not even partially solved. @xref{Declarations}, for a way to tell Calc that the signs of the variables in a formula are in fact known. @@ -24186,13 +24186,13 @@ value of the variable which minimizes the formula's value, along with the minimum value itself. Note that this command looks for a @emph{local} minimum. Many functions -have more than one minimum; some, like +have more than one minimum; some, like @texline @math{x \sin x}, -@infoline @expr{x sin(x)}, +@infoline @expr{x sin(x)}, have infinitely many. In fact, there is no easy way to define the -``global'' minimum of +``global'' minimum of @texline @math{x \sin x} -@infoline @expr{x sin(x)} +@infoline @expr{x sin(x)} but Calc can still locate any particular local minimum for you. Calc basically goes downhill from the initial guess until it finds a point at which the function's value is greater both to the left @@ -24271,7 +24271,7 @@ to be determined. For a typical set of measured data there will be no single @expr{m} and @expr{b} that exactly fit the data; in this case, Calc chooses values of the parameters that provide the closest possible fit. The model formula can be entered in various ways after -the key sequence @kbd{a F} is pressed. +the key sequence @kbd{a F} is pressed. If the letter @kbd{P} is pressed after @kbd{a F} but before the model description is entered, the data as well as the model formula will be @@ -24319,7 +24319,7 @@ the @dfn{parameters} of the model. The @kbd{a F} command takes the data set to be fitted from the stack. By default, it expects the data in the form of a matrix. For example, -for a linear or polynomial fit, this would be a +for a linear or polynomial fit, this would be a @texline @math{2\times N} @infoline 2xN matrix where the first row is a list of @expr{x} values and the second @@ -24327,10 +24327,10 @@ row has the corresponding @expr{y} values. For the multilinear fit shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2}, @expr{x_3}, and @expr{y}, respectively). -If you happen to have an +If you happen to have an @texline @math{N\times2} @infoline Nx2 -matrix instead of a +matrix instead of a @texline @math{2\times N} @infoline 2xN matrix, just press @kbd{v t} first to transpose the matrix. @@ -24425,13 +24425,13 @@ $$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$ which is clearly zero if @expr{a + b x} exactly fits all data points, and increases as various @expr{a + b x_i} values fail to match the corresponding @expr{y_i} values. There are several reasons why the -summand is squared, one of them being to ensure that +summand is squared, one of them being to ensure that @texline @math{\chi^2 \ge 0}. @infoline @expr{chi^2 >= 0}. Least-squares fitting simply chooses the values of @expr{a} and @expr{b} -for which the error +for which the error @texline @math{\chi^2} -@infoline @expr{chi^2} +@infoline @expr{chi^2} is as small as possible. Other kinds of models do the same thing but with a different model @@ -24593,9 +24593,9 @@ contain error forms. The data values must either all include errors or all be plain numbers. Error forms can go anywhere but generally go on the numbers in the last row of the data matrix. If the last row contains error forms -@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}', -@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}', -then the +@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}', +@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}', +then the @texline @math{\chi^2} @infoline @expr{chi^2} statistic is now, @@ -24617,9 +24617,9 @@ the fitting operation. If there are error forms on other rows of the data matrix, all the errors for a given data point are combined; the square root of the -sum of the squares of the errors forms the +sum of the squares of the errors forms the @texline @math{\sigma_i} -@infoline @expr{sigma_i} +@infoline @expr{sigma_i} used for the data point. Both @kbd{a F} and @kbd{H a F} can accept error forms in the input @@ -24627,19 +24627,19 @@ matrix, although if you are concerned about error analysis you will probably use @kbd{H a F} so that the output also contains error estimates. -If the input contains error forms but all the +If the input contains error forms but all the @texline @math{\sigma_i} -@infoline @expr{sigma_i} +@infoline @expr{sigma_i} values are the same, it is easy to see that the resulting fitted model -will be the same as if the input did not have error forms at all +will be the same as if the input did not have error forms at all @texline (@math{\chi^2} @infoline (@expr{chi^2} -is simply scaled uniformly by +is simply scaled uniformly by @texline @math{1 / \sigma^2}, -@infoline @expr{1 / sigma^2}, +@infoline @expr{1 / sigma^2}, which doesn't affect where it has a minimum). But there @emph{will} be a difference in the estimated errors of the coefficients reported by -@kbd{H a F}. +@kbd{H a F}. Consult any text on statistical modeling of data for a discussion of where these error estimates come from and how they should be @@ -24671,18 +24671,18 @@ will have length @expr{M = d+1} with the constant term first. The covariance matrix @expr{C} computed from the fit. This is an @var{m}x@var{m} symmetric matrix; the diagonal elements @texline @math{C_{jj}} -@infoline @expr{C_j_j} -are the variances +@infoline @expr{C_j_j} +are the variances @texline @math{\sigma_j^2} -@infoline @expr{sigma_j^2} +@infoline @expr{sigma_j^2} of the parameters. The other elements are covariances -@texline @math{\sigma_{ij}^2} -@infoline @expr{sigma_i_j^2} +@texline @math{\sigma_{ij}^2} +@infoline @expr{sigma_i_j^2} that describe the correlation between pairs of parameters. (A related -set of numbers, the @dfn{linear correlation coefficients} +set of numbers, the @dfn{linear correlation coefficients} @texline @math{r_{ij}}, @infoline @expr{r_i_j}, -are defined as +are defined as @texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.) @infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.) @@ -24693,35 +24693,35 @@ will instead be an empty vector; this is always the case for the polynomial and multilinear fits described so far. @item -The value of +The value of @texline @math{\chi^2} -@infoline @expr{chi^2} +@infoline @expr{chi^2} for the fit, calculated by the formulas shown above. This gives a measure of the quality of the fit; statisticians consider @texline @math{\chi^2 \approx N - M} -@infoline @expr{chi^2 = N - M} +@infoline @expr{chi^2 = N - M} to indicate a moderately good fit (where again @expr{N} is the number of data points and @expr{M} is the number of parameters). @item A measure of goodness of fit expressed as a probability @expr{Q}. This is computed from the @code{utpc} probability distribution -function using +function using @texline @math{\chi^2} -@infoline @expr{chi^2} +@infoline @expr{chi^2} with @expr{N - M} degrees of freedom. A value of 0.5 implies a good fit; some texts recommend that often @expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In -particular, +particular, @texline @math{\chi^2} -@infoline @expr{chi^2} +@infoline @expr{chi^2} statistics assume the errors in your inputs follow a normal (Gaussian) distribution; if they don't, you may have to accept smaller values of @expr{Q}. The @expr{Q} value is computed only if the input included error estimates. Otherwise, Calc will report the symbol @code{nan} -for @expr{Q}. The reason is that in this case the +for @expr{Q}. The reason is that in this case the @texline @math{\chi^2} @infoline @expr{chi^2} value has effectively been used to estimate the original errors @@ -24763,7 +24763,7 @@ Power law. @mathit{a x^b y^c}. @item q Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}. @item g -Gaussian. +Gaussian. @texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}. @infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}. @item s @@ -24788,7 +24788,7 @@ the parameter values from the vector that is placed in the trail.) All models except Gaussian, logistics, Hubbert and polynomials can generalize as shown to any number of independent variables. Also, all -the built-in models except for the logistic and Hubbert curves have an +the built-in models except for the logistic and Hubbert curves have an additive or multiplicative parameter shown as @expr{a} in the above table which can be replaced by zero or one, as appropriate, by typing @kbd{h} before the model key. @@ -24893,9 +24893,9 @@ form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always returns results in the range from @mathit{-90} to 90 degrees (or the equivalent range in radians). Suppose you had data that you believed to represent roughly three oscillations of a sine wave, -so that the argument of the sine might go from zero to +so that the argument of the sine might go from zero to @texline @math{3\times360} -@infoline @mathit{3*360} +@infoline @mathit{3*360} degrees. The above model would appear to be a good way to determine the true frequency and phase of the sine wave, but in practice it @@ -24955,18 +24955,18 @@ ln(y) = ln(a) + b ln(x) @end example @noindent -which matches the desired form with +which matches the desired form with @texline @math{Y = \ln(y)}, -@infoline @expr{Y = ln(y)}, +@infoline @expr{Y = ln(y)}, @texline @math{A = \ln(a)}, @infoline @expr{A = ln(a)}, -@expr{F = 1}, @expr{B = b}, and +@expr{F = 1}, @expr{B = b}, and @texline @math{G = \ln(x)}. -@infoline @expr{G = ln(x)}. +@infoline @expr{G = ln(x)}. Calc thus computes the logarithms of your @expr{y} and @expr{x} values, -does a linear fit for @expr{A} and @expr{B}, then solves to get -@texline @math{a = \exp(A)} -@infoline @expr{a = exp(A)} +does a linear fit for @expr{A} and @expr{B}, then solves to get +@texline @math{a = \exp(A)} +@infoline @expr{a = exp(A)} and @expr{b = B}. Another interesting example is the ``quadratic'' model, which can @@ -25015,7 +25015,7 @@ from the list of parameters when you answer the variables prompt. A last desperate step would be to use the general-purpose @code{minimize} function rather than @code{fit}. After all, both -functions solve the problem of minimizing an expression (the +functions solve the problem of minimizing an expression (the @texline @math{\chi^2} @infoline @expr{chi^2} sum) by adjusting certain parameters in the expression. The @kbd{a F} @@ -25026,9 +25026,9 @@ command can do the same thing by brute force. A compromise would be to pick out a few parameters without which the fit is linearizable, and use @code{minimize} on a call to @code{fit} which efficiently takes care of the rest of the parameters. The thing -to be minimized would be the value of +to be minimized would be the value of @texline @math{\chi^2} -@infoline @expr{chi^2} +@infoline @expr{chi^2} returned as the fifth result of the @code{xfit} function: @smallexample @@ -25086,13 +25086,13 @@ of the sum of the squares of the errors. It then changes @expr{x} and @expr{y} to be plain numbers, and makes @expr{z} into an error form with this combined error. The @expr{Y(x,y,z)} part of the linearized model is evaluated, and the result should be an error -form. The error part of that result is used for +form. The error part of that result is used for @texline @math{\sigma_i} -@infoline @expr{sigma_i} -for the data point. If for some reason @expr{Y(x,y,z)} does not return -an error form, the combined error from @expr{z} is used directly for +@infoline @expr{sigma_i} +for the data point. If for some reason @expr{Y(x,y,z)} does not return +an error form, the combined error from @expr{z} is used directly for @texline @math{\sigma_i}. -@infoline @expr{sigma_i}. +@infoline @expr{sigma_i}. Finally, @expr{z} is also stripped of its error for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on; the righthand side of the linearized model is computed in regular @@ -25104,7 +25104,7 @@ depends only on the dependent variable @expr{z}, and in fact is often simply equal to @expr{z}. For common cases like polynomials and multilinear models, the combined error is simply used as the @texline @math{\sigma} -@infoline @expr{sigma} +@infoline @expr{sigma} for the data point with no further ado.) @tex @@ -25481,7 +25481,7 @@ this would be a division by zero. But at @expr{k = k_0}, this formula works out to the indeterminate form @expr{0 / 0}, which Calc will not assume is zero. Better would be to use @samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does -an ``if-then-else'' test: This expression says, ``if +an ``if-then-else'' test: This expression says, ``if @texline @math{k \ne k_0}, @infoline @expr{k != k_0}, then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)} @@ -25644,7 +25644,7 @@ equivalent expression involving intervals: @samp{b in [a .. c)}. of @samp{<} and @samp{<=} are allowed, or any of the four combinations of @samp{>} and @samp{>=}. Four-argument constructions like @samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that -involve both equalities and inequalities, are not allowed. +involve both equations and inequalities, are not allowed. @kindex a . @pindex calc-remove-equal @@ -26496,16 +26496,16 @@ f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF}, then the rule set @samp{[f(0) := 0, import(linearF)]} will apply all three rules. It is possible to modify the imported rules slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports -the rule set @expr{x} with all occurrences of +the rule set @expr{x} with all occurrences of @texline @math{v_1}, -@infoline @expr{v1}, -as either a variable name or a function name, replaced with +@infoline @expr{v1}, +as either a variable name or a function name, replaced with @texline @math{x_1} -@infoline @expr{x1} -and so on. (If +@infoline @expr{x1} +and so on. (If @texline @math{v_1} -@infoline @expr{v1} -is used as a function name, then +@infoline @expr{v1} +is used as a function name, then @texline @math{x_1} @infoline @expr{x1} must be either a function name itself or a @w{@samp{< >}} nameless @@ -27609,7 +27609,7 @@ the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies @code{tri} to the value on the top of the stack. @xref{Programming}. @cindex Quaternions -The following rule set, contributed by +The following rule set, contributed by @texline Fran\c cois @infoline Francois Pinard, implements @dfn{quaternions}, a generalization of the concept of @@ -27764,9 +27764,9 @@ equivalent temperature on the Fahrenheit scale. While many of Calc's conversion factors are exact, some are necessarily approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then unit conversions will try to give exact, rational conversions, but it -isn't always possible. Given @samp{55 mph} in fraction mode, typing -@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example, -while typing @kbd{u c au/yr @key{RET}} produces +isn't always possible. Given @samp{55 mph} in fraction mode, typing +@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example, +while typing @kbd{u c au/yr @key{RET}} produces @samp{5.18665819999e-3 au/yr}. If the units you request are inconsistent with the original units, the @@ -27994,7 +27994,7 @@ defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}. Other units used by @TeX{} are available; they are @code{texpc} (a pica), @code{texbp} (a ``big point'', equal to a standard point which is larger than the point used by @TeX{}), @code{texdd} (a Didot point), -@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point, +@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point, all dimensions representable in @TeX{} are multiples of this value). When Calc is using the @TeX{} or La@TeX{} language mode (@pxref{TeX @@ -28131,17 +28131,17 @@ The units @code{dB} (decibels) and @code{Np} (nepers) are logarithmic units which are manipulated differently than standard units. Calc provides commands to work with these logarithmic units. -Decibels and nepers are used to measure power quantities as well as +Decibels and nepers are used to measure power quantities as well as field quantities (quantities whose squares are proportional to power); these two types of quantities are handled slightly different from each other. By default the Calc commands work as if power quantities are being used; with the @kbd{H} prefix the Calc commands work as if field quantities are being used. -The decibel level of a power +The decibel level of a power @infoline @math{P1}, @texline @math{P_1}, -relative to a reference power +relative to a reference power @infoline @math{P0}, @texline @math{P_0}, is defined to be @@ -28151,10 +28151,10 @@ is defined to be one-tenth of a bel. The bel, named after Alexander Graham Bell, was considered to be too large of a unit and was effectively replaced by the decibel.) If @math{F} is a field quantity with power -@math{P=k F^2}, then a reference quantity of +@math{P=k F^2}, then a reference quantity of @infoline @math{F0} @texline @math{F_0} -would correspond to a power of +would correspond to a power of @infoline @math{P0=k F0^2}. @texline @math{P_{0}=kF_{0}^2}. If @@ -28163,7 +28163,7 @@ If then @ifnottex -@example +@example 10 log10(P1/P0) = 10 log10(F1^2/F0^2) = 20 log10(F1/F0). @end example @end ifnottex @@ -28175,42 +28175,42 @@ $$ 10 \log_{10}(P_1/P_0) = 10 \log_{10}(F_1^2/F_0^2) = 20 @noindent In order to get the same decibel level regardless of whether a field quantity or the corresponding power quantity is used, the decibel -level of a field quantity +level of a field quantity @infoline @math{F1}, -@texline @math{F_1}, -relative to a reference +@texline @math{F_1}, +relative to a reference @infoline @math{F0}, -@texline @math{F_0}, +@texline @math{F_0}, is defined as @infoline @math{20 log10(F1/F0) dB}. @texline @math{20 \log_{10}(F_{1}/F_{0}) {\rm dB}}. -For example, the decibel value of a sound pressure level of +For example, the decibel value of a sound pressure level of @infoline @math{60 uPa} @texline @math{60 \mu{\rm Pa}} -relative to +relative to @infoline @math{20 uPa} @texline @math{20 \mu{\rm Pa}} -(the threshhold of human hearing) is +(the threshold of human hearing) is @infoline @math{20 log10(60 uPa/ 20 uPa) dB = 20 log10(3) dB}, @texline @math{20 \log_{10}(60 \mu{\rm Pa}/20 \mu{\rm Pa}) {\rm dB} = 20 \log_{10}(3) {\rm dB}}, -which is about +which is about @infoline @math{9.54 dB}. @texline @math{9.54 {\rm dB}}. Note that in taking the ratio, the original units cancel and so these -logarithmic units are dimensionless. +logarithmic units are dimensionless. Nepers (named after John Napier, who is credited with inventing the logarithm) are similar to bels except they use natural logarithms instead -of common logarithms. The neper level of a power +of common logarithms. The neper level of a power @infoline @math{P1}, @texline @math{P_1}, -relative to a reference power +relative to a reference power @infoline @math{P0}, @texline @math{P_0}, is @infoline @math{(1/2) ln(P1/P0) Np}. @texline @math{(1/2) \ln(P_1/P_0) {\rm Np}}. -The neper level of a field +The neper level of a field @infoline @math{F1}, @texline @math{F_1}, relative to a reference field @@ -28223,13 +28223,13 @@ is @vindex calc-lu-power-reference @vindex calc-lu-field-reference For power quantities, Calc uses -@infoline @math{1 mW} +@infoline @math{1 mW} @texline @math{1 {\rm mW}} -as the default reference quantity; this default can be changed by changing +as the default reference quantity; this default can be changed by changing the value of the customizable variable @code{calc-lu-power-reference} (@pxref{Customizing Calc}). -For field quantities, Calc uses -@infoline @math{20 uPa} +For field quantities, Calc uses +@infoline @math{20 uPa} @texline @math{20 \mu{\rm Pa}} as the default reference quantity; this is the value used in acoustics which is where decibels are commonly encountered. This default can be @@ -28247,9 +28247,9 @@ command computes the power quantity corresponding to a given number of logarithmic units. With the capital @kbd{O} prefix, @kbd{O l q}, the reference level will be read from the top of the stack. (In an algebraic formula, @code{lupquant} can be given an optional second -argument which will be used for the reference level.) For example, -@code{20 dB @key{RET} l q} will return @code{100 mW}; -@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}. +argument which will be used for the reference level.) For example, +@code{20 dB @key{RET} l q} will return @code{100 mW}; +@code{20 dB @key{RET} 4 W @key{RET} O l q} will return @code{400 W}. The @kbd{H l q} [@code{lufquant}] command behaves like @kbd{l q} but computes field quantities instead of power quantities. @@ -28288,13 +28288,13 @@ the reference level can be given as an optional second argument. @tindex lufdiv The sum of two power or field quantities doesn't correspond to the sum of the corresponding decibel or neper levels. If the powers -corresponding to decibel levels -@infoline @math{D1} -@texline @math{D_1} -and -@infoline @math{D2} -@texline @math{D_2} -are added, the corresponding decibel level ``sum'' will be +corresponding to decibel levels +@infoline @math{D1} +@texline @math{D_1} +and +@infoline @math{D2} +@texline @math{D_2} +are added, the corresponding decibel level ``sum'' will be @ifnottex @example @@ -28338,7 +28338,7 @@ $$ D + 10 \log_{10}(N) {\rm dB},$$ @noindent if a field quantity is multiplied by @math{N} the corresponding decibel level -will be +will be @ifnottex @example @@ -28375,31 +28375,31 @@ operating on notes. Scientific pitch notation refers to a note by giving a letter A through G, possibly followed by a flat or sharp) with a subscript indicating an octave number. Each octave starts with C and ends with -B and +B and @c increasing each note by a semitone will result @c in the sequence @expr{C}, @expr{C} sharp, @expr{D}, @expr{E} flat, @expr{E}, @c @expr{F}, @expr{F} sharp, @expr{G}, @expr{A} flat, @expr{A}, @expr{B} -@c flat and @expr{B}. +@c flat and @expr{B}. the octave numbered 0 was chosen to correspond to the lowest audible frequency. Using this system, middle C (about 261.625 Hz) corresponds to the note @expr{C} in octave 4 and is denoted @expr{C_4}. Any frequency can be described by giving a note plus an offset in cents (where a cent is a ratio of frequencies so that a -semitone consists of 100 cents). +semitone consists of 100 cents). The midi note number system assigns numbers to notes so that @expr{C_(-1)} corresponds to the midi note number 0 and @expr{G_9} corresponds to the midi note number 127. A midi controller can have up to 128 keys and each midi note number from 0 to 127 corresponds to -a possible key. +a possible key. @kindex l s @pindex calc-spn @tindex spn The @kbd{l s} (@code{calc-spn}) [@code{spn}] command converts either a frequency or a midi number to scientific pitch notation. For -example, @code{500 Hz} gets converted to -@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}. +example, @code{500 Hz} gets converted to +@code{B_4 + 21.3094853649 cents} and @code{84} to @code{C_6}. @kindex l m @@ -28464,7 +28464,7 @@ The @kbd{s s} (@code{calc-store}) command stores the value at the top of the stack into a specified variable. It prompts you to enter the name of the variable. If you press a single digit, the value is stored immediately in one of the ``quick'' variables @code{q0} through -@code{q9}. Or you can enter any variable name. +@code{q9}. Or you can enter any variable name. @kindex s t @pindex calc-store-into @@ -28554,12 +28554,12 @@ and @kbd{s ]} which decrease or increase a variable by one. All the arithmetic stores accept the Inverse prefix to reverse the order of the operands. If @expr{v} represents the contents of the variable, and @expr{a} is the value drawn from the stack, then regular -@w{@kbd{s -}} assigns +@w{@kbd{s -}} assigns @texline @math{v \coloneq v - a}, -@infoline @expr{v := v - a}, +@infoline @expr{v := v - a}, but @kbd{I s -} assigns @texline @math{v \coloneq a - v}. -@infoline @expr{v := a - v}. +@infoline @expr{v := a - v}. While @kbd{I s *} might seem pointless, it is useful if matrix multiplication is involved. Actually, all the arithmetic stores use formulas designed to behave usefully both @@ -28668,7 +28668,7 @@ magic property is preserved, however, when a variable is copied with @kindex s k @pindex calc-copy-special-constant If one of the ``special constants'' is redefined (or undefined) so that -it no longer has its magic property, the property can be restored with +it no longer has its magic property, the property can be restored with @kbd{s k} (@code{calc-copy-special-constant}). This command will prompt for a special constant and a variable to store it in, and so a special constant can be stored in any variable. Here, the special constant that @@ -28850,7 +28850,7 @@ explicitly naming them in an @kbd{s p} command.) The @kbd{s i} (@code{calc-insert-variables}) command writes the values of all Calc variables into a specified buffer. The variables are written with the prefix @code{var-} in the form of -Lisp @code{setq} commands +Lisp @code{setq} commands which store the values in string form. You can place these commands in your Calc init file (or @file{.emacs}) if you wish, though in this case it would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i} @@ -29159,9 +29159,9 @@ In the first case, ``x'' and ``y'' are each vectors (not necessarily of the same length); either or both may instead be interval forms. The ``z'' value must be a matrix with the same number of rows as elements in ``x'', and the same number of columns as elements in ``y''. The -result is a surface plot where +result is a surface plot where @texline @math{z_{ij}} -@infoline @expr{z_ij} +@infoline @expr{z_ij} is the height of the point at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will be displayed from a certain default viewpoint; you can change this @@ -29270,9 +29270,9 @@ that don't have common ``x'' values. (Of course, the range of ``x'' values covered by all the curves ought to be roughly the same if they are to look nice on the same graph.) -For example, to plot +For example, to plot @texline @math{\sin n x} -@infoline @expr{sin(n x)} +@infoline @expr{sin(n x)} for integers @expr{n} from 1 to 5, you could use @kbd{v x} to create a vector of integers (@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)} @@ -29510,8 +29510,8 @@ available for any device. The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns the symbols at the data points on or off, or sets the point style. If you turn both lines and points off, the data points will show as -tiny dots. If the ``y'' values being plotted contain error forms and -the connecting lines are turned off, then this command will also turn +tiny dots. If the ``y'' values being plotted contain error forms and +the connecting lines are turned off, then this command will also turn the error bars on or off. @cindex @code{LineStyles} variable @@ -29563,7 +29563,7 @@ terminals with no special graphics facilities. It writes a crude picture of the graph composed of characters like @code{-} and @code{|} to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays. The graph is made the same size as the Emacs screen, which on most -dumb terminals will be +dumb terminals will be @texline @math{80\times24} @infoline 80x24 characters. The graph is displayed in @@ -29820,7 +29820,7 @@ difference.) @pindex calc-prepend-to-register @pindex calc-append-to-register @cindex Registers -An alternative to killing and yanking stack entries is using +An alternative to killing and yanking stack entries is using registers in Calc. Saving stack entries in registers is like saving text in normal Emacs registers; although, like Calc's kill commands, register commands always operate on whole stack @@ -29935,7 +29935,7 @@ separately as a matrix element. If a line contained would correctly split the line into two error forms. @xref{Matrix Functions}, to see how to pull the matrix apart into its -constituent rows and columns. (If it is a +constituent rows and columns. (If it is a @texline @math{1\times1} @infoline 1x1 matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.) @@ -30273,7 +30273,7 @@ same limit as last time. @key{INV GCD} computes the LCM (least common multiple) function. -@key{INV FACT} is the gamma function. +@key{INV FACT} is the gamma function. @texline @math{\Gamma(x) = (x-1)!}. @infoline @expr{gamma(x) = (x-1)!}. @@ -30490,7 +30490,7 @@ Similarly, Calc will use @TeX{} language for @code{tex-mode}, @code{plain-tex-mode} and @code{context-mode}, C language for @code{c-mode} and @code{c++-mode}, FORTRAN language for @code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode}, -and eqn for @code{nroff-mode} (@pxref{Customizing Calc}). +and eqn for @code{nroff-mode} (@pxref{Customizing Calc}). These can be overridden with Calc's mode changing commands (@pxref{Mode Settings in Embedded Mode}). If no suitable language is available, Calc will continue with its current language. @@ -30670,13 +30670,13 @@ version. Plain formulas are preceded and followed by @samp{%%%} signs by default. This notation has the advantage that the @samp{%} -character begins a comment in @TeX{} and La@TeX{}, so if your formula is +character begins a comment in @TeX{} and La@TeX{}, so if your formula is embedded in a @TeX{} or La@TeX{} document its plain version will be invisible in the final printed copy. Certain major modes have different -delimiters to ensure that the ``plain'' version will be -in a comment for those modes, also. +delimiters to ensure that the ``plain'' version will be +in a comment for those modes, also. See @ref{Customizing Embedded Mode} to see how to change the ``plain'' -formula delimiters. +formula delimiters. There are several notations which Calc's parser for ``big'' formatted formulas can't yet recognize. In particular, it can't @@ -31178,7 +31178,7 @@ We would have to go down to the other formula and press @kbd{C-x * u} on it in order to get it to notice the new annotation. Two more mode-recording modes selectable by @kbd{m R} are available -which are also available outside of Embedded mode. +which are also available outside of Embedded mode. (@pxref{General Mode Commands}.) They are @code{Save}, in which mode settings are recorded permanently in your Calc init file (the file given by the variable @code{calc-settings-file}, typically @file{~/.emacs.d/calc.el}) @@ -31195,11 +31195,11 @@ for @code{Save} have no effect. @noindent You can modify Embedded mode's behavior by setting various Lisp -variables described here. These variables are customizable +variables described here. These variables are customizable (@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable} or @kbd{M-x edit-options} to adjust a variable on the fly. (Another possibility would be to use a file-local variable annotation at -the end of the file; +the end of the file; @pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.) Many of the variables given mentioned here can be set to depend on the major mode of the editing buffer (@pxref{Customizing Calc}). @@ -31334,7 +31334,7 @@ Calc never scans for this string; Calc always looks for the annotation itself. But this is the string that is inserted before the opening bracket when Calc adds an annotation on its own. The default is @code{"% "}, but may be different for different major -modes. +modes. @vindex calc-embedded-close-mode The @code{calc-embedded-close-mode} variable is a string which @@ -31459,7 +31459,7 @@ without its key binding, type @kbd{M-x} and enter a function name. (The (If the command you give implies a function, the function will be saved, and if the function has any display formats, those will be saved, but not the other way around: Saving a function will not save any commands -or key bindings associated with the function.) +or key bindings associated with the function.) @kindex Z E @pindex calc-user-define-edit @@ -31542,7 +31542,7 @@ Once you have bound your keyboard macro to a key, you can use @cindex Keyboard macros, editing The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has been defined by a keyboard macro tries to use the @code{edmacro} package -edit the macro. Type @kbd{C-c C-c} to finish editing and update +edit the macro. Type @kbd{C-c C-c} to finish editing and update the definition stored on the key, or, to cancel the edit, kill the buffer with @kbd{C-x k}. The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @@ -31552,7 +31552,7 @@ sequences, written in all uppercase, as must the prefixes @code{C-} and copied verbatim into the keyboard macro. Basically, the notation is the same as is used in all of this manual's examples, except that the manual takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}}, -we take it for granted that it is clear we really mean +we take it for granted that it is clear we really mean @kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}. @kindex C-x * m @@ -31823,7 +31823,7 @@ prompt for the @kbd{Z #} command; it will not play any role in any subsequent calculations.) This command allows your keyboard macros to accept numbers or formulas as interactive input. -As an example, +As an example, @kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for input with ``Power: '' in the minibuffer, then return 2 to the provided power. (The response to the prompt that's given, 3 in this example, @@ -31900,7 +31900,7 @@ The third prompt is for an algebraic function name. The default is to use the same name as the command name but without the @samp{calc-} prefix. (If this is of the form @samp{User-m}, the hyphen is removed so it won't be taken for a minus sign in algebraic formulas.) -This is the name you will use if you want to enter your +This is the name you will use if you want to enter your new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}. Then the new function can be invoked by pushing two numbers on the stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic @@ -32695,7 +32695,7 @@ same thing with a single division by 512. @end ignore @tindex mysin A somewhat limited sine function could be defined as follows, using the -well-known Taylor series expansion for +well-known Taylor series expansion for @texline @math{\sin x}: @infoline @samp{sin(x)}: @@ -34631,7 +34631,7 @@ the derivative is evaluated at the value of @var{var}; otherwise, the derivative is left in terms of @var{var}. If the expression contains functions for which no derivative formula is known, new derivative functions are invented by adding primes to the names; @pxref{Calculus}. -However, if @var{symb} is non-@code{nil}, the presence of undifferentiable +However, if @var{symb} is non-@code{nil}, the presence of nondifferentiable functions in @var{expr} instead cancels the whole differentiation, and @code{deriv} returns @code{nil} instead. @@ -35241,7 +35241,7 @@ to use a different prefix, you can put @end example @noindent -in your .emacs file. +in your .emacs file. (@xref{Key Bindings,,Customizing Key Bindings,emacs, The GNU Emacs Manual}, for more information on binding keys.) A convenient way to start Calc is with @kbd{C-x * *}; to make it equally @@ -35269,7 +35269,7 @@ to see how regular expressions work. @defvar calc-settings-file The variable @code{calc-settings-file} holds the file name in which commands like @kbd{m m} and @kbd{Z P} store ``permanent'' -definitions. +definitions. If @code{calc-settings-file} is not your user init file (typically @file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is @code{nil}, then Calc will automatically load your settings file (if it @@ -35314,7 +35314,7 @@ enabled, it will try to use the current major mode to determine what language should be used. (This can be overridden using Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.) The variable @code{calc-language-alist} consists of a list of pairs of -the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example, +the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example, @code{(latex-mode . latex)} is one such pair. If Calc embedded is activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself to use the language @var{LANGUAGE}. @@ -35342,7 +35342,7 @@ what formulas @kbd{C-x * a} will activate in a buffer. It is a regular expression, and when activating embedded formulas with @kbd{C-x * a}, it will tell Calc that what follows is a formula to be activated. (Calc also uses other patterns to find formulas, such as -@samp{=>} and @samp{:=}.) +@samp{=>} and @samp{:=}.) The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks for @samp{%Embed} followed by any number of lines beginning with @@ -35367,7 +35367,7 @@ It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} . (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*")) @end example Any major modes added to @code{calc-embedded-announce-formula-alist} -should also be added to @code{calc-embedded-open-close-plain-alist} +should also be added to @code{calc-embedded-open-close-plain-alist} and @code{calc-embedded-open-close-mode-alist}. @end defvar @@ -35378,7 +35378,7 @@ See @ref{Customizing Embedded Mode}.@* The variables @code{calc-embedded-open-formula} and @code{calc-embedded-close-formula} control the region that Calc will activate as a formula when Embedded mode is entered with @kbd{C-x * e}. -They are regular expressions; +They are regular expressions; Calc normally scans backward and forward in the buffer for the nearest text matching these regular expressions to be the ``formula delimiters''. @@ -35403,7 +35403,7 @@ The variable @code{calc-embedded-open-close-formula-alist} is used to set @code{calc-embedded-open-formula} and @code{calc-embedded-close-formula} to different regular expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form +It consists of a list of lists of the form @code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP} @var{CLOSE-FORMULA-REGEXP})}, and its default value is @code{nil}. @@ -35422,7 +35422,7 @@ The default value of @code{calc-embedded-word-regexp} is The variable @code{calc-embedded-word-regexp-alist} is used to set @code{calc-embedded-word-regexp} to a different regular expression depending on the major mode of the editing buffer. -It consists of a list of lists of the form +It consists of a list of lists of the form @code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is @code{nil}. @end defvar @@ -35437,8 +35437,8 @@ formulas. Note that these are actual strings, not regular expressions, because Calc must be able to write these string into a buffer as well as to recognize them. -The default string for @code{calc-embedded-open-plain} is -@code{"%%% "}, note the trailing space. The default string for +The default string for @code{calc-embedded-open-plain} is +@code{"%%% "}, note the trailing space. The default string for @code{calc-embedded-close-plain} is @code{" %%%\n"}, without the trailing newline here, the first line of a Big mode formula that followed might be shifted over with respect to the other lines. @@ -35447,7 +35447,7 @@ The variable @code{calc-embedded-open-close-plain-alist} is used to set @code{calc-embedded-open-plain} and @code{calc-embedded-close-plain} to different strings depending on the major mode of the editing buffer. -It consists of a list of lists of the form +It consists of a list of lists of the form @code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING} @var{CLOSE-PLAIN-STRING})}, and its default value is @example @@ -35490,7 +35490,7 @@ The variable @code{calc-embedded-open-close-new-formula-alist} is used to set @code{calc-embedded-open-new-formula} and @code{calc-embedded-close-new-formula} to different strings depending on the major mode of the editing buffer. -It consists of a list of lists of the form +It consists of a list of lists of the form @code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING} @var{CLOSE-NEW-FORMULA-STRING})}, and its default value is @code{nil}. @@ -35508,7 +35508,7 @@ necessary to add them to user-written annotations. The default value of @code{calc-embedded-open-mode} is @code{"% "} and the default value of @code{calc-embedded-close-mode} is -@code{"\n"}. +@code{"\n"}. If you change the value of @code{calc-embedded-close-mode}, it is a good idea still to end with a newline so that mode annotations will appear on lines by themselves. @@ -35517,7 +35517,7 @@ The variable @code{calc-embedded-open-close-mode-alist} is used to set @code{calc-embedded-open-mode} and @code{calc-embedded-close-mode} to different strings expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form +It consists of a list of lists of the form @code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING} @var{CLOSE-MODE-STRING})}, and its default value is @example @@ -35548,7 +35548,7 @@ units. The default value of @code{calc-lu-power-reference} is @code{"mW"} and the default value of @code{calc-lu-field-reference} is -@code{"20 uPa"}. +@code{"20 uPa"}. @end defvar @defvar calc-note-threshold @@ -35564,15 +35564,15 @@ The default value of @code{calc-note-threshold} is 1. @defvarx calc-selected-face @defvarx calc-nonselected-face See @ref{Displaying Selections}.@* -The variable @code{calc-highlight-selections-with-faces} +The variable @code{calc-highlight-selections-with-faces} determines how selected sub-formulas are distinguished. -If @code{calc-highlight-selections-with-faces} is nil, then +If @code{calc-highlight-selections-with-faces} is nil, then a selected sub-formula is distinguished either by changing every character not part of the sub-formula with a dot or by changing every -character in the sub-formula with a @samp{#} sign. +character in the sub-formula with a @samp{#} sign. If @code{calc-highlight-selections-with-faces} is t, then a selected sub-formula is distinguished either by displaying the -non-selected portion of the formula with @code{calc-nonselected-face} +non-selected portion of the formula with @code{calc-nonselected-face} or by displaying the selected sub-formula with @code{calc-nonselected-face}. @end defvar @@ -36651,9 +36651,9 @@ input data set. Each entry may be a single value or a vector of values. @c 20 @item -With a prefix argument of 1, take a single +With a prefix argument of 1, take a single @texline @var{n}@math{\times2} -@infoline @mathit{@var{N}x2} +@infoline @mathit{@var{N}x2} matrix from the stack instead of two separate data vectors. @c 21 @@ -36754,7 +36754,7 @@ Variable name may be a single digit or a full name. @c 30 @item -Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or +Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or @key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation of the result of the edit. @@ -36854,7 +36854,7 @@ to evaluate variables. @item The variable is replaced by the formula shown on the right. The Inverse flag reverses the order of the operands, e.g., @kbd{I s - x} -assigns +assigns @texline @math{x \coloneq a-x}. @infoline @expr{x := a-x}. diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 55c2c4c0ae8..d5f403e5cdb 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -912,7 +912,7 @@ construct, should the point start inside it. If @ccmode fails to find function beginnings or ends inside the current declaration scope, it will search the enclosing scopes. If you want @ccmode to recognize functions only at the top level@footnote{this was @ccmode{}'s -behavior prior to version 5.32.}, set @code{c-defun-tatic} to +behavior prior to version 5.32.}, set @code{c-defun-tactic} to @code{t}. These functions are analogous to the Emacs built-in commands diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 79c7ada3b0b..88b068ccd5b 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -332,7 +332,7 @@ Example: @code{method}, @code{signal}, and @code{property} elements. Unlike properties, which can change their values during lifetime of a D-Bus object, annotations are static. Often they are used for code -generators of D-Bus langugae bindings. Example: +generators of D-Bus language bindings. Example: @example <annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/> diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 99530e6356d..a026c63e25b 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -476,7 +476,7 @@ in your @code{dired-mode-hook}. This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs directory local variables mechanism (@pxref{Directory Variables,,,emacs,The Gnu Emacs manual}) replaces it. For an example of -the new mechanims, @pxref{Omitting Variables}. +the new mechanisms, @pxref{Omitting Variables}. When Dired visits a directory, it looks for a file whose name is the value of variable @code{dired-local-variables-file} (default: @file{.dired}). diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 55dc7f9a822..cc566086f44 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -268,7 +268,7 @@ projects. Some project modes do not have a project file, but directly read a Makefile or other existing file. Instead of directly editing the -object, you can edit the file by typine @kbd{C-c . e} +object, you can edit the file by typing @kbd{C-c . e} (@code{ede-edit-file-target}). You should ``rescan'' the project afterwards (@pxref{Miscellaneous commands}). @@ -3526,7 +3526,7 @@ use the same autoconf form. @item :objectextention Type: @code{string} -A string which is the extention used for object files. +A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc. @refill @@ -3634,7 +3634,7 @@ it's rule definition. @item :objectextention Type: @code{string} -A string which is the extention used for object files. +A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc. @refill @@ -3782,7 +3782,7 @@ it's rule definition. @item :objectextention Type: @code{string} -A string which is the extention used for object files. +A string which is the extension used for object files. For example, C code uses .o on unix, and Emacs Lisp uses .elc. @refill diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index 8ee40288fe0..d65c7a15f7b 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -1212,9 +1212,9 @@ This method does nothing by default, but that may change in the future. This would be the best way to make your objects persistent when using in-place editing. -@section Widget extention +@section Widget extension -When widgets are being created, one new widget extention has been added, +When widgets are being created, one new widget extension has been added, called the @code{:slotofchoices}. When this occurs in a widget definition, all elements after it are removed, and the slot is specifies is queried and converted into a series of constants. @@ -1458,7 +1458,7 @@ Useful methods to define for your new class include: @defmethod eieio-speedbar eieio-speedbar-derive-line-path obj depth Return a string representing a directory associated with an instance -of @var{obj}. @var{depth} can be used to indice how many levels of +of @var{obj}. @var{depth} can be used to index how many levels of indentation have been opened by the user where @var{obj} is shown. @end defmethod diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index d2705155887..7c178757927 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -61,7 +61,7 @@ developing GNU and promoting software freedom.'' @node Top, What is Eshell?, (dir), (dir) @top Eshell -Eshell is a shell-like command interpretor +Eshell is a shell-like command interpreter implemented in Emacs Lisp. It invokes no external processes except for those requested by the user. It is intended to be a functional replacement for command shells such as @command{bash}, @command{zsh}, @@ -608,7 +608,7 @@ scrolls back. @item Using C-p and C-n with rebind gets into a locked state -This happened a few times in Emacs 21, but has been unreproducible +This happened a few times in Emacs 21, but has been irreproducible since. @item If an interactive process is currently running, @kbd{M-!} doesn't work diff --git a/doc/misc/faq.texi b/doc/misc/faq.texi index 262c3d734fe..15c9232d4b6 100644 --- a/doc/misc/faq.texi +++ b/doc/misc/faq.texi @@ -627,7 +627,7 @@ translations of the reference card into several languages; look for files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang} is a two-letter code of the language. For example, the German version of the reference card is in the files @file{etc/refcards/de-refcard.tex} -and @file{etc/recards/de-refcard.pdf}. +and @file{etc/refcards/de-refcard.pdf}. @item There are many other commands in Emacs for getting help and diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index ab9c0232d3d..a79c68f0123 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -1,7 +1,7 @@ \input texinfo @setfilename gnus-coding -@settitle Gnus Coding Style and Maintainance Guide +@settitle Gnus Coding Style and Maintenance Guide @syncodeindex fn cp @syncodeindex vr cp @syncodeindex pg cp @@ -45,7 +45,7 @@ license to the document, as described in section 6 of the license. @ifnottex @node Top -@top Gnus Coding Style and Maintainance Guide +@top Gnus Coding Style and Maintenance Guide This manual describes @dots{} @insertcopying @@ -53,7 +53,7 @@ This manual describes @dots{} @menu * Gnus Coding Style:: Gnus Coding Style -* Gnus Maintainance Guide:: Gnus Maintainance Guide +* Gnus Maintenance Guide:: Gnus Maintenance Guide @end menu @c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader} @@ -250,8 +250,8 @@ Emacs 20.7 and up. XEmacs 21.1 and up. @end itemize -@node Gnus Maintainance Guide -@chapter Gnus Maintainance Guide +@node Gnus Maintenance Guide +@chapter Gnus Maintenance Guide @section Stable and development versions diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index b5bb75f7284..ace7bb42c21 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -266,9 +266,9 @@ and how to prevent it? @subsubheading Answer This message means that the last time you used Gnus, it -wasn't properly exited and therefor couldn't write its -informations to disk (e.g. which messages you read), you -are now asked if you want to restore those informations +wasn't properly exited and therefore couldn't write its +information to disk (e.g. which messages you read), you +are now asked if you want to restore that information from the auto-save file. To prevent this message make sure you exit Gnus @@ -563,7 +563,7 @@ However, the first thing to do is to tell Gnus in which way it should store the mail, in Gnus terminology which back end to use. Gnus supports many different back ends, the most commonly used one is nnml. It stores every mail in one file -and is therefor quite fast. However you might prefer a one +and is therefore quite fast. However you might prefer a one file per group approach if your file system has problems with many small files, the nnfolder back end is then probably the choice for you. To use nnml add the following to ~/.gnus.el: @@ -580,7 +580,7 @@ As you might have guessed, if you want nnfolder, it's @end example @noindent -Now we need to tell Gnus, where to get it's mail from. If +Now we need to tell Gnus, where to get its mail from. If it's a POP3 server, then you need something like this: @example @@ -1104,11 +1104,11 @@ I don't like the way the Summary buffer looks, how to tweak it? @subsubheading Answer You've got to play around with the variable -gnus-summary-line-format. It's value is a string of +gnus-summary-line-format. Its value is a string of symbols which stand for things like author, date, subject etc. A list of the available specifiers can be found in the manual node "Summary Buffer Lines" and the often forgotten -node "Formatting Variables" and it's sub-nodes. There +node "Formatting Variables" and its sub-nodes. There you'll find useful things like positioning the cursor and tabulators which allow you a summary in table form, but sadly hard tabulators are broken in 5.8.8. @@ -2190,7 +2190,7 @@ Starting Gnus is really slow, how to speed it up? @subsubheading Answer -The reason for this could be the way Gnus reads it's +The reason for this could be the way Gnus reads its active file, see the node "The Active File" in the Gnus manual for things you might try to speed the process up. An other idea would be to byte compile your ~/.gnus.el (say diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi index 62c1663508b..612ea14e2cf 100644 --- a/doc/misc/gnus-news.texi +++ b/doc/misc/gnus-news.texi @@ -107,7 +107,7 @@ EasyPG is included in Emacs 23 and available separately as well. @itemize @bullet @item -Symbols like @code{gcc-self} now has the same presedence rules in +Symbols like @code{gcc-self} now have the same precedence rules in @code{gnus-parameters} as other ``real'' variables: The last match wins instead of the first match. diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index a3a93c6ef61..5ae86c4e631 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -4491,23 +4491,6 @@ news. @table @kbd -@item H f -@kindex H f (Group) -@findex gnus-group-fetch-faq -@vindex gnus-group-faq-directory -@cindex FAQ -@cindex ange-ftp -Try to fetch the @acronym{FAQ} for the current group -(@code{gnus-group-fetch-faq}). Gnus will try to get the @acronym{FAQ} -from @code{gnus-group-faq-directory}, which is usually a directory on -a remote machine. This variable can also be a list of directories. -In that case, giving a prefix to this command will allow you to choose -between the various sites. @code{ange-ftp} (or @code{efs}) will be -used for fetching the file. - -If fetching from the first site is unsuccessful, Gnus will attempt to go -through @code{gnus-group-faq-directory} and try to open them one by one. - @item H d @itemx C-c C-d @c @icon{gnus-group-describe-group} @@ -8992,8 +8975,8 @@ apostrophe or quotation mark, then try this wash. Translate many non-@acronym{ASCII} characters into their @acronym{ASCII} equivalents (@code{gnus-article-treat-non-ascii}). This is mostly useful if you're on a terminal that has a limited font -and does't show accented characters, ``advanced'' punctuation, and the -like. For instance, @samp{»} is tranlated into @samp{>>}, and so on. +and doesn't show accented characters, ``advanced'' punctuation, and the +like. For instance, @samp{»} is translated into @samp{>>}, and so on. @item W Y f @kindex W Y f (Summary) @@ -13778,7 +13761,7 @@ The same as the above, but don't do automatic @acronym{STARTTLS} upgrades. @findex nntp-open-tls-stream @item nntp-open-tls-stream Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{http://www.gnu.org/software/gnutls/, GNUTLS} +this you must have @uref{http://www.gnu.org/software/gnutls/, GnuTLS} installed. You then define a server as follows: @lisp @@ -21228,7 +21211,7 @@ features (inspired by the Google search input language): AND, OR, and NOT are supported, and parentheses can be used to control operator precedence, e.g. (emacs OR xemacs) AND linux. Note that operators must be written with all capital letters to be -recognised. Also preceding a term with a - sign is equivalent to NOT +recognized. Also preceding a term with a - sign is equivalent to NOT term. @item Automatic AND queries @@ -21273,7 +21256,7 @@ Gmane queries follow a simple query language: AND, OR, NOT (or AND NOT), and XOR are supported, and brackets can be used to control operator precedence, e.g. (emacs OR xemacs) AND linux. Note that operators must be written with all capital letters to be -recognised. +recognized. @item Required and excluded terms + and - can be used to require or exclude terms, e.g. football -american @@ -21296,7 +21279,7 @@ name (or part of a name) to match. @node The swish++ Engine @subsubsection The swish++ Engine -FIXEM: Say something more here. +FIXME: Say something more here. Documentation for swish++ may be found at the swish++ sourceforge page: @uref{http://swishplusplus.sourceforge.net} @@ -21319,7 +21302,7 @@ to get a group name. By default this is @code{$HOME/Mail}. @node The swish-e Engine @subsubsection The swish-e Engine -FIXEM: Say something more here. +FIXME: Say something more here. Documentation for swish-e may be found at the swish-e homepage @uref{http://swish-e.org} @@ -21912,7 +21895,7 @@ Clearly, the easiest way would be if marks could somehow be automatically set for the original article. This is exactly what @emph{marks propagation} is about. -Marks propagation is deactivated by default. You can activate it for a +Marks propagation is inactive by default. You can activate it for a certain @code{nnmairix} group with @code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b p}). This function will warn you if you try to use it with your default @@ -22064,7 +22047,7 @@ an example server definition: (nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil)) @end lisp -(The @code{nnmaildir} back end also has a server variabe +(The @code{nnmaildir} back end also has a server variable @code{get-new-mail}, but its default value is @code{nil}, so you don't have to explicitly set it if you use a @code{nnmaildir} server just for mairix.) @@ -25471,7 +25454,7 @@ Write @code{spam-check-blackbox} if Blackbox can check incoming mail. Write @code{spam-blackbox-register-routine} and @code{spam-blackbox-unregister-routine} using the bogofilter -register/unregister routines as a start, or other restister/unregister +register/unregister routines as a start, or other register/unregister routines more appropriate to Blackbox, if Blackbox can register/unregister spam and ham. @@ -27425,7 +27408,7 @@ considered home score and adapt files (@pxref{Home Score File}) have been added. @item -@code{nndoc} was rewritten to be easily extendable (@pxref{Document +@code{nndoc} was rewritten to be easily extensible (@pxref{Document Server Internals}). @item @@ -27818,7 +27801,7 @@ The revised Gnus @acronym{FAQ} is included in the manual, @acronym{TLS} wrapper shipped with Gnus @acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and -@acronym{NNTP} via @file{tls.el} and GNUTLS. +@acronym{NNTP} via @file{tls.el} and GnuTLS. @item Improved anti-spam features. @@ -30030,7 +30013,7 @@ this: @subsection Score File Syntax Score files are meant to be easily parseable, but yet extremely -mallable. It was decided that something that had the same read syntax +malleable. It was decided that something that had the same read syntax as an Emacs Lisp list would fit that spec. Here's a typical score file: diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 8e172301915..5149eb91651 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -62,7 +62,7 @@ developing GNU and promoting software freedom.'' IDLWAVE is a package which supports editing source code written in the Interactive Data Language (IDL), and running IDL as an inferior shell. -@insertcopying +@insertcopying @end ifnottex @menu @@ -72,8 +72,8 @@ Interactive Data Language (IDL), and running IDL as an inferior shell. * The IDLWAVE Major Mode:: The mode for editing IDL programs * The IDLWAVE Shell:: The mode for running IDL as an inferior program * Acknowledgements:: Who did what -* Sources of Routine Info:: How does IDLWAVE know about routine XYZ -* HTML Help Browser Tips:: +* Sources of Routine Info:: How does IDLWAVE know about routine XYZ +* HTML Help Browser Tips:: * Configuration Examples:: The user is king * Windows and MacOS:: What still works, and how * Troubleshooting:: When good computers turn bad @@ -85,9 +85,9 @@ Interactive Data Language (IDL), and running IDL as an inferior shell. Getting Started (Tutorial) -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: +* Lesson I -- Development Cycle:: +* Lesson II -- Customization:: +* Lesson III -- User Catalog:: The IDLWAVE Major Mode @@ -107,7 +107,7 @@ The IDLWAVE Major Mode Code Formatting * Code Indentation:: Reflecting the logical structure -* Continued Statement Indentation:: +* Continued Statement Indentation:: * Comment Indentation:: Special indentation for comment lines * Continuation Lines:: Splitting statements over lines * Syntax Highlighting:: Font-lock support @@ -115,14 +115,14 @@ Code Formatting Online Help -* Help with HTML Documentation:: -* Help with Source:: +* Help with HTML Documentation:: +* Help with Source:: Completion * Case of Completed Words:: CaseOFcomPletedWords * Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: +* Object Method Completion in the Shell:: * Class and Keyword Inheritance:: obj->Method, _EXTRA=e * Structure Tag Completion:: Completing state.Tag @@ -136,32 +136,32 @@ The IDLWAVE Shell * Starting the Shell:: How to launch IDL as a subprocess * Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: +* Commands Sent to the Shell:: +* Debugging IDL Programs:: +* Examining Variables:: +* Custom Expression Examination:: Debugging IDL Programs -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: +* A Tale of Two Modes:: +* Debug Key Bindings:: +* Breakpoints and Stepping:: +* Compiling Programs:: +* Walking the Calling Stack:: +* Electric Debug Mode:: Sources of Routine Info * Routine Definitions:: Where IDL Routines are defined. * Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: +* Catalogs:: * Load-Path Shadows:: Routines defined in several places * Documentation Scan:: Scanning the IDL Manuals Catalogs -* Library Catalogs:: -* User Catalog:: +* Library Catalogs:: +* User Catalog:: @end detailmenu @end menu @@ -193,13 +193,13 @@ form a complete development environment. Here is a brief summary of what IDLWAVE does: @itemize @bullet -@item +@item Smart code indentation and automatic-formatting. @item Three level syntax highlighting support. -@item +@item Context-sensitive display of calling sequences and keywords for more -than 1000 native IDL routines, extendible to any additional number of +than 1000 native IDL routines, extensible to any additional number of local routines, and already available with many pre-scanned libraries. @item Fast, context-sensitive online HTML help, or source-header help for @@ -373,9 +373,9 @@ at point. @cindex Getting Started @menu -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: +* Lesson I -- Development Cycle:: +* Lesson II -- Customization:: +* Lesson III -- User Catalog:: @end menu @node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started @@ -418,13 +418,13 @@ function daynr,d,m,y y1 = y * delta return, d + floor(m1*30.6)+floor(y1*365.25)+5 end - + function weekday,day,month,year ;; compute weekday number for date nr = daynr(day,month,year) return, nr mod 7 end - + pro plot_wday,day,month ;; Plot the weekday of a date in the first 10 years of this century. years = 2000,+indgen(10) @@ -753,7 +753,7 @@ them. @menu * Code Indentation:: Reflecting the logical structure -* Continued Statement Indentation:: +* Continued Statement Indentation:: * Comment Indentation:: Special indentation for comment lines * Continuation Lines:: Splitting statements over lines * Syntax Highlighting:: Font-lock support @@ -797,7 +797,7 @@ subprogram). The command @kbd{C-M-q} reindents the entire current routine. @xref{Actions}, for information how to impose additional formatting conventions on foreign code. -@defopt idlwave-main-block-indent (@code{2}) +@defopt idlwave-main-block-indent (@code{2}) Extra indentation for the main block of code. That is the block between the FUNCTION/PRO statement and the END statement for that program unit. @@ -998,7 +998,7 @@ in the first line of a comment paragraph. @defopt idlwave-use-last-hang-indent (@code{nil}) Non-@code{nil} means use last match on line for -@code{idlwave-indent-regexp}. +@code{idlwave-indent-regexp}. @end defopt @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting @@ -1026,7 +1026,7 @@ for highlighting using the variable @defopt idlwave-default-font-lock-items Items which should be fontified on the default fontification level -2. +2. @end defopt @node Octals and Highlighting, , Syntax Highlighting, Code Formatting @@ -1104,7 +1104,7 @@ plot,x,alog(x+5*sin(x) + 2), On positions 1,2 and 8, information about the @samp{plot} procedure will be shown. On positions 3,4, and 7, the @samp{alog} function will be described, while positions 5 and 6 will investigate the @samp{sin} -function. +function. When you ask for routine information about an object method, and the method exists in several classes, IDLWAVE queries for the class of the @@ -1162,7 +1162,7 @@ will automatically split into the next two. @item @i{Other} @tab Any other routine with a file not known to be on the search path. @item @i{Unresolved} -@tab An otherwise unknown routine the shell lists as unresolved +@tab An otherwise unknown routine the shell lists as unresolved (referenced, but not compiled). @end multitable @@ -1198,7 +1198,7 @@ with the middle mouse button inserts keywords or visits files: @item @i{Usage} @tab If online help is installed, a click with the @emph{right} mouse button on the @i{Usage:} line will access the help for the -routine (@pxref{Online Help}). +routine (@pxref{Online Help}). @item @i{Keyword} @tab Online help about keywords is also available with the @emph{right} mouse button. Clicking on a keyword with the @emph{middle} @@ -1340,8 +1340,8 @@ directly in the originating source file. @menu -* Help with HTML Documentation:: -* Help with Source:: +* Help with HTML Documentation:: +* Help with Source:: @end menu @node Help with HTML Documentation, Help with Source, Online Help, Online Help @@ -1393,7 +1393,7 @@ configuring a browser for use with IDL's HTML help system. Relative directory of the system-supplied HTML help directory, considered with respect to @code{idlwave-system-directory}. Relevant for IDL 6.2 and greater. Should not change. -@end defopt +@end defopt @defopt idlwave-html-help-location @file{/usr/local/etc/} The directory where the @file{idl_html_help} HTML directory live. @@ -1580,8 +1580,8 @@ available will be emphasized (e.g. colored blue). For other items, the corresponding source code or DocLib header will be used as the help text. -@cindex Completion, cancelling -@cindex Cancelling completion +@cindex Completion, canceling +@cindex Canceling completion Completion is not a blocking operation --- you are free to continue editing, enter commands, or simply ignore the @file{*Completions*} buffer during a completion operation. If, however, the most recent @@ -1613,7 +1613,7 @@ available. @menu * Case of Completed Words:: CaseOFcomPletedWords * Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: +* Object Method Completion in the Shell:: * Class and Keyword Inheritance:: obj->Method, _EXTRA=e * Structure Tag Completion:: Completing state.Tag @end menu @@ -1681,7 +1681,7 @@ narrow down the number of possible completions. The variable @code{idlwave-query-class} can be configured to make such prompting the default for all methods (not recommended), or selectively for very common methods for which the number of completing keywords would be too -large (e.g. @code{Init,SetProperty,GetProperty}). +large (e.g. @code{Init,SetProperty,GetProperty}). @cindex Saving object class on @code{->} @cindex @code{->} @@ -1729,7 +1729,7 @@ routine info, or online help within a method routine, a query is sent to determine the class of the object. If this query is successful, the class found will be used to select appropriate completions, routine info, or help. If unsuccessful, information from all known classes will -be used (as in the buffer). +be used (as in the buffer). @node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion @subsection Class and Keyword Inheritance @@ -1772,7 +1772,7 @@ keywords based on their originating class. Non-@code{nil} means consider inheritance during completion, online help etc. @end defopt -@defopt idlwave-keyword-class-inheritance +@defopt idlwave-keyword-class-inheritance A list of regular expressions to match methods for which simple class-driven keyword inheritance will be used for Completion. @end defopt @@ -1802,7 +1802,7 @@ Structure tag completion is not enabled by default. To enable it, simply add the following to your @file{.emacs}: @lisp - (add-hook 'idlwave-load-hook + (add-hook 'idlwave-load-hook (lambda () (require 'idlw-complete-structtag))) @end lisp @@ -2226,7 +2226,7 @@ your @file{.emacs} file: (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" '(capitalize-word 1) t) ;; Capitalize common block name - (idlwave-action-and-binding "\\<common\\>[ \t]+\\<" + (idlwave-action-and-binding "\\<common\\>[ \t]+\\<" '(capitalize-word 1) t))) @end lisp @@ -2384,10 +2384,10 @@ currently only works under Unix and MacOSX. @menu * Starting the Shell:: How to launch IDL as a subprocess * Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: +* Commands Sent to the Shell:: +* Debugging IDL Programs:: +* Examining Variables:: +* Custom Expression Examination:: @end menu @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell @@ -2414,7 +2414,7 @@ In order to create a separate frame for the IDLWAVE shell buffer, call @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell window, configure the variable -@code{idlwave-shell-use-dedicated-frame}. +@code{idlwave-shell-use-dedicated-frame}. To launch a quick IDLWAVE shell directly from a shell prompt without an IDLWAVE buffer (e.g., as a replacement for running inside an @@ -2471,7 +2471,7 @@ The file in which the command history of the idlwave shell is saved. Unless it's an absolute path, it goes in @code{idlwave-config-directory}. @end defopt - + @defopt idlwave-shell-use-dedicated-frame (@code{nil}) Non-@code{nil} means IDLWAVE should use a special frame to display the shell buffer. @@ -2574,7 +2574,7 @@ keywords, system variables, system variable tags etc. @item @kbd{C-c C-v} @tab Find the source file of a routine (@code{idlwave-find-module}) @item @kbd{C-c C-t} -@tab Find the source file of a routine in the currently visited file +@tab Find the source file of a routine in the currently visited file (@code{idlwave-find-module-this-file}). @item @kbd{C-c =} @tab Compile a library routine (@code{idlwave-resolve}) @@ -2697,12 +2697,12 @@ buffers. @end defopt @menu -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: +* A Tale of Two Modes:: +* Debug Key Bindings:: +* Breakpoints and Stepping:: +* Compiling Programs:: +* Walking the Calling Stack:: +* Electric Debug Mode:: @end menu @@ -2795,7 +2795,7 @@ executed from the shell window, the breakpoint where IDL is currently stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled and re-enabled: @kbd{C-c C-d C-\} -(@code{idlwave-shell-toggle-enable-current-bp}). +(@code{idlwave-shell-toggle-enable-current-bp}). Breakpoint lines are highlighted or indicated with an icon in the source code (different icons for conditional, after, and other break types). @@ -2804,7 +2804,7 @@ places breakpoints as close as possible on or after the line you specify. IDLWAVE queries the shell for the actual breakpoint location which was set, so the exact line you specify may not be marked. You can re-sync the breakpoint list and update the display at any time (e.g., if -you add or remove some on the command line) using @kbd{C-c C-d C-l}. +you add or remove some on the command line) using @kbd{C-c C-d C-l}. In recent IDLWAVE versions, the breakpoint line is highlighted when the mouse is moved over it, and a tooltip pops up describing the break @@ -2914,8 +2914,8 @@ configured in @code{idlwave-shell-mark-stop-line}. @kindex C-c C-d C-c In order to compile the current buffer under the IDLWAVE shell, press @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the -current buffer and then sends the command @samp{.run path/to/file} to the -shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in +current buffer and then sends the command @samp{.run path/to/file} to the +shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in which case the most recently compiled buffer will be saved and re-compiled. @@ -3080,9 +3080,9 @@ halts. @defopt idlwave-shell-electric-stop-color (Violet) Default color of the stopped line overlay when in electric debug mode. -@end defopt +@end defopt -@defopt idlwave-shell-electric-stop-line-face +@defopt idlwave-shell-electric-stop-line-face The face to use for the stopped line. Defaults to a face similar to the modeline, with color @code{idlwave-shell-electric-stop-color}. @end defopt @@ -3188,14 +3188,14 @@ the expression printed by IDL. @end defopt @defopt idlwave-shell-output-face -The face for @code{idlwave-shell-output-overlay}. +The face for @code{idlwave-shell-output-overlay}. Allows to choose the font, color and other properties for the most recent output of IDL when examining an expression." @end defopt @defopt idlwave-shell-separate-examine-output (@code{t}) If non-@code{nil}, re-direct the output of examine commands to a special -@file{*Examine*} buffer, instead of in the shell itself. +@file{*Examine*} buffer, instead of in the shell itself. @end defopt @defopt idlwave-shell-max-print-length (200) @@ -3249,17 +3249,17 @@ Both functions take a single string argument sharing the syntax of the @lisp (add-hook 'idlwave-shell-mode-hook (lambda () - (idlwave-shell-define-key-both [s-down-mouse-2] - (idlwave-shell-mouse-examine + (idlwave-shell-define-key-both [s-down-mouse-2] + (idlwave-shell-mouse-examine "print, size(___,/DIMENSIONS)")) (idlwave-shell-define-key-both [f9] (idlwave-shell-examine "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f10] (idlwave-shell-examine + (idlwave-shell-define-key-both [f10] (idlwave-shell-examine "print,size(___,/TNAME)")) (idlwave-shell-define-key-both [f11] (idlwave-shell-examine "help,___,/STRUCTURE")))) -@end lisp - +@end lisp + @noindent Now pressing @key{f9}, or middle-mouse dragging with the @key{SUPER} key depressed, will print the dimensions of the nearby or highlighted expression. Pressing @key{f10} will give the type string, @@ -3297,7 +3297,7 @@ of the package from version 3.0, during which time he overhauled almost everything, modernized IDLWAVE with many new features, and developed the manual. -@item +@item @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current maintainer, as of version 4.10, helped shape object method completion and most new features introduced in versions 4.x, and introduced many @@ -3364,7 +3364,7 @@ know about the accessible routines. @menu * Routine Definitions:: Where IDL Routines are defined. * Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: +* Catalogs:: * Load-Path Shadows:: Routines defined in several places * Documentation Scan:: Scanning the IDL Manuals @end menu @@ -3382,7 +3382,7 @@ know about the accessible routines. several places: @enumerate -@item +@item @emph{Builtin routines} are defined inside IDL itself. The source code of such routines is not available, but instead are learned about through the IDL documentation. @@ -3390,7 +3390,7 @@ the IDL documentation. Routines which are @emph{part of the current program}, are defined in a file explicitly compiled by the user. This file may or may not be located on the IDL search path. -@item +@item @emph{Library routines} are defined in files located on IDL's search path. When a library routine is called for the first time, IDL will find the source file and compile it dynamically. A special sub-category @@ -3428,7 +3428,7 @@ directly with IDL in the form of an XML catalog which IDLWAVE scans. Formerly, this list was created by scanning the IDL manuals to produce the file @file{idlw-rinfo.el}. -@item +@item IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session for routine definitions. This is done automatically when routine information or completion is first requested by the user. Each new @@ -3547,8 +3547,8 @@ later). @end defopt @menu -* Library Catalogs:: -* User Catalog:: +* Library Catalogs:: +* User Catalog:: @end menu @html @@ -3636,7 +3636,7 @@ instead, including: @itemize @bullet @item The scan is internal to Emacs, so you don't need a working Perl installation, as you do for library catalogs. -@item Can be used to scan directories for which the user has no write +@item Can be used to scan directories for which the user has no write privileges. @item Easy widget-based path selection. @end itemize @@ -3752,7 +3752,7 @@ Another way to find out if a specific routine has multiple definitions on the load path is routine info display (@pxref{Routine Info}). @node Documentation Scan, , Load-Path Shadows, Sources of Routine Info -@appendixsec Documentation Scan +@appendixsec Documentation Scan @cindex @file{get_html_rinfo} @cindex @file{idlw-rinfo.el} @cindex Scanning the documentation @@ -3920,7 +3920,7 @@ user is King! (setq idlwave-main-block-indent 3) (setq idlwave-end-offset -3) (setq idlwave-continuation-indent 1) -(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" +(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" ; anchored at start of line. (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' @@ -3987,10 +3987,10 @@ user is King! ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. ;; Some personal abbreviations - (define-abbrev idlwave-mode-abbrev-table + (define-abbrev idlwave-mode-abbrev-table (concat idlwave-abbrev-start-char "wb") "widget_base()" (idlwave-keyword-abbrev 1)) - (define-abbrev idlwave-mode-abbrev-table + (define-abbrev idlwave-mode-abbrev-table (concat idlwave-abbrev-start-char "on") "obj_new()" (idlwave-keyword-abbrev 1)) )) @@ -4008,12 +4008,12 @@ user is King! (add-hook 'idlwave-shell-mode-hook (lambda () ;; Set up some custom key and mouse examine commands - (idlwave-shell-define-key-both [s-down-mouse-2] - (idlwave-shell-mouse-examine + (idlwave-shell-define-key-both [s-down-mouse-2] + (idlwave-shell-mouse-examine "print, size(___,/DIMENSIONS)")) (idlwave-shell-define-key-both [f9] (idlwave-shell-examine "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f10] (idlwave-shell-examine + (idlwave-shell-define-key-both [f10] (idlwave-shell-examine "print,size(___,/TNAME)")) (idlwave-shell-define-key-both [f11] (idlwave-shell-examine "help,___,/STRUCTURE")))) @@ -4066,7 +4066,7 @@ system. I am assuming that IDLWAVE has been installed in sure you check the following things: @itemize @bullet -@item When you download the IDLWAVE distribution, make sure you save the +@item When you download the IDLWAVE distribution, make sure you save the file under the names @file{idlwave.tar.gz}. @item M-TAB switches among running programs --- use Esc-TAB instead. @@ -4102,7 +4102,7 @@ customize the variable @code{idlwave-shell-automatic-electric-debug} if you prefer not to enter electric debug on breakpoints@dots{} but you really should try it before you disable it! You can also customize this variable to enter debug mode when errors are -encountered. +encountered. @item @strong{I get errors like @samp{Searching for program: no such file or directory, idl} when attempting to start the IDL shell.} @@ -4141,7 +4141,7 @@ in compiled lisp files. Presumably, you kept the original .elc files in place, and this is the source of the error. If you recompile (or just "make; make install") from source, it should resolve this problem. Another option is to recompile the @file{idlw*.el} files by hand using -@kbd{M-x byte-compile-file}. +@kbd{M-x byte-compile-file}. @item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches windows on my desktop.} @@ -4266,7 +4266,7 @@ You have a mismatch between your help index and the HTML help package you downloaded. You need to ensure you download a ``downgrade kit'' if you are using anything older than the latest HTML help package. A new help package appears with each IDL release (assuming the documentation -is updated). +is updated). Starting with IDL 6.2, the HTML help and its catalog are distributed with IDL, and so should never be inconsistent. diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in index 1e497fe309f..0edaf3db3d6 100644 --- a/doc/misc/makefile.w32-in +++ b/doc/misc/makefile.w32-in @@ -100,123 +100,127 @@ info.dvi: $(INFOSOURCES) $(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi -$(infodir)/ccmode: cc-mode.texi +$(infodir)/ccmode: cc-mode.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) cc-mode.texi -cc-mode.dvi: cc-mode.texi +cc-mode.dvi: cc-mode.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/cc-mode.texi -$(infodir)/ada-mode: ada-mode.texi +$(infodir)/ada-mode: ada-mode.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) ada-mode.texi -ada-mode.dvi: ada-mode.texi +ada-mode.dvi: ada-mode.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ada-mode.texi -$(infodir)/pcl-cvs: pcl-cvs.texi +$(infodir)/pcl-cvs: pcl-cvs.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) pcl-cvs.texi -pcl-cvs.dvi: pcl-cvs.texi +pcl-cvs.dvi: pcl-cvs.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/pcl-cvs.texi -$(infodir)/eshell: eshell.texi +$(infodir)/eshell: eshell.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) eshell.texi -eshell.dvi: eshell.texi +eshell.dvi: eshell.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/eshell.texi -$(infodir)/cl: cl.texi +$(infodir)/cl: cl.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) cl.texi -cl.dvi: cl.texi +cl.dvi: cl.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/cl.texi -$(infodir)/dbus: dbus.texi +$(infodir)/dbus: dbus.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) dbus.texi -dbus.dvi: dbus.texi +dbus.dvi: dbus.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/dbus.texi -$(infodir)/dired-x: dired-x.texi +$(infodir)/dired-x: dired-x.texi $(emacsdir)/emacsver.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) dired-x.texi -dired-x.dvi: dired-x.texi +dired-x.dvi: dired-x.texi $(emacsdir)/emacsver.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/dired-x.texi -$(infodir)/ediff: ediff.texi +$(infodir)/ediff: ediff.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) ediff.texi -ediff.dvi: ediff.texi +ediff.dvi: ediff.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ediff.texi -$(infodir)/flymake: flymake.texi +$(infodir)/flymake: flymake.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) flymake.texi -flymake.dvi: flymake.texi +flymake.dvi: flymake.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/flymake.texi -$(infodir)/forms: forms.texi +$(infodir)/forms: forms.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) forms.texi -forms.dvi: forms.texi +forms.dvi: forms.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/forms.texi # gnus/message/emacs-mime/sieve/pgg are part of Gnus: -$(infodir)/gnus: gnus.texi +$(infodir)/gnus: gnus.texi gnus-overrides.texi message.texi emacs-mime.texi \ + sieve.texi pgg.texi sasl.texi gnus-news.texi gnus-faq.texi \ + doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) gnus.texi -gnus.dvi: gnus.texi +gnus.dvi: gnus.texi gnus-overrides.texi message.texi emacs-mime.texi \ + sieve.texi pgg.texi sasl.texi gnus-news.texi gnus-faq.texi \ + doclicense.texi sed -e "/@iflatex/,/@end iflatex/d" $(srcdir)/gnus.texi > gnustmp.texi $(ENVADD) $(TEXI2DVI) gnustmp.texi cp gnustmp.dvi $*.dvi rm gnustmp.* # -$(infodir)/message: message.texi +$(infodir)/message: message.texi gnus-overrides.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) message.texi -message.dvi: message.texi +message.dvi: message.texi gnus-overrides.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/message.texi # -$(infodir)/emacs-mime: emacs-mime.texi +$(infodir)/emacs-mime: emacs-mime.texi gnus-overrides.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) --enable-encoding emacs-mime.texi -emacs-mime.dvi: emacs-mime.texi +emacs-mime.dvi: emacs-mime.texi gnus-overrides.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-mime.texi # -$(infodir)/sieve: sieve.texi +$(infodir)/sieve: sieve.texi gnus-overrides.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) sieve.texi -sieve.dvi: sieve.texi +sieve.dvi: sieve.texi gnus-overrides.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/sieve.texi # -$(infodir)/pgg: pgg.texi +$(infodir)/pgg: pgg.texi gnus-overrides.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) pgg.texi -pgg.dvi: pgg.texi +pgg.dvi: pgg.texi gnus-overrides.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/pgg.texi -$(infodir)/mh-e: mh-e.texi +$(infodir)/mh-e: mh-e.texi doclicense.texi gpl.texi $(MAKEINFO) $(MAKEINFO_OPTS) mh-e.texi -mh-e.dvi: mh-e.texi +mh-e.dvi: mh-e.texi doclicense.texi gpl.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/mh-e.texi -$(infodir)/reftex: reftex.texi +$(infodir)/reftex: reftex.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) reftex.texi -reftex.dvi: reftex.texi +reftex.dvi: reftex.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/reftex.texi -$(infodir)/remember: remember.texi +$(infodir)/remember: remember.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) remember.texi -remember.dvi: remember.texi +remember.dvi: remember.texi doclicense.texix $(ENVADD) $(TEXI2DVI) $(srcdir)/remember.texi -$(infodir)/sasl: sasl.texi +$(infodir)/sasl: sasl.texi gnus-overrides.texi $(MAKEINFO) $(MAKEINFO_OPTS) sasl.texi -sasl.dvi: sasl.texi +sasl.dvi: sasl.texi gnus-overrides.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/sasl.texi -$(infodir)/sc: sc.texi +$(infodir)/sc: sc.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) sc.texi -sc.dvi: sc.texi +sc.dvi: sc.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/sc.texi -$(infodir)/vip: vip.texi +$(infodir)/vip: vip.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) vip.texi -vip.dvi: vip.texi +vip.dvi: vip.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/vip.texi -$(infodir)/viper: viper.texi +$(infodir)/viper: viper.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) viper.texi -viper.dvi: viper.texi +viper.dvi: viper.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/viper.texi -$(infodir)/widget: widget.texi +$(infodir)/widget: widget.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) widget.texi -widget.dvi: widget.texi +widget.dvi: widget.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/widget.texi $(infodir)/efaq: faq.texi $(emacsdir)/emacsver.texi @@ -224,57 +228,56 @@ $(infodir)/efaq: faq.texi $(emacsdir)/emacsver.texi faq.dvi: faq.texi $(emacsdir)/emacsver.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/faq.texi -$(infodir)/autotype: autotype.texi +$(infodir)/autotype: autotype.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) autotype.texi -autotype.dvi: autotype.texi +autotype.dvi: autotype.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/autotype.texi -$(infodir)/calc: calc.texi $(emacsdir)/emacsver.texi +$(infodir)/calc: calc.texi $(emacsdir)/emacsver.texi gpl.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) calc.texi - -calc.dvi: calc.texi $(emacsdir)/emacsver.texi +calc.dvi: calc.texi $(emacsdir)/emacsver.texi gpl.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/calc.texi # This is produced with --no-split to avoid making files whose # names clash on DOS 8+3 filesystems -$(infodir)/idlwave: idlwave.texi +$(infodir)/idlwave: idlwave.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) --no-split idlwave.texi -idlwave.dvi: idlwave.texi +idlwave.dvi: idlwave.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/idlwave.texi -$(infodir)/eudc: eudc.texi +$(infodir)/eudc: eudc.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) eudc.texi -eudc.dvi: eudc.texi +eudc.dvi: eudc.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/eudc.texi -$(infodir)/ebrowse: ebrowse.texi +$(infodir)/ebrowse: ebrowse.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) ebrowse.texi -ebrowse.dvi: ebrowse.texi +ebrowse.dvi: ebrowse.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ebrowse.texi -$(infodir)/woman: woman.texi +$(infodir)/woman: woman.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) woman.texi -woman.dvi: woman.texi +woman.dvi: woman.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/woman.texi -$(infodir)/speedbar: speedbar.texi +$(infodir)/speedbar: speedbar.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) speedbar.texi -speedbar.dvi: speedbar.texi +speedbar.dvi: speedbar.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/speedbar.texi -$(infodir)/tramp: tramp.texi +$(infodir)/tramp: tramp.texi trampver.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) tramp.texi -tramp.dvi: tramp.texi +tramp.dvi: tramp.texi trampver.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/tramp.texi -$(infodir)/ses: ses.texi +$(infodir)/ses: ses.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) ses.texi -ses.dvi: ses.texi +ses.dvi: ses.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ses.texi -$(infodir)/smtpmail: smtpmail.texi +$(infodir)/smtpmail: smtpmail.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) smtpmail.texi -smtpmail.dvi: smtpmail.texi +smtpmail.dvi: smtpmail.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/smtpmail.texi $(infodir)/org: org.texi @@ -282,14 +285,14 @@ $(infodir)/org: org.texi org.dvi: org.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/org.texi -$(infodir)/url: url.texi +$(infodir)/url: url.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) url.texi -url.dvi: url.texi +url.dvi: url.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/url.texi -$(infodir)/newsticker: newsticker.texi +$(infodir)/newsticker: newsticker.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) newsticker.texi -newsticker.dvi: newsticker.texi +newsticker.dvi: newsticker.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi $(infodir)/nxml-mode: nxml-mode.texi @@ -297,14 +300,14 @@ $(infodir)/nxml-mode: nxml-mode.texi nxml-mod.dvi: nxml-mode.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/nxml-mode.texi -$(infodir)/rcirc: rcirc.texi +$(infodir)/rcirc: rcirc.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) rcirc.texi -rcirc.dvi: rcirc.texi +rcirc.dvi: rcirc.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/rcirc.texi -$(infodir)/erc: erc.texi +$(infodir)/erc: erc.texi gpl.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) erc.texi -erc.dvi: erc.texi +erc.dvi: erc.texi gpl.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/erc.texi $(infodir)/ert: ert.texi @@ -322,9 +325,9 @@ $(infodir)/mairix-el: mairix-el.texi mairix-el.dvi: mairix-el.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/mairix-el.texi -$(infodir)/auth: auth.texi +$(infodir)/auth: auth.texi gnus-overrides.texi $(MAKEINFO) $(MAKEINFO_OPTS) auth.texi -auth.dvi: auth.texi +auth.dvi: auth.texi gnus-overrides.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/auth.texi $(infodir)/eieio: eieio.texi @@ -337,14 +340,14 @@ $(infodir)/ede: ede.texi ede.dvi: ede.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/ede.texi -$(infodir)/semantic: semantic.texi +$(infodir)/semantic: semantic.texi sem-user.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) semantic.texi -semantic.dvi: semantic.texi +semantic.dvi: semantic.texi sem-user.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/semantic.texi -$(infodir)/edt: edt.texi +$(infodir)/edt: edt.texi doclicense.texi $(MAKEINFO) $(MAKEINFO_OPTS) edt.texi -edt.dvi: edt.texi +edt.dvi: edt.texi doclicense.texi $(ENVADD) $(TEXI2DVI) $(srcdir)/edt.texi mostlyclean: diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 48d0028e452..774bf180266 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -904,7 +904,7 @@ happen---Message will encode non-@acronym{ASCII} domain names in @code{From}, Until @acronym{IDNA} becomes more well known, Message queries you whether @acronym{IDNA} encoding of the domain name really should occur. Some users might not be aware that domain names can contain -non-@acronym{ASCII} now, so this gives them a safety net if they accidently +non-@acronym{ASCII} now, so this gives them a safety net if they accidentally typed a non-@acronym{ASCII} domain name. @vindex message-use-idna @@ -1974,7 +1974,7 @@ that look like: Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes: @end example -@c FIXME: Add `message-insert-formated-citation-line' and +@c FIXME: Add `message-insert-formatted-citation-line' and @c `message-citation-line-format' Point will be at the beginning of the body of the message when this @@ -2120,7 +2120,7 @@ follows this line--} by default. @item message-directory @vindex message-directory -Directory used by many mailey things. The default is @file{~/Mail/}. +Directory used by many mailish things. The default is @file{~/Mail/}. All other mail file variables are derived from @code{message-directory}. @item message-auto-save-directory diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 34a4ba4f8f3..a6fae5e216f 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -7219,7 +7219,7 @@ will be made in the agenda: #+CATEGORY: Holiday %%(org-calendar-holiday) ; special function for holiday names #+CATEGORY: Ann -%%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is allways according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old +%%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is always according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old @end example @@ -7797,8 +7797,8 @@ Interactively select another agenda view and append it to the current view. @item o Delete other windows. @c -@orgcmdkskc{v d,d,org-aganda-day-view} -@xorgcmdkskc{v w,w,org-aganda-day-view} +@orgcmdkskc{v d,d,org-agenda-day-view} +@xorgcmdkskc{v w,w,org-agenda-day-view} @xorgcmd{v m,org-agenda-month-view} @xorgcmd{v y,org-agenda-month-year} @xorgcmd{v SPC,org-agenda-reset-view} @@ -11399,16 +11399,16 @@ a file is retrieved with @code{org-publish-find-date}. @tab Should sorting be case-sensitive? Default @code{nil}. @item @code{:sitemap-file-entry-format} -@tab With this option one can tell how a sitemap's entry is formated in the +@tab With this option one can tell how a sitemap's entry is formatted in the sitemap. This is a format string with some escape sequences: @code{%t} stands for the title of the file, @code{%a} stands for the author of the file and @code{%d} stands for the date of the file. The date is retrieved with the -@code{org-publish-find-date} function and formated with +@code{org-publish-find-date} function and formatted with @code{org-publish-sitemap-date-format}. Default @code{%t}. @item @code{:sitemap-date-format} @tab Format string for the @code{format-time-string} function that tells how -a sitemap entry's date is to be formated. This property bypasses +a sitemap entry's date is to be formatted. This property bypasses @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}. @item @code{:sitemap-sans-extension} diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index f12942da2d3..d4f82b6b3a7 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -70,7 +70,7 @@ customize-group RET pcl-cvs @key{RET}} and to look at the documentation strings of the various commands and major modes for further information. @c This manual is updated to release 2.5 of PCL-CVS. -@insertcopying +@insertcopying @end ifnottex @@ -1275,7 +1275,7 @@ will be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can be useful if your site has several repositories. @item log-edit-require-final-newline -@c wordy to avoid unhderfull hbox +@c wordy to avoid underfull hbox When you enter a log message by typing into the @samp{*cvs-commit-message*} buffer, PCL-CVS normally automatically inserts a trailing newline, unless there already is one. This behavior diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index 7a363523aa6..e1631bcacc8 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -547,7 +547,7 @@ reparsed regardless of their size. @end deffn @deffn Option semantic-idle-scheduler-no-working-message -If non-@code{nil}, disable display of working messages whie reparsing. +If non-@code{nil}, disable display of working messages while reparsing. @end deffn @deffn Option semantic-idle-scheduler-working-in-modeline-flag @@ -880,7 +880,7 @@ command, like this: @end example @end defun -These commands are often more accurate than than the @code{find-tag} +These commands are often more accurate than the @code{find-tag} command (@pxref{Tags,,,emacs,Emacs manual}), because the Semantic Analyzer is context-sensitive. diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi index ad6159feb1a..dcfff1fcb96 100644 --- a/doc/misc/semantic.texi +++ b/doc/misc/semantic.texi @@ -421,7 +421,7 @@ local variables, and tag lists in scope for various reasons, such as C++ using statements. @item semanticdb-typecache.el -The typecache is part of @code{semanticdb}, but is used primarilly by +The typecache is part of @code{semanticdb}, but is used primarily by the analyzer to look up datatypes and complex names. The typecache is bound across source files and builds a master lookup table for data type names. @@ -613,7 +613,7 @@ Emacs Lisp. It is an LALR parser suitable for complex languages. @c LocalWords: multitable NAvigaTOR noindent nomedian nonterm noselect @c LocalWords: nosnarf obarray OLE OO outputfile paren parsetable POINT's @c LocalWords: popup positionalonly positiononly positionormarker pre -@c LocalWords: printf printindex Programmatically pt punctuations quotemode +@c LocalWords: printf printindex Programmatically pt quotemode @c LocalWords: ref regex regexp Regexps reparse resetfile samp sb @c LocalWords: scopestart SEmantic semanticdb setfilename setq @c LocalWords: settitle setupfunction sexp sp SPC speedbar speedbar's diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index d9739b93925..8300e6511a6 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -446,7 +446,7 @@ list. execute when starting SES mode for a buffer). The variable @code{safe-functions} is a list of possibly-unsafe -functions to be treated as safe when analysing formulas and printers. +functions to be treated as safe when analyzing formulas and printers. @xref{Virus protection}. Before customizing @code{safe-functions}, think about how much you trust the person who's suggesting this change. The value @code{t} turns off all anti-virus protection. A diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index 1d4bbbff4ac..854be0d0012 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -233,7 +233,7 @@ least one of the following external tools are installed: @enumerate @item -The GNUTLS command line tool @samp{gnutls-cli}, you can get it from +The GnuTLS command line tool @samp{gnutls-cli}, you can get it from @url{http://www.gnu.org/software/gnutls/}. This is the recommended tool, mainly because it can verify the server certificates. diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 0accc6fac43..e2c2594b66e 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -3180,7 +3180,7 @@ names: '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) @end lisp -This shortens the file openening command to @kbd{C-x C-f /xy +This shortens the file opening command to @kbd{C-x C-f /xy @key{RET}}. The disadvantage is, again, that you cannot edit the file name, because the expansion happens after entering the file name only. @@ -3573,7 +3573,7 @@ The verbosity levels are When @code{tramp-verbose} is greater than or equal to 4, the messages are also written into a @value{tramp} debug buffer. This debug buffer -is useful for analysing problems; sending a @value{tramp} bug report +is useful for analyzing problems; sending a @value{tramp} bug report should be done with @code{tramp-verbose} set to a verbosity level of at least 6 (@pxref{Bug Reports}). @@ -3704,4 +3704,4 @@ for @value{emacsothername}. @c host and then send commands to it. @c * Use `filename' resp. `file name' consistently. @c * Use `host' resp. `machine' consistently. -@c * Consistent small or capitalized words especially in menues. +@c * Consistent small or capitalized words especially in menus. |