From: tomo Date: Mon, 13 Aug 2001 10:51:21 +0000 (+0000) Subject: XEmacs 21.2.39 "Millennium". X-Git-Tag: r21-2-39^2 X-Git-Url: http://git.chise.org/gitweb/?a=commitdiff_plain;h=0f8eefdb51c808a670537deb173a817aed5915bb;p=chise%2Fxemacs-chise.git.1 XEmacs 21.2.39 "Millennium". --- diff --git a/info/cl.info-1 b/info/cl.info-1 index 11eb3c9..d0cc813 100644 --- a/info/cl.info-1 +++ b/info/cl.info-1 @@ -909,7 +909,7 @@ variables. strictly speaking redundant now that `setf' exists. Many programmers continue to prefer `setq' for setting simple variables, though, purely for stylistic or historical reasons. - The macro `(setf x y)' actually expands to `(setq x y)', so + The form `(setf x y)' actually expands to `(setq x y)', so there is no performance penalty for using it in compiled code. * A call to any of the following Lisp functions: diff --git a/info/cl.info-5 b/info/cl.info-5 index 2f39545..b700ffb 100644 --- a/info/cl.info-5 +++ b/info/cl.info-5 @@ -369,28 +369,27 @@ idea for them to include side-effects. (assert (> x 10) t "x is too small: %d") - This usage of SHOW-ARGS is an extension to Common Lisp. In true + This usage of SHOW-ARGS is a change to Common Lisp. In true Common Lisp, the second argument gives a list of PLACES which can - be `setf''d by the user before continuing from the error. Since - Emacs Lisp does not support continuable errors, it makes no sense - to specify PLACES. + be `setf''d by the user before continuing from the error. - - Special Form: check-type form type [string] - This form verifies that FORM evaluates to a value of type TYPE. + - Special Form: check-type place type &optional string + This form verifies that PLACE evaluates to a value of type TYPE. If so, it returns `nil'. If not, `check-type' signals a - `wrong-type-argument' error. The default error message lists the - erroneous value along with TYPE and FORM themselves. If STRING is - specified, it is included in the error message in place of TYPE. - For example: + continuable `wrong-type-argument' error. The default error + message lists the erroneous value along with TYPE and PLACE + themselves. If STRING is specified, it is included in the error + message in place of TYPE. For example: (check-type x (integer 1 *) "a positive integer") *Note Type Predicates::, for a description of the type specifiers that may be used for TYPE. - Note that in Common Lisp, the first argument to `check-type' must - be a PLACE suitable for use by `setf', because `check-type' - signals a continuable error that allows the user to modify PLACE. + Note that as in Common Lisp, the first argument to `check-type' + should be a PLACE suitable for use by `setf', because `check-type' + signals a continuable error that allows the user to modify PLACE, + most simply by returning a value from the debugger. The following error-related macro is also defined: diff --git a/info/internals.info-5 b/info/internals.info-5 index 19f604d..602847d 100644 --- a/info/internals.info-5 +++ b/info/internals.info-5 @@ -880,7 +880,7 @@ and can be enumerated thru either: differences though: 1. We do not use the mark bit (which does not exist for C structures - anyway), we use a big hash table instead. + anyway); we use a big hash table instead. 2. We do not use the mark function of lrecords but instead rely on the external descriptions. This happens essentially because we need to @@ -895,7 +895,7 @@ both delegate the description management to pdump_register_sub. allows us to look up a pdump_entry_list_elmt with the object it points to). Entries are added with `pdump_add_entry()' and looked up with `pdump_get_entry()'. There is no need for entry removal. The hash -value is computed quite basically from the object pointer by +value is computed quite simply from the object pointer by `pdump_make_hash()'. The roots for the marking are: @@ -904,7 +904,7 @@ value is computed quite basically from the object pointer by `staticpro_nodump()' call for protected variables we do not want to dump). - 2. the `pdump_wire''d variables (`staticpro' is equivalent to + 2. the `pdump_wire''d variables (`staticpro()' is equivalent to `staticpro_nodump()' + `pdump_wire()'). 3. the `dumpstruct''ed variables, which points to C structures. @@ -934,7 +934,7 @@ is called indirectly by `pdump_scan_by_alignment()'. 2. the C compiler is required to adjust the size of a struct so that you can have an array of them next to each other. This means you - can have a upper bound of the alignment requirements of a given + can have an upper bound of the alignment requirements of a given structure by looking at which power of two its size is a multiple. 3. the non-variant part of variable size lrecords has an alignment @@ -949,7 +949,7 @@ first. This ensures the best packing. The maximum alignment requirement we take into account is 2^8. `pdump_allocate_offset()' only has to do a linear allocation, -starting at offset 256 (this leaves room for the header and keep the +starting at offset 256 (this leaves room for the header and keeps the alignments happy).  @@ -959,7 +959,7 @@ The header ---------- The next step creates the file and writes a header with a signature -and some random informations in it (number of staticpro, number of +and some random information in it (number of staticpro, number of assigned lrecord types, etc...). The reloc_address field, which indicates at which address the file should be loaded if we want to avoid post-reload relocation, is set to 0. It then seeks to offset 256 @@ -998,14 +998,14 @@ then written. They are: 4. a vector of all the offsets to the objects in the file that include a description (for faster relocation at reload time) - 5. the pdump_wired and pdump_wired_list arrays + 5. the pdump_wire and pdump_wire_list arrays For each of the arrays we write both the pointer to the variables and the relocated offset of the object they point to. Since these variables are global, the pointers are still valid when restarting the program and are used to regenerate the global pointers. - The `pdump_wired_list' array is a special case. The variables it + The `pdump_wire_list' array is a special case. The variables it points to are the head of weak linked lists of lisp objects of the same type. Not all objects of this list are dumped so the relocated pointer we associate with them points to the first dumped object of the list, or diff --git a/info/internals.info-8 b/info/internals.info-8 index 0e44efd..fc9bea3 100644 --- a/info/internals.info-8 +++ b/info/internals.info-8 @@ -694,12 +694,13 @@ Glyphs Glyphs are graphical elements that can be displayed in XEmacs buffers or gutters. We use the term graphical element here in the -broadest possible sense since glyphs can be as mundane as text to as +broadest possible sense since glyphs can be as mundane as text or as arcane as a native tab widget. In XEmacs, glyphs represent the uninstantiated state of graphical elements, i.e. they hold all the information necessary to produce an -image on-screen but the image does not exist at this stage. +image on-screen but the image need not exist at this stage, and multiple +screen images can be instantiated from a single glyph. Glyphs are lazily instantiated by calling one of the glyph functions. This usually occurs within redisplay when `Fglyph_height' is @@ -717,7 +718,7 @@ usage - and this would be extremely memory and cpu intensive. Widget-glyphs (a.k.a native widgets) are not cached in this way. This is because widget-glyph image-instances on screen are toolkit windows, and thus cannot be reused in multiple XEmacs domains. Thus -widget-glyphs are cached on a window basis. +widget-glyphs are cached on an XEmacs window basis. Any action on a glyph first consults the cache before actually instantiating a widget. @@ -730,28 +731,11 @@ Widget-Glyphs in the MS-Windows Environment Widget-Glyphs in the X Environment ================================== - Widget-glyphs under X make heavy use of lwlib for manipulating the -native toolkit objects. This is primarily so that different toolkits can -be supported for widget-glyphs, just as they are supported for features -such as menubars etc. - - Lwlib is extremely poorly documented and quite hairy so here is my -understanding of what goes on. - - Lwlib maintains a set of widget_instances which mirror the -hierarchical state of Xt widgets. I think this is so that widgets can -be updated and manipulated generically by the lwlib library. For -instance update_one_widget_instance can cope with multiple types of -widget and multiple types of toolkit. Each element in the widget -hierarchy is updated from its corresponding widget_instance by walking -the widget_instance tree recursively. - - This has desirable properties such as lw_modify_all_widgets which is -called from `glyphs-x.c' and updates all the properties of a widget -without having to know what the widget is or what toolkit it is from. -Unfortunately this also has hairy properties such as making the lwlib -code quite complex. And of course lwlib has to know at some level what -the widget is and how to set its properties. + Widget-glyphs under X make heavy use of lwlib (*note Lucid Widget +Library::) for manipulating the native toolkit objects. This is +primarily so that different toolkits can be supported for +widget-glyphs, just as they are supported for features such as menubars +etc.  File: internals.info, Node: Specifiers, Next: Menus, Prev: Glyphs, Up: Top @@ -813,7 +797,7 @@ argument, which is the callback function or form given in the menu's description.  -File: internals.info, Node: Subprocesses, Next: Interface to X Windows, Prev: Menus, Up: Top +File: internals.info, Node: Subprocesses, Next: Interface to the X Window System, Prev: Menus, Up: Top Subprocesses ************ @@ -887,15 +871,160 @@ Subprocesses it is using pipes.  -File: internals.info, Node: Interface to X Windows, Next: Index, Prev: Subprocesses, Up: Top +File: internals.info, Node: Interface to the X Window System, Next: Index, Prev: Subprocesses, Up: Top -Interface to X Windows -********************** +Interface to the X Window System +******************************** - Not yet documented. + Mostly undocumented. + +* Menu: + +* Lucid Widget Library:: An interface to various widget sets. + + +File: internals.info, Node: Lucid Widget Library, Up: Interface to the X Window System + +Lucid Widget Library +==================== + + Lwlib is extremely poorly documented and quite hairy. The author(s) +blame that on X, Xt, and Motif, with some justice, but also sufficient +hypocrisy to avoid drawing the obvious conclusion about their own work. + + The Lucid Widget Library is composed of two more or less independent +pieces. The first, as the name suggests, is a set of widgets. These +widgets are intended to resemble and improve on widgets provided in the +Motif toolkit but not in the Athena widgets, including menubars and +scrollbars. Recent additions by Andy Piper integrate some "modern" +widgets by Edward Falk, including checkboxes, radio buttons, progress +gauges, and index tab controls (aka notebooks). + + The second piece of the Lucid widget library is a generic interface +to several toolkits for X (including Xt, the Athena widget set, and +Motif, as well as the Lucid widgets themselves) so that core XEmacs +code need not know which widget set has been used to build the +graphical user interface. + +* Menu: + +* Generic Widget Interface:: The lwlib generic widget interface. +* Scrollbars:: +* Menubars:: +* Checkboxes and Radio Buttons:: +* Progress Bars:: +* Tab Controls:: + + +File: internals.info, Node: Generic Widget Interface, Next: Scrollbars, Up: Lucid Widget Library + +Generic Widget Interface +------------------------ + + In general in any toolkit a widget may be a composite object. In Xt, +all widgets have an X window that they manage, but typically a complex +widget will have widget children, each of which manages a subwindow of +the parent widget's X window. These children may themselves be +composite widgets. Thus a widget is actually a tree or hierarchy of +widgets. + + For each toolkit widget, lwlib maintains a tree of `widget_values' +which mirror the hierarchical state of Xt widgets (including Motif, +Athena, 3D Athena, and Falk's widget sets). Each `widget_value' has +`contents' member, which points to the head of a linked list of its +children. The linked list of siblings is chained through the `next' +member of `widget_value'. + + +-----------+ + | composite | + +-----------+ + | + | contents + V + +-------+ next +-------+ next +-------+ + | child |----->| child |----->| child | + +-------+ +-------+ +-------+ + | + | contents + V + +-------------+ next +-------------+ + | grand child |----->| grand child | + +-------------+ +-------------+ + + The `widget_value' hierarchy of a composite widget with two simple + children and one composite child. + + The `widget_instance' structure maintains the inverse view of the +tree. As for the `widget_value', siblings are chained through the +`next' member. However, rather than naming children, the +`widget_instance' tree links to parents. + + +-----------+ + | composite | + +-----------+ + A + | parent + | + +-------+ next +-------+ next +-------+ + | child |----->| child |----->| child | + +-------+ +-------+ +-------+ + A + | parent + | + +-------------+ next +-------------+ + | grand child |----->| grand child | + +-------------+ +-------------+ + + The `widget_value' hierarchy of a composite widget with two simple + children and one composite child. + + This permits widgets derived from different toolkits to be updated +and manipulated generically by the lwlib library. For instance +`update_one_widget_instance' can cope with multiple types of widget and +multiple types of toolkit. Each element in the widget hierarchy is +updated from its corresponding `widget_value' by walking the +`widget_value' tree. This has desirable properties. For example, +`lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the +properties of a widget without having to know what the widget is or +what toolkit it is from. Unfortunately this also has its hairy +properties; the lwlib code quite complex. And of course lwlib has to +know at some level what the widget is and how to set its properties. + + The `widget_instance' structure also contains a pointer to the root +of its tree. Widget instances are further confi + + +File: internals.info, Node: Scrollbars, Next: Menubars, Prev: Generic Widget Interface, Up: Lucid Widget Library + +Scrollbars +---------- + + +File: internals.info, Node: Menubars, Next: Checkboxes and Radio Buttons, Prev: Scrollbars, Up: Lucid Widget Library + +Menubars +-------- + + +File: internals.info, Node: Checkboxes and Radio Buttons, Next: Progress Bars, Prev: Menubars, Up: Lucid Widget Library + +Checkboxes and Radio Buttons +---------------------------- + + +File: internals.info, Node: Progress Bars, Next: Tab Controls, Prev: Checkboxes and Radio Buttons, Up: Lucid Widget Library + +Progress Bars +------------- + + +File: internals.info, Node: Tab Controls, Prev: Progress Bars, Up: Lucid Widget Library + +Tab Controls +------------  -File: internals.info, Node: Index, Prev: Interface to X Windows, Up: Top +File: internals.info, Node: Index, Prev: Interface to the X Window System, Up: Top Index ***** diff --git a/info/lispref.info-12 b/info/lispref.info-12 index 6fd3e06..f32c4f5 100644 --- a/info/lispref.info-12 +++ b/info/lispref.info-12 @@ -689,6 +689,7 @@ in byte compilation. * Eval During Compile:: Code to be evaluated when you compile. * Compiled-Function Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code. +* Different Behavior:: When compiled code gives different results.  File: lispref.info, Node: Speed of Byte-Code, Next: Compilation Functions, Up: Byte Compilation diff --git a/info/lispref.info-13 b/info/lispref.info-13 index 06f3d06..3cf322d 100644 --- a/info/lispref.info-13 +++ b/info/lispref.info-13 @@ -50,7 +50,7 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Disassembly, Prev: Compiled-Function Objects, Up: Byte Compilation +File: lispref.info, Node: Disassembly, Next: Different Behavior, Prev: Compiled-Function Objects, Up: Byte Compilation Disassembled Byte-Code ====================== @@ -224,6 +224,36 @@ source; these do not appear in the output of `disassemble'. => nil  +File: lispref.info, Node: Different Behavior, Prev: Disassembly, Up: Byte Compilation + +Different Behavior +================== + + The intent is that compiled byte-code and the corresponding code +executed by the Lisp interpreter produce identical results. However, +there are some circumstances where the results will differ. + + * Arithmetic operations may be rearranged for efficiency or + compile-time evaluation. When floating point numbers are + involved, this may produce different values or an overflow. + + * Some arithmetic operations may be optimized away. For example, the + expression `(+ x)' may be optimized to simply `x'. If the value + of `x' is a marker, then the value will be a marker instead of an + integer. If the value of `x' is a cons cell, then the interpreter + will issue an error, while the bytecode will not. + + If you're trying to use `(+ OBJECT 0)' to convert OBJECT to + integer, consider using an explicit conversion function, which is + clearer and guaranteed to work. Instead of `(+ MARKER 0)', use + `(marker-position MARKER)'. Instead of `(+ CHAR 0)', use + `(char-int CHAR)'. + + For maximal equivalence between interpreted and compiled code, the +variables `byte-compile-delete-errors' and `byte-compile-optimize' can +be set to `nil', but this is not recommended. + + File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top Debugging Lisp Programs @@ -1117,84 +1147,3 @@ with one of the non-instrumenting commands, or reload the file. See *Note Edebug Eval:: for other evaluation functions available inside of Edebug. - -File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug - -Edebug Execution Modes ----------------------- - - Edebug supports several execution modes for running the program you -are debugging. We call these alternatives "Edebug execution modes"; do -not confuse them with major or minor modes. The current Edebug -execution mode determines how Edebug displays the progress of the -evaluation, whether it stops at each stop point, or continues to the -next breakpoint, for example. - - Normally, you specify the Edebug execution mode by typing a command -to continue the program in a certain mode. Here is a table of these -commands. All except for `S' resume execution of the program, at least -for a certain distance. - -`S' - Stop: don't execute any more of the program for now, just wait for - more Edebug commands (`edebug-stop'). - -`' - Step: stop at the next stop point encountered (`edebug-step-mode'). - -`n' - Next: stop at the next stop point encountered after an expression - (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note - Edebug Misc::. - -`t' - Trace: pause one second at each Edebug stop point - (`edebug-trace-mode'). - -`T' - Rapid trace: update at each stop point, but don't actually pause - (`edebug-Trace-fast-mode'). - -`g' - Go: run until the next breakpoint (`edebug-go-mode'). *Note - Breakpoints::. - -`c' - Continue: pause for one second at each breakpoint, but don't stop - (`edebug-continue-mode'). - -`C' - Rapid continue: update at each breakpoint, but don't actually pause - (`edebug-Continue-fast-mode'). - -`G' - Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You - can still stop the program by hitting any key. - - In general, the execution modes earlier in the above list run the -program more slowly or stop sooner. - - When you enter a new Edebug level, the initial execution mode comes -from the value of the variable `edebug-initial-mode'. By default, this -specifies `step' mode. Note that you may reenter the same Edebug level -several times if, for example, an instrumented function is called -several times from one command. - - While executing or tracing, you can interrupt the execution by typing -any Edebug command. Edebug stops the program at the next stop point and -then executes the command that you typed. For example, typing `t' -during execution switches to trace mode at the next stop point. You can -use `S' to stop execution without doing anything else. - - If your function happens to read input, a character you hit -intending to interrupt execution may be read by the function instead. -You can avoid such unintended results by paying attention to when your -program wants input. - - Keyboard macros containing Edebug commands do not work; when you exit -from Edebug, to resume the program, whether you are defining or -executing a keyboard macro is forgotten. Also, defining or executing a -keyboard macro outside of Edebug does not affect the command loop inside -Edebug. This is usually an advantage. But see -`edebug-continue-kbd-macro'. - diff --git a/info/lispref.info-14 b/info/lispref.info-14 index bd55715..40329bc 100644 --- a/info/lispref.info-14 +++ b/info/lispref.info-14 @@ -50,6 +50,87 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug + +Edebug Execution Modes +---------------------- + + Edebug supports several execution modes for running the program you +are debugging. We call these alternatives "Edebug execution modes"; do +not confuse them with major or minor modes. The current Edebug +execution mode determines how Edebug displays the progress of the +evaluation, whether it stops at each stop point, or continues to the +next breakpoint, for example. + + Normally, you specify the Edebug execution mode by typing a command +to continue the program in a certain mode. Here is a table of these +commands. All except for `S' resume execution of the program, at least +for a certain distance. + +`S' + Stop: don't execute any more of the program for now, just wait for + more Edebug commands (`edebug-stop'). + +`' + Step: stop at the next stop point encountered (`edebug-step-mode'). + +`n' + Next: stop at the next stop point encountered after an expression + (`edebug-next-mode'). Also see `edebug-forward-sexp' in *Note + Edebug Misc::. + +`t' + Trace: pause one second at each Edebug stop point + (`edebug-trace-mode'). + +`T' + Rapid trace: update at each stop point, but don't actually pause + (`edebug-Trace-fast-mode'). + +`g' + Go: run until the next breakpoint (`edebug-go-mode'). *Note + Breakpoints::. + +`c' + Continue: pause for one second at each breakpoint, but don't stop + (`edebug-continue-mode'). + +`C' + Rapid continue: update at each breakpoint, but don't actually pause + (`edebug-Continue-fast-mode'). + +`G' + Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode'). You + can still stop the program by hitting any key. + + In general, the execution modes earlier in the above list run the +program more slowly or stop sooner. + + When you enter a new Edebug level, the initial execution mode comes +from the value of the variable `edebug-initial-mode'. By default, this +specifies `step' mode. Note that you may reenter the same Edebug level +several times if, for example, an instrumented function is called +several times from one command. + + While executing or tracing, you can interrupt the execution by typing +any Edebug command. Edebug stops the program at the next stop point and +then executes the command that you typed. For example, typing `t' +during execution switches to trace mode at the next stop point. You can +use `S' to stop execution without doing anything else. + + If your function happens to read input, a character you hit +intending to interrupt execution may be read by the function instead. +You can avoid such unintended results by paying attention to when your +program wants input. + + Keyboard macros containing Edebug commands do not work; when you exit +from Edebug, to resume the program, whether you are defining or +executing a keyboard macro is forgotten. Also, defining or executing a +keyboard macro outside of Edebug does not affect the command loop inside +Edebug. This is usually an advantage. But see +`edebug-continue-kbd-macro'. + + File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug Jumping @@ -1151,57 +1232,3 @@ want to set the option `edebug-unwrap-results' to a non-`nil' value while debugging such expressions, but it would slow Edebug down to always do this. - -File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls - -Specification Examples -...................... - - Here we provide several examples of Edebug specifications to show -many of its capabilities. - - A `let' special form has a sequence of bindings and a body. Each of -the bindings is either a symbol or a sublist with a symbol and optional -value. In the specification below, notice the `gate' inside of the -sublist to prevent backtracking. - - (def-edebug-spec let - ((&rest - &or symbolp (gate symbolp &optional form)) - body)) - - Edebug uses the following specifications for `defun' and `defmacro' -and the associated argument list and `interactive' specifications. It -is necessary to handle the expression argument of an interactive form -specially since it is actually evaluated outside of the function body. - - (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec - (def-edebug-spec defun - (&define name lambda-list - [&optional stringp] ; Match the doc string, if present. - [&optional ("interactive" interactive)] - def-body)) - - (def-edebug-spec lambda-list - (([&rest arg] - [&optional ["&optional" arg &rest arg]] - &optional ["&rest" arg] - ))) - - (def-edebug-spec interactive - (&optional &or stringp def-form)) ; Notice: `def-form' - - The specification for backquote below illustrates how to match -dotted lists and use `nil' to terminate recursion. It also illustrates -how components of a vector may be matched. (The actual specification -provided by Edebug does not support dotted lists because doing so -causes very deep recursion that could fail.) - - (def-edebug-spec ` (backquote-form)) ;; alias just for clarity - - (def-edebug-spec backquote-form - (&or ([&or "," ",@"] &or ("quote" backquote-form) form) - (backquote-form . [&or nil backquote-form]) - (vector &rest backquote-form) - sexp)) - diff --git a/info/lispref.info-15 b/info/lispref.info-15 index 8e2a635..340e0ea 100644 --- a/info/lispref.info-15 +++ b/info/lispref.info-15 @@ -50,6 +50,60 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls + +Specification Examples +...................... + + Here we provide several examples of Edebug specifications to show +many of its capabilities. + + A `let' special form has a sequence of bindings and a body. Each of +the bindings is either a symbol or a sublist with a symbol and optional +value. In the specification below, notice the `gate' inside of the +sublist to prevent backtracking. + + (def-edebug-spec let + ((&rest + &or symbolp (gate symbolp &optional form)) + body)) + + Edebug uses the following specifications for `defun' and `defmacro' +and the associated argument list and `interactive' specifications. It +is necessary to handle the expression argument of an interactive form +specially since it is actually evaluated outside of the function body. + + (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec + (def-edebug-spec defun + (&define name lambda-list + [&optional stringp] ; Match the doc string, if present. + [&optional ("interactive" interactive)] + def-body)) + + (def-edebug-spec lambda-list + (([&rest arg] + [&optional ["&optional" arg &rest arg]] + &optional ["&rest" arg] + ))) + + (def-edebug-spec interactive + (&optional &or stringp def-form)) ; Notice: `def-form' + + The specification for backquote below illustrates how to match +dotted lists and use `nil' to terminate recursion. It also illustrates +how components of a vector may be matched. (The actual specification +provided by Edebug does not support dotted lists because doing so +causes very deep recursion that could fail.) + + (def-edebug-spec ` (backquote-form)) ;; alias just for clarity + + (def-edebug-spec backquote-form + (&or ([&or "," ",@"] &or ("quote" backquote-form) form) + (backquote-form . [&or nil backquote-form]) + (vector &rest backquote-form) + sexp)) + + File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug Edebug Options diff --git a/info/lispref.info-19 b/info/lispref.info-19 index 39a30bf..58f7d19 100644 --- a/info/lispref.info-19 +++ b/info/lispref.info-19 @@ -1078,7 +1078,7 @@ information. indirect keymap bindings. This makes it possible to search for an indirect definition itself. - This function is used by `where-is' (*note Help: (emacs)Help.). + This function is used by `where-is' (*note Help: (xemacs)Help.). (where-is-internal 'describe-function) => ([(control h) d] [(control h) f] [f1 d] [f1 f]) diff --git a/info/lispref.info-21 b/info/lispref.info-21 index cf39e4c..6378b5c 100644 --- a/info/lispref.info-21 +++ b/info/lispref.info-21 @@ -1024,7 +1024,7 @@ visited. If you run `normal-mode' interactively, the argument FIND-FILE is normally `nil'. In this case, `normal-mode' unconditionally processes any local variables list. *Note Local Variables in - Files: (emacs)File variables, for the syntax of the local + Files: (xemacs)File variables, for the syntax of the local variables section of a file. `normal-mode' uses `condition-case' around the call to the major @@ -1058,7 +1058,7 @@ visited. value of a local variable. However, this function does not look for the `mode:' local variable near the end of a file; the `hack-local-variables' function does that. *Note How Major Modes - are Chosen: (emacs)Choosing Modes. + are Chosen: (xemacs)Choosing Modes. - User Option: default-major-mode This variable holds the default major mode for new buffers. The diff --git a/info/lispref.info-22 b/info/lispref.info-22 index fd881c3..6d897d5 100644 --- a/info/lispref.info-22 +++ b/info/lispref.info-22 @@ -864,7 +864,7 @@ that information to read the documentation from the appropriate file; this is transparent to the user. For information on the uses of documentation strings, see *Note -Help: (emacs)Help. +Help: (xemacs)Help. The `emacs/lib-src' directory contains two utilities that you can use to print nice-looking hardcopy for the file diff --git a/info/lispref.info-25 b/info/lispref.info-25 index 793aca3..60bd85c 100644 --- a/info/lispref.info-25 +++ b/info/lispref.info-25 @@ -254,7 +254,7 @@ Auto-Saving called "auto-saving". Auto-saving prevents you from losing more than a limited amount of work if the system crashes. By default, auto-saves happen every 300 keystrokes, or after around 30 seconds of idle time. -*Note Auto-Save: (emacs)Auto-Save, for information on auto-save for +*Note Auto-Save: (xemacs)Auto-Save, for information on auto-save for users. Here we describe the functions used to implement auto-saving and the variables that control them. @@ -436,7 +436,7 @@ Reverting If you have made extensive changes to a file and then change your mind about them, you can get rid of them by reading in the previous version of the file with the `revert-buffer' command. *Note Reverting -a Buffer: (emacs)Reverting. +a Buffer: (xemacs)Reverting. - Command: revert-buffer &optional check-auto-save noconfirm preserve-modes diff --git a/info/lispref.info-28 b/info/lispref.info-28 index 02d67fe..811de90 100644 --- a/info/lispref.info-28 +++ b/info/lispref.info-28 @@ -916,18 +916,19 @@ Motion by Words These functions for parsing words use the syntax table to decide whether a given character is part of a word. *Note Syntax Tables::. - - Command: forward-word count &optional buffer + - Command: forward-word &optional count buffer This function moves point forward COUNT words (or backward if COUNT is negative). Normally it returns `t'. If this motion encounters the beginning or end of the buffer, or the limits of the accessible portion when narrowing is in effect, point stops there - and the value is `nil'. BUFFER defaults to the current buffer if - omitted. + and the value is `nil'. + + COUNT defaults to `1' and BUFFER defaults to the current buffer. In an interactive call, COUNT is set to the numeric prefix argument. - - Command: backward-word count &optional buffer + - Command: backward-word &optional count buffer This function is just like `forward-word', except that it moves backward until encountering the front of a word, rather than forward. BUFFER defaults to the current buffer if omitted. @@ -935,9 +936,6 @@ whether a given character is part of a word. *Note Syntax Tables::. In an interactive call, COUNT is set to the numeric prefix argument. - This function is rarely used in programs, as it is more efficient - to call `forward-word' with a negative argument. - - Variable: words-include-escapes This variable affects the behavior of `forward-word' and everything that uses it. If it is non-`nil', then characters in the "escape" @@ -1170,3 +1168,82 @@ performance of your code. *Note cache-long-line-scans: Text Lines. The value returned is the window line number point has moved to, with the top line in the window numbered 0. + +File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion + +Moving over Balanced Expressions +-------------------------------- + + Here are several functions concerned with balanced-parenthesis +expressions (also called "sexps" in connection with moving across them +in XEmacs). The syntax table controls how these functions interpret +various characters; see *Note Syntax Tables::. *Note Parsing +Expressions::, for lower-level primitives for scanning sexps or parts of +sexps. For user-level commands, see *Note Lists and Sexps: +(xemacs)Lists and Sexps. + + - Command: forward-list &optional arg + This function moves forward across ARG balanced groups of + parentheses. (Other syntactic entities such as words or paired + string quotes are ignored.) ARG defaults to 1 if omitted. If ARG + is negative, move backward across that many groups of parentheses. + + - Command: backward-list &optional count + This function moves backward across COUNT balanced groups of + parentheses. (Other syntactic entities such as words or paired + string quotes are ignored.) COUNT defaults to 1 if omitted. If + COUNT is negative, move forward across that many groups of + parentheses. + + - Command: up-list &optional count + This function moves forward out of COUNT levels of parentheses. A + negative argument means move backward but still to a less deep + spot. + + - Command: down-list &optional count + This function moves forward into COUNT levels of parentheses. A + negative argument means move backward but still go deeper in + parentheses (-COUNT levels). + + - Command: forward-sexp &optional count + This function moves forward across COUNT balanced expressions. + Balanced expressions include both those delimited by parentheses + and other kinds, such as words and string constants. COUNT + defaults to 1 if omitted. If COUNT is negative, move backward + across that many balanced expressions. For example, + + ---------- Buffer: foo ---------- + (concat-!- "foo " (car x) y z) + ---------- Buffer: foo ---------- + + (forward-sexp 3) + => nil + + ---------- Buffer: foo ---------- + (concat "foo " (car x) y-!- z) + ---------- Buffer: foo ---------- + + - Command: backward-sexp &optional count + This function moves backward across COUNT balanced expressions. + COUNT defaults to 1 if omitted. If COUNT is negative, move + forward across that many balanced expressions. + + - Command: beginning-of-defun &optional count + This function moves back to the COUNTth beginning of a defun. If + COUNT is negative, this actually moves forward, but it still moves + to the beginning of a defun, not to the end of one. COUNT + defaults to 1 if omitted. + + - Command: end-of-defun &optional count + This function moves forward to the COUNTth end of a defun. If + COUNT is negative, this actually moves backward, but it still + moves to the end of a defun, not to the beginning of one. COUNT + defaults to 1 if omitted. + + - User Option: defun-prompt-regexp + If non-`nil', this variable holds a regular expression that + specifies what text can appear before the open-parenthesis that + starts a defun. That is to say, a defun begins on a line that + starts with a match for this regular expression, followed by a + character with open-parenthesis syntax. + diff --git a/info/lispref.info-29 b/info/lispref.info-29 index d9b7423..e0e0b52 100644 --- a/info/lispref.info-29 +++ b/info/lispref.info-29 @@ -50,85 +50,6 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion - -Moving over Balanced Expressions --------------------------------- - - Here are several functions concerned with balanced-parenthesis -expressions (also called "sexps" in connection with moving across them -in XEmacs). The syntax table controls how these functions interpret -various characters; see *Note Syntax Tables::. *Note Parsing -Expressions::, for lower-level primitives for scanning sexps or parts of -sexps. For user-level commands, see *Note Lists and Sexps: -(emacs)Lists and Sexps. - - - Command: forward-list &optional arg - This function moves forward across ARG balanced groups of - parentheses. (Other syntactic entities such as words or paired - string quotes are ignored.) ARG defaults to 1 if omitted. If ARG - is negative, move backward across that many groups of parentheses. - - - Command: backward-list &optional count - This function moves backward across COUNT balanced groups of - parentheses. (Other syntactic entities such as words or paired - string quotes are ignored.) COUNT defaults to 1 if omitted. If - COUNT is negative, move forward across that many groups of - parentheses. - - - Command: up-list &optional count - This function moves forward out of COUNT levels of parentheses. A - negative argument means move backward but still to a less deep - spot. - - - Command: down-list &optional count - This function moves forward into COUNT levels of parentheses. A - negative argument means move backward but still go deeper in - parentheses (-COUNT levels). - - - Command: forward-sexp &optional count - This function moves forward across COUNT balanced expressions. - Balanced expressions include both those delimited by parentheses - and other kinds, such as words and string constants. COUNT - defaults to 1 if omitted. If COUNT is negative, move backward - across that many balanced expressions. For example, - - ---------- Buffer: foo ---------- - (concat-!- "foo " (car x) y z) - ---------- Buffer: foo ---------- - - (forward-sexp 3) - => nil - - ---------- Buffer: foo ---------- - (concat "foo " (car x) y-!- z) - ---------- Buffer: foo ---------- - - - Command: backward-sexp &optional count - This function moves backward across COUNT balanced expressions. - COUNT defaults to 1 if omitted. If COUNT is negative, move - forward across that many balanced expressions. - - - Command: beginning-of-defun &optional count - This function moves back to the COUNTth beginning of a defun. If - COUNT is negative, this actually moves forward, but it still moves - to the beginning of a defun, not to the end of one. COUNT - defaults to 1 if omitted. - - - Command: end-of-defun &optional count - This function moves forward to the COUNTth end of a defun. If - COUNT is negative, this actually moves backward, but it still - moves to the end of a defun, not to the beginning of one. COUNT - defaults to 1 if omitted. - - - User Option: defun-prompt-regexp - If non-`nil', this variable holds a regular expression that - specifies what text can appear before the open-parenthesis that - starts a defun. That is to say, a defun begins on a line that - starts with a match for this regular expression, followed by a - character with open-parenthesis syntax. - - File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion Skipping Characters @@ -1166,3 +1087,75 @@ operated on the current buffer.) The end of the buffer (or of its accessible portion) is always considered the end of a line. + +File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text + +Examining Buffer Contents +========================= + + This section describes two functions that allow a Lisp program to +convert any portion of the text in the buffer into a string. + + - Function: buffer-substring start end &optional buffer + - Function: buffer-string start end &optional buffer + These functions are equivalent and return a string containing a + copy of the text of the region defined by positions START and END + in the buffer. If the arguments are not positions in the + accessible portion of the buffer, `buffer-substring' signals an + `args-out-of-range' error. If optional argument BUFFER is `nil', + the current buffer is assumed. + + If the region delineated by START and END contains duplicable + extents, they will be remembered in the string. *Note Duplicable + Extents::. + + It is not necessary for START to be less than END; the arguments + can be given in either order. But most often the smaller argument + is written first. + + ---------- Buffer: foo ---------- + This is the contents of buffer foo + + ---------- Buffer: foo ---------- + + (buffer-substring 1 10) + => "This is t" + (buffer-substring (point-max) 10) + => "he contents of buffer foo + " + + +File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text + +Comparing Text +============== + + This function lets you compare portions of the text in a buffer, +without copying them into strings first. + + - Function: compare-buffer-substrings buffer1 start1 end1 buffer2 + start2 end2 + This function lets you compare two substrings of the same buffer + or two different buffers. The first three arguments specify one + substring, giving a buffer and two positions within the buffer. + The last three arguments specify the other substring in the same + way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for + the current buffer. + + The value is negative if the first substring is less, positive if + the first is greater, and zero if they are equal. The absolute + value of the result is one plus the index of the first differing + characters within the substrings. + + This function ignores case when comparing characters if + `case-fold-search' is non-`nil'. It always ignores text + properties. + + Suppose the current buffer contains the text `foobarbar + haha!rara!'; then in this example the two substrings are `rbar ' + and `rara!'. The value is 2 because the first substring is greater + at the second character. + + (compare-buffer-substring nil 6 11 nil 16 21) + => 2 + diff --git a/info/lispref.info-30 b/info/lispref.info-30 index 982442c..fbaa5f6 100644 --- a/info/lispref.info-30 +++ b/info/lispref.info-30 @@ -50,78 +50,6 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text - -Examining Buffer Contents -========================= - - This section describes two functions that allow a Lisp program to -convert any portion of the text in the buffer into a string. - - - Function: buffer-substring start end &optional buffer - - Function: buffer-string start end &optional buffer - These functions are equivalent and return a string containing a - copy of the text of the region defined by positions START and END - in the buffer. If the arguments are not positions in the - accessible portion of the buffer, `buffer-substring' signals an - `args-out-of-range' error. If optional argument BUFFER is `nil', - the current buffer is assumed. - - If the region delineated by START and END contains duplicable - extents, they will be remembered in the string. *Note Duplicable - Extents::. - - It is not necessary for START to be less than END; the arguments - can be given in either order. But most often the smaller argument - is written first. - - ---------- Buffer: foo ---------- - This is the contents of buffer foo - - ---------- Buffer: foo ---------- - - (buffer-substring 1 10) - => "This is t" - (buffer-substring (point-max) 10) - => "he contents of buffer foo - " - - -File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text - -Comparing Text -============== - - This function lets you compare portions of the text in a buffer, -without copying them into strings first. - - - Function: compare-buffer-substrings buffer1 start1 end1 buffer2 - start2 end2 - This function lets you compare two substrings of the same buffer - or two different buffers. The first three arguments specify one - substring, giving a buffer and two positions within the buffer. - The last three arguments specify the other substring in the same - way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for - the current buffer. - - The value is negative if the first substring is less, positive if - the first is greater, and zero if they are equal. The absolute - value of the result is one plus the index of the first differing - characters within the substrings. - - This function ignores case when comparing characters if - `case-fold-search' is non-`nil'. It always ignores text - properties. - - Suppose the current buffer contains the text `foobarbar - haha!rara!'; then in this example the two substrings are `rbar ' - and `rara!'. The value is 2 because the first substring is greater - at the second character. - - (compare-buffer-substring nil 6 11 nil 16 21) - => 2 - - File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text Inserting Text @@ -310,10 +238,11 @@ return a value of `nil'. START and END. The value is `nil'. If optional argument BUFFER is `nil', the current buffer is assumed. - - Command: delete-char count &optional killp + - Command: delete-char &optional count killp This command deletes COUNT characters directly after point, or - before point if COUNT is negative. If KILLP is non-`nil', then it - saves the deleted characters in the kill ring. + before point if COUNT is negative. COUNT defaults to `1'. If + KILLP is non-`nil', then it saves the deleted characters in the + kill ring. In an interactive call, COUNT is the numeric prefix argument, and KILLP is the unprocessed prefix argument. Therefore, if a prefix @@ -323,10 +252,11 @@ return a value of `nil'. The value returned is always `nil'. - - Command: delete-backward-char count &optional killp + - Command: delete-backward-char &optional count killp This command deletes COUNT characters directly before point, or - after point if COUNT is negative. If KILLP is non-`nil', then it - saves the deleted characters in the kill ring. + after point if COUNT is negative. COUNT defaults to 1. If KILLP + is non-`nil', then it saves the deleted characters in the kill + ring. In an interactive call, COUNT is the numeric prefix argument, and KILLP is the unprocessed prefix argument. Therefore, if a prefix diff --git a/info/lispref.info-32 b/info/lispref.info-32 index 2153849..0a55015 100644 --- a/info/lispref.info-32 +++ b/info/lispref.info-32 @@ -786,8 +786,8 @@ Regular Expression Searching In XEmacs, you can search for the next match for a regexp either incrementally or not. Incremental search commands are described in the -`The XEmacs Reference Manual'. *Note Regular Expression Search: -(emacs)Regexp Search. Here we describe only the search functions +`The XEmacs Lisp Reference Manual'. *Note Regular Expression Search: +(xemacs)Regexp Search. Here we describe only the search functions useful in programs. The principal one is `re-search-forward'. - Command: re-search-forward regexp &optional limit noerror count diff --git a/info/lispref.info-33 b/info/lispref.info-33 index 0124e25..20ec664 100644 --- a/info/lispref.info-33 +++ b/info/lispref.info-33 @@ -887,11 +887,12 @@ higher-level functions for moving over balanced expressions. You can use `forward-comment' to move forward or backward over one comment or several comments. - - Function: forward-comment count &optional buffer + - Function: forward-comment &optional count buffer This function moves point forward across COUNT comments (backward, if COUNT is negative). If it finds anything other than a comment or whitespace, it stops, leaving point at the place where it - stopped. It also stops after satisfying COUNT. + stopped. It also stops after satisfying COUNT. COUNT defaults to + `1'. Optional argument BUFFER defaults to the current buffer. @@ -1016,7 +1017,7 @@ Therefore, it is safe to use them in an extremely nonstandard way. *Note Creating Symbols::. For the user-level commands for abbrevs, see *Note Abbrev Mode: -(emacs)Abbrevs. +(xemacs)Abbrevs. * Menu: diff --git a/info/lispref.info-38 b/info/lispref.info-38 index 85d95e3..b0dade8 100644 --- a/info/lispref.info-38 +++ b/info/lispref.info-38 @@ -480,10 +480,10 @@ The Echo Area `message' primitive, and for echoing keystrokes. It is not the same as the minibuffer, despite the fact that the minibuffer appears (when active) in the same place on the screen as the echo area. The `XEmacs -Reference Manual' specifies the rules for resolving conflicts between -the echo area and the minibuffer for use of that screen space (*note -The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo -area; see *Note Errors::. +Lisp Reference Manual' specifies the rules for resolving conflicts +between the echo area and the minibuffer for use of that screen space +(*note The Minibuffer: (xemacs)Minibuffer.). Error messages appear in +the echo area; see *Note Errors::. You can write output in the echo area by using the Lisp printing functions with `t' as the stream (*note Output Functions::), or as diff --git a/info/lispref.info-46 b/info/lispref.info-46 index 2e76962..a94d72b 100644 --- a/info/lispref.info-46 +++ b/info/lispref.info-46 @@ -482,7 +482,7 @@ indent them: The indentation commands of the Lisp modes in XEmacs, such as `M-;' (`indent-for-comment') and (`lisp-indent-line') automatically indent comments according to these conventions, depending on the number -of semicolons. *Note Manipulating Comments: (emacs)Comments. +of semicolons. *Note Manipulating Comments: (xemacs)Comments.  File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips diff --git a/info/lispref.info-47 b/info/lispref.info-47 index 196b605..524e88d 100644 --- a/info/lispref.info-47 +++ b/info/lispref.info-47 @@ -114,7 +114,7 @@ define such variables for their internal use; we don't list them here. *note Usual Display:: `comment-column' - *note Comments: (emacs)Comments. + *note Comments: (xemacs)Comments. `default-directory' *note System Environment:: @@ -126,7 +126,7 @@ define such variables for their internal use; we don't list them here. *note Auto Filling:: `goal-column' - *note Moving Point: (emacs)Moving Point. + *note Moving Point: (xemacs)Moving Point. `left-margin' *note Indentation:: diff --git a/info/texinfo.info-4 b/info/texinfo.info-4 index 8d30a06..be6cc69 100644 --- a/info/texinfo.info-4 +++ b/info/texinfo.info-4 @@ -649,13 +649,13 @@ entry format, which saves the reader from having to type the file name. @end menu For example, to refer directly to the `Outlining' and `Rebinding' -nodes in the `Emacs Manual', you would write a menu like this: +nodes in the `XEmacs User's Manual', you would write a menu like this: @menu - * Outlining: (emacs)Outline Mode. The major mode for - editing outlines. - * Rebinding: (emacs)Rebinding. How to redefine the - meaning of a key. + * Outlining: (xemacs)Outline Mode. The major mode for + editing outlines. + * Rebinding: (xemacs)Rebinding. How to redefine the + meaning of a key. @end menu If you do not list the node name, but only name the file, then Info diff --git a/info/xemacs.info-10 b/info/xemacs.info-10 index ffebd79..0c68a6c 100644 --- a/info/xemacs.info-10 +++ b/info/xemacs.info-10 @@ -30,6 +30,579 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Specify Coding, Prev: Recognize Coding, Up: Mule + +Specifying a Coding System +========================== + + In cases where XEmacs does not automatically choose the right coding +system, you can use these commands to specify one: + +`C-x f CODING ' + Use coding system CODING for the visited file in the current + buffer. + +`C-x c CODING ' + Specify coding system CODING for the immediately following command. + +`C-x k CODING ' + Use coding system CODING for keyboard input. + +`C-x t CODING ' + Use coding system CODING for terminal output. + +`C-x p CODING ' + Use coding system CODING for subprocess input and output in the + current buffer. + + The command `C-x RET f' (`set-buffer-file-coding-system') specifies +the file coding system for the current buffer--in other words, which +coding system to use when saving or rereading the visited file. You +specify which coding system using the minibuffer. Since this command +applies to a file you have already visited, it affects only the way the +file is saved. + + Another way to specify the coding system for a file is when you visit +the file. First use the command `C-x c' +(`universal-coding-system-argument'); this command uses the minibuffer +to read a coding system name. After you exit the minibuffer, the +specified coding system is used for _the immediately following command_. + + So if the immediately following command is `C-x C-f', for example, +it reads the file using that coding system (and records the coding +system for when the file is saved). Or if the immediately following +command is `C-x C-w', it writes the file using that coding system. +Other file commands affected by a specified coding system include `C-x +C-i' and `C-x C-v', as well as the other-window variants of `C-x C-f'. + + In addition, if you run some file input commands with the precedent +`C-u', you can specify coding system to read from minibuffer. So if +the immediately following command is `C-x C-f', for example, it reads +the file using that coding system (and records the coding system for +when the file is saved). Other file commands affected by a specified +coding system include `C-x C-i' and `C-x C-v', as well as the +other-window variants of `C-x C-f'. + + The variable `default-buffer-file-coding-system' specifies the +choice of coding system to use when you create a new file. It applies +when you find a new file, and when you create a buffer and then save it +in a file. Selecting a language environment typically sets this +variable to a good choice of default coding system for that language +environment. + + The command `C-x t' (`set-terminal-coding-system') specifies +the coding system for terminal output. If you specify a character code +for terminal output, all characters output to the terminal are +translated into that coding system. + + This feature is useful for certain character-only terminals built to +support specific languages or character sets--for example, European +terminals that support one of the ISO Latin character sets. + + By default, output to the terminal is not translated at all. + + The command `C-x k' (`set-keyboard-coding-system') specifies +the coding system for keyboard input. Character-code translation of +keyboard input is useful for terminals with keys that send non-ASCII +graphic characters--for example, some terminals designed for ISO +Latin-1 or subsets of it. + + By default, keyboard input is not translated at all. + + There is a similarity between using a coding system translation for +keyboard input, and using an input method: both define sequences of +keyboard input that translate into single characters. However, input +methods are designed to be convenient for interactive use by humans, and +the sequences that are translated are typically sequences of ASCII +printing characters. Coding systems typically translate sequences of +non-graphic characters. + + The command `C-x p' (`set-buffer-process-coding-system') +specifies the coding system for input and output to a subprocess. This +command applies to the current buffer; normally, each subprocess has its +own buffer, and thus you can use this command to specify translation to +and from a particular subprocess by giving the command in the +corresponding buffer. + + By default, process input and output are not translated at all. + + The variable `file-name-coding-system' specifies a coding system to +use for encoding file names. If you set the variable to a coding +system name (as a Lisp symbol or a string), XEmacs encodes file names +using that coding system for all file operations. This makes it +possible to use non-Latin-1 characters in file names--or, at least, +those non-Latin-1 characters which the specified coding system can +encode. By default, this variable is `nil', which implies that you +cannot use non-Latin-1 characters in file names. + + +File: xemacs.info, Node: Major Modes, Next: Indentation, Prev: Mule, Up: Top + +Major Modes +*********** + + Emacs has many different "major modes", each of which customizes +Emacs for editing text of a particular sort. The major modes are +mutually exclusive; at any time, each buffer has one major mode. The +mode line normally contains the name of the current major mode in +parentheses. *Note Mode Line::. + + The least specialized major mode is called "Fundamental mode". This +mode has no mode-specific redefinitions or variable settings. Each +Emacs command behaves in its most general manner, and each option is in +its default state. For editing any specific type of text, such as Lisp +code or English text, you should switch to the appropriate major mode, +such as Lisp mode or Text mode. + + Selecting a major mode changes the meanings of a few keys to become +more specifically adapted to the language being edited. , , +and are changed frequently. In addition, commands which handle +comments use the mode to determine how to delimit comments. Many major +modes redefine the syntactical properties of characters appearing in +the buffer. *Note Syntax::. + + The major modes fall into three major groups. Lisp mode (which has +several variants), C mode, and Muddle mode are for specific programming +languages. Text mode, Nroff mode, TeX mode, and Outline mode are for +editing English text. The remaining major modes are not intended for +use on users' files; they are used in buffers created by Emacs for +specific purposes and include Dired mode for buffers made by Dired +(*note Dired::), Mail mode for buffers made by `C-x m' (*note Sending +Mail::), and Shell mode for buffers used for communicating with an +inferior shell process (*note Interactive Shell::). + + Most programming language major modes specify that only blank lines +separate paragraphs. This is so that the paragraph commands remain +useful. *Note Paragraphs::. They also cause Auto Fill mode to use the +definition of to indent the new lines it creates. This is +because most lines in a program are usually indented. *Note +Indentation::. + +* Menu: + +* Choosing Modes:: How major modes are specified or chosen. + + +File: xemacs.info, Node: Choosing Modes, Prev: Major Modes, Up: Major Modes + +Choosing Major Modes +==================== + + You can select a major mode explicitly for the current buffer, but +most of the time Emacs determines which mode to use based on the file +name or some text in the file. + + Use a `M-x' command to explicitly select a new major mode. Add +`-mode' to the name of a major mode to get the name of a command to +select that mode. For example, to enter Lisp mode, execute `M-x +lisp-mode'. + + When you visit a file, Emacs usually chooses the right major mode +based on the file's name. For example, files whose names end in `.c' +are edited in C mode. The variable `auto-mode-alist' controls the +correspondence between file names and major mode. Its value is a list +in which each element has the form: + + (REGEXP . MODE-FUNCTION) + +For example, one element normally found in the list has the form +`("\\.c$" . c-mode)'. It is responsible for selecting C mode for files +whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to +include a `\' in the string, which is needed to suppress the special +meaning of `.' in regexps.) The only practical way to change this +variable is with Lisp code. + + You can specify which major mode should be used for editing a certain +file by a special sort of text in the first non-blank line of the file. +The mode name should appear in this line both preceded and followed by +`-*-'. Other text may appear on the line as well. For example, + + ;-*-Lisp-*- + +tells Emacs to use Lisp mode. Note how the semicolon is used to make +Lisp treat this line as a comment. Such an explicit specification +overrides any default mode based on the file name. + + Another format of mode specification is: + + -*-Mode: MODENAME;-*- + +which allows other things besides the major mode name to be specified. +However, Emacs does not look for anything except the mode name. + + The major mode can also be specified in a local variables list. +*Note File Variables::. + + When you visit a file that does not specify a major mode to use, or +when you create a new buffer with `C-x b', Emacs uses the major mode +specified by the variable `default-major-mode'. Normally this value is +the symbol `fundamental-mode', which specifies Fundamental mode. If +`default-major-mode' is `nil', the major mode is taken from the +previously selected buffer. + + +File: xemacs.info, Node: Indentation, Next: Text, Prev: Major Modes, Up: Top + +Indentation +*********** + +`' + Indent current line "appropriately" in a mode-dependent fashion. + +`' + Perform followed by (`newline-and-indent'). + +`M-^' + Merge two lines (`delete-indentation'). This would cancel out the + effect of . + +`C-M-o' + Split line at point; text on the line after point becomes a new + line indented to the same column that it now starts in + (`split-line'). + +`M-m' + Move (forward or back) to the first non-blank character on the + current line (`back-to-indentation'). + +`C-M-\' + Indent several lines to same column (`indent-region'). + +`C-x ' + Shift block of lines rigidly right or left (`indent-rigidly'). + +`M-i' + Indent from point to the next prespecified tab stop column + (`tab-to-tab-stop'). + +`M-x indent-relative' + Indent from point to under an indentation point in the previous + line. + + Most programming languages have some indentation convention. For +Lisp code, lines are indented according to their nesting in +parentheses. The same general idea is used for C code, though details +differ. + + Use the command to indent a line whatever the language. Each +major mode defines this command to perform indentation appropriate for +the particular language. In Lisp mode, aligns a line according +to its depth in parentheses. No matter where in the line you are when +you type , it aligns the line as a whole. In C mode, +implements a subtle and sophisticated indentation style that knows +about many aspects of C syntax. + + In Text mode, runs the command `tab-to-tab-stop', which +indents to the next tab stop column. You can set the tab stops with +`M-x edit-tab-stops'. + +* 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. + + +File: xemacs.info, Node: Indentation Commands, Next: Tab Stops, Prev: Indentation, Up: Indentation + +Indentation Commands and Techniques +=================================== + + If you just want to insert a tab character in the buffer, you can +type `C-q '. + + To move over the indentation on a line, type `Meta-m' +(`back-to-indentation'). This command, given anywhere on a line, +positions point at the first non-blank character on the line. + + To insert an indented line before the current line, type `C-a C-o +'. To make an indented line after the current line, use `C-e +'. + + `C-M-o' (`split-line') moves the text from point to the end of the +line vertically down, so that the current line becomes two lines. +`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, `C-M-o' resembles `C-o'. + + To join two lines cleanly, use the `Meta-^' (`delete-indentation') +command to delete the indentation at the front of the current line, and +the line boundary as well. Empty spaces are replaced by a single +space, or by no space if at the beginning of a line, before a close +parenthesis, or after an open parenthesis. To delete just the +indentation of a line, go to the beginning of the line and use `Meta-\' +(`delete-horizontal-space'), which deletes all spaces and tabs around +the cursor. + + There are also commands for changing the indentation of several +lines at once. `Control-Meta-\' (`indent-region') gives each line which +begins in the region the "usual" indentation by invoking at the +beginning of the line. A numeric argument specifies the column to +indent to. Each line is shifted left or right so that its first +non-blank character appears in that column. `C-x ' +(`indent-rigidly') moves all 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. + + `M-x indent-relative' indents at point based on the previous line +(actually, the last non-empty line.) It inserts whitespace at point, +moving point, until it is underneath an 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, the whitespace before point is +deleted and the first indentation point then applicable is used. If no +indentation point is applicable even then, `tab-to-tab-stop' is run +(see next section). + + `indent-relative' is the definition of in Indented Text mode. +*Note Text::. + + +File: xemacs.info, Node: Tab Stops, Next: Just Spaces, Prev: Indentation Commands, Up: Indentation + +Tab Stops +========= + + For typing in tables, you can use Text mode's definition of , +`tab-to-tab-stop'. This command inserts indentation before point, +enough to reach the next tab stop column. Even if you are not in Text +mode, this function is associated with `M-i' anyway. + + You can arbitrarily set the tab stops used by `M-i'. They are +stored as a list of column-numbers in increasing order in the variable +`tab-stop-list'. + + The convenient way to set the tab stops is using `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 `C-c C-c' to make those new +tab stops take effect. In the tab stop buffer, `C-c C-c' runs the +function `edit-tab-stops-note-changes' rather than the default +`save-buffer'. `edit-tab-stops' records which buffer was current when +you invoked it, and stores the tab stops in that buffer. Normally all +buffers share the same tab stops and changing them in one buffer +affects all. If you make `tab-stop-list' local in one buffer +`edit-tab-stops' in that buffer edits only the local settings. + + Below is the text representing ordinary tab stops every eight +columns: + + : : : : : : + 0 1 2 3 4 + 0123456789012345678901234567890123456789012345678 + To install changes, type C-c C-c + + The first line contains a colon at each tab stop. The remaining +lines help you see where the colons are and tell you what to do. + + Note that the tab stops that control `tab-to-tab-stop' have nothing +to do with displaying tab characters in the buffer. *Note Display +Vars::, for more information on that. + + +File: xemacs.info, Node: Just Spaces, Prev: Tab Stops, Up: Indentation + +Tabs vs. Spaces +=============== + + 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 `indent-tabs-mode' to `nil'. This is a per-buffer variable; +altering the variable affects only the current buffer, but there is a +default value which you can change as well. *Note Locals::. + + There are also commands to convert tabs to spaces or vice versa, +always preserving the columns of all non-blank text. `M-x tabify' +scans the region for sequences of spaces, and converts sequences of at +least three spaces to tabs if that is possible without changing +indentation. `M-x untabify' changes all tabs in the region to +corresponding numbers of spaces. + + +File: xemacs.info, Node: Text, Next: Programs, Prev: Indentation, Up: Top + +Commands for Human Languages +**************************** + + The term "text" has two widespread meanings in our area of the +computer field. One is data that is a sequence of characters. In this +sense of the word any file that you edit with Emacs is text. The other +meaning is more restrictive: a sequence of characters in a human +language for humans to read (possibly after processing by a text +formatter), as opposed to a program or commands for a program. + + Human languages have syntactic and stylistic conventions that editor +commands should support or use to advantage: conventions involving +words, sentences, paragraphs, and capital letters. This chapter +describes Emacs commands for all these things. There are also commands +for "filling", or rearranging paragraphs into lines of approximately +equal length. The commands for moving over and killing words, +sentences, and paragraphs, while intended primarily for editing text, +are also often useful for editing programs. + + Emacs has several major modes for editing human language text. If a +file contains plain text, use Text mode, which customizes Emacs in +small ways for the syntactic conventions of text. For text which +contains embedded commands for text formatters, Emacs has other major +modes, each for a particular text formatter. Thus, for input to TeX, +you can use TeX mode; for input to nroff, Nroff mode. + +* Menu: + +* Text Mode:: The major modes for editing text files. +* Nroff Mode:: The major mode for editing input to the formatter nroff. +* TeX Mode:: The major modes for editing input to the formatter TeX. +* Outline Mode:: The major mode for editing outlines. +* Words:: Moving over and killing words. +* Sentences:: Moving over and killing sentences. +* Paragraphs:: Moving over paragraphs. +* Pages:: Moving over pages. +* Filling:: Filling or justifying text +* Case:: Changing the case of text + + +File: xemacs.info, Node: Text Mode, Next: Words, Prev: Text, Up: Text + +Text Mode +========= + + You should use Text mode--rather than Fundamental or Lisp mode--to +edit files of text in a human language. Invoke `M-x text-mode' to +enter Text mode. In Text mode, runs the function +`tab-to-tab-stop', which allows you to use arbitrary tab stops set with +`M-x edit-tab-stops' (*note Tab Stops::). Features concerned with +comments in programs are turned off unless they are explicitly invoked. +The syntax table is changed so that periods are not considered part of a +word, while apostrophes, backspaces and underlines are. + + A similar variant mode is Indented Text mode, intended for editing +text in which most lines are indented. This mode defines to run +`indent-relative' (*note Indentation::), and makes Auto Fill indent the +lines it creates. As a result, a line made by Auto Filling, or by +, is normally indented just like the previous line. Use `M-x +indented-text-mode' to select this mode. + + Entering Text mode or Indented Text mode calls the value of the +variable `text-mode-hook' with no arguments, if that value exists and +is not `nil'. This value is also called when modes related to Text +mode are entered; this includes Nroff mode, TeX mode, Outline mode, and +Mail mode. Your hook can look at the value of `major-mode' to see +which of these modes is actually being entered. + + Two modes similar to Text mode are of use for editing text that is to +be passed through a text formatter before achieving its final readable +form. + +* Menu: + +* Nroff Mode:: The major mode for editing input to the formatter nroff. +* TeX Mode:: The major modes for editing input to the formatter TeX. + + + Another similar mode is used for editing outlines. It allows you +to view the text at various levels of detail. You can view either +the outline headings alone or both headings and text; you can also +hide some of the headings at lower levels from view to make the high +level structure more visible. + + +* Outline Mode:: The major mode for editing outlines. + + +File: xemacs.info, Node: Nroff Mode, Next: TeX Mode, Prev: Text Mode, Up: Text Mode + +Nroff Mode +---------- + + Nroff mode is a mode like Text mode but modified to handle nroff +commands present in the text. Invoke `M-x nroff-mode' to enter this +mode. Nroff mode differs from Text mode in only a few ways. All nroff +command lines are considered paragraph separators, so that filling never +garbles the nroff commands. Pages are separated by `.bp' commands. +Comments start with backslash-doublequote. There are also three special +commands that are not available in Text mode: + +`M-n' + Move to the beginning of the next line that isn't an nroff command + (`forward-text-line'). An argument is a repeat count. + +`M-p' + Like `M-n' but move up (`backward-text-line'). + +`M-?' + Prints in the echo area the number of text lines (lines that are + not nroff commands) in the region (`count-text-lines'). + + The other feature of Nroff mode is Electric Nroff newline mode. +This is a minor mode that you can turn on or off with `M-x +electric-nroff-mode' (*note Minor Modes::). When the mode is on and +you use to end a line containing an nroff command that opens a +kind of grouping, Emacs automatically inserts the matching nroff +command to close that grouping on the following line. For example, if +you are at the beginning of a line and type `.(b ', the matching +command `.)b' will be inserted on a new line following point. + + Entering Nroff mode calls the value of the variable `text-mode-hook' +with no arguments, if that value exists and is not `nil'; then it does +the same with the variable `nroff-mode-hook'. + + +File: xemacs.info, Node: TeX Mode, Next: Outline Mode, Prev: Nroff Mode, Up: Text Mode + +TeX Mode +-------- + + TeX is a powerful text formatter written by Donald Knuth; like GNU +Emacs, it is free. LaTeX is a simplified input format for TeX, +implemented by TeX macros. It is part of TeX. + + Emacs has a special TeX mode for editing TeX input files. It +provides facilities for checking the balance of delimiters and for +invoking TeX on all or part of the file. + + TeX mode has two variants, Plain TeX mode and LaTeX mode, which are +two distinct major modes that differ only slightly. These modes are +designed for editing the two different input formats. The command `M-x +tex-mode' looks at the contents of a buffer to determine whether it +appears to be LaTeX input or not; it then selects the appropriate mode. +If it can't tell which is right (e.g., the buffer is empty), the +variable `tex-default-mode' controls which mode is used. + + The commands `M-x plain-tex-mode' and `M-x latex-mode' explicitly +select one of the variants of TeX mode. Use these commands when `M-x +tex-mode' does not guess right. + +* Menu: + +* Editing: TeX Editing. Special commands for editing in TeX mode. +* Printing: TeX Print. Commands for printing part of a file with TeX. + + TeX for Unix systems can be obtained from the University of +Washington for a distribution fee. + + To order a full distribution, send $140.00 for a 1/2 inch 9-track +tape, $165.00 for two 4-track 1/4 inch cartridge tapes (foreign sites +$150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover the extra +postage) payable to the University of Washington to: + + The Director + Northwest Computer Support Group, DW-10 + University of Washington + Seattle, Washington 98195 + +Purchase orders are acceptable, but there is an extra charge of $10.00 +to pay for processing charges. (The total cost comes to $150 for +domestic sites, $175 for foreign sites). + + The normal distribution is a tar tape, blocked 20, 1600 bpi, on an +industry standard 2400 foot half-inch reel. The physical format for +the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track +serpentine recording for the SUN. Also, SystemV tapes can be written +in cpio format, blocked 5120 bytes, ASCII headers. + + File: xemacs.info, Node: TeX Editing, Next: TeX Print, Prev: TeX Mode, Up: TeX Mode TeX Editing Commands @@ -584,597 +1157,3 @@ contained in it must match both regexps. For example, normally The default values of these variables recognize the usual separator for pages. - -File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text - -Pages -===== - - Files are often thought of as divided into "pages" by the "formfeed" -character (ASCII Control-L, octal code 014). For example, if a file is -printed on a line printer, each "page" of the file starts on a new page -of paper. Emacs treats a page-separator character just like any other -character. It can be inserted with `C-q C-l' or deleted with . -You are free to paginate your file or not. However, since pages are -often meaningful divisions of the file, commands are provided to move -over them and operate on them. - -`C-x [' - Move point to previous page boundary (`backward-page'). - -`C-x ]' - Move point to next page boundary (`forward-page'). - -`C-x C-p' - Put point and mark around this page (or another page) - (`mark-page'). - -`C-x l' - Count the lines in this page (`count-lines-page'). - - The `C-x [' (`backward-page') command moves point to immediately -after the previous page delimiter. If point is already right after a -page delimiter, the command skips that one and stops at the previous -one. A numeric argument serves as a repeat count. The `C-x ]' -(`forward-page') command moves forward past the next page delimiter. - - The `C-x C-p' command (`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). You can follow this command by `C-w' to -kill a page you want to move elsewhere. If you insert the page after a -page delimiter, at a place where `C-x ]' or `C-x [' would take you, the -page will be properly delimited before and after once again. - - A numeric argument to `C-x C-p' is used to specify which page to go -to, relative to the current one. Zero means the current page. One -means the next page, and -1 means the previous one. - - The `C-x l' command (`count-lines-page') can help you decide where -to break a page in two. It prints the total number of lines in the -current page in the echo area, then divides the lines into those -preceding the current line and those following it, for example - - Page has 96 (72+25) lines - -Notice that the sum is off by one; this is correct if point is not at -the beginning of a line. - - The variable `page-delimiter' should have as its value a regexp that -matches the beginning of a line that separates pages. This defines -where pages begin. The normal value of this variable is `"^\f"', which -matches a formfeed character at the beginning of a line. - - -File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text - -Filling Text -============ - - If you use Auto Fill mode, Emacs "fills" text (breaks it up into -lines that fit in a specified width) as you insert it. When you alter -existing text it is often no longer be properly filled afterwards and -you can use explicit commands for filling. - -* Menu: - -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling when every line is indented or in a comment, etc. - - -File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling - -Auto Fill Mode --------------- - - "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 or . - -`M-x auto-fill-mode' - Enable or disable Auto Fill mode. - -`' -`' - In Auto Fill mode, break lines when appropriate. - - `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 the command always turns -Auto Fill mode on, and with a negative argument it always turns it off. -The presence of the word `Fill' in the mode line, inside the -parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode -is a minor mode; you can turn it on or off for each buffer individually. -*Note Minor Modes::. - - In Auto Fill mode, lines are broken automatically at spaces when -they get longer than desired. Line breaking and rearrangement takes -place only when you type or . To insert a space or newline -without permitting line-breaking, type `C-q ' or `C-q ' -(recall that a newline is really a linefeed). `C-o' inserts a newline -without line breaking. - - Auto Fill mode works well with Lisp mode: when it makes a new line in -Lisp mode, it indents that line with . If a line ending in a Lisp -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 `comment-multi-line' controls the -choice (*note Comments::). - - Auto Fill mode does not refill entire paragraphs. It can break -lines but cannot merge lines. 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 using an explicit fill -commands. - - Many users like Auto Fill mode and want to use it in all text files. -The section on init files explains how you can arrange this permanently -for yourself. *Note Init File::. - - -File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling - -Explicit Fill Commands ----------------------- - -`M-q' - Fill current paragraph (`fill-paragraph'). - -`M-g' - Fill each paragraph in the region (`fill-region'). - -`C-x f' - Set the fill column (`set-fill-column'). - -`M-x fill-region-as-paragraph' - Fill the region, considering it as one paragraph. - -`M-s' - Center a line. - - To refill a paragraph, use the command `Meta-q' (`fill-paragraph'). -It causes the paragraph containing point, or the one after point if -point is between paragraphs, to be refilled. All line breaks are -removed, and new ones are inserted where necessary. `M-q' can be -undone with `C-_'. *Note Undo::. - - To refill many paragraphs, use `M-g' (`fill-region'), which divides -the region into paragraphs and fills each of them. - - `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding -paragraph boundaries (*note Paragraphs::). For more control, you can -use `M-x fill-region-as-paragraph', which refills everything between -point and mark. This command recognizes only blank lines as paragraph -separators. - - A numeric argument to `M-g' or `M-q' causes it to "justify" the text -as well as filling it. Extra spaces are inserted to make the right -margin line up exactly at the fill column. To remove the extra spaces, -use `M-q' or `M-g' with no argument. - - The variable `auto-fill-inhibit-regexp' takes as a value a regexp to -match lines that should not be auto-filled. - - The command `Meta-s' (`center-line') centers the current line within -the current fill column. With an argument, it centers several lines -individually and moves past them. - - The maximum line width for filling is in the variable `fill-column'. -Altering the value of `fill-column' makes it local to the current -buffer; until then, the default value--initially 70--is in effect. -*Note Locals::. - - The easiest way to set `fill-column' is to use the command `C-x f' -(`set-fill-column'). With no argument, it sets `fill-column' to the -current horizontal position of point. With a numeric argument, it uses -that number as the new fill column. - - -File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling - -The 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), use the -"fill prefix" feature. The fill prefix is a string which is not -included in filling. Emacs expects every line to start with a fill -prefix. - -`C-x .' - Set the fill prefix (`set-fill-prefix'). - -`M-q' - Fill a paragraph using current fill prefix (`fill-paragraph'). - -`M-x fill-individual-paragraphs' - Fill the region, considering each change of indentation as - starting a new paragraph. - - To specify a fill prefix, move to a line that starts with the desired -prefix, put point at the end of the prefix, and give the command -`C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn -off the fill prefix, specify an empty prefix: type `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 before filling and insert it on each line after -filling. Auto Fill mode also inserts the fill prefix inserted on new -lines it creates. Lines that do not start with the fill prefix are -considered to start paragraphs, both in `M-q' and the paragraph -commands; this is just right if you are using paragraphs with hanging -indentation (every line indented except the first one). Lines which are -blank or indented once the prefix is removed also separate or start -paragraphs; this is what you want if you are writing multi-paragraph -comments with a comment delimiter on each line. - - The fill prefix is stored in the variable `fill-prefix'. Its value -is a string, or `nil' when there is no fill prefix. This is a -per-buffer variable; altering the variable affects only the current -buffer, but there is a default value which you can change as well. -*Note Locals::. - - Another way to use fill prefixes is through `M-x -fill-individual-paragraphs'. This function divides the region into -groups of consecutive lines with the same amount and kind of -indentation and fills each group as a paragraph, using its indentation -as a fill prefix. - - -File: xemacs.info, Node: Case, Prev: Filling, Up: Text - -Case Conversion Commands -======================== - - Emacs has commands for converting either a single word or any -arbitrary range of text to upper case or to lower case. - -`M-l' - Convert following word to lower case (`downcase-word'). - -`M-u' - Convert following word to upper case (`upcase-word'). - -`M-c' - Capitalize the following word (`capitalize-word'). - -`C-x C-l' - Convert region to lower case (`downcase-region'). - -`C-x C-u' - Convert region to upper case (`upcase-region'). - - The word conversion commands are used most frequently. `Meta-l' -(`downcase-word') converts the word after point to lower case, moving -past it. Thus, repeating `Meta-l' converts successive words. `Meta-u' -(`upcase-word') converts to all capitals instead, while `Meta-c' -(`capitalize-word') puts the first letter of the word into upper case -and the rest into lower case. The word conversion 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: you can move through the text using `M-l', `M-u', or `M-c' -on each word as appropriate, occasionally using `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. This is convenient when you have just typed a word in the wrong -case: you can give the case conversion command and continue typing. - - If a word case conversion command is given in the middle of a word, -it applies only to the part of the word which follows point. This is -just like what `Meta-d' (`kill-word') does. With a negative argument, -case conversion applies only to the part of the word before point. - - The other case conversion commands are `C-x C-u' (`upcase-region') -and `C-x C-l' (`downcase-region'), which convert everything between -point and mark to the specified case. Point and mark do not move. - - -File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top - -Editing Programs -**************** - - Emacs has many commands designed to understand the syntax of -programming languages such as Lisp and C. These commands can: - - * Move over or kill balanced expressions or "sexps" (*note Lists::). - - * Move over or mark top-level balanced expressions ("defuns", in - Lisp; functions, in C). - - * Show how parentheses balance (*note Matching::). - - * Insert, kill, or align comments (*note Comments::). - - * Follow the usual indentation conventions of the language (*note - Grinding::). - - The commands available for words, sentences, and paragraphs are -useful in editing code even though their canonical application is for -editing human language text. Most symbols contain words (*note -Words::); sentences can be found in strings and comments (*note -Sentences::). Paragraphs per se are not present in code, but the -paragraph commands are useful anyway, because Lisp mode and C mode -define paragraphs to begin and end at blank lines (*note Paragraphs::). -Judicious use of blank lines to make the program clearer also provides -interesting chunks of text for the paragraph commands to work on. - - The selective display feature is useful for looking at the overall -structure of a function (*note Selective Display::). This feature -causes only the lines that are indented less than a specified amount to -appear on the screen. - -* Menu: - -* Program Modes:: Major modes for editing programs. -* Lists:: Expressions with balanced parentheses. - There are editing commands to operate on them. -* Defuns:: Each program is made up of separate functions. - There are editing commands to operate on them. -* Grinding:: Adjusting indentation to show the nesting. -* Matching:: Insertion of a close-delimiter flashes matching open. -* Comments:: Inserting, filling and aligning comments. -* Balanced Editing:: Inserting two matching parentheses at once, etc. -* Lisp Completion:: Completion on symbol names in Lisp code. -* Documentation:: Getting documentation of functions you plan to call. -* Change Log:: Maintaining a change history for your program. -* Tags:: Go direct to any function in your program in one - command. Tags remembers which file it is in. -* Fortran:: Fortran mode and its special features. -* Asm Mode:: Asm mode and its special features. - - -File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs - -Major Modes for Programming Languages -===================================== - - Emacs has several major modes for the programming languages Lisp, -Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major -mode should be implemented for each programming language you might want -to edit with Emacs; but often the mode for one language can serve for -other syntactically similar languages. The language modes that exist -are those that someone decided to take the trouble to write. - - There are several variants of Lisp mode, which differ in the way they -interface to Lisp execution. *Note Lisp Modes::. - - Each of the programming language modes defines the key to run -an indentation function that knows the indentation conventions of that -language and updates the current line's indentation accordingly. For -example, in C mode is bound to `c-indent-line'. is -normally defined to do followed by ; thus it, too, indents -in a mode-specific fashion. - - In most programming languages, indentation is likely to vary from -line to line. So the major modes for those languages rebind to -treat a tab as if it were the equivalent number of spaces (using the -command `backward-delete-char-untabify'). This makes it possible to -rub out indentation one column at a time without worrying whether it is -made up of spaces or tabs. In these modes, use `C-b C-d' to delete a -tab character before point. - - Programming language modes define paragraphs to be separated only by -blank lines, so that the paragraph commands remain useful. Auto Fill -mode, if enabled in a programming language major mode, indents the new -lines which it creates. - - Turning on a major mode calls a user-supplied function called the -"mode hook", which is the value of a Lisp variable. For example, -turning on C mode calls the value of the variable `c-mode-hook' if that -value exists and is non-`nil'. Mode hook variables for other -programming language modes include `lisp-mode-hook', -`emacs-lisp-mode-hook', `lisp-interaction-mode-hook', -`scheme-mode-hook', and `muddle-mode-hook'. The mode hook function -receives no arguments. - - -File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs - -Lists and Sexps -=============== - - By convention, Emacs keys for dealing with balanced expressions are -usually `Control-Meta-' characters. They tend to be analogous in -function to their `Control-' and `Meta-' equivalents. These commands -are usually thought of as pertaining to expressions in programming -languages, but can be useful with any language in which some sort of -parentheses exist (including English). - - The commands fall into two classes. Some commands deal only with -"lists" (parenthetical groupings). They see nothing except -parentheses, brackets, braces (depending on what must balance in the -language you are working with), and escape characters that might be used -to quote those. - - The other commands deal with expressions or "sexps". The word `sexp' -is derived from "s-expression", the term for a symbolic expression in -Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It -refers to an expression in the language your program is written in. -Each programming language has its own major mode, which customizes the -syntax tables so that expressions in that language count as sexps. - - Sexps typically include symbols, numbers, and string constants, as -well as anything contained in parentheses, brackets, or braces. - - In languages that use prefix and infix operators, such as C, it is -not possible for all expressions to be sexps. For example, C mode does -not recognize `foo + bar' as an sexp, even though it is a C expression; -it recognizes `foo' as one sexp and `bar' as another, with the `+' as -punctuation between them. This is a fundamental ambiguity: both `foo + -bar' and `foo' are legitimate choices for the sexp to move over if -point is at the `f'. Note that `(foo + bar)' is a sexp in C mode. - - Some languages have obscure forms of syntax for expressions that -nobody has bothered to make Emacs understand properly. - -`C-M-f' - Move forward over an sexp (`forward-sexp'). - -`C-M-b' - Move backward over an sexp (`backward-sexp'). - -`C-M-k' - Kill sexp forward (`kill-sexp'). - -`C-M-u' - Move up and backward in list structure (`backward-up-list'). - -`C-M-d' - Move down and forward in list structure (`down-list'). - -`C-M-n' - Move forward over a list (`forward-list'). - -`C-M-p' - Move backward over a list (`backward-list'). - -`C-M-t' - Transpose expressions (`transpose-sexps'). - -`C-M-@' - Put mark after following expression (`mark-sexp'). - - To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the -first significant character after point is an opening delimiter (`(' in -Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing -delimiter. If the character begins a symbol, string, or number, -`C-M-f' moves over that. If the character after point is a closing -delimiter, `C-M-f' just moves past it. (This last is not really moving -across an sexp; it is an exception which is included in the definition -of `C-M-f' because it is as useful a behavior as anyone can think of -for that situation.) - - The command `C-M-b' (`backward-sexp') moves backward over a sexp. -The detailed rules are like those above for `C-M-f', but with -directions reversed. If there are any prefix characters (single quote, -back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back -over them as well. - - `C-M-f' or `C-M-b' with an argument repeats that operation the -specified number of times; with a negative argument, it moves in the -opposite direction. - - In languages such as C where the comment-terminator can be -recognized, the sexp commands move across comments as if they were -whitespace. In Lisp and other languages where comments run until the -end of a line, it is very difficult to ignore comments when parsing -backwards; therefore, in such languages the sexp commands treat the -text of comments as if it were code. - - Killing an sexp at a time can be done with `C-M-k' (`kill-sexp'). -`C-M-k' kills the characters that `C-M-f' would move over. - - The "list commands", `C-M-n' (`forward-list') and `C-M-p' -(`backward-list'), move over lists like the sexp commands but skip over -any number of other kinds of sexps (symbols, strings, etc). In some -situations, these commands are useful because they usually ignore -comments, since the comments usually do not contain any lists. - - `C-M-n' and `C-M-p' stay at the same level in parentheses, when that -is possible. To move up one (or N) levels, use `C-M-u' -(`backward-up-list'). `C-M-u' moves backward up past one unmatched -opening delimiter. A positive argument serves as a repeat count; a -negative argument reverses direction of motion and also requests -repetition, so it moves forward and up one or more levels. - - To move down in list structure, use `C-M-d' (`down-list'). In Lisp -mode, where `(' is the only opening delimiter, this is nearly the same -as searching for a `('. An argument specifies the number of levels of -parentheses to go down. - - `C-M-t' (`transpose-sexps') drags the previous sexp across the next -one. An argument serves as a repeat count, and a negative argument -drags backwards (thus canceling out the effect of `C-M-t' with a -positive argument). An argument of zero, rather than doing nothing, -transposes the sexps ending after point and the mark. - - To make the region be the next sexp in the buffer, use `C-M-@' -(`mark-sexp') which sets the mark at the same place that `C-M-f' would -move to. `C-M-@' takes arguments like `C-M-f'. In particular, a -negative argument is useful for putting the mark at the beginning of -the previous sexp. - - The list and sexp commands' understanding of syntax is completely -controlled by the syntax table. Any character can, for example, be -declared to be an opening delimiter and act like an open parenthesis. -*Note Syntax::. - - -File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs - -Defuns -====== - - In Emacs, a parenthetical grouping at the top level in the buffer is -called a "defun". The name derives from the fact that most top-level -lists in Lisp are instances of the special form `defun', but Emacs -calls any top-level parenthetical grouping counts a defun regardless of -its contents or the programming language. For example, in C, the body -of a function definition is a defun. - -`C-M-a' - Move to beginning of current or preceding defun - (`beginning-of-defun'). - -`C-M-e' - Move to end of current or following defun (`end-of-defun'). - -`C-M-h' - Put region around whole current or following defun (`mark-defun'). - - The commands to move to the beginning and end of the current defun -are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun'). - - To operate on the current defun, use `C-M-h' (`mark-defun') which -puts point at the beginning and the mark at the end of the current or -next defun. This is the easiest way to prepare for moving the defun to -a different place. In C mode, `C-M-h' runs the function -`mark-c-function', which is almost the same as `mark-defun', but which -backs up over the argument declarations, function name, and returned -data type so that the entire C function is inside the region. - - To compile and evaluate the current defun, use `M-x compile-defun'. -This function prints the results in the minibuffer. If you include an -argument, it inserts the value in the current buffer after the defun. - - Emacs assumes that any open-parenthesis found in the leftmost column -is the start of a defun. Therefore, never put an open-parenthesis at -the left margin in a Lisp file unless it is the start of a top level -list. Never put an open-brace or other opening delimiter at the -beginning of a line of C code unless it starts the body of a function. -The most likely problem case is when you want an opening delimiter at -the start of a line inside a string. To avoid trouble, put an escape -character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects) -before the opening delimiter. It will not affect the contents of the -string. - - The original Emacs found defuns by moving upward a level of -parentheses until there were no more levels to go up. This required -scanning back to the beginning of the buffer for every function. To -speed this up, Emacs was changed to assume that any `(' (or other -character assigned the syntactic class of opening-delimiter) at the -left margin is the start of a defun. This heuristic is nearly always -right; however, it mandates the convention described above. - - -File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs - -Indentation for Programs -======================== - - The best way to keep a program properly indented ("ground") is to -use Emacs to re-indent it as you change the program. Emacs has commands -to indent properly either a single line, a specified number of lines, or -all of the lines inside a single parenthetical grouping. - -* Menu: - -* Basic Indent:: -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Choosing an indentation style for C code. - diff --git a/info/xemacs.info-11 b/info/xemacs.info-11 index b8daf71..8e0ab08 100644 --- a/info/xemacs.info-11 +++ b/info/xemacs.info-11 @@ -30,6 +30,600 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text + +Pages +===== + + Files are often thought of as divided into "pages" by the "formfeed" +character (ASCII Control-L, octal code 014). For example, if a file is +printed on a line printer, each "page" of the file starts on a new page +of paper. Emacs treats a page-separator character just like any other +character. It can be inserted with `C-q C-l' or deleted with . +You are free to paginate your file or not. However, since pages are +often meaningful divisions of the file, commands are provided to move +over them and operate on them. + +`C-x [' + Move point to previous page boundary (`backward-page'). + +`C-x ]' + Move point to next page boundary (`forward-page'). + +`C-x C-p' + Put point and mark around this page (or another page) + (`mark-page'). + +`C-x l' + Count the lines in this page (`count-lines-page'). + + The `C-x [' (`backward-page') command moves point to immediately +after the previous page delimiter. If point is already right after a +page delimiter, the command skips that one and stops at the previous +one. A numeric argument serves as a repeat count. The `C-x ]' +(`forward-page') command moves forward past the next page delimiter. + + The `C-x C-p' command (`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). You can follow this command by `C-w' to +kill a page you want to move elsewhere. If you insert the page after a +page delimiter, at a place where `C-x ]' or `C-x [' would take you, the +page will be properly delimited before and after once again. + + A numeric argument to `C-x C-p' is used to specify which page to go +to, relative to the current one. Zero means the current page. One +means the next page, and -1 means the previous one. + + The `C-x l' command (`count-lines-page') can help you decide where +to break a page in two. It prints the total number of lines in the +current page in the echo area, then divides the lines into those +preceding the current line and those following it, for example + + Page has 96 (72+25) lines + +Notice that the sum is off by one; this is correct if point is not at +the beginning of a line. + + The variable `page-delimiter' should have as its value a regexp that +matches the beginning of a line that separates pages. This defines +where pages begin. The normal value of this variable is `"^\f"', which +matches a formfeed character at the beginning of a line. + + +File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text + +Filling Text +============ + + If you use Auto Fill mode, Emacs "fills" text (breaks it up into +lines that fit in a specified width) as you insert it. When you alter +existing text it is often no longer be properly filled afterwards and +you can use explicit commands for filling. + +* Menu: + +* Auto Fill:: Auto Fill mode breaks long lines automatically. +* Fill Commands:: Commands to refill paragraphs and center lines. +* Fill Prefix:: Filling when every line is indented or in a comment, etc. + + +File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling + +Auto Fill Mode +-------------- + + "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 or . + +`M-x auto-fill-mode' + Enable or disable Auto Fill mode. + +`' +`' + In Auto Fill mode, break lines when appropriate. + + `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 the command always turns +Auto Fill mode on, and with a negative argument it always turns it off. +The presence of the word `Fill' in the mode line, inside the +parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode +is a minor mode; you can turn it on or off for each buffer individually. +*Note Minor Modes::. + + In Auto Fill mode, lines are broken automatically at spaces when +they get longer than desired. Line breaking and rearrangement takes +place only when you type or . To insert a space or newline +without permitting line-breaking, type `C-q ' or `C-q ' +(recall that a newline is really a linefeed). `C-o' inserts a newline +without line breaking. + + Auto Fill mode works well with Lisp mode: when it makes a new line in +Lisp mode, it indents that line with . If a line ending in a Lisp +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 `comment-multi-line' controls the +choice (*note Comments::). + + Auto Fill mode does not refill entire paragraphs. It can break +lines but cannot merge lines. 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 using an explicit fill +commands. + + Many users like Auto Fill mode and want to use it in all text files. +The section on init files explains how you can arrange this permanently +for yourself. *Note Init File::. + + +File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling + +Explicit Fill Commands +---------------------- + +`M-q' + Fill current paragraph (`fill-paragraph'). + +`M-g' + Fill each paragraph in the region (`fill-region'). + +`C-x f' + Set the fill column (`set-fill-column'). + +`M-x fill-region-as-paragraph' + Fill the region, considering it as one paragraph. + +`M-s' + Center a line. + + To refill a paragraph, use the command `Meta-q' (`fill-paragraph'). +It causes the paragraph containing point, or the one after point if +point is between paragraphs, to be refilled. All line breaks are +removed, and new ones are inserted where necessary. `M-q' can be +undone with `C-_'. *Note Undo::. + + To refill many paragraphs, use `M-g' (`fill-region'), which divides +the region into paragraphs and fills each of them. + + `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding +paragraph boundaries (*note Paragraphs::). For more control, you can +use `M-x fill-region-as-paragraph', which refills everything between +point and mark. This command recognizes only blank lines as paragraph +separators. + + A numeric argument to `M-g' or `M-q' causes it to "justify" the text +as well as filling it. Extra spaces are inserted to make the right +margin line up exactly at the fill column. To remove the extra spaces, +use `M-q' or `M-g' with no argument. + + The variable `auto-fill-inhibit-regexp' takes as a value a regexp to +match lines that should not be auto-filled. + + The command `Meta-s' (`center-line') centers the current line within +the current fill column. With an argument, it centers several lines +individually and moves past them. + + The maximum line width for filling is in the variable `fill-column'. +Altering the value of `fill-column' makes it local to the current +buffer; until then, the default value--initially 70--is in effect. +*Note Locals::. + + The easiest way to set `fill-column' is to use the command `C-x f' +(`set-fill-column'). With no argument, it sets `fill-column' to the +current horizontal position of point. With a numeric argument, it uses +that number as the new fill column. + + +File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling + +The 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), use the +"fill prefix" feature. The fill prefix is a string which is not +included in filling. Emacs expects every line to start with a fill +prefix. + +`C-x .' + Set the fill prefix (`set-fill-prefix'). + +`M-q' + Fill a paragraph using current fill prefix (`fill-paragraph'). + +`M-x fill-individual-paragraphs' + Fill the region, considering each change of indentation as + starting a new paragraph. + + To specify a fill prefix, move to a line that starts with the desired +prefix, put point at the end of the prefix, and give the command +`C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn +off the fill prefix, specify an empty prefix: type `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 before filling and insert it on each line after +filling. Auto Fill mode also inserts the fill prefix inserted on new +lines it creates. Lines that do not start with the fill prefix are +considered to start paragraphs, both in `M-q' and the paragraph +commands; this is just right if you are using paragraphs with hanging +indentation (every line indented except the first one). Lines which are +blank or indented once the prefix is removed also separate or start +paragraphs; this is what you want if you are writing multi-paragraph +comments with a comment delimiter on each line. + + The fill prefix is stored in the variable `fill-prefix'. Its value +is a string, or `nil' when there is no fill prefix. This is a +per-buffer variable; altering the variable affects only the current +buffer, but there is a default value which you can change as well. +*Note Locals::. + + Another way to use fill prefixes is through `M-x +fill-individual-paragraphs'. This function divides the region into +groups of consecutive lines with the same amount and kind of +indentation and fills each group as a paragraph, using its indentation +as a fill prefix. + + +File: xemacs.info, Node: Case, Prev: Filling, Up: Text + +Case Conversion Commands +======================== + + Emacs has commands for converting either a single word or any +arbitrary range of text to upper case or to lower case. + +`M-l' + Convert following word to lower case (`downcase-word'). + +`M-u' + Convert following word to upper case (`upcase-word'). + +`M-c' + Capitalize the following word (`capitalize-word'). + +`C-x C-l' + Convert region to lower case (`downcase-region'). + +`C-x C-u' + Convert region to upper case (`upcase-region'). + + The word conversion commands are used most frequently. `Meta-l' +(`downcase-word') converts the word after point to lower case, moving +past it. Thus, repeating `Meta-l' converts successive words. `Meta-u' +(`upcase-word') converts to all capitals instead, while `Meta-c' +(`capitalize-word') puts the first letter of the word into upper case +and the rest into lower case. The word conversion 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: you can move through the text using `M-l', `M-u', or `M-c' +on each word as appropriate, occasionally using `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. This is convenient when you have just typed a word in the wrong +case: you can give the case conversion command and continue typing. + + If a word case conversion command is given in the middle of a word, +it applies only to the part of the word which follows point. This is +just like what `Meta-d' (`kill-word') does. With a negative argument, +case conversion applies only to the part of the word before point. + + The other case conversion commands are `C-x C-u' (`upcase-region') +and `C-x C-l' (`downcase-region'), which convert everything between +point and mark to the specified case. Point and mark do not move. + + +File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top + +Editing Programs +**************** + + Emacs has many commands designed to understand the syntax of +programming languages such as Lisp and C. These commands can: + + * Move over or kill balanced expressions or "sexps" (*note Lists::). + + * Move over or mark top-level balanced expressions ("defuns", in + Lisp; functions, in C). + + * Show how parentheses balance (*note Matching::). + + * Insert, kill, or align comments (*note Comments::). + + * Follow the usual indentation conventions of the language (*note + Grinding::). + + The commands available for words, sentences, and paragraphs are +useful in editing code even though their canonical application is for +editing human language text. Most symbols contain words (*note +Words::); sentences can be found in strings and comments (*note +Sentences::). Paragraphs per se are not present in code, but the +paragraph commands are useful anyway, because Lisp mode and C mode +define paragraphs to begin and end at blank lines (*note Paragraphs::). +Judicious use of blank lines to make the program clearer also provides +interesting chunks of text for the paragraph commands to work on. + + The selective display feature is useful for looking at the overall +structure of a function (*note Selective Display::). This feature +causes only the lines that are indented less than a specified amount to +appear on the screen. + +* Menu: + +* Program Modes:: Major modes for editing programs. +* Lists:: Expressions with balanced parentheses. + There are editing commands to operate on them. +* Defuns:: Each program is made up of separate functions. + There are editing commands to operate on them. +* Grinding:: Adjusting indentation to show the nesting. +* Matching:: Insertion of a close-delimiter flashes matching open. +* Comments:: Inserting, filling and aligning comments. +* Balanced Editing:: Inserting two matching parentheses at once, etc. +* Lisp Completion:: Completion on symbol names in Lisp code. +* Documentation:: Getting documentation of functions you plan to call. +* Change Log:: Maintaining a change history for your program. +* Tags:: Go direct to any function in your program in one + command. Tags remembers which file it is in. +* Fortran:: Fortran mode and its special features. +* Asm Mode:: Asm mode and its special features. + + +File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs + +Major Modes for Programming Languages +===================================== + + Emacs has several major modes for the programming languages Lisp, +Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major +mode should be implemented for each programming language you might want +to edit with Emacs; but often the mode for one language can serve for +other syntactically similar languages. The language modes that exist +are those that someone decided to take the trouble to write. + + There are several variants of Lisp mode, which differ in the way they +interface to Lisp execution. *Note Lisp Modes::. + + Each of the programming language modes defines the key to run +an indentation function that knows the indentation conventions of that +language and updates the current line's indentation accordingly. For +example, in C mode is bound to `c-indent-line'. is +normally defined to do followed by ; thus it, too, indents +in a mode-specific fashion. + + In most programming languages, indentation is likely to vary from +line to line. So the major modes for those languages rebind to +treat a tab as if it were the equivalent number of spaces (using the +command `backward-delete-char-untabify'). This makes it possible to +rub out indentation one column at a time without worrying whether it is +made up of spaces or tabs. In these modes, use `C-b C-d' to delete a +tab character before point. + + Programming language modes define paragraphs to be separated only by +blank lines, so that the paragraph commands remain useful. Auto Fill +mode, if enabled in a programming language major mode, indents the new +lines which it creates. + + Turning on a major mode calls a user-supplied function called the +"mode hook", which is the value of a Lisp variable. For example, +turning on C mode calls the value of the variable `c-mode-hook' if that +value exists and is non-`nil'. Mode hook variables for other +programming language modes include `lisp-mode-hook', +`emacs-lisp-mode-hook', `lisp-interaction-mode-hook', +`scheme-mode-hook', and `muddle-mode-hook'. The mode hook function +receives no arguments. + + +File: xemacs.info, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs + +Lists and Sexps +=============== + + By convention, Emacs keys for dealing with balanced expressions are +usually `Control-Meta-' characters. They tend to be analogous in +function to their `Control-' and `Meta-' equivalents. These commands +are usually thought of as pertaining to expressions in programming +languages, but can be useful with any language in which some sort of +parentheses exist (including English). + + The commands fall into two classes. Some commands deal only with +"lists" (parenthetical groupings). They see nothing except +parentheses, brackets, braces (depending on what must balance in the +language you are working with), and escape characters that might be used +to quote those. + + The other commands deal with expressions or "sexps". The word `sexp' +is derived from "s-expression", the term for a symbolic expression in +Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It +refers to an expression in the language your program is written in. +Each programming language has its own major mode, which customizes the +syntax tables so that expressions in that language count as sexps. + + Sexps typically include symbols, numbers, and string constants, as +well as anything contained in parentheses, brackets, or braces. + + In languages that use prefix and infix operators, such as C, it is +not possible for all expressions to be sexps. For example, C mode does +not recognize `foo + bar' as an sexp, even though it is a C expression; +it recognizes `foo' as one sexp and `bar' as another, with the `+' as +punctuation between them. This is a fundamental ambiguity: both `foo + +bar' and `foo' are legitimate choices for the sexp to move over if +point is at the `f'. Note that `(foo + bar)' is a sexp in C mode. + + Some languages have obscure forms of syntax for expressions that +nobody has bothered to make Emacs understand properly. + +`C-M-f' + Move forward over an sexp (`forward-sexp'). + +`C-M-b' + Move backward over an sexp (`backward-sexp'). + +`C-M-k' + Kill sexp forward (`kill-sexp'). + +`C-M-u' + Move up and backward in list structure (`backward-up-list'). + +`C-M-d' + Move down and forward in list structure (`down-list'). + +`C-M-n' + Move forward over a list (`forward-list'). + +`C-M-p' + Move backward over a list (`backward-list'). + +`C-M-t' + Transpose expressions (`transpose-sexps'). + +`C-M-@' + Put mark after following expression (`mark-sexp'). + + To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the +first significant character after point is an opening delimiter (`(' in +Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing +delimiter. If the character begins a symbol, string, or number, +`C-M-f' moves over that. If the character after point is a closing +delimiter, `C-M-f' just moves past it. (This last is not really moving +across an sexp; it is an exception which is included in the definition +of `C-M-f' because it is as useful a behavior as anyone can think of +for that situation.) + + The command `C-M-b' (`backward-sexp') moves backward over a sexp. +The detailed rules are like those above for `C-M-f', but with +directions reversed. If there are any prefix characters (single quote, +back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back +over them as well. + + `C-M-f' or `C-M-b' with an argument repeats that operation the +specified number of times; with a negative argument, it moves in the +opposite direction. + + In languages such as C where the comment-terminator can be +recognized, the sexp commands move across comments as if they were +whitespace. In Lisp and other languages where comments run until the +end of a line, it is very difficult to ignore comments when parsing +backwards; therefore, in such languages the sexp commands treat the +text of comments as if it were code. + + Killing an sexp at a time can be done with `C-M-k' (`kill-sexp'). +`C-M-k' kills the characters that `C-M-f' would move over. + + The "list commands", `C-M-n' (`forward-list') and `C-M-p' +(`backward-list'), move over lists like the sexp commands but skip over +any number of other kinds of sexps (symbols, strings, etc). In some +situations, these commands are useful because they usually ignore +comments, since the comments usually do not contain any lists. + + `C-M-n' and `C-M-p' stay at the same level in parentheses, when that +is possible. To move up one (or N) levels, use `C-M-u' +(`backward-up-list'). `C-M-u' moves backward up past one unmatched +opening delimiter. A positive argument serves as a repeat count; a +negative argument reverses direction of motion and also requests +repetition, so it moves forward and up one or more levels. + + To move down in list structure, use `C-M-d' (`down-list'). In Lisp +mode, where `(' is the only opening delimiter, this is nearly the same +as searching for a `('. An argument specifies the number of levels of +parentheses to go down. + + `C-M-t' (`transpose-sexps') drags the previous sexp across the next +one. An argument serves as a repeat count, and a negative argument +drags backwards (thus canceling out the effect of `C-M-t' with a +positive argument). An argument of zero, rather than doing nothing, +transposes the sexps ending after point and the mark. + + To make the region be the next sexp in the buffer, use `C-M-@' +(`mark-sexp') which sets the mark at the same place that `C-M-f' would +move to. `C-M-@' takes arguments like `C-M-f'. In particular, a +negative argument is useful for putting the mark at the beginning of +the previous sexp. + + The list and sexp commands' understanding of syntax is completely +controlled by the syntax table. Any character can, for example, be +declared to be an opening delimiter and act like an open parenthesis. +*Note Syntax::. + + +File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs + +Defuns +====== + + In Emacs, a parenthetical grouping at the top level in the buffer is +called a "defun". The name derives from the fact that most top-level +lists in Lisp are instances of the special form `defun', but Emacs +calls any top-level parenthetical grouping counts a defun regardless of +its contents or the programming language. For example, in C, the body +of a function definition is a defun. + +`C-M-a' + Move to beginning of current or preceding defun + (`beginning-of-defun'). + +`C-M-e' + Move to end of current or following defun (`end-of-defun'). + +`C-M-h' + Put region around whole current or following defun (`mark-defun'). + + The commands to move to the beginning and end of the current defun +are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun'). + + To operate on the current defun, use `C-M-h' (`mark-defun') which +puts point at the beginning and the mark at the end of the current or +next defun. This is the easiest way to prepare for moving the defun to +a different place. In C mode, `C-M-h' runs the function +`mark-c-function', which is almost the same as `mark-defun', but which +backs up over the argument declarations, function name, and returned +data type so that the entire C function is inside the region. + + To compile and evaluate the current defun, use `M-x compile-defun'. +This function prints the results in the minibuffer. If you include an +argument, it inserts the value in the current buffer after the defun. + + Emacs assumes that any open-parenthesis found in the leftmost column +is the start of a defun. Therefore, never put an open-parenthesis at +the left margin in a Lisp file unless it is the start of a top level +list. Never put an open-brace or other opening delimiter at the +beginning of a line of C code unless it starts the body of a function. +The most likely problem case is when you want an opening delimiter at +the start of a line inside a string. To avoid trouble, put an escape +character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects) +before the opening delimiter. It will not affect the contents of the +string. + + The original Emacs found defuns by moving upward a level of +parentheses until there were no more levels to go up. This required +scanning back to the beginning of the buffer for every function. To +speed this up, Emacs was changed to assume that any `(' (or other +character assigned the syntactic class of opening-delimiter) at the +left margin is the start of a defun. This heuristic is nearly always +right; however, it mandates the convention described above. + + +File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs + +Indentation for Programs +======================== + + The best way to keep a program properly indented ("ground") is to +use Emacs to re-indent it as you change the program. Emacs has commands +to indent properly either a single line, a specified number of lines, or +all of the lines inside a single parenthetical grouping. + +* Menu: + +* Basic Indent:: +* Multi-line Indent:: Commands to reindent many lines at once. +* Lisp Indent:: Specifying how each Lisp function should be indented. +* C Indent:: Choosing an indentation style for C code. + + File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding Basic Program Indentation Commands @@ -577,543 +1171,3 @@ concatenates all the entries it finds. For example, the topic `termcap' finds the description of the termcap library from section 3, followed by the description of the termcap data base from section 5. - -File: xemacs.info, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs - -Change Logs -=========== - - The Emacs command `M-x add-change-log-entry' helps you keep a record -of when and why you have changed a program. It assumes that you have a -file in which you write a chronological sequence of entries describing -individual changes. The default is to store the change entries in a -file called `ChangeLog' in the same directory as the file you are -editing. The same `ChangeLog' file therefore records changes for all -the files in a directory. - - A change log entry starts with a header line that contains your name -and the current date. Except for these header lines, every line in the -change log starts with a tab. One entry can describe several changes; -each change starts with a line starting with a tab and a star. `M-x -add-change-log-entry' visits the change log file and creates a new entry -unless the most recent entry is for today's date and your name. In -either case, it adds a new line to start the description of another -change just after the header line of the entry. When `M-x -add-change-log-entry' is finished, all is prepared for you to edit in -the description of what you changed and how. You must then save the -change log file yourself. - - The change log file is always visited in Indented Text mode, which -means that and auto-filling indent each new line like the previous -line. This is convenient for entering the contents of an entry, which -must be indented. *Note Text Mode::. - - Here is an example of the formatting conventions used in the change -log for Emacs: - - Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep) - - * xdisp.c (try_window_id): - If C-k is done at end of next-to-last line, - this fn updates window_end_vpos and cannot leave - window_end_pos nonnegative (it is zero, in fact). - If display is preempted before lines are output, - this is inconsistent. Fix by setting - blank_end_of_window to nonzero. - - Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep) - - * cmds.c (Fnewline): - Call the auto fill hook if appropriate. - - * xdisp.c (try_window_id): - If point is found by compute_motion after xp, record that - permanently. If display_text_line sets point position wrong - (case where line is killed, point is at eob and that line is - not displayed), set it again in final compute_motion. - - -File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs - -Tags Tables -=========== - - A "tags table" is a description of how a multi-file program is -broken up into files. It lists the names of the component files and the -names and positions of the functions (or other named subunits) in each -file. Grouping the related files makes it possible to search or replace -through all the files with one command. Recording the function names -and positions makes possible the `M-.' command which finds the -definition of a function by looking up which of the files it is in. - - Tags tables are stored in files called "tags table files". The -conventional name for a tags table file is `TAGS'. - - Each entry in the tags table records the name of one tag, the name -of the file that the tag is defined in (implicitly), and the position -in that file of the tag's definition. - - Just what names from the described files are recorded in the tags -table depends on the programming language of the described file. They -normally include all functions and subroutines, and may also include -global variables, data types, and anything else convenient. Each name -recorded is called a "tag". - -* Menu: - -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with `etags'. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Listing and finding tags defined in a file. - - -File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Prev: Tags, Up: Tags - -Source File Tag Syntax ----------------------- - - Here is how tag syntax is defined for the most popular languages: - - * In C code, any C function or typedef is a tag, and so are - definitions of `struct', `union' and `enum'. You can tag function - declarations and external variables in addition to function - definitions by giving the `--declarations' option to `etags'. - `#define' macro definitions and `enum' constants are also tags, - unless you specify `--no-defines' when making the tags table. - Similarly, global variables are tags, unless you specify - `--no-globals'. Use of `--no-globals' and `--no-defines' can make - the tags table file much smaller. - - * In C++ code, in addition to all the tag constructs of C code, - member functions are also recognized, and optionally member - variables if you use the `--members' option. Tags for variables - and functions in classes are named `CLASS::VARIABLE' and - `CLASS::FUNCTION'. `operator' functions tags are named, for - example `operator+'. - - * In Java code, tags include all the constructs recognized in C++, - plus the `interface', `extends' and `implements' constructs. Tags - for variables and functions in classes are named `CLASS.VARIABLE' - and `CLASS.FUNCTION'. - - * In LaTeX text, the argument of any of the commands `\chapter', - `\section', `\subsection', `\subsubsection', `\eqno', `\label', - `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or - `\index', is a tag. - - Other commands can make tags as well, if you specify them in the - environment variable `TEXTAGS' before invoking `etags'. The value - of this environment variable should be a colon-separated list of - command names. For example, - - TEXTAGS="def:newcommand:newenvironment" - export TEXTAGS - - specifies (using Bourne shell syntax) that the commands `\def', - `\newcommand' and `\newenvironment' also define tags. - - * In Lisp code, any function defined with `defun', any variable - defined with `defvar' or `defconst', and in general the first - argument of any expression that starts with `(def' in column zero, - is a tag. - - * In Scheme code, tags include anything defined with `def' or with a - construct whose name starts with `def'. They also include - variables set with `set!' at top level in the file. - - Several other languages are also supported: - - * In Ada code, functions, procedures, packages, tasks, and types are - tags. Use the `--packages-only' option to create tags for packages - only. - - * In assembler code, labels appearing at the beginning of a line, - followed by a colon, are tags. - - * In Bison or Yacc input files, each rule defines as a tag the - nonterminal it constructs. The portions of the file that contain - C code are parsed as C code. - - * In Cobol code, tags are paragraph names; that is, any word - starting in column 8 and followed by a period. - - * In Erlang code, the tags are the functions, records, and macros - defined in the file. - - * In Fortran code, functions, subroutines and blockdata are tags. - - * In Objective C code, tags include Objective C definitions for - classes, class categories, methods, and protocols. - - * In Pascal code, the tags are the functions and procedures defined - in the file. - - * In Perl code, the tags are the procedures defined by the `sub', - `my' and `local' keywords. Use `--globals' if you want to tag - global variables. - - * In Postscript code, the tags are the functions. - - * In Prolog code, a tag name appears at the left margin. - - * In Python code, `def' or `class' at the beginning of a line - generate a tag. - - You can also generate tags based on regexp matching (*note Etags -Regexps::) to handle other formats and languages. - - -File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags - -Creating Tags Tables --------------------- - - The `etags' program is used to create a tags table file. It knows -the syntax of several languages, as described in *Note Tag Syntax::. -Here is how to run `etags': - - etags INPUTFILES... - -The `etags' program reads the specified files, and writes a tags table -named `TAGS' in the current working directory. You can intermix -compressed and plain text source file names. `etags' knows about the -most common compression formats, and does the right thing. So you can -compress all your source files and have `etags' look for compressed -versions of its file name arguments, if it does not find uncompressed -versions. Under MS-DOS, `etags' also looks for file names like -`mycode.cgz' if it is given `mycode.c' on the command line and -`mycode.c' does not exist. - - `etags' recognizes the language used in an input file based on its -file name and contents. You can specify the language with the -`--language=NAME' option, described below. - - If the tags table data become outdated due to changes in the files -described in the table, the way to update the tags table is the same -way it was made in the first place. It is not necessary to do this -often. - - If the tags table fails to record a tag, or records it for the wrong -file, then Emacs cannot possibly find its definition. However, if the -position recorded in the tags table becomes a little bit wrong (due to -some editing in the file that the tag definition is in), the only -consequence is a slight delay in finding the tag. Even if the stored -position is very wrong, Emacs will still find the tag, but it must -search the entire file for it. - - So you should update a tags table when you define new tags that you -want to have listed, or when you move tag definitions from one file to -another, or when changes become substantial. Normally there is no need -to update the tags table after each edit, or even every day. - - One tags table can effectively include another. Specify the included -tags file name with the `--include=FILE' option when creating the file -that is to include it. The latter file then acts as if it contained -all the files specified in the included file, as well as the files it -directly contains. - - If you specify the source files with relative file names when you run -`etags', the tags file will contain file names relative to the -directory where the tags file was initially written. This way, you can -move an entire directory tree containing both the tags file and the -source files, and the tags file will still refer correctly to the source -files. - - If you specify absolute file names as arguments to `etags', then the -tags file will contain absolute file names. This way, the tags file -will still refer to the same files even if you move it, as long as the -source files remain in the same place. Absolute file names start with -`/', or with `DEVICE:/' on MS-DOS and MS-Windows. - - When you want to make a tags table from a great number of files, you -may have problems listing them on the command line, because some systems -have a limit on its length. The simplest way to circumvent this limit -is to tell `etags' to read the file names from its standard input, by -typing a dash in place of the file names, like this: - - find . -name "*.[chCH]" -print | etags - - - Use the option `--language=NAME' to specify the language explicitly. -You can intermix these options with file names; each one applies to -the file names that follow it. Specify `--language=auto' to tell -`etags' to resume guessing the language from the file names and file -contents. Specify `--language=none' to turn off language-specific -processing entirely; then `etags' recognizes tags by regexp matching -alone (*note Etags Regexps::). - - `etags --help' prints the list of the languages `etags' knows, and -the file name rules for guessing the language. It also prints a list of -all the available `etags' options, together with a short explanation. - - -File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags - -Etags Regexps -------------- - - The `--regex' option provides a general way of recognizing tags -based on regexp matching. You can freely intermix it with file names. -Each `--regex' option adds to the preceding ones, and applies only to -the following files. The syntax is: - - --regex=/TAGREGEXP[/NAMEREGEXP]/ - -where TAGREGEXP is used to match the lines to tag. It is always -anchored, that is, it behaves as if preceded by `^'. If you want to -account for indentation, just match any initial number of blanks by -beginning your regular expression with `[ \t]*'. In the regular -expressions, `\' quotes the next character, and `\t' stands for the tab -character. Note that `etags' does not handle the other C escape -sequences for special characters. - - The syntax of regular expressions in `etags' is the same as in -Emacs, augmented with the "interval operator", which works as in `grep' -and `ed'. The syntax of an interval operator is `\{M,N\}', and its -meaning is to match the preceding expression at least M times and up to -N times. - - You should not match more characters with TAGREGEXP than that needed -to recognize what you want to tag. If the match is such that more -characters than needed are unavoidably matched by TAGREGEXP (as will -usually be the case), you should add a NAMEREGEXP, to pick out just the -tag. This will enable Emacs to find tags more accurately and to do -completion on tag names more reliably. You can find some examples -below. - - The option `--ignore-case-regex' (or `-c') is like `--regex', except -that the regular expression provided will be matched without regard to -case, which is appropriate for various programming languages. - - The `-R' option deletes all the regexps defined with `--regex' -options. It applies to the file names following it, as you can see -from the following example: - - etags --regex=/REG1/ voo.doo --regex=/REG2/ \ - bar.ber -R --lang=lisp los.er - -Here `etags' chooses the parsing language for `voo.doo' and `bar.ber' -according to their contents. `etags' also uses REG1 to recognize -additional tags in `voo.doo', and both REG1 and REG2 to recognize -additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no -regexp matching, to recognize tags in `los.er'. - - A regular expression can be bound to a given language, by prepending -it with `{lang}'. When you do this, `etags' will use the regular -expression only for files of that language. `etags --help' prints the -list of languages recognised by `etags'. The following example tags -the `DEFVAR' macros in the Emacs source files. `etags' applies this -regular expression to C files only: - - --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' - -This feature is particularly useful when storing a list of regular -expressions in a file. The following option syntax instructs `etags' -to read two files of regular expressions. The regular expressions -contained in the second file are matched without regard to case. - - --regex=@first-file --ignore-case-regex=@second-file - -A regex file contains one regular expressions per line. Empty lines, -and lines beginning with space or tab are ignored. When the first -character in a line is `@', `etags' assumes that the rest of the line -is the name of a file of regular expressions. This means that such -files can be nested. All the other lines are taken to be regular -expressions. For example, one can create a file called `emacs.tags' -with the following contents (the first line in the file is a comment): - - -- This is for GNU Emacs source files - {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ - -and then use it like this: - - etags --regex=@emacs.tags *.[ch] */*.[ch] - - Here are some more examples. The regexps are quoted to protect them -from shell interpretation. - - * Tag Octave files: - - etags --language=none \ - --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ - --regex='/###key \(.*\)/\1/' \ - --regex='/[ \t]*global[ \t].*/' \ - *.m - - Note that tags are not generated for scripts so that you have to - add a line by yourself of the form `###key ' if you - want to jump to it. - - * Tag Tcl files: - - etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl - - * Tag VHDL files: - - --language=none \ - --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ - --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ - \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' - - -File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags - -Selecting a Tags Table ----------------------- - - At any time Emacs has one "selected" tags table, and all the commands -for working with tags tables use the selected one. To select a tags -table, use the variable `tag-table-alist'. - - The value of `tag-table-alist' is a list that determines which -`TAGS' files should be active for a given buffer. This is not really -an association list, in that all elements are checked. The car of each -element of this list is a pattern against which the buffers file name -is compared; if it matches, then the cdr of the list should be the name -of the tags table to use. If more than one element of this list -matches the buffers file name, all of the associated tags tables are -used. Earlier ones are searched first. - - If the car of elements of this list are strings, they are treated as -regular-expressions against which the file is compared (like the -`auto-mode-alist'). If they are not strings, they are evaluated. If -they evaluate to non-`nil', the current buffer is considered to match. - - If the cdr of the elements of this list are strings, they are -assumed to name a tags file. If they name a directory, the string -`tags' is appended to them to get the file name. If they are not -strings, they are evaluated and must return an appropriate string. - - For example: - - (setq tag-table-alist - '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/") - ("\\.el$" . "/usr/local/emacs/src/") - ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/") - ("" . "/usr/local/emacs/src/") - )) - - The example defines the tags table alist in the following way: - - * Anything in the directory `/usr/src/public/perl/' should use the - `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'. - - * Files ending in `.el' should use the `TAGS' file - `/usr/local/emacs/src/TAGS'. - - * Anything in or below the directory `/jbw/gnu/' should use the - `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'. - - If you had a file called `/usr/jbw/foo.el', it would use both `TAGS' -files, -`/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in -that order), because it matches both patterns. - - If the buffer-local variable `buffer-tag-table' is set, it names a -tags table that is searched before all others when `find-tag' is -executed from this buffer. - - If there is a file called `TAGS' in the same directory as the file -in question, then that tags file will always be used as well (after the -`buffer-tag-table' but before the tables specified by this list). - - If the variable `tags-file-name' is set, the `TAGS' file it names -will apply to all buffers (for backwards compatibility.) It is searched -first. - - If the value of the variable `tags-always-build-completion-table' is -`t', the tags file will always be added to the completion table without -asking first, regardless of the size of the tags file. - - The function `M-x visit-tags-table', is largely made obsolete by the -variable `tag-table-alist', tells tags commands to use the tags table -file FILE first. The FILE should be the name of a file created with -the `etags' program. A directory name is also acceptable; it means the -file `TAGS' in that directory. The function only stores the file name -you provide in the variable `tags-file-name'. Emacs does not actually -read in the tags table contents until you try to use them. You can set -the variable explicitly instead of using `visit-tags-table'. The value -of the variable `tags-file-name' is the name of the tags table used by -all buffers. This is for backward compatibility, and is largely -supplanted by the variable `tag-table-alist'. - - -File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags - -Finding a Tag -------------- - - The most important thing that a tags table enables you to do is to -find the definition of a specific tag. - -`M-. TAG &OPTIONAL OTHER-WINDOW' - Find first definition of TAG (`find-tag'). - -`C-u M-.' - Find next alternate definition of last tag specified. - -`C-x 4 . TAG' - Find first definition of TAG, but display it in another window - (`find-tag-other-window'). - - `M-.' (`find-tag') is the command to find the definition of a -specified tag. It searches through the tags table for that tag, as a -string, then uses the tags table information to determine the file in -which the definition is used and the approximate character position of -the definition in the file. Then `find-tag' visits the file, moves -point to the approximate character position, and starts searching -ever-increasing distances away for the text that should appear at the -beginning of the definition. - - If an empty argument is given (by typing ), the sexp in the -buffer before or around point is used as the name of the tag to find. -*Note Lists::, for information on sexps. - - The argument to `find-tag' need not be the whole tag name; it can be -a substring of a tag name. However, there can be many tag names -containing the substring you specify. Since `find-tag' works by -searching the text of the tags table, it finds the first tag in the -table that the specified substring appears in. To find other tags that -match the substring, give `find-tag' a numeric argument, as in `C-u -M-.'. This does not read a tag name, but continues searching the tag -table's text for another tag containing the same substring last used. -If your keyboard has a real key, `M-0 M-.' is an easier -alternative to `C-u M-.'. - - If the optional second argument OTHER-WINDOW is non-`nil', it uses -another window to display the tag. Multiple active tags tables and -completion are supported. - - Variables of note include the following: - -`tag-table-alist' - Controls which tables apply to which buffers. - -`tags-file-name' - Stores a default tags table. - -`tags-build-completion-table' - Controls completion behavior. - -`buffer-tag-table' - Specifies a buffer-local table. - -`make-tags-files-invisible' - Sets whether tags tables should be very hidden. - -`tag-mark-stack-max' - Specifies how many tags-based hops to remember. - - Like most commands that can switch buffers, `find-tag' has another -similar command that displays the new buffer in another window. `C-x 4 -.' invokes the function `find-tag-other-window'. (This key sequence -ends with a period.) - - Emacs comes with a tags table file `TAGS' (in the directory -containing Lisp libraries) that includes all the Lisp libraries and all -the C sources of Emacs. By specifying this file with `visit-tags-table' -and then using `M-.' you can quickly look at the source of any Emacs -function. - diff --git a/info/xemacs.info-12 b/info/xemacs.info-12 index ce1f2c4..0233211 100644 --- a/info/xemacs.info-12 +++ b/info/xemacs.info-12 @@ -30,6 +30,546 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs + +Change Logs +=========== + + The Emacs command `M-x add-change-log-entry' helps you keep a record +of when and why you have changed a program. It assumes that you have a +file in which you write a chronological sequence of entries describing +individual changes. The default is to store the change entries in a +file called `ChangeLog' in the same directory as the file you are +editing. The same `ChangeLog' file therefore records changes for all +the files in a directory. + + A change log entry starts with a header line that contains your name +and the current date. Except for these header lines, every line in the +change log starts with a tab. One entry can describe several changes; +each change starts with a line starting with a tab and a star. `M-x +add-change-log-entry' visits the change log file and creates a new entry +unless the most recent entry is for today's date and your name. In +either case, it adds a new line to start the description of another +change just after the header line of the entry. When `M-x +add-change-log-entry' is finished, all is prepared for you to edit in +the description of what you changed and how. You must then save the +change log file yourself. + + The change log file is always visited in Indented Text mode, which +means that and auto-filling indent each new line like the previous +line. This is convenient for entering the contents of an entry, which +must be indented. *Note Text Mode::. + + Here is an example of the formatting conventions used in the change +log for Emacs: + + Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep) + + * xdisp.c (try_window_id): + If C-k is done at end of next-to-last line, + this fn updates window_end_vpos and cannot leave + window_end_pos nonnegative (it is zero, in fact). + If display is preempted before lines are output, + this is inconsistent. Fix by setting + blank_end_of_window to nonzero. + + Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep) + + * cmds.c (Fnewline): + Call the auto fill hook if appropriate. + + * xdisp.c (try_window_id): + If point is found by compute_motion after xp, record that + permanently. If display_text_line sets point position wrong + (case where line is killed, point is at eob and that line is + not displayed), set it again in final compute_motion. + + +File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs + +Tags Tables +=========== + + A "tags table" is a description of how a multi-file program is +broken up into files. It lists the names of the component files and the +names and positions of the functions (or other named subunits) in each +file. Grouping the related files makes it possible to search or replace +through all the files with one command. Recording the function names +and positions makes possible the `M-.' command which finds the +definition of a function by looking up which of the files it is in. + + Tags tables are stored in files called "tags table files". The +conventional name for a tags table file is `TAGS'. + + Each entry in the tags table records the name of one tag, the name +of the file that the tag is defined in (implicitly), and the position +in that file of the tag's definition. + + Just what names from the described files are recorded in the tags +table depends on the programming language of the described file. They +normally include all functions and subroutines, and may also include +global variables, data types, and anything else convenient. Each name +recorded is called a "tag". + +* Menu: + +* Tag Syntax:: Tag syntax for various types of code and text files. +* Create Tags Table:: Creating a tags table with `etags'. +* Etags Regexps:: Create arbitrary tags using regular expressions. +* Select Tags Table:: How to visit a tags table. +* Find Tag:: Commands to find the definition of a specific tag. +* Tags Search:: Using a tags table for searching and replacing. +* List Tags:: Listing and finding tags defined in a file. + + +File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Prev: Tags, Up: Tags + +Source File Tag Syntax +---------------------- + + Here is how tag syntax is defined for the most popular languages: + + * In C code, any C function or typedef is a tag, and so are + definitions of `struct', `union' and `enum'. You can tag function + declarations and external variables in addition to function + definitions by giving the `--declarations' option to `etags'. + `#define' macro definitions and `enum' constants are also tags, + unless you specify `--no-defines' when making the tags table. + Similarly, global variables are tags, unless you specify + `--no-globals'. Use of `--no-globals' and `--no-defines' can make + the tags table file much smaller. + + * In C++ code, in addition to all the tag constructs of C code, + member functions are also recognized, and optionally member + variables if you use the `--members' option. Tags for variables + and functions in classes are named `CLASS::VARIABLE' and + `CLASS::FUNCTION'. `operator' functions tags are named, for + example `operator+'. + + * In Java code, tags include all the constructs recognized in C++, + plus the `interface', `extends' and `implements' constructs. Tags + for variables and functions in classes are named `CLASS.VARIABLE' + and `CLASS.FUNCTION'. + + * In LaTeX text, the argument of any of the commands `\chapter', + `\section', `\subsection', `\subsubsection', `\eqno', `\label', + `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or + `\index', is a tag. + + Other commands can make tags as well, if you specify them in the + environment variable `TEXTAGS' before invoking `etags'. The value + of this environment variable should be a colon-separated list of + command names. For example, + + TEXTAGS="def:newcommand:newenvironment" + export TEXTAGS + + specifies (using Bourne shell syntax) that the commands `\def', + `\newcommand' and `\newenvironment' also define tags. + + * In Lisp code, any function defined with `defun', any variable + defined with `defvar' or `defconst', and in general the first + argument of any expression that starts with `(def' in column zero, + is a tag. + + * In Scheme code, tags include anything defined with `def' or with a + construct whose name starts with `def'. They also include + variables set with `set!' at top level in the file. + + Several other languages are also supported: + + * In Ada code, functions, procedures, packages, tasks, and types are + tags. Use the `--packages-only' option to create tags for packages + only. + + * In assembler code, labels appearing at the beginning of a line, + followed by a colon, are tags. + + * In Bison or Yacc input files, each rule defines as a tag the + nonterminal it constructs. The portions of the file that contain + C code are parsed as C code. + + * In Cobol code, tags are paragraph names; that is, any word + starting in column 8 and followed by a period. + + * In Erlang code, the tags are the functions, records, and macros + defined in the file. + + * In Fortran code, functions, subroutines and blockdata are tags. + + * In Objective C code, tags include Objective C definitions for + classes, class categories, methods, and protocols. + + * In Pascal code, the tags are the functions and procedures defined + in the file. + + * In Perl code, the tags are the procedures defined by the `sub', + `my' and `local' keywords. Use `--globals' if you want to tag + global variables. + + * In Postscript code, the tags are the functions. + + * In Prolog code, a tag name appears at the left margin. + + * In Python code, `def' or `class' at the beginning of a line + generate a tag. + + You can also generate tags based on regexp matching (*note Etags +Regexps::) to handle other formats and languages. + + +File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags + +Creating Tags Tables +-------------------- + + The `etags' program is used to create a tags table file. It knows +the syntax of several languages, as described in *Note Tag Syntax::. +Here is how to run `etags': + + etags INPUTFILES... + +The `etags' program reads the specified files, and writes a tags table +named `TAGS' in the current working directory. You can intermix +compressed and plain text source file names. `etags' knows about the +most common compression formats, and does the right thing. So you can +compress all your source files and have `etags' look for compressed +versions of its file name arguments, if it does not find uncompressed +versions. Under MS-DOS, `etags' also looks for file names like +`mycode.cgz' if it is given `mycode.c' on the command line and +`mycode.c' does not exist. + + `etags' recognizes the language used in an input file based on its +file name and contents. You can specify the language with the +`--language=NAME' option, described below. + + If the tags table data become outdated due to changes in the files +described in the table, the way to update the tags table is the same +way it was made in the first place. It is not necessary to do this +often. + + If the tags table fails to record a tag, or records it for the wrong +file, then Emacs cannot possibly find its definition. However, if the +position recorded in the tags table becomes a little bit wrong (due to +some editing in the file that the tag definition is in), the only +consequence is a slight delay in finding the tag. Even if the stored +position is very wrong, Emacs will still find the tag, but it must +search the entire file for it. + + So you should update a tags table when you define new tags that you +want to have listed, or when you move tag definitions from one file to +another, or when changes become substantial. Normally there is no need +to update the tags table after each edit, or even every day. + + One tags table can effectively include another. Specify the included +tags file name with the `--include=FILE' option when creating the file +that is to include it. The latter file then acts as if it contained +all the files specified in the included file, as well as the files it +directly contains. + + If you specify the source files with relative file names when you run +`etags', the tags file will contain file names relative to the +directory where the tags file was initially written. This way, you can +move an entire directory tree containing both the tags file and the +source files, and the tags file will still refer correctly to the source +files. + + If you specify absolute file names as arguments to `etags', then the +tags file will contain absolute file names. This way, the tags file +will still refer to the same files even if you move it, as long as the +source files remain in the same place. Absolute file names start with +`/', or with `DEVICE:/' on MS-DOS and MS-Windows. + + When you want to make a tags table from a great number of files, you +may have problems listing them on the command line, because some systems +have a limit on its length. The simplest way to circumvent this limit +is to tell `etags' to read the file names from its standard input, by +typing a dash in place of the file names, like this: + + find . -name "*.[chCH]" -print | etags - + + Use the option `--language=NAME' to specify the language explicitly. +You can intermix these options with file names; each one applies to +the file names that follow it. Specify `--language=auto' to tell +`etags' to resume guessing the language from the file names and file +contents. Specify `--language=none' to turn off language-specific +processing entirely; then `etags' recognizes tags by regexp matching +alone (*note Etags Regexps::). + + `etags --help' prints the list of the languages `etags' knows, and +the file name rules for guessing the language. It also prints a list of +all the available `etags' options, together with a short explanation. + + +File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags + +Etags Regexps +------------- + + The `--regex' option provides a general way of recognizing tags +based on regexp matching. You can freely intermix it with file names. +Each `--regex' option adds to the preceding ones, and applies only to +the following files. The syntax is: + + --regex=/TAGREGEXP[/NAMEREGEXP]/ + +where TAGREGEXP is used to match the lines to tag. It is always +anchored, that is, it behaves as if preceded by `^'. If you want to +account for indentation, just match any initial number of blanks by +beginning your regular expression with `[ \t]*'. In the regular +expressions, `\' quotes the next character, and `\t' stands for the tab +character. Note that `etags' does not handle the other C escape +sequences for special characters. + + The syntax of regular expressions in `etags' is the same as in +Emacs, augmented with the "interval operator", which works as in `grep' +and `ed'. The syntax of an interval operator is `\{M,N\}', and its +meaning is to match the preceding expression at least M times and up to +N times. + + You should not match more characters with TAGREGEXP than that needed +to recognize what you want to tag. If the match is such that more +characters than needed are unavoidably matched by TAGREGEXP (as will +usually be the case), you should add a NAMEREGEXP, to pick out just the +tag. This will enable Emacs to find tags more accurately and to do +completion on tag names more reliably. You can find some examples +below. + + The option `--ignore-case-regex' (or `-c') is like `--regex', except +that the regular expression provided will be matched without regard to +case, which is appropriate for various programming languages. + + The `-R' option deletes all the regexps defined with `--regex' +options. It applies to the file names following it, as you can see +from the following example: + + etags --regex=/REG1/ voo.doo --regex=/REG2/ \ + bar.ber -R --lang=lisp los.er + +Here `etags' chooses the parsing language for `voo.doo' and `bar.ber' +according to their contents. `etags' also uses REG1 to recognize +additional tags in `voo.doo', and both REG1 and REG2 to recognize +additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no +regexp matching, to recognize tags in `los.er'. + + A regular expression can be bound to a given language, by prepending +it with `{lang}'. When you do this, `etags' will use the regular +expression only for files of that language. `etags --help' prints the +list of languages recognised by `etags'. The following example tags +the `DEFVAR' macros in the Emacs source files. `etags' applies this +regular expression to C files only: + + --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' + +This feature is particularly useful when storing a list of regular +expressions in a file. The following option syntax instructs `etags' +to read two files of regular expressions. The regular expressions +contained in the second file are matched without regard to case. + + --regex=@first-file --ignore-case-regex=@second-file + +A regex file contains one regular expressions per line. Empty lines, +and lines beginning with space or tab are ignored. When the first +character in a line is `@', `etags' assumes that the rest of the line +is the name of a file of regular expressions. This means that such +files can be nested. All the other lines are taken to be regular +expressions. For example, one can create a file called `emacs.tags' +with the following contents (the first line in the file is a comment): + + -- This is for GNU Emacs source files + {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ + +and then use it like this: + + etags --regex=@emacs.tags *.[ch] */*.[ch] + + Here are some more examples. The regexps are quoted to protect them +from shell interpretation. + + * Tag Octave files: + + etags --language=none \ + --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ + --regex='/###key \(.*\)/\1/' \ + --regex='/[ \t]*global[ \t].*/' \ + *.m + + Note that tags are not generated for scripts so that you have to + add a line by yourself of the form `###key ' if you + want to jump to it. + + * Tag Tcl files: + + etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl + + * Tag VHDL files: + + --language=none \ + --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ + --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ + \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' + + +File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags + +Selecting a Tags Table +---------------------- + + At any time Emacs has one "selected" tags table, and all the commands +for working with tags tables use the selected one. To select a tags +table, use the variable `tag-table-alist'. + + The value of `tag-table-alist' is a list that determines which +`TAGS' files should be active for a given buffer. This is not really +an association list, in that all elements are checked. The car of each +element of this list is a pattern against which the buffers file name +is compared; if it matches, then the cdr of the list should be the name +of the tags table to use. If more than one element of this list +matches the buffers file name, all of the associated tags tables are +used. Earlier ones are searched first. + + If the car of elements of this list are strings, they are treated as +regular-expressions against which the file is compared (like the +`auto-mode-alist'). If they are not strings, they are evaluated. If +they evaluate to non-`nil', the current buffer is considered to match. + + If the cdr of the elements of this list are strings, they are +assumed to name a tags file. If they name a directory, the string +`tags' is appended to them to get the file name. If they are not +strings, they are evaluated and must return an appropriate string. + + For example: + + (setq tag-table-alist + '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/") + ("\\.el$" . "/usr/local/emacs/src/") + ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/") + ("" . "/usr/local/emacs/src/") + )) + + The example defines the tags table alist in the following way: + + * Anything in the directory `/usr/src/public/perl/' should use the + `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'. + + * Files ending in `.el' should use the `TAGS' file + `/usr/local/emacs/src/TAGS'. + + * Anything in or below the directory `/jbw/gnu/' should use the + `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'. + + If you had a file called `/usr/jbw/foo.el', it would use both `TAGS' +files, +`/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in +that order), because it matches both patterns. + + If the buffer-local variable `buffer-tag-table' is set, it names a +tags table that is searched before all others when `find-tag' is +executed from this buffer. + + If there is a file called `TAGS' in the same directory as the file +in question, then that tags file will always be used as well (after the +`buffer-tag-table' but before the tables specified by this list). + + If the variable `tags-file-name' is set, the `TAGS' file it names +will apply to all buffers (for backwards compatibility.) It is searched +first. + + If the value of the variable `tags-always-build-completion-table' is +`t', the tags file will always be added to the completion table without +asking first, regardless of the size of the tags file. + + The function `M-x visit-tags-table', is largely made obsolete by the +variable `tag-table-alist', tells tags commands to use the tags table +file FILE first. The FILE should be the name of a file created with +the `etags' program. A directory name is also acceptable; it means the +file `TAGS' in that directory. The function only stores the file name +you provide in the variable `tags-file-name'. Emacs does not actually +read in the tags table contents until you try to use them. You can set +the variable explicitly instead of using `visit-tags-table'. The value +of the variable `tags-file-name' is the name of the tags table used by +all buffers. This is for backward compatibility, and is largely +supplanted by the variable `tag-table-alist'. + + +File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags + +Finding a Tag +------------- + + The most important thing that a tags table enables you to do is to +find the definition of a specific tag. + +`M-. TAG &OPTIONAL OTHER-WINDOW' + Find first definition of TAG (`find-tag'). + +`C-u M-.' + Find next alternate definition of last tag specified. + +`C-x 4 . TAG' + Find first definition of TAG, but display it in another window + (`find-tag-other-window'). + + `M-.' (`find-tag') is the command to find the definition of a +specified tag. It searches through the tags table for that tag, as a +string, then uses the tags table information to determine the file in +which the definition is used and the approximate character position of +the definition in the file. Then `find-tag' visits the file, moves +point to the approximate character position, and starts searching +ever-increasing distances away for the text that should appear at the +beginning of the definition. + + If an empty argument is given (by typing ), the sexp in the +buffer before or around point is used as the name of the tag to find. +*Note Lists::, for information on sexps. + + The argument to `find-tag' need not be the whole tag name; it can be +a substring of a tag name. However, there can be many tag names +containing the substring you specify. Since `find-tag' works by +searching the text of the tags table, it finds the first tag in the +table that the specified substring appears in. To find other tags that +match the substring, give `find-tag' a numeric argument, as in `C-u +M-.'. This does not read a tag name, but continues searching the tag +table's text for another tag containing the same substring last used. +If your keyboard has a real key, `M-0 M-.' is an easier +alternative to `C-u M-.'. + + If the optional second argument OTHER-WINDOW is non-`nil', it uses +another window to display the tag. Multiple active tags tables and +completion are supported. + + Variables of note include the following: + +`tag-table-alist' + Controls which tables apply to which buffers. + +`tags-file-name' + Stores a default tags table. + +`tags-build-completion-table' + Controls completion behavior. + +`buffer-tag-table' + Specifies a buffer-local table. + +`make-tags-files-invisible' + Sets whether tags tables should be very hidden. + +`tag-mark-stack-max' + Specifies how many tags-based hops to remember. + + Like most commands that can switch buffers, `find-tag' has another +similar command that displays the new buffer in another window. `C-x 4 +.' invokes the function `find-tag-other-window'. (This key sequence +ends with a period.) + + Emacs comes with a tags table file `TAGS' (in the directory +containing Lisp libraries) that includes all the Lisp libraries and all +the C sources of Emacs. By specifying this file with `visit-tags-table' +and then using `M-.' you can quickly look at the source of any Emacs +function. + + File: xemacs.info, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags Searching and Replacing with Tags Tables @@ -661,498 +1201,3 @@ Emacs-Lisp mode (*note Lisp Modes::). * Compiling Libraries:: Compiling a library makes it load and run faster. * Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it. - -File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries - -Loading Libraries ------------------ - -`M-x load-file FILE' - Load the file FILE of Lisp code. - -`M-x load-library LIBRARY' - Load the library named LIBRARY. - -`M-x locate-library LIBRARY &optional NOSUFFIX' - Show the full path name of Emacs library LIBRARY. - - To execute a file of Emacs Lisp, use `M-x load-file'. This command -reads the file name you provide in the minibuffer, then executes the -contents of that file as Lisp code. It is not necessary to visit the -file first; in fact, this command reads the file as found on disk, not -the text in an Emacs buffer. - - Once a file of Lisp code is installed in the Emacs Lisp library -directories, users can load it using `M-x load-library'. Programs can -load it by calling `load-library', or with `load', a more primitive -function that is similar but accepts some additional arguments. - - `M-x load-library' differs from `M-x load-file' in that it searches -a sequence of directories and tries three file names in each directory. -The three names are: first, the specified name with `.elc' appended; -second, the name with `.el' appended; third, the specified name alone. -A `.elc' file would be the result of compiling the Lisp file into byte -code; if possible, it is loaded in preference to the Lisp file itself -because the compiled file loads and runs faster. - - Because the argument to `load-library' is usually not in itself a -valid file name, file name completion is not available. In fact, when -using this command, you usually do not know exactly what file name will -be used. - - The sequence of directories searched by `M-x load-library' is -specified by the variable `load-path', a list of strings that are -directory names. The elements of this list may not begin with "`~'", -so you must call `expand-file-name' on them before adding them to the -list. The default value of the list contains the directory where the -Lisp code for Emacs itself is stored. If you have libraries of your -own, put them in a single directory and add that directory to -`load-path'. `nil' in this list stands for the current default -directory, but it is probably not a good idea to put `nil' in the list. -If you start wishing that `nil' were in the list, you should probably -use `M-x load-file' for this case. - - The variable is initialized by the EMACSLOADPATH environment -variable. If no value is specified, the variable takes the default value -specified in the file `paths.h' when Emacs was built. If a path isn't -specified in `paths.h', a default value is obtained from the file -system, near the directory in which the Emacs executable resides. - - Like `M-x load-library', `M-x locate-library' searches the -directories in `load-path' to find the file that `M-x load-library' -would load. If the optional second argument NOSUFFIX is non-`nil', the -suffixes `.elc' or `.el' are not added to the specified name LIBRARY -(like calling `load' instead of `load-library'). - - You often do not have to give any command to load a library, because -the commands defined in the library are set up to "autoload" that -library. Running any of those commands causes `load' to be called to -load the library; this replaces the autoload definitions with the real -ones from the library. - - If autoloading a file does not finish, either because of an error or -because of a `C-g' quit, all function definitions made by the file are -undone automatically. So are any calls to `provide'. As a -consequence, the entire file is loaded a second time if you use one of -the autoloadable commands again. This prevents problems when the -command is no longer autoloading but is working incorrectly because the -file was only partially loaded. Function definitions are undone only -for autoloading; explicit calls to `load' do not undo anything if -loading is not completed. - - The variable `after-load-alist' takes an alist of expressions to be -evaluated when particular files are loaded. Each element has the form -`(FILENAME forms...)'. When `load' is run and the filename argument is -FILENAME, the forms in the corresponding element are executed at the -end of loading. - - FILENAME must match exactly. Normally FILENAME is the name of a -library, with no directory specified, since that is how load is -normally called. An error in `forms' does not undo the load, but it -does prevent execution of the rest of the `forms'. - - -File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries - -Compiling Libraries -------------------- - - Emacs Lisp code can be compiled into byte-code which loads faster, -takes up less space when loaded, and executes faster. - -`M-x batch-byte-compile' - Run byte-compile-file on the files remaining on the command line. - -`M-x byte-compile-buffer &optional BUFFER' - Byte-compile and evaluate contents of BUFFER (default is current - buffer). - -`M-x byte-compile-file' - Compile a file of Lisp code named FILENAME into a file of byte - code. - -`M-x byte-compile-and-load-file FILENAME' - Compile a file of Lisp code named FILENAME into a file of byte - code and load it. - -`M-x byte-recompile-directory DIRECTORY' - Recompile every `.el' file in DIRECTORY that needs recompilation. - -`M-x disassemble' - Print disassembled code for OBJECT on (optional) STREAM. - -`M-x make-obsolete FUNCTION NEW' - Make the byte-compiler warn that FUNCTION is obsolete and NEW - should be used instead. - - `byte-compile-file' creates a byte-code compiled file from an -Emacs-Lisp source file. The default argument for this function is the -file visited in the current buffer. The function reads the specified -file, compiles it into byte code, and writes an output file whose name -is made by appending `c' to the input file name. Thus, the file -`rmail.el' would be compiled into `rmail.elc'. To compile a file of -Lisp code named FILENAME into a file of byte code and then load it, use -`byte-compile-and-load-file'. To compile and evaluate Lisp code in a -given buffer, use `byte-compile-buffer'. - - To recompile all changed Lisp files in a directory, use `M-x -byte-recompile-directory'. Specify just the directory name as an -argument. Each `.el' file that has been byte-compiled before is -byte-compiled again if it has changed since the previous compilation. -A numeric argument to this command tells it to offer to compile each -`.el' file that has not been compiled yet. You must answer `y' or `n' -to each offer. - - You can use the function `batch-byte-compile' to invoke Emacs -non-interactively from the shell to do byte compilation. When you use -this function, the files to be compiled are specified with command-line -arguments. Use a shell command of the form: - - emacs -batch -f batch-byte-compile FILES... - - Directory names may also be given as arguments; in that case, -`byte-recompile-directory' is invoked on each such directory. -`batch-byte-compile' uses all remaining command-line arguments as file -or directory names, then kills the Emacs process. - - `M-x disassemble' explains the result of byte compilation. Its -argument is a function name. It displays the byte-compiled code in a -help window in symbolic form, one instruction per line. If the -instruction refers to a variable or constant, that is shown, too. - - -File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries - -Converting Mocklisp to Lisp ---------------------------- - - XEmacs can run Mocklisp files by converting them to Emacs Lisp first. -To convert a Mocklisp file, visit it and then type `M-x -convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file -in a file whose name ends in `.el' and use the new file as a Lisp -library. - - You cannot currently byte-compile converted Mocklisp code. The -reason is that converted Mocklisp code uses some special Lisp features -to deal with Mocklisp's incompatible ideas of how arguments are -evaluated and which values signify "true" or "false". - - -File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running - -Evaluating Emacs-Lisp Expressions -================================= - - Lisp programs intended to be run in Emacs should be edited in -Emacs-Lisp mode; this will happen automatically for file names ending in -`.el'. By contrast, Lisp mode itself should be used for editing Lisp -programs intended for other Lisp systems. Emacs-Lisp mode can be -selected with the command `M-x emacs-lisp-mode'. - - For testing of Lisp programs to run in Emacs, it is useful to be able -to evaluate part of the program as it is found in the Emacs buffer. For -example, if you change the text of a Lisp function definition and then -evaluate the definition, Emacs installs the change for future calls to -the function. Evaluation of Lisp expressions is also useful in any -kind of editing task for invoking non-interactive functions (functions -that are not commands). - -`M-' - Read a Lisp expression in the minibuffer, evaluate it, and print - the value in the minibuffer (`eval-expression'). - -`C-x C-e' - Evaluate the Lisp expression before point, and print the value in - the minibuffer (`eval-last-sexp'). - -`C-M-x' - Evaluate the defun containing point or after point, and print the - value in the minibuffer (`eval-defun'). - -`M-x eval-region' - Evaluate all the Lisp expressions in the region. - -`M-x eval-current-buffer' - Evaluate all the Lisp expressions in the buffer. - - `M-' (`eval-expression') is the most basic command for -evaluating a Lisp expression interactively. It reads the expression -using the minibuffer, so you can execute any expression on a buffer -regardless of what the buffer contains. When evaluation is complete, -the current buffer is once again the buffer that was current when -`M-' was typed. - - `M-' can easily confuse users, especially on keyboards with -autorepeat, where it can result from holding down the key for too -long. Therefore, `eval-expression' is normally a disabled command. -Attempting to use this command asks for confirmation and gives you the -option of enabling it; once you enable the command, you are no longer -required to confirm. *Note Disabling::. - - In Emacs-Lisp mode, the key `C-M-x' is bound to the function -`eval-defun', which parses the defun containing point or following point -as a Lisp expression and evaluates it. The value is printed in the echo -area. This command is convenient for installing in the Lisp environment -changes that you have just made in the text of a function definition. - - The command `C-x C-e' (`eval-last-sexp') performs a similar job but -is available in all major modes, not just Emacs-Lisp mode. It finds -the sexp before point, reads it as a Lisp expression, evaluates it, and -prints the value in the echo area. It is sometimes useful to type in an -expression and then, with point still after it, type `C-x C-e'. - - If `C-M-x' or `C-x C-e' are given a numeric argument, they print the -value by inserting it into the current buffer at point, rather than in -the echo area. The argument value does not matter. - - The most general command for evaluating Lisp expressions from a -buffer is `eval-region'. `M-x eval-region' parses the text of the -region as one or more Lisp expressions, evaluating them one by one. -`M-x eval-current-buffer' is similar, but it evaluates the entire -buffer. This is a reasonable way to install the contents of a file of -Lisp code that you are just ready to test. After finding and fixing a -bug, use `C-M-x' on each function that you change, to keep the Lisp -world in step with the source file. - - -File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running - -The Emacs-Lisp Debugger -======================= - - XEmacs contains a debugger for Lisp programs executing inside it. -This debugger is normally not used; many commands frequently get Lisp -errors when invoked in inappropriate contexts (such as `C-f' at the end -of the buffer) and it would be unpleasant to enter a special debugging -mode in this case. When you want to make Lisp errors invoke the -debugger, you must set the variable `debug-on-error' to non-`nil'. -Quitting with `C-g' is not considered an error, and `debug-on-error' -has no effect on the handling of `C-g'. However, if you set -`debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This -can be useful for debugging an infinite loop; type `C-g' once the loop -has had time to reach its steady state. `debug-on-quit' has no effect -on errors. - - You can make Emacs enter the debugger when a specified function is -called or at a particular place in Lisp code. Use `M-x debug-on-entry' -with argument FUN-NAME to have Emacs enter the debugger as soon as -FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the -function stop entering the debugger when called. (Redefining the -function also does this.) To enter the debugger from some other place -in Lisp code, you must insert the expression `(debug)' there and -install the changed code with `C-M-x'. *Note Lisp Eval::. - - When the debugger is entered, it displays the previously selected -buffer in one window and a buffer named `*Backtrace*' in another -window. The backtrace buffer contains one line for each level of Lisp -function execution currently going on. At the beginning of the buffer -is a message describing the reason that the debugger was invoked, for -example, an error message if it was invoked due to an error. - - The backtrace buffer is read-only and is in Backtrace mode, a special -major mode in which letters are defined as debugger commands. The -usual Emacs editing commands are available; you can switch windows to -examine the buffer that was being edited at the time of the error, and -you can switch buffers, visit files, and perform any other editing -operations. However, the debugger is a recursive editing level (*note -Recursive Edit::); it is a good idea to return to the backtrace buffer -and explicitly exit the debugger when you don't want to use it any -more. Exiting the debugger kills the backtrace buffer. - - The contents of the backtrace buffer show you the functions that are -executing and the arguments that were given to them. It also allows you -to specify a stack frame by moving point to the line describing that -frame. The frame whose line point is on is considered the "current -frame". Some of the debugger commands operate on the current frame. -Debugger commands are mainly used for stepping through code one -expression at a time. Here is a list of them: - -`c' - Exit the debugger and continue execution. In most cases, - execution of the program continues as if the debugger had never - been entered (aside from the effect of any variables or data - structures you may have changed while inside the debugger). This - includes entry to the debugger due to function entry or exit, - explicit invocation, and quitting or certain errors. Most errors - cannot be continued; trying to continue an error usually causes - the same error to occur again. - -`d' - Continue execution, but enter the debugger the next time a Lisp - function is called. This allows you to step through the - subexpressions of an expression, and see what the subexpressions - do and what values they compute. - - When you enter the debugger this way, Emacs flags the stack frame - for the function call from which you entered. The same function - is then called when you exit the frame. To cancel this flag, use - `u'. - -`b' - Set up to enter the debugger when the current frame is exited. - Frames that invoke the debugger on exit are flagged with stars. - -`u' - Don't enter the debugger when the current frame is exited. This - cancels a `b' command on a frame. - -`e' - Read a Lisp expression in the minibuffer, evaluate it, and print - the value in the echo area. This is equivalent to the command - `M-', except that `e' is not normally disabled like `M-'. - -`q' - Terminate the program being debugged; return to top-level Emacs - command execution. - - If the debugger was entered due to a `C-g' but you really want to - quit, not to debug, use the `q' command. - -`r' - Return a value from the debugger. The value is computed by - reading an expression with the minibuffer and evaluating it. - - The value returned by the debugger makes a difference when the - debugger was invoked due to exit from a Lisp call frame (as - requested with `b'); then the value specified in the `r' command - is used as the value of that frame. - - The debugger's return value also matters with many errors. For - example, `wrong-type-argument' errors will use the debugger's - return value instead of the invalid argument; `no-catch' errors - will use the debugger value as a throw tag instead of the tag that - was not found. If an error was signaled by calling the Lisp - function `signal', the debugger's return value is returned as the - value of `signal'. - - -File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running - -Lisp Interaction Buffers -======================== - - The buffer `*scratch*', which is selected when Emacs starts up, is -provided for evaluating Lisp expressions interactively inside Emacs. -Both the expressions you evaluate and their output goes in the buffer. - - The `*scratch*' buffer's major mode is Lisp Interaction mode, which -is the same as Emacs-Lisp mode except for one command, . In -Emacs-Lisp mode, is an indentation command. In Lisp Interaction -mode, is bound to `eval-print-last-sexp'. This function reads -the Lisp expression before point, evaluates it, and inserts the value -in printed representation before point. - - The way to use the `*scratch*' buffer is to insert Lisp expressions -at the end, ending each one with so that it will be evaluated. -The result is a complete typescript of the expressions you have -evaluated and their values. - - The rationale for this feature is that Emacs must have a buffer when -it starts up, but that buffer is not useful for editing files since a -new buffer is made for every file that you visit. The Lisp interpreter -typescript is the most useful thing I can think of for the initial -buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp -Interaction mode. - - -File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running - -Running an External Lisp -======================== - - Emacs has facilities for running programs in other Lisp systems. -You can run a Lisp process as an inferior of Emacs, and pass -expressions to it to be evaluated. You can also pass changed function -definitions directly from the Emacs buffers in which you edit the Lisp -programs to the inferior Lisp process. - - To run an inferior Lisp process, type `M-x run-lisp'. This runs the -program named `lisp', the same program you would run by typing `lisp' -as a shell command, with both input and output going through an Emacs -buffer named `*lisp*'. In other words, any "terminal output" from Lisp -will go into the buffer, advancing point, and any "terminal input" for -Lisp comes from text in the buffer. To give input to Lisp, go to the -end of the buffer and type the input, terminated by . The -`*lisp*' buffer is in Inferior Lisp mode, which has all the special -characteristics of Lisp mode and Shell mode (*note Shell Mode::). - - Use Lisp mode to run the source files of programs in external Lisps. -You can select this mode with `M-x lisp-mode'. It is used automatically -for files whose names end in `.l' or `.lisp', as most Lisp systems -usually expect. - - When you edit a function in a Lisp program you are running, the -easiest way to send the changed definition to the inferior Lisp process -is the key `C-M-x'. In Lisp mode, this key runs the function -`lisp-send-defun', which finds the defun around or following point and -sends it as input to the Lisp process. (Emacs can send input to any -inferior process regardless of what buffer is current.) - - Contrast the meanings of `C-M-x' in Lisp mode (for editing programs -to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp -programs to be run in Emacs): in both modes it has the effect of -installing the function definition that point is in, but the way of -doing so is different according to where the relevant Lisp environment -is found. *Note Lisp Modes::. - - -File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top - -Packages -======== - - The XEmacs 21 distribution comes only with a very basic set of -built-in modes and packages. Most of the packages that were part of -the distribution of earlier versions of XEmacs are now available -separately. The installer as well as the user can choose which -packages to install; the actual installation process is easy. This -gives an installer the ability to tailor an XEmacs installation for -local needs with safe removal of unnecessary code. - -* Menu: - -* Package Terminology:: Understanding different kinds of packages. -* Using Packages:: How to install and use packages. -* Building Packages:: Building packages from sources. -* Available Packages:: A brief, out-of-date, directory of packaged LISP. - - -File: xemacs.info, Node: Package Terminology, Next: Using Packages, Up: Packages - -Package Flavors ---------------- - - There are two main flavors of packages. - - * Regular Packages A regular package is one in which multiple files - are involved and one may not in general safely remove any of them. - - * Single-File Packages A single-file package is an aggregate - collection of thematically related but otherwise independent lisp - files. These files are bundled together for download convenience - and individual files may be deleted at will without any loss of - functionality. - -Package Distributions ---------------------- - - XEmacs Lisp packages are distributed in two ways, depending on the -intended use. Binary Packages are for installers and end-users and may -be installed directly into an XEmacs package directory. Source Packages -are for developers and include all files necessary for rebuilding -bytecompiled lisp and creating tarballs for distribution. - -Binary Packages ---------------- - - Binary packages may be installed directly into an XEmacs package -hierarchy. - -Source Packages ---------------- - - Source packages contain all of the Package author's (where -appropriate in regular packages) source code plus all of the files -necessary to build distribution tarballs (Unix Tar format files, -gzipped for space savings). - diff --git a/info/xemacs.info-13 b/info/xemacs.info-13 index bfce027..739ba70 100644 --- a/info/xemacs.info-13 +++ b/info/xemacs.info-13 @@ -30,6 +30,502 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries + +Loading Libraries +----------------- + +`M-x load-file FILE' + Load the file FILE of Lisp code. + +`M-x load-library LIBRARY' + Load the library named LIBRARY. + +`M-x locate-library LIBRARY &optional NOSUFFIX' + Show the full path name of Emacs library LIBRARY. + + To execute a file of Emacs Lisp, use `M-x load-file'. This command +reads the file name you provide in the minibuffer, then executes the +contents of that file as Lisp code. It is not necessary to visit the +file first; in fact, this command reads the file as found on disk, not +the text in an Emacs buffer. + + Once a file of Lisp code is installed in the Emacs Lisp library +directories, users can load it using `M-x load-library'. Programs can +load it by calling `load-library', or with `load', a more primitive +function that is similar but accepts some additional arguments. + + `M-x load-library' differs from `M-x load-file' in that it searches +a sequence of directories and tries three file names in each directory. +The three names are: first, the specified name with `.elc' appended; +second, the name with `.el' appended; third, the specified name alone. +A `.elc' file would be the result of compiling the Lisp file into byte +code; if possible, it is loaded in preference to the Lisp file itself +because the compiled file loads and runs faster. + + Because the argument to `load-library' is usually not in itself a +valid file name, file name completion is not available. In fact, when +using this command, you usually do not know exactly what file name will +be used. + + The sequence of directories searched by `M-x load-library' is +specified by the variable `load-path', a list of strings that are +directory names. The elements of this list may not begin with "`~'", +so you must call `expand-file-name' on them before adding them to the +list. The default value of the list contains the directory where the +Lisp code for Emacs itself is stored. If you have libraries of your +own, put them in a single directory and add that directory to +`load-path'. `nil' in this list stands for the current default +directory, but it is probably not a good idea to put `nil' in the list. +If you start wishing that `nil' were in the list, you should probably +use `M-x load-file' for this case. + + The variable is initialized by the EMACSLOADPATH environment +variable. If no value is specified, the variable takes the default value +specified in the file `paths.h' when Emacs was built. If a path isn't +specified in `paths.h', a default value is obtained from the file +system, near the directory in which the Emacs executable resides. + + Like `M-x load-library', `M-x locate-library' searches the +directories in `load-path' to find the file that `M-x load-library' +would load. If the optional second argument NOSUFFIX is non-`nil', the +suffixes `.elc' or `.el' are not added to the specified name LIBRARY +(like calling `load' instead of `load-library'). + + You often do not have to give any command to load a library, because +the commands defined in the library are set up to "autoload" that +library. Running any of those commands causes `load' to be called to +load the library; this replaces the autoload definitions with the real +ones from the library. + + If autoloading a file does not finish, either because of an error or +because of a `C-g' quit, all function definitions made by the file are +undone automatically. So are any calls to `provide'. As a +consequence, the entire file is loaded a second time if you use one of +the autoloadable commands again. This prevents problems when the +command is no longer autoloading but is working incorrectly because the +file was only partially loaded. Function definitions are undone only +for autoloading; explicit calls to `load' do not undo anything if +loading is not completed. + + The variable `after-load-alist' takes an alist of expressions to be +evaluated when particular files are loaded. Each element has the form +`(FILENAME forms...)'. When `load' is run and the filename argument is +FILENAME, the forms in the corresponding element are executed at the +end of loading. + + FILENAME must match exactly. Normally FILENAME is the name of a +library, with no directory specified, since that is how load is +normally called. An error in `forms' does not undo the load, but it +does prevent execution of the rest of the `forms'. + + +File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries + +Compiling Libraries +------------------- + + Emacs Lisp code can be compiled into byte-code which loads faster, +takes up less space when loaded, and executes faster. + +`M-x batch-byte-compile' + Run byte-compile-file on the files remaining on the command line. + +`M-x byte-compile-buffer &optional BUFFER' + Byte-compile and evaluate contents of BUFFER (default is current + buffer). + +`M-x byte-compile-file' + Compile a file of Lisp code named FILENAME into a file of byte + code. + +`M-x byte-compile-and-load-file FILENAME' + Compile a file of Lisp code named FILENAME into a file of byte + code and load it. + +`M-x byte-recompile-directory DIRECTORY' + Recompile every `.el' file in DIRECTORY that needs recompilation. + +`M-x disassemble' + Print disassembled code for OBJECT on (optional) STREAM. + +`M-x make-obsolete FUNCTION NEW' + Make the byte-compiler warn that FUNCTION is obsolete and NEW + should be used instead. + + `byte-compile-file' creates a byte-code compiled file from an +Emacs-Lisp source file. The default argument for this function is the +file visited in the current buffer. The function reads the specified +file, compiles it into byte code, and writes an output file whose name +is made by appending `c' to the input file name. Thus, the file +`rmail.el' would be compiled into `rmail.elc'. To compile a file of +Lisp code named FILENAME into a file of byte code and then load it, use +`byte-compile-and-load-file'. To compile and evaluate Lisp code in a +given buffer, use `byte-compile-buffer'. + + To recompile all changed Lisp files in a directory, use `M-x +byte-recompile-directory'. Specify just the directory name as an +argument. Each `.el' file that has been byte-compiled before is +byte-compiled again if it has changed since the previous compilation. +A numeric argument to this command tells it to offer to compile each +`.el' file that has not been compiled yet. You must answer `y' or `n' +to each offer. + + You can use the function `batch-byte-compile' to invoke Emacs +non-interactively from the shell to do byte compilation. When you use +this function, the files to be compiled are specified with command-line +arguments. Use a shell command of the form: + + emacs -batch -f batch-byte-compile FILES... + + Directory names may also be given as arguments; in that case, +`byte-recompile-directory' is invoked on each such directory. +`batch-byte-compile' uses all remaining command-line arguments as file +or directory names, then kills the Emacs process. + + `M-x disassemble' explains the result of byte compilation. Its +argument is a function name. It displays the byte-compiled code in a +help window in symbolic form, one instruction per line. If the +instruction refers to a variable or constant, that is shown, too. + + +File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries + +Converting Mocklisp to Lisp +--------------------------- + + XEmacs can run Mocklisp files by converting them to Emacs Lisp first. +To convert a Mocklisp file, visit it and then type `M-x +convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file +in a file whose name ends in `.el' and use the new file as a Lisp +library. + + You cannot currently byte-compile converted Mocklisp code. The +reason is that converted Mocklisp code uses some special Lisp features +to deal with Mocklisp's incompatible ideas of how arguments are +evaluated and which values signify "true" or "false". + + +File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running + +Evaluating Emacs-Lisp Expressions +================================= + + Lisp programs intended to be run in Emacs should be edited in +Emacs-Lisp mode; this will happen automatically for file names ending in +`.el'. By contrast, Lisp mode itself should be used for editing Lisp +programs intended for other Lisp systems. Emacs-Lisp mode can be +selected with the command `M-x emacs-lisp-mode'. + + For testing of Lisp programs to run in Emacs, it is useful to be able +to evaluate part of the program as it is found in the Emacs buffer. For +example, if you change the text of a Lisp function definition and then +evaluate the definition, Emacs installs the change for future calls to +the function. Evaluation of Lisp expressions is also useful in any +kind of editing task for invoking non-interactive functions (functions +that are not commands). + +`M-' + Read a Lisp expression in the minibuffer, evaluate it, and print + the value in the minibuffer (`eval-expression'). + +`C-x C-e' + Evaluate the Lisp expression before point, and print the value in + the minibuffer (`eval-last-sexp'). + +`C-M-x' + Evaluate the defun containing point or after point, and print the + value in the minibuffer (`eval-defun'). + +`M-x eval-region' + Evaluate all the Lisp expressions in the region. + +`M-x eval-current-buffer' + Evaluate all the Lisp expressions in the buffer. + + `M-' (`eval-expression') is the most basic command for +evaluating a Lisp expression interactively. It reads the expression +using the minibuffer, so you can execute any expression on a buffer +regardless of what the buffer contains. When evaluation is complete, +the current buffer is once again the buffer that was current when +`M-' was typed. + + `M-' can easily confuse users, especially on keyboards with +autorepeat, where it can result from holding down the key for too +long. Therefore, `eval-expression' is normally a disabled command. +Attempting to use this command asks for confirmation and gives you the +option of enabling it; once you enable the command, you are no longer +required to confirm. *Note Disabling::. + + In Emacs-Lisp mode, the key `C-M-x' is bound to the function +`eval-defun', which parses the defun containing point or following point +as a Lisp expression and evaluates it. The value is printed in the echo +area. This command is convenient for installing in the Lisp environment +changes that you have just made in the text of a function definition. + + The command `C-x C-e' (`eval-last-sexp') performs a similar job but +is available in all major modes, not just Emacs-Lisp mode. It finds +the sexp before point, reads it as a Lisp expression, evaluates it, and +prints the value in the echo area. It is sometimes useful to type in an +expression and then, with point still after it, type `C-x C-e'. + + If `C-M-x' or `C-x C-e' are given a numeric argument, they print the +value by inserting it into the current buffer at point, rather than in +the echo area. The argument value does not matter. + + The most general command for evaluating Lisp expressions from a +buffer is `eval-region'. `M-x eval-region' parses the text of the +region as one or more Lisp expressions, evaluating them one by one. +`M-x eval-current-buffer' is similar, but it evaluates the entire +buffer. This is a reasonable way to install the contents of a file of +Lisp code that you are just ready to test. After finding and fixing a +bug, use `C-M-x' on each function that you change, to keep the Lisp +world in step with the source file. + + +File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running + +The Emacs-Lisp Debugger +======================= + + XEmacs contains a debugger for Lisp programs executing inside it. +This debugger is normally not used; many commands frequently get Lisp +errors when invoked in inappropriate contexts (such as `C-f' at the end +of the buffer) and it would be unpleasant to enter a special debugging +mode in this case. When you want to make Lisp errors invoke the +debugger, you must set the variable `debug-on-error' to non-`nil'. +Quitting with `C-g' is not considered an error, and `debug-on-error' +has no effect on the handling of `C-g'. However, if you set +`debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This +can be useful for debugging an infinite loop; type `C-g' once the loop +has had time to reach its steady state. `debug-on-quit' has no effect +on errors. + + You can make Emacs enter the debugger when a specified function is +called or at a particular place in Lisp code. Use `M-x debug-on-entry' +with argument FUN-NAME to have Emacs enter the debugger as soon as +FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the +function stop entering the debugger when called. (Redefining the +function also does this.) To enter the debugger from some other place +in Lisp code, you must insert the expression `(debug)' there and +install the changed code with `C-M-x'. *Note Lisp Eval::. + + When the debugger is entered, it displays the previously selected +buffer in one window and a buffer named `*Backtrace*' in another +window. The backtrace buffer contains one line for each level of Lisp +function execution currently going on. At the beginning of the buffer +is a message describing the reason that the debugger was invoked, for +example, an error message if it was invoked due to an error. + + The backtrace buffer is read-only and is in Backtrace mode, a special +major mode in which letters are defined as debugger commands. The +usual Emacs editing commands are available; you can switch windows to +examine the buffer that was being edited at the time of the error, and +you can switch buffers, visit files, and perform any other editing +operations. However, the debugger is a recursive editing level (*note +Recursive Edit::); it is a good idea to return to the backtrace buffer +and explicitly exit the debugger when you don't want to use it any +more. Exiting the debugger kills the backtrace buffer. + + The contents of the backtrace buffer show you the functions that are +executing and the arguments that were given to them. It also allows you +to specify a stack frame by moving point to the line describing that +frame. The frame whose line point is on is considered the "current +frame". Some of the debugger commands operate on the current frame. +Debugger commands are mainly used for stepping through code one +expression at a time. Here is a list of them: + +`c' + Exit the debugger and continue execution. In most cases, + execution of the program continues as if the debugger had never + been entered (aside from the effect of any variables or data + structures you may have changed while inside the debugger). This + includes entry to the debugger due to function entry or exit, + explicit invocation, and quitting or certain errors. Most errors + cannot be continued; trying to continue an error usually causes + the same error to occur again. + +`d' + Continue execution, but enter the debugger the next time a Lisp + function is called. This allows you to step through the + subexpressions of an expression, and see what the subexpressions + do and what values they compute. + + When you enter the debugger this way, Emacs flags the stack frame + for the function call from which you entered. The same function + is then called when you exit the frame. To cancel this flag, use + `u'. + +`b' + Set up to enter the debugger when the current frame is exited. + Frames that invoke the debugger on exit are flagged with stars. + +`u' + Don't enter the debugger when the current frame is exited. This + cancels a `b' command on a frame. + +`e' + Read a Lisp expression in the minibuffer, evaluate it, and print + the value in the echo area. This is equivalent to the command + `M-', except that `e' is not normally disabled like `M-'. + +`q' + Terminate the program being debugged; return to top-level Emacs + command execution. + + If the debugger was entered due to a `C-g' but you really want to + quit, not to debug, use the `q' command. + +`r' + Return a value from the debugger. The value is computed by + reading an expression with the minibuffer and evaluating it. + + The value returned by the debugger makes a difference when the + debugger was invoked due to exit from a Lisp call frame (as + requested with `b'); then the value specified in the `r' command + is used as the value of that frame. + + The debugger's return value also matters with many errors. For + example, `wrong-type-argument' errors will use the debugger's + return value instead of the invalid argument; `no-catch' errors + will use the debugger value as a throw tag instead of the tag that + was not found. If an error was signaled by calling the Lisp + function `signal', the debugger's return value is returned as the + value of `signal'. + + +File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running + +Lisp Interaction Buffers +======================== + + The buffer `*scratch*', which is selected when Emacs starts up, is +provided for evaluating Lisp expressions interactively inside Emacs. +Both the expressions you evaluate and their output goes in the buffer. + + The `*scratch*' buffer's major mode is Lisp Interaction mode, which +is the same as Emacs-Lisp mode except for one command, . In +Emacs-Lisp mode, is an indentation command. In Lisp Interaction +mode, is bound to `eval-print-last-sexp'. This function reads +the Lisp expression before point, evaluates it, and inserts the value +in printed representation before point. + + The way to use the `*scratch*' buffer is to insert Lisp expressions +at the end, ending each one with so that it will be evaluated. +The result is a complete typescript of the expressions you have +evaluated and their values. + + The rationale for this feature is that Emacs must have a buffer when +it starts up, but that buffer is not useful for editing files since a +new buffer is made for every file that you visit. The Lisp interpreter +typescript is the most useful thing I can think of for the initial +buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp +Interaction mode. + + +File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running + +Running an External Lisp +======================== + + Emacs has facilities for running programs in other Lisp systems. +You can run a Lisp process as an inferior of Emacs, and pass +expressions to it to be evaluated. You can also pass changed function +definitions directly from the Emacs buffers in which you edit the Lisp +programs to the inferior Lisp process. + + To run an inferior Lisp process, type `M-x run-lisp'. This runs the +program named `lisp', the same program you would run by typing `lisp' +as a shell command, with both input and output going through an Emacs +buffer named `*lisp*'. In other words, any "terminal output" from Lisp +will go into the buffer, advancing point, and any "terminal input" for +Lisp comes from text in the buffer. To give input to Lisp, go to the +end of the buffer and type the input, terminated by . The +`*lisp*' buffer is in Inferior Lisp mode, which has all the special +characteristics of Lisp mode and Shell mode (*note Shell Mode::). + + Use Lisp mode to run the source files of programs in external Lisps. +You can select this mode with `M-x lisp-mode'. It is used automatically +for files whose names end in `.l' or `.lisp', as most Lisp systems +usually expect. + + When you edit a function in a Lisp program you are running, the +easiest way to send the changed definition to the inferior Lisp process +is the key `C-M-x'. In Lisp mode, this key runs the function +`lisp-send-defun', which finds the defun around or following point and +sends it as input to the Lisp process. (Emacs can send input to any +inferior process regardless of what buffer is current.) + + Contrast the meanings of `C-M-x' in Lisp mode (for editing programs +to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp +programs to be run in Emacs): in both modes it has the effect of +installing the function definition that point is in, but the way of +doing so is different according to where the relevant Lisp environment +is found. *Note Lisp Modes::. + + +File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top + +Packages +======== + + The XEmacs 21 distribution comes only with a very basic set of +built-in modes and packages. Most of the packages that were part of +the distribution of earlier versions of XEmacs are now available +separately. The installer as well as the user can choose which +packages to install; the actual installation process is easy. This +gives an installer the ability to tailor an XEmacs installation for +local needs with safe removal of unnecessary code. + +* Menu: + +* Package Terminology:: Understanding different kinds of packages. +* Using Packages:: How to install and use packages. +* Building Packages:: Building packages from sources. +* Creating Packages:: The basics. +* Available Packages:: A brief, out-of-date, directory of packaged LISP. + + +File: xemacs.info, Node: Package Terminology, Next: Using Packages, Up: Packages + +Package Flavors +--------------- + + There are two main flavors of packages. + + * Regular Packages A regular package is one in which multiple files + are involved and one may not in general safely remove any of them. + + * Single-File Packages A single-file package is an aggregate + collection of thematically related but otherwise independent lisp + files. These files are bundled together for download convenience + and individual files may be deleted at will without any loss of + functionality. + +Package Distributions +--------------------- + + XEmacs Lisp packages are distributed in two ways, depending on the +intended use. Binary Packages are for installers and end-users and may +be installed directly into an XEmacs package directory. Source Packages +are for developers and include all files necessary for rebuilding +bytecompiled lisp and creating tarballs for distribution. + +Binary Packages +--------------- + + Binary packages may be installed directly into an XEmacs package +hierarchy. + +Source Packages +--------------- + + Source packages contain all of the Package author's (where +appropriate in regular packages) source code plus all of the files +necessary to build distribution tarballs (Unix Tar format files, +gzipped for space savings). + + File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages Getting Started @@ -271,7 +767,7 @@ it's best to exit XEmacs before upgrading an existing package.  -File: xemacs.info, Node: Building Packages, Next: Available Packages, Prev: Using Packages, Up: Packages +File: xemacs.info, Node: Building Packages, Next: Creating Packages, Prev: Using Packages, Up: Packages Source packages are available from the `packages/source-packages' subdirectory of your favorite XEmacs distribution site. Alternatively, @@ -314,9 +810,9 @@ to others. TeXinfo documentation if present. `srckit' - Usually aliased to `make srckit-std'. This does a `make - distclean' and creates a package source tarball in the staging - directory. This is generally only of use for package maintainers. + Usually aliased to `srckit-std'. This does a `make distclean' and + creates a package source tarball in the staging directory. This + is generally only of use for package maintainers. `binkit' May be aliased to `binkit-sourceonly', `binkit-sourceinfo', @@ -334,7 +830,120 @@ to others. of use by XEmacs maintainers producing files for distribution.  -File: xemacs.info, Node: Available Packages, Prev: Building Packages, Up: Packages +File: xemacs.info, Node: Creating Packages, Next: Available Packages, Prev: Building Packages, Up: Packages + + Creating a package from an existing Lisp library is not very +difficult. + + In addition to the Lisp libraries themselves, you need a +`package-info.in' file and a simple `Makefile'. The rest is done by +`XEmacs.rules', part of the packaging system infrastructure. + + `package-info.in' contains a single Lisp form like this: + + (name ; your package's name + (standards-version 1.1 + version VERSION + author-version AUTHOR_VERSION + date DATE + build-date BUILD_DATE + maintainer MAINTAINER + distribution xemacs ; change to "mule" if MULE is needed + priority high + category CATEGORY + dump nil + description "description" ; a one-line description string + filename FILENAME + md5sum MD5SUM + size SIZE + provides (feature1 feature2) ; one for every `provides' form + requires (REQUIRES) + type regular + )) + + You must fill in the four commented lines. The value of `name' is +the name of your package as an unquoted symbol. Normally it is the name +of the main Lisp file or principal feature provided. The allowed values +for distribution are `xemacs' and `mule'. Write them as unquoted +symbols. The `description' is a quoted Lisp string; use the usual +conventions. The value for `provides' is a list of feature symbols +(written unquoted). All of the features provided by libraries in your +package should be elements of this list. Implementing an automatic +method for generating the `provides' line is desirable, but as yet +undone. + + The variables in upper-case are references to variables set in the +`Makefile' or automatically generated. Do not change them; they are +automatically filled in by the build process. + + The remaining lines refer to implementation constants +(`standards-version'), or features that are unimplemented or have been +removed (`priority' and `dump'). The `type' line is not normally +relevant to external maintainers; the alternate value is `single-file', +which refers to packages consed up out of a number of single-file +libraries that are more or less thematically related. An example is +`prog-modes'. Single-file packages are basically for administrative +convenience, and new packages should generally be created as regular +packages. + + The `Makefile' is quite stylized. The idea is similar to an +`Imakefile' or an `automake' file: the complexity is hidden in generic +rules files, in this case the `XEmacs.rules' include file in the top +directory of the packages hierarchy. Although a number of facilities +are available for complex libraries, most simple packages' `Makefile's +contain a copyright notice, a few variable definitions, an include for +`XEmacs.rules', and a couple of standard targets. + + The first few `make' variables defined are `VERSION', +`AUTHOR_VERSION', `MAINTAINER', `PACKAGE', `PKG_TYPE', `REQUIRES', and +`CATEGORY'. All but one were described in the description of +`package-info.in'. The last is an admistrative grouping. Current +categories include `comm', `games', `libs', `mule', `oa', `os', `prog', +and `wp'. *Note Available Packages::, for a list of categories. + + Next, define the variable `ELCS'. This contains the list of the +byte-compiled Lisp files used by the package. These files and their +`.el' versions will be included in the binary package. If there are +other files (such as extra Lisp sources or an upstream `Makefile') that +are normally placed in the installed Lisp directory, but not +byte-compiled, they can be listed as the value of `EXTRA_SOURCES'. + + The include is simply + include ../../XEmacs.rules + + The standard targets follow. These are + + all:: $(ELCS) auto-autoloads.elc + + srckit: srckit-alias + + binkit: binkit-alias + + Other targets (such as Texinfo sources) may need to be added as +dependencies for the `all' target. Dependencies for `srckit' and +`binkit' (that is, values for SRCKIT-ALIAS and BINKIT-ALIAS) are +defined in `XEmacs.rules'. The most useful of these values are given +in the following table. + +SRCKIT-ALIAS + Usually set to `srckit-std'. + +BINKIT-ALIAS + May be set to `binkit-sourceonly', `binkit-sourceinfo', + `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly' + indicates there is nothing to install in a data directory or info + directory. `sourceinfo' indicates that source and info files are + to be installed. `sourcedata' indicates that source and etc + (data) files are to be installed. `sourcedatainfo' indicates + source, etc (data), and info files are to be installed. + + Data files include things like pixmaps for a package-specific +toolbar, and are normally installed in `etc/PACKAGE_NAME'. A few +packages have needs beyond the basic templates. See `XEmacs.rules' or +a future revision of this manual for details. + + +File: xemacs.info, Node: Available Packages, Prev: Creating Packages, Up: Packages This section is surely out-of-date. If you're sure that XEmacs is able to do something, but your installed XEmacs won't do it for you, @@ -553,8 +1162,7 @@ Program Editing Support (prog) CVS frontend. `prog-modes' - Miscellaneous single-file lisp files for various programming - languages. + Miscellaneous Lisp libraries for various programming languages. `scheme' Front-end support for Inferior Scheme. @@ -563,11 +1171,10 @@ Program Editing Support (prog) Support for editing shell scripts. `vc' - Version Control for Free systems. + Version control for free systems. `vc-cc' - Version Control for ClearCase. This package must be installed - prior to building XEmacs [broken as of XEmacs 20.5-beta19]. + Version control for ClearCase. `vhdl' Support for VHDL. @@ -702,637 +1309,3 @@ since those two definitions are independent for one abbrev. `M-x kill-all-abbrevs' removes all existing abbrev definitions. - -File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs - -Controlling Abbrev Expansion -============================ - - An abbrev expands whenever it is in a buffer just before point and -you type a self-inserting punctuation character (, comma, etc.). -Most often an abbrev is used by inserting the abbrev followed by -punctuation. - - Abbrev expansion preserves case; thus, `foo' expands into `find -outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER -OTTER' or `Find Outer Otter' according to the variable -`abbrev-all-caps' (a non-`nil' value chooses the first of the two -expansions). - - Two commands are available to control abbrev expansion: - -`M-'' - Separate a prefix from a following abbrev to be expanded - (`abbrev-prefix-mark'). - -`C-x a e' - Expand the abbrev before point (`expand-abbrev'). This is - effective even when Abbrev mode is not enabled. - -`M-x unexpand-abbrev' - Undo last abbrev expansion. - -`M-x expand-region-abbrevs' - Expand some or all abbrevs found in the region. - - You may wish to expand an abbrev with a prefix attached. For -example, if `cnst' expands into `construction', you may want to use it -to enter `reconstruction'. It does not work to type `recnst', because -that is not necessarily a defined abbrev. Instead, you can use the -command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the -abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a -minus sign in the buffer to indicate that it has done its work. Then -insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now -insert a punctuation character to expand the abbrev `cnst' into -`construction'. The minus sign is deleted at this point by `M-''. The -resulting text is the desired `reconstruction'. - - If you actually want the text of the abbrev in the buffer, rather -than its expansion, insert the following punctuation with `C-q'. Thus, -`foo C-q -' leaves `foo-' in the buffer. - - If you expand an abbrev by mistake, you can undo the expansion -(replace the expansion by the original abbrev text) with `M-x -unexpand-abbrev'. You can also use `C-_' (`undo') to undo the -expansion; but that will first undo the insertion of the punctuation -character. - - `M-x expand-region-abbrevs' searches through the region for defined -abbrevs, and offers to replace each one it finds with its expansion. -This command is useful if you have typed text using abbrevs but forgot -to turn on Abbrev mode first. It may also be useful together with a -special set of abbrev definitions for making several global -replacements at once. The command is effective even if Abbrev mode is -not enabled. - - -File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs - -Examining and Editing Abbrevs -============================= - -`M-x list-abbrevs' - Print a list of all abbrev definitions. - -`M-x edit-abbrevs' - Edit a list of abbrevs; you can add, alter, or remove definitions. - - The output from `M-x list-abbrevs' looks like this: - - (lisp-mode-abbrev-table) - "dk" 0 "define-key" - (global-abbrev-table) - "dfn" 0 "definition" - -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) - - A line containing a name in parentheses is the header for abbrevs in -a particular abbrev table; `global-abbrev-table' contains all the global -abbrevs, and the other abbrev tables that are named after major modes -contain the mode-specific abbrevs. - - Within each abbrev table, each non-blank line defines one abbrev. -The word at the beginning is the abbrev. The number that appears is -the number of times the abbrev has been expanded. Emacs keeps track of -this to help you see which abbrevs you actually use, in case you want -to eliminate those that you don't use often. The string at the end of -the line is the expansion. - - `M-x edit-abbrevs' allows you to add, change or kill abbrev -definitions by editing a list of them in an Emacs buffer. The list has -the format described above. The buffer of abbrevs is called -`*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key -`C-c C-c' to install the abbrev definitions as specified in the buffer. -The `edit-abbrevs-redefine' command does this. Any abbrevs not -described in the buffer are eliminated when this is done. - - `edit-abbrevs' is actually the same as `list-abbrevs', except that -it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely -displays it in another window. - - -File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs - -Saving Abbrevs -============== - - These commands allow you to keep abbrev definitions between editing -sessions. - -`M-x write-abbrev-file' - Write a file describing all defined abbrevs. - -`M-x read-abbrev-file' - Read such an abbrev file and define abbrevs as specified there. - -`M-x quietly-read-abbrev-file' - Similar, but do not display a message about what is going on. - -`M-x define-abbrevs' - Define abbrevs from buffer. - -`M-x insert-abbrevs' - Insert all abbrevs and their expansions into the buffer. - - Use `M-x write-abbrev-file' to save abbrev definitions for use in a -later session. The command reads a file name using the minibuffer and -writes a description of all current abbrev definitions into the -specified file. The text stored in the file looks like the output of -`M-x list-abbrevs'. - - `M-x read-abbrev-file' prompts for a file name using the minibuffer -and reads the specified file, defining abbrevs according to its -contents. `M-x quietly-read-abbrev-file' is the same but does not -display a message in the echo area; it is actually useful primarily in -the init file. *Note Init File::. If you give an empty argument to -either of these functions, the file name Emacs uses is the value of the -variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'. - - Emacs offers to save abbrevs automatically if you have changed any of -them, whenever it offers to save all files (for `C-x s' or `C-x C-c'). -Set the variable `save-abbrevs' to `nil' to inhibit this feature. - - The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are -similar to the previous commands but work on text in an Emacs buffer. -`M-x insert-abbrevs' inserts text into the current buffer before point, -describing all current abbrev definitions; `M-x define-abbrevs' parses -the entire current buffer and defines abbrevs accordingly. - - -File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs - -Dynamic Abbrev Expansion -======================== - - The abbrev facility described above operates automatically as you -insert text, but all abbrevs must be defined explicitly. By contrast, -"dynamic abbrevs" allow the meanings of abbrevs to be determined -automatically from the contents of the buffer, but dynamic abbrev -expansion happens only when you request it explicitly. - -`M-/' - Expand the word in the buffer before point as a "dynamic abbrev", - by searching in the buffer for words starting with that - abbreviation (`dabbrev-expand'). - - For example, if the buffer contains `does this follow ' and you type -`f o M-/', the effect is to insert `follow' because that is the last -word in the buffer that starts with `fo'. A numeric argument to `M-/' -says to take the second, third, etc. distinct expansion found looking -backward from point. Repeating `M-/' searches for an alternative -expansion by looking farther back. After the entire buffer before -point has been considered, the buffer after point is searched. - - Dynamic abbrev expansion is completely independent of Abbrev mode; -the expansion of a word with `M-/' is completely independent of whether -it has a definition as an ordinary abbrev. - - -File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top - -Editing Pictures -**************** - - If you want to create a picture made out of text characters (for -example, a picture of the division of a register into fields, as a -comment in a program), use the command `edit-picture' to enter Picture -mode. - - In Picture mode, editing is based on the "quarter-plane" model of -text. In this model, the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the -end of a line does not exist in this model; the most you can say is -where the last non-blank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But in Picture mode most -frequently-used keys are rebound to commands that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture -mode to do essentially the same thing but in a quarter-plane way. In -addition, Picture mode defines various keys starting with the `C-c' -prefix to run special picture editing commands. - - One of these keys, `C-c C-c', is pretty important. Often a picture -is part of a larger file that is usually edited in some other major -mode. `M-x edit-picture' records the name of the previous major mode. -You can then use the `C-c C-c' command (`picture-mode-exit') to restore -that mode. `C-c C-c' also deletes spaces from the ends of lines, -unless you give it a numeric argument. - - The commands used in Picture mode all work in other modes (provided -the `picture' library is loaded), but are only bound to keys in -Picture mode. Note that the descriptions below talk of moving "one -column" and so on, but all the picture mode commands handle numeric -arguments as their normal equivalents do. - - Turning on Picture mode calls the value of the variable -`picture-mode-hook' as a function, with no arguments, if that value -exists and is non-`nil'. - -* Menu: - -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. - - -File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture - -Basic Editing in Picture Mode -============================= - - Most keys do the same thing in Picture mode that they usually do, -but do it in a quarter-plane style. For example, `C-f' is rebound to -run `picture-forward-column', which moves point one column to the -right, by inserting a space if necessary, so that the actual end of the -line makes no difference. `C-b' is rebound to run -`picture-backward-column', which always moves point left one column, -converting a tab to multiple spaces if necessary. `C-n' and `C-p' are -rebound to run `picture-move-down' and `picture-move-up', which can -either insert spaces or convert tabs as necessary to make sure that -point stays in exactly the same column. `C-e' runs -`picture-end-of-line', which moves to after the last non-blank -character on the line. There was no need to change `C-a', as the choice -of screen model does not affect beginnings of lines. - - Insertion of text is adapted to the quarter-plane screen model -through the use of Overwrite mode (*note Minor Modes::). -Self-inserting characters replace existing text, column by column, -rather than pushing existing text to the right. runs -`picture-newline', which just moves to the beginning of the following -line so that new text will replace that line. - - Text is erased instead of deleted and killed. -(`picture-backward-clear-column') replaces the preceding character with -a space rather than removing it. `C-d' (`picture-clear-column') does -the same in a forward direction. `C-k' (`picture-clear-line') really -kills the contents of lines, but never removes the newlines from a -buffer. - - To do actual insertion, you must use special commands. `C-o' -(`picture-open-line') creates a blank line, but does so after the -current line; it never splits a line. `C-M-o', `split-line', makes -sense in Picture mode, so it remains unchanged. -(`picture-duplicate-line') inserts another line with the same contents -below the current line. - - To actually delete parts of the picture, use `C-w', or with `C-c -C-d' (which is defined as `delete-char', as `C-d' is in other modes), -or with one of the picture rectangle commands (*note Rectangles in -Picture::). - - -File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture - -Controlling Motion After Insert -=============================== - - Since "self-inserting" characters just overwrite and move point in -Picture mode, there is no essential restriction on how point should be -moved. Normally point moves right, but you can specify any of the eight -orthogonal or diagonal directions for motion after a "self-inserting" -character. This is useful for drawing lines in the buffer. - -`C-c <' - Move left after insertion (`picture-movement-left'). - -`C-c >' - Move right after insertion (`picture-movement-right'). - -`C-c ^' - Move up after insertion (`picture-movement-up'). - -`C-c .' - Move down after insertion (`picture-movement-down'). - -`C-c `' - Move up and left ("northwest") after insertion - (`picture-movement-nw'). - -`C-c '' - Move up and right ("northeast") after insertion - (`picture-movement-ne'). - -`C-c /' - Move down and left ("southwest") after insertion - (`picture-movement-sw'). - -`C-c \' - Move down and right ("southeast") after insertion - (`picture-movement-se'). - - Two motion commands move based on the current Picture insertion -direction. The command `C-c C-f' (`picture-motion') moves in the same -direction as motion after "insertion" currently does, while `C-c C-b' -(`picture-motion-reverse') moves in the opposite direction. - - -File: xemacs.info, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture - -Picture Mode Tabs -================= - - Two kinds of tab-like action are provided in Picture mode. -Context-based tabbing is done with `M-' (`picture-tab-search'). -With no argument, it moves to a point underneath the next "interesting" -character that follows whitespace in the previous non-blank line. -"Next" here means "appearing at a horizontal position greater than the -one point starts out at". With an argument, as in `C-u M-', the -command moves to the next such interesting character in the current -line. `M-' does not change the text; it only moves point. -"Interesting" characters are defined by the variable -`picture-tab-chars', which contains a string of characters considered -interesting. Its default value is `"!-~"'. - - itself runs `picture-tab', which operates based on the current -tab stop settings; it is the Picture mode equivalent of -`tab-to-tab-stop'. Without arguments it just moves point, but with a -numeric argument it clears the text that it moves over. - - The context-based and tab-stop-based forms of tabbing are brought -together by the command `C-c ' (`picture-set-tab-stops'.) This -command sets the tab stops to the positions which `M-' would -consider significant in the current line. If you use this command with -, you can get the effect of context-based tabbing. But `M-' -is more convenient in the cases where it is sufficient. - - -File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture - -Picture Mode Rectangle Commands -=============================== - - Picture mode defines commands for working on rectangular pieces of -the text in ways that fit with the quarter-plane model. The standard -rectangle commands may also be useful (*note Rectangles::). - -`C-c C-k' - Clear out the region-rectangle (`picture-clear-rectangle'). With - argument, kill it. - -`C-c C-w R' - Similar but save rectangle contents in register R first - (`picture-clear-rectangle-to-register'). - -`C-c C-y' - Copy last killed rectangle into the buffer by overwriting, with - upper left corner at point (`picture-yank-rectangle'). With - argument, insert instead. - -`C-c C-x R' - Similar, but use the rectangle in register R - (`picture-yank-rectangle-from-register'). - - The picture rectangle commands `C-c C-k' (`picture-clear-rectangle') -and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the -standard rectangle commands in that they normally clear the rectangle -instead of deleting it; this is analogous with the way `C-d' is changed -in Picture mode. - - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. - - The Picture mode commands for yanking rectangles differ from the -standard ones in overwriting instead of inserting. This is the same -way that Picture mode insertion of other text is different from other -modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting) -the rectangle that was most recently killed, while `C-c C-x' -(`picture-yank-rectangle-from-register') does for the rectangle found -in a specified register. - - Since most region commands in Picture mode operate on rectangles, -when you select a region of text with the mouse in Picture mode, it is -highlighted as a rectangle. - - -File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top - -Sending Mail -************ - - To send a message in Emacs, start by typing the command (`C-x m') to -select and initialize the `*mail*' buffer. You can then edit the text -and headers of the message in the mail buffer, and type the command -(`C-c C-c') to send the message. - -`C-x m' - Begin composing a message to send (`mail'). - -`C-x 4 m' - Likewise, but display the message in another window - (`mail-other-window'). - -`C-c C-c' - In Mail mode, send the message and switch to another buffer - (`mail-send-and-exit'). - - The command `C-x m' (`mail') selects a buffer named `*mail*' and -initializes it with the skeleton of an outgoing message. `C-x 4 m' -(`mail-other-window') selects the `*mail*' buffer in a different -window, leaving the previous current buffer visible. - - Because the buffer for mail composition is an ordinary Emacs buffer, -you can switch to other buffers while in the middle of composing mail, -and switch back later (or never). If you use the `C-x m' command again -when you have been composing another message but have not sent it, a -new mail buffer will be created; in this way, you can compose multiple -messages at once. You can switch back to and complete an unsent -message by using the normal buffer selection mechanisms. - - `C-u C-x m' is another way to switch back to a message in progress: -it will search for an existing, unsent mail message buffer and select -it. - -* Menu: - -* Format: Mail Format. Format of the mail being composed. -* Headers: Mail Headers. Details of allowed mail header fields. -* Mode: Mail Mode. Special commands for editing mail being composed. - - -File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail - -The Format of the Mail Buffer -============================= - - In addition to the "text" or contents, a message has "header -fields", which say who sent it, when, to whom, why, and so on. Some -header fields, such as the date and sender, are created automatically -after the message is sent. Others, such as the recipient names, must -be specified by you in order to send the message properly. - - Mail mode provides a few commands to help you edit some header -fields, and some are preinitialized in the buffer automatically at -times. You can insert or edit any header fields using ordinary editing -commands. - - The line in the buffer that says: - - --text follows this line-- - -is a special delimiter that separates the headers you have specified -from the text. Whatever follows this line is the text of the message; -the headers precede it. The delimiter line itself does not appear in -the message actually sent. The text used for the delimiter line is -controlled by the variable `mail-header-separator'. - - Here is an example of what the headers and text in the `*mail*' -buffer might look like. - - To: rms@mc - CC: mly@mc, rg@oz - Subject: The XEmacs User's Manual - --Text follows this line-- - Please ignore this message. - - -File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail - -Mail Header Fields -================== - - There are several header fields you can use in the `*mail*' buffer. -Each header field starts with a field name at the beginning of a line, -terminated by a colon. It does not matter whether you use upper or -lower case in the field name. After the colon and optional whitespace -comes the contents of the field. - -`To' - This field contains the mailing addresses of the message. - -`Subject' - The contents of the `Subject' field should be a piece of text that - says what the message is about. Subject fields are useful because - most mail-reading programs can provide a summary of messages, - listing the subject of each message but not its text. - -`CC' - This field contains additional mailing addresses to send the - message to, but whose readers should not regard the message as - addressed to them. - -`BCC' - This field contains additional mailing addresses to send the - message to, but which should not appear in the header of the - message actually sent. - -`FCC' - This field contains the name of one file (in Unix mail file - format) to which a copy of the message should be appended when the - message is sent. - -`From' - Use the `From' field to say who you are, when the account you are - using to send the mail is not your own. The contents of the - `From' field should be a valid mailing address, since replies will - normally go there. - -`Reply-To' - Use the `Reply-To' field to direct replies to a different address, - not your own. `From' and `Reply-To' have the same effect on where - replies go, but they convey a different meaning to the person who - reads the message. - -`In-Reply-To' - This field contains a piece of text describing a message you are - replying to. Some mail systems can use the information to - correlate related pieces of mail. This field is normally filled - in by your mail handling package when you are replying to a - message and you never need to think about it. - -The `To', `CC', `BCC' and `FCC' fields can appear any number of times, -to specify many places to send the message. - -The `To', `CC', and `BCC', fields can have continuation lines. All the -lines starting with whitespace, following the line on which the field -starts, are considered part of the field. For example, - - To: foo@here, this@there, - me@gnu.cambridge.mass.usa.earth.spiral3281 - -If you have a `~/.mailrc' file, Emacs scans it for mail aliases the -first time you try to send mail in an Emacs session. Emacs expands -aliases found in the `To', `CC', and `BCC' fields where appropriate. -You can set the variable `mail-abbrev-mailrc-file' to the name of the -file with mail aliases. If `nil', `~/.mailrc' is used. - - Your `.mailrc' file ensures that word-abbrevs are defined for each -of your mail aliases when point is in a `To', `CC', `BCC', or `From' -field. The aliases are defined in your `.mailrc' file or in a file -specified by the MAILRC environment variable if it exists. Your mail -aliases expand any time you type a word-delimiter at the end of an -abbreviation. - - In this version of Emacs, what you see is what you get: in contrast -to some other versions, no abbreviations are expanded after you have -sent the mail. This means you don't suffer the annoyance of having the -system do things behind your back--if the system rewrites an address -you typed, you know it immediately, instead of after the mail has been -sent and it's too late to do anything about it. For example, you will -never again be in trouble because you forgot to delete an old alias -from your `.mailrc' and a new local user is given a userid which -conflicts with one of your aliases. - - Your mail alias abbrevs are in effect only when point is in an -appropriate header field. The mail aliases will not expand in the body -of the message, or in other header fields. The default mode-specific -abbrev table `mail-mode-abbrev-table' is used instead if defined. That -means if you have been using mail-mode specific abbrevs, this code will -not adversely affect you. You can control which header fields the -abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'. - - If auto-fill mode is on, abbrevs wrap at commas instead of at word -boundaries, and header continuation lines will be properly indented. - - You can also insert a mail alias with -`mail-interactive-insert-alias'. This function, which is bound to `C-c -C-a', prompts you for an alias (with completion) and inserts its -expansion at point. - - In this version of Emacs, it is possible to have lines like the -following in your `.mailrc' file: - - alias someone "John Doe " - - That is, if you want an address to have embedded spaces, simply -surround it with double-quotes. The quotes are necessary because the -format of the `.mailrc' file uses spaces as address delimiters. - - Aliases in the `.mailrc' file may be nested. For example, assume you -define aliases like: - alias group1 fred ethel - alias group2 larry curly moe - alias everybody group1 group2 - - When you now type `everybody' on the `To' line, it will expand to: - fred, ethyl, larry, curly, moe - - Aliases may contain forward references; the alias of `everybody' in -the example above can precede the aliases of `group1' and `group2'. - - In this version of Emacs, you can use the `source' `.mailrc' command -for reading aliases from some other file as well. - - Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even -though word-abbrevs normally cannot contain hyphens. - - To read in the contents of another `.mailrc'-type file from Emacs, -use the command `M-x merge-mail-aliases'. The `rebuild-mail-aliases' -command is similar, but deletes existing aliases first. - - If you want multiple addresses separated by a string other than `,' -(a comma), then set the variable `mail-alias-separator-string' to it. -This has to be a comma bracketed by whitespace if you want any kind of -reasonable behavior. - - If the variable `mail-archive-file-name' is non-`nil', it should be -a string naming a file. Each time you start to edit a message to send, -an `FCC' field is entered for that file. Unless you remove the `FCC' -field, every message is written into that file when it is sent. - diff --git a/info/xemacs.info-14 b/info/xemacs.info-14 index f3b8478..5147bce 100644 --- a/info/xemacs.info-14 +++ b/info/xemacs.info-14 @@ -30,6 +30,640 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs + +Controlling Abbrev Expansion +============================ + + An abbrev expands whenever it is in a buffer just before point and +you type a self-inserting punctuation character (, comma, etc.). +Most often an abbrev is used by inserting the abbrev followed by +punctuation. + + Abbrev expansion preserves case; thus, `foo' expands into `find +outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER +OTTER' or `Find Outer Otter' according to the variable +`abbrev-all-caps' (a non-`nil' value chooses the first of the two +expansions). + + Two commands are available to control abbrev expansion: + +`M-'' + Separate a prefix from a following abbrev to be expanded + (`abbrev-prefix-mark'). + +`C-x a e' + Expand the abbrev before point (`expand-abbrev'). This is + effective even when Abbrev mode is not enabled. + +`M-x unexpand-abbrev' + Undo last abbrev expansion. + +`M-x expand-region-abbrevs' + Expand some or all abbrevs found in the region. + + You may wish to expand an abbrev with a prefix attached. For +example, if `cnst' expands into `construction', you may want to use it +to enter `reconstruction'. It does not work to type `recnst', because +that is not necessarily a defined abbrev. Instead, you can use the +command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the +abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a +minus sign in the buffer to indicate that it has done its work. Then +insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now +insert a punctuation character to expand the abbrev `cnst' into +`construction'. The minus sign is deleted at this point by `M-''. The +resulting text is the desired `reconstruction'. + + If you actually want the text of the abbrev in the buffer, rather +than its expansion, insert the following punctuation with `C-q'. Thus, +`foo C-q -' leaves `foo-' in the buffer. + + If you expand an abbrev by mistake, you can undo the expansion +(replace the expansion by the original abbrev text) with `M-x +unexpand-abbrev'. You can also use `C-_' (`undo') to undo the +expansion; but that will first undo the insertion of the punctuation +character. + + `M-x expand-region-abbrevs' searches through the region for defined +abbrevs, and offers to replace each one it finds with its expansion. +This command is useful if you have typed text using abbrevs but forgot +to turn on Abbrev mode first. It may also be useful together with a +special set of abbrev definitions for making several global +replacements at once. The command is effective even if Abbrev mode is +not enabled. + + +File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs + +Examining and Editing Abbrevs +============================= + +`M-x list-abbrevs' + Print a list of all abbrev definitions. + +`M-x edit-abbrevs' + Edit a list of abbrevs; you can add, alter, or remove definitions. + + The output from `M-x list-abbrevs' looks like this: + + (lisp-mode-abbrev-table) + "dk" 0 "define-key" + (global-abbrev-table) + "dfn" 0 "definition" + +(Some blank lines of no semantic significance, and some other abbrev +tables, have been omitted.) + + A line containing a name in parentheses is the header for abbrevs in +a particular abbrev table; `global-abbrev-table' contains all the global +abbrevs, and the other abbrev tables that are named after major modes +contain the mode-specific abbrevs. + + Within each abbrev table, each non-blank line defines one abbrev. +The word at the beginning is the abbrev. The number that appears is +the number of times the abbrev has been expanded. Emacs keeps track of +this to help you see which abbrevs you actually use, in case you want +to eliminate those that you don't use often. The string at the end of +the line is the expansion. + + `M-x edit-abbrevs' allows you to add, change or kill abbrev +definitions by editing a list of them in an Emacs buffer. The list has +the format described above. The buffer of abbrevs is called +`*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key +`C-c C-c' to install the abbrev definitions as specified in the buffer. +The `edit-abbrevs-redefine' command does this. Any abbrevs not +described in the buffer are eliminated when this is done. + + `edit-abbrevs' is actually the same as `list-abbrevs', except that +it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely +displays it in another window. + + +File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs + +Saving Abbrevs +============== + + These commands allow you to keep abbrev definitions between editing +sessions. + +`M-x write-abbrev-file' + Write a file describing all defined abbrevs. + +`M-x read-abbrev-file' + Read such an abbrev file and define abbrevs as specified there. + +`M-x quietly-read-abbrev-file' + Similar, but do not display a message about what is going on. + +`M-x define-abbrevs' + Define abbrevs from buffer. + +`M-x insert-abbrevs' + Insert all abbrevs and their expansions into the buffer. + + Use `M-x write-abbrev-file' to save abbrev definitions for use in a +later session. The command reads a file name using the minibuffer and +writes a description of all current abbrev definitions into the +specified file. The text stored in the file looks like the output of +`M-x list-abbrevs'. + + `M-x read-abbrev-file' prompts for a file name using the minibuffer +and reads the specified file, defining abbrevs according to its +contents. `M-x quietly-read-abbrev-file' is the same but does not +display a message in the echo area; it is actually useful primarily in +the init file. *Note Init File::. If you give an empty argument to +either of these functions, the file name Emacs uses is the value of the +variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'. + + Emacs offers to save abbrevs automatically if you have changed any of +them, whenever it offers to save all files (for `C-x s' or `C-x C-c'). +Set the variable `save-abbrevs' to `nil' to inhibit this feature. + + The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are +similar to the previous commands but work on text in an Emacs buffer. +`M-x insert-abbrevs' inserts text into the current buffer before point, +describing all current abbrev definitions; `M-x define-abbrevs' parses +the entire current buffer and defines abbrevs accordingly. + + +File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs + +Dynamic Abbrev Expansion +======================== + + The abbrev facility described above operates automatically as you +insert text, but all abbrevs must be defined explicitly. By contrast, +"dynamic abbrevs" allow the meanings of abbrevs to be determined +automatically from the contents of the buffer, but dynamic abbrev +expansion happens only when you request it explicitly. + +`M-/' + Expand the word in the buffer before point as a "dynamic abbrev", + by searching in the buffer for words starting with that + abbreviation (`dabbrev-expand'). + + For example, if the buffer contains `does this follow ' and you type +`f o M-/', the effect is to insert `follow' because that is the last +word in the buffer that starts with `fo'. A numeric argument to `M-/' +says to take the second, third, etc. distinct expansion found looking +backward from point. Repeating `M-/' searches for an alternative +expansion by looking farther back. After the entire buffer before +point has been considered, the buffer after point is searched. + + Dynamic abbrev expansion is completely independent of Abbrev mode; +the expansion of a word with `M-/' is completely independent of whether +it has a definition as an ordinary abbrev. + + +File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top + +Editing Pictures +**************** + + If you want to create a picture made out of text characters (for +example, a picture of the division of a register into fields, as a +comment in a program), use the command `edit-picture' to enter Picture +mode. + + In Picture mode, editing is based on the "quarter-plane" model of +text. In this model, the text characters lie studded on an area that +stretches infinitely far to the right and downward. The concept of the +end of a line does not exist in this model; the most you can say is +where the last non-blank character on the line is found. + + Of course, Emacs really always considers text as a sequence of +characters, and lines really do have ends. But in Picture mode most +frequently-used keys are rebound to commands that simulate the +quarter-plane model of text. They do this by inserting spaces or by +converting tabs to spaces. + + Most of the basic editing commands of Emacs are redefined by Picture +mode to do essentially the same thing but in a quarter-plane way. In +addition, Picture mode defines various keys starting with the `C-c' +prefix to run special picture editing commands. + + One of these keys, `C-c C-c', is pretty important. Often a picture +is part of a larger file that is usually edited in some other major +mode. `M-x edit-picture' records the name of the previous major mode. +You can then use the `C-c C-c' command (`picture-mode-exit') to restore +that mode. `C-c C-c' also deletes spaces from the ends of lines, +unless you give it a numeric argument. + + The commands used in Picture mode all work in other modes (provided +the `picture' library is loaded), but are only bound to keys in +Picture mode. Note that the descriptions below talk of moving "one +column" and so on, but all the picture mode commands handle numeric +arguments as their normal equivalents do. + + Turning on Picture mode calls the value of the variable +`picture-mode-hook' as a function, with no arguments, if that value +exists and is non-`nil'. + +* Menu: + +* Basic Picture:: Basic concepts and simple commands of Picture Mode. +* Insert in Picture:: Controlling direction of cursor motion + after "self-inserting" characters. +* Tabs in Picture:: Various features for tab stops and indentation. +* Rectangles in Picture:: Clearing and superimposing rectangles. + + +File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture + +Basic Editing in Picture Mode +============================= + + Most keys do the same thing in Picture mode that they usually do, +but do it in a quarter-plane style. For example, `C-f' is rebound to +run `picture-forward-column', which moves point one column to the +right, by inserting a space if necessary, so that the actual end of the +line makes no difference. `C-b' is rebound to run +`picture-backward-column', which always moves point left one column, +converting a tab to multiple spaces if necessary. `C-n' and `C-p' are +rebound to run `picture-move-down' and `picture-move-up', which can +either insert spaces or convert tabs as necessary to make sure that +point stays in exactly the same column. `C-e' runs +`picture-end-of-line', which moves to after the last non-blank +character on the line. There was no need to change `C-a', as the choice +of screen model does not affect beginnings of lines. + + Insertion of text is adapted to the quarter-plane screen model +through the use of Overwrite mode (*note Minor Modes::). +Self-inserting characters replace existing text, column by column, +rather than pushing existing text to the right. runs +`picture-newline', which just moves to the beginning of the following +line so that new text will replace that line. + + Text is erased instead of deleted and killed. +(`picture-backward-clear-column') replaces the preceding character with +a space rather than removing it. `C-d' (`picture-clear-column') does +the same in a forward direction. `C-k' (`picture-clear-line') really +kills the contents of lines, but never removes the newlines from a +buffer. + + To do actual insertion, you must use special commands. `C-o' +(`picture-open-line') creates a blank line, but does so after the +current line; it never splits a line. `C-M-o', `split-line', makes +sense in Picture mode, so it remains unchanged. +(`picture-duplicate-line') inserts another line with the same contents +below the current line. + + To actually delete parts of the picture, use `C-w', or with `C-c +C-d' (which is defined as `delete-char', as `C-d' is in other modes), +or with one of the picture rectangle commands (*note Rectangles in +Picture::). + + +File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture + +Controlling Motion After Insert +=============================== + + Since "self-inserting" characters just overwrite and move point in +Picture mode, there is no essential restriction on how point should be +moved. Normally point moves right, but you can specify any of the eight +orthogonal or diagonal directions for motion after a "self-inserting" +character. This is useful for drawing lines in the buffer. + +`C-c <' + Move left after insertion (`picture-movement-left'). + +`C-c >' + Move right after insertion (`picture-movement-right'). + +`C-c ^' + Move up after insertion (`picture-movement-up'). + +`C-c .' + Move down after insertion (`picture-movement-down'). + +`C-c `' + Move up and left ("northwest") after insertion + (`picture-movement-nw'). + +`C-c '' + Move up and right ("northeast") after insertion + (`picture-movement-ne'). + +`C-c /' + Move down and left ("southwest") after insertion + (`picture-movement-sw'). + +`C-c \' + Move down and right ("southeast") after insertion + (`picture-movement-se'). + + Two motion commands move based on the current Picture insertion +direction. The command `C-c C-f' (`picture-motion') moves in the same +direction as motion after "insertion" currently does, while `C-c C-b' +(`picture-motion-reverse') moves in the opposite direction. + + +File: xemacs.info, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture + +Picture Mode Tabs +================= + + Two kinds of tab-like action are provided in Picture mode. +Context-based tabbing is done with `M-' (`picture-tab-search'). +With no argument, it moves to a point underneath the next "interesting" +character that follows whitespace in the previous non-blank line. +"Next" here means "appearing at a horizontal position greater than the +one point starts out at". With an argument, as in `C-u M-', the +command moves to the next such interesting character in the current +line. `M-' does not change the text; it only moves point. +"Interesting" characters are defined by the variable +`picture-tab-chars', which contains a string of characters considered +interesting. Its default value is `"!-~"'. + + itself runs `picture-tab', which operates based on the current +tab stop settings; it is the Picture mode equivalent of +`tab-to-tab-stop'. Without arguments it just moves point, but with a +numeric argument it clears the text that it moves over. + + The context-based and tab-stop-based forms of tabbing are brought +together by the command `C-c ' (`picture-set-tab-stops'.) This +command sets the tab stops to the positions which `M-' would +consider significant in the current line. If you use this command with +, you can get the effect of context-based tabbing. But `M-' +is more convenient in the cases where it is sufficient. + + +File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture + +Picture Mode Rectangle Commands +=============================== + + Picture mode defines commands for working on rectangular pieces of +the text in ways that fit with the quarter-plane model. The standard +rectangle commands may also be useful (*note Rectangles::). + +`C-c C-k' + Clear out the region-rectangle (`picture-clear-rectangle'). With + argument, kill it. + +`C-c C-w R' + Similar but save rectangle contents in register R first + (`picture-clear-rectangle-to-register'). + +`C-c C-y' + Copy last killed rectangle into the buffer by overwriting, with + upper left corner at point (`picture-yank-rectangle'). With + argument, insert instead. + +`C-c C-x R' + Similar, but use the rectangle in register R + (`picture-yank-rectangle-from-register'). + + The picture rectangle commands `C-c C-k' (`picture-clear-rectangle') +and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the +standard rectangle commands in that they normally clear the rectangle +instead of deleting it; this is analogous with the way `C-d' is changed +in Picture mode. + + However, deletion of rectangles can be useful in Picture mode, so +these commands delete the rectangle if given a numeric argument. + + The Picture mode commands for yanking rectangles differ from the +standard ones in overwriting instead of inserting. This is the same +way that Picture mode insertion of other text is different from other +modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting) +the rectangle that was most recently killed, while `C-c C-x' +(`picture-yank-rectangle-from-register') does for the rectangle found +in a specified register. + + Since most region commands in Picture mode operate on rectangles, +when you select a region of text with the mouse in Picture mode, it is +highlighted as a rectangle. + + +File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top + +Sending Mail +************ + + To send a message in Emacs, start by typing the command (`C-x m') to +select and initialize the `*mail*' buffer. You can then edit the text +and headers of the message in the mail buffer, and type the command +(`C-c C-c') to send the message. + +`C-x m' + Begin composing a message to send (`mail'). + +`C-x 4 m' + Likewise, but display the message in another window + (`mail-other-window'). + +`C-c C-c' + In Mail mode, send the message and switch to another buffer + (`mail-send-and-exit'). + + The command `C-x m' (`mail') selects a buffer named `*mail*' and +initializes it with the skeleton of an outgoing message. `C-x 4 m' +(`mail-other-window') selects the `*mail*' buffer in a different +window, leaving the previous current buffer visible. + + Because the buffer for mail composition is an ordinary Emacs buffer, +you can switch to other buffers while in the middle of composing mail, +and switch back later (or never). If you use the `C-x m' command again +when you have been composing another message but have not sent it, a +new mail buffer will be created; in this way, you can compose multiple +messages at once. You can switch back to and complete an unsent +message by using the normal buffer selection mechanisms. + + `C-u C-x m' is another way to switch back to a message in progress: +it will search for an existing, unsent mail message buffer and select +it. + +* Menu: + +* Format: Mail Format. Format of the mail being composed. +* Headers: Mail Headers. Details of allowed mail header fields. +* Mode: Mail Mode. Special commands for editing mail being composed. + + +File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail + +The Format of the Mail Buffer +============================= + + In addition to the "text" or contents, a message has "header +fields", which say who sent it, when, to whom, why, and so on. Some +header fields, such as the date and sender, are created automatically +after the message is sent. Others, such as the recipient names, must +be specified by you in order to send the message properly. + + Mail mode provides a few commands to help you edit some header +fields, and some are preinitialized in the buffer automatically at +times. You can insert or edit any header fields using ordinary editing +commands. + + The line in the buffer that says: + + --text follows this line-- + +is a special delimiter that separates the headers you have specified +from the text. Whatever follows this line is the text of the message; +the headers precede it. The delimiter line itself does not appear in +the message actually sent. The text used for the delimiter line is +controlled by the variable `mail-header-separator'. + + Here is an example of what the headers and text in the `*mail*' +buffer might look like. + + To: rms@mc + CC: mly@mc, rg@oz + Subject: The XEmacs User's Manual + --Text follows this line-- + Please ignore this message. + + +File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail + +Mail Header Fields +================== + + There are several header fields you can use in the `*mail*' buffer. +Each header field starts with a field name at the beginning of a line, +terminated by a colon. It does not matter whether you use upper or +lower case in the field name. After the colon and optional whitespace +comes the contents of the field. + +`To' + This field contains the mailing addresses of the message. + +`Subject' + The contents of the `Subject' field should be a piece of text that + says what the message is about. Subject fields are useful because + most mail-reading programs can provide a summary of messages, + listing the subject of each message but not its text. + +`CC' + This field contains additional mailing addresses to send the + message to, but whose readers should not regard the message as + addressed to them. + +`BCC' + This field contains additional mailing addresses to send the + message to, but which should not appear in the header of the + message actually sent. + +`FCC' + This field contains the name of one file (in Unix mail file + format) to which a copy of the message should be appended when the + message is sent. + +`From' + Use the `From' field to say who you are, when the account you are + using to send the mail is not your own. The contents of the + `From' field should be a valid mailing address, since replies will + normally go there. + +`Reply-To' + Use the `Reply-To' field to direct replies to a different address, + not your own. `From' and `Reply-To' have the same effect on where + replies go, but they convey a different meaning to the person who + reads the message. + +`In-Reply-To' + This field contains a piece of text describing a message you are + replying to. Some mail systems can use the information to + correlate related pieces of mail. This field is normally filled + in by your mail handling package when you are replying to a + message and you never need to think about it. + +The `To', `CC', `BCC' and `FCC' fields can appear any number of times, +to specify many places to send the message. + +The `To', `CC', and `BCC', fields can have continuation lines. All the +lines starting with whitespace, following the line on which the field +starts, are considered part of the field. For example, + + To: foo@here, this@there, + me@gnu.cambridge.mass.usa.earth.spiral3281 + +If you have a `~/.mailrc' file, Emacs scans it for mail aliases the +first time you try to send mail in an Emacs session. Emacs expands +aliases found in the `To', `CC', and `BCC' fields where appropriate. +You can set the variable `mail-abbrev-mailrc-file' to the name of the +file with mail aliases. If `nil', `~/.mailrc' is used. + + Your `.mailrc' file ensures that word-abbrevs are defined for each +of your mail aliases when point is in a `To', `CC', `BCC', or `From' +field. The aliases are defined in your `.mailrc' file or in a file +specified by the MAILRC environment variable if it exists. Your mail +aliases expand any time you type a word-delimiter at the end of an +abbreviation. + + In this version of Emacs, what you see is what you get: in contrast +to some other versions, no abbreviations are expanded after you have +sent the mail. This means you don't suffer the annoyance of having the +system do things behind your back--if the system rewrites an address +you typed, you know it immediately, instead of after the mail has been +sent and it's too late to do anything about it. For example, you will +never again be in trouble because you forgot to delete an old alias +from your `.mailrc' and a new local user is given a userid which +conflicts with one of your aliases. + + Your mail alias abbrevs are in effect only when point is in an +appropriate header field. The mail aliases will not expand in the body +of the message, or in other header fields. The default mode-specific +abbrev table `mail-mode-abbrev-table' is used instead if defined. That +means if you have been using mail-mode specific abbrevs, this code will +not adversely affect you. You can control which header fields the +abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'. + + If auto-fill mode is on, abbrevs wrap at commas instead of at word +boundaries, and header continuation lines will be properly indented. + + You can also insert a mail alias with +`mail-interactive-insert-alias'. This function, which is bound to `C-c +C-a', prompts you for an alias (with completion) and inserts its +expansion at point. + + In this version of Emacs, it is possible to have lines like the +following in your `.mailrc' file: + + alias someone "John Doe " + + That is, if you want an address to have embedded spaces, simply +surround it with double-quotes. The quotes are necessary because the +format of the `.mailrc' file uses spaces as address delimiters. + + Aliases in the `.mailrc' file may be nested. For example, assume you +define aliases like: + alias group1 fred ethel + alias group2 larry curly moe + alias everybody group1 group2 + + When you now type `everybody' on the `To' line, it will expand to: + fred, ethyl, larry, curly, moe + + Aliases may contain forward references; the alias of `everybody' in +the example above can precede the aliases of `group1' and `group2'. + + In this version of Emacs, you can use the `source' `.mailrc' command +for reading aliases from some other file as well. + + Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even +though word-abbrevs normally cannot contain hyphens. + + To read in the contents of another `.mailrc'-type file from Emacs, +use the command `M-x merge-mail-aliases'. The `rebuild-mail-aliases' +command is similar, but deletes existing aliases first. + + If you want multiple addresses separated by a string other than `,' +(a comma), then set the variable `mail-alias-separator-string' to it. +This has to be a comma bracketed by whitespace if you want any kind of +reasonable behavior. + + If the variable `mail-archive-file-name' is non-`nil', it should be +a string naming a file. Each time you start to edit a message to send, +an `FCC' field is entered for that file. Unless you remove the `FCC' +field, every message is written into that file when it is sent. + + File: xemacs.info, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail Mail Mode @@ -170,7 +804,7 @@ mode is Calendar mode. particular date; `Buttons3' brings up a menu of commonly used calendar features that are independent of any particular date. To exit the calendar, type `q'. *Note Customizing the Calendar and Diary: -(elisp)Calendar, for customization information about the calendar and +(lispref)Calendar, for customization information about the calendar and diary. * Menu: @@ -611,649 +1245,3 @@ begins on the first Sunday in April. When the daylight savings rules are set up for the United States, Emacs always uses the present definition, even though it is wrong for some prior years. - -File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary - -Times of Sunrise and Sunset ---------------------------- - - Special calendar commands can tell you, to within a minute or two, -the times of sunrise and sunset for any date. - -`S' - Display times of sunrise and sunset for the selected date - (`calendar-sunrise-sunset'). - -`Button2 Sunrise/Sunset' - Display times of sunrise and sunset for the date you click on. - -`M-x sunrise-sunset' - Display times of sunrise and sunset for today's date. - -`C-u M-x sunrise-sunset' - Display times of sunrise and sunset for a specified date. - - Within the calendar, to display the _local times_ of sunrise and -sunset in the echo area, move point to the date you want, and type `S'. -Alternatively, click `Button2' on the date, then choose -`Sunrise/Sunset' from the menu that appears. The command `M-x -sunrise-sunset' is available outside the calendar to display this -information for today's date or a specified date. To specify a date -other than today, use `C-u M-x sunrise-sunset', which prompts for the -year, month, and day. - - You can display the times of sunrise and sunset for any location and -any date with `C-u C-u M-x sunrise-sunset'. This asks you for a -longitude, latitude, number of minutes difference from Coordinated -Universal Time, and date, and then tells you the times of sunrise and -sunset for that location on that date. - - Because the times of sunrise and sunset depend on the location on -earth, you need to tell Emacs your latitude, longitude, and location -name before using these commands. Here is an example of what to set: - - (setq calendar-latitude 40.1) - (setq calendar-longitude -88.2) - (setq calendar-location-name "Urbana, IL") - -Use one decimal place in the values of `calendar-latitude' and -`calendar-longitude'. - - Your time zone also affects the local time of sunrise and sunset. -Emacs usually gets time zone information from the operating system, but -if these values are not what you want (or if the operating system does -not supply them), you must set them yourself. Here is an example: - - (setq calendar-time-zone -360) - (setq calendar-standard-time-zone-name "CST") - (setq calendar-daylight-time-zone-name "CDT") - -The value of `calendar-time-zone' is the number of minutes difference -between your local standard time and Coordinated Universal Time -(Greenwich time). The values of `calendar-standard-time-zone-name' and -`calendar-daylight-time-zone-name' are the abbreviations used in your -time zone. Emacs displays the times of sunrise and sunset _corrected -for daylight savings time_. *Note Daylight Savings::, for how daylight -savings time is determined. - - As a user, you might find it convenient to set the calendar location -variables for your usual physical location in your init file. And when -you install Emacs on a machine, you can create a `default.el' file -which sets them properly for the typical location of most users of that -machine. *Note Init File::. - - -File: xemacs.info, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary - -Phases of the Moon ------------------- - - These calendar commands display the dates and times of the phases of -the moon (new moon, first quarter, full moon, last quarter). This -feature is useful for debugging problems that "depend on the phase of -the moon." - -`M' - Display the dates and times for all the quarters of the moon for - the three-month period shown (`calendar-phases-of-moon'). - -`M-x phases-of-moon' - Display dates and times of the quarters of the moon for three - months around today's date. - - Within the calendar, use the `M' command to display a separate -buffer of the phases of the moon for the current three-month range. The -dates and times listed are accurate to within a few minutes. - - Outside the calendar, use the command `M-x phases-of-moon' to -display the list of the phases of the moon for the current month and the -preceding and succeeding months. For information about a different -month, use `C-u M-x phases-of-moon', which prompts for the month and -year. - - The dates and times given for the phases of the moon are given in -local time (corrected for daylight savings, when appropriate); but if -the variable `calendar-time-zone' is void, Coordinated Universal Time -(the Greenwich time zone) is used. *Note Daylight Savings::. - - -File: xemacs.info, Node: Other Calendars, Next: Calendar Systems, Prev: Lunar Phases, Up: Calendar/Diary - -Conversion To and From Other Calendars --------------------------------------- - - The Emacs calendar displayed is _always_ the Gregorian calendar, -sometimes called the "new style" calendar, which is used in most of the -world today. However, this calendar did not exist before the sixteenth -century and was not widely used before the eighteenth century; it did -not fully displace the Julian calendar and gain universal acceptance -until the early twentieth century. The Emacs calendar can display any -month since January, year 1 of the current era, but the calendar -displayed is the Gregorian, even for a date at which the Gregorian -calendar did not exist. - - While Emacs cannot display other calendars, it can convert dates to -and from several other calendars. - -* Menu: - -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. - - If you are interested in these calendars, you can convert dates one -at a time. Put point on the desired date of the Gregorian calendar and -press the appropriate keys. The `p' is a mnemonic for "print" since -Emacs "prints' the equivalent date in the echo area. - - -File: xemacs.info, Node: Calendar Systems, Next: To Other Calendar, Prev: Other Calendars, Up: Other Calendars - -Supported Calendar Systems -========================== - - The ISO commercial calendar is used largely in Europe. - - The Julian calendar, named after Julius Caesar, was the one used in -Europe throughout medieval times, and in many countries up until the -nineteenth century. - - Astronomers use a simple counting of days elapsed since noon, Monday, -January 1, 4713 B.C. on the Julian calendar. The number of days elapsed -is called the _Julian day number_ or the _Astronomical day number_. - - The Hebrew calendar is used by tradition in the Jewish religion. The -Emacs calendar program uses the Hebrew calendar to determine the dates -of Jewish holidays. Hebrew calendar dates begin and end at sunset. - - The Islamic calendar is used in many predominantly Islamic countries. -Emacs uses it to determine the dates of Islamic holidays. There is no -universal agreement in the Islamic world about the calendar; Emacs uses -a widely accepted version, but the precise dates of Islamic holidays -often depend on proclamation by religious authorities, not on -calculations. As a consequence, the actual dates of observance can vary -slightly from the dates computed by Emacs. Islamic calendar dates begin -and end at sunset. - - The French Revolutionary calendar was created by the Jacobins after -the 1789 revolution, to represent a more secular and nature-based view -of the annual cycle, and to install a 10-day week in a rationalization -measure similar to the metric system. The French government officially -abandoned this calendar at the end of 1805. - - The Maya of Central America used three separate, overlapping calendar -systems, the _long count_, the _tzolkin_, and the _haab_. Emacs knows -about all three of these calendars. Experts dispute the exact -correlation between the Mayan calendar and our calendar; Emacs uses the -Goodman-Martinez-Thompson correlation in its calculations. - - The Copts use a calendar based on the ancient Egyptian solar -calendar. Their calendar consists of twelve 30-day months followed by -an extra five-day period. Once every fourth year they add a leap day -to this extra period to make it six days. The Ethiopic calendar is -identical in structure, but has different year numbers and month names. - - The Persians use a solar calendar based on a design of Omar Khayyam. -Their calendar consists of twelve months of which the first six have 31 -days, the next five have 30 days, and the last has 29 in ordinary years -and 30 in leap years. Leap years occur in a complicated pattern every -four or five years. - - The Chinese calendar is a complicated system of lunar months arranged -into solar years. The years go in cycles of sixty, each year containing -either twelve months in an ordinary year or thirteen months in a leap -year; each month has either 29 or 30 days. Years, ordinary months, and -days are named by combining one of ten "celestial stems" with one of -twelve "terrestrial branches" for a total of sixty names that are -repeated in a cycle of sixty. - - -File: xemacs.info, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars - -Converting To Other Calendars -============================= - - The following commands describe the selected date (the date at point) -in various other calendar systems: - -`Button2 Other Calendars' - Display the date that you click on, expressed in various other - calendars. - -`p c' - Display ISO commercial calendar equivalent for selected day - (`calendar-print-iso-date'). - -`p j' - Display Julian date for selected day - (`calendar-print-julian-date'). - -`p a' - Display astronomical (Julian) day number for selected day - (`calendar-print-astro-day-number'). - -`p h' - Display Hebrew date for selected day - (`calendar-print-hebrew-date'). - -`p i' - Display Islamic date for selected day - (`calendar-print-islamic-date'). - -`p f' - Display French Revolutionary date for selected day - (`calendar-print-french-date'). - -`p C' - Display Chinese date for selected day - (`calendar-print-chinese-date'). - -`p k' - Display Coptic date for selected day - (`calendar-print-coptic-date'). - -`p e' - Display Ethiopic date for selected day - (`calendar-print-ethiopic-date'). - -`p p' - Display Persian date for selected day - (`calendar-print-persian-date'). - -`p m' - Display Mayan date for selected day (`calendar-print-mayan-date'). - - If you are using X, the easiest way to translate a date into other -calendars is to click on it with `Button2', then choose `Other -Calendars' from the menu that appears. This displays the equivalent -forms of the date in all the calendars Emacs understands, in the form of -a menu. (Choosing an alternative from this menu doesn't actually do -anything--the menu is used only for display.) - - Put point on the desired date of the Gregorian calendar, then type -the appropriate keys. The `p' is a mnemonic for "print" since Emacs -"prints" the equivalent date in the echo area. - - -File: xemacs.info, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars - -Converting From Other Calendars -=============================== - - You can use the other supported calendars to specify a date to move -to. This section describes the commands for doing this using calendars -other than Mayan; for the Mayan calendar, see the following section. - -`g c' - Move to a date specified in the ISO commercial calendar - (`calendar-goto-iso-date'). - -`g j' - Move to a date specified in the Julian calendar - (`calendar-goto-julian-date'). - -`g a' - Move to a date specified in astronomical (Julian) day number - (`calendar-goto-astro-day-number'). - -`g h' - Move to a date specified in the Hebrew calendar - (`calendar-goto-hebrew-date'). - -`g i' - Move to a date specified in the Islamic calendar - (`calendar-goto-islamic-date'). - -`g f' - Move to a date specified in the French Revolutionary calendar - (`calendar-goto-french-date'). - -`g C' - Move to a date specified in the Chinese calendar - (`calendar-goto-chinese-date'). - -`g p' - Move to a date specified in the Persian calendar - (`calendar-goto-persian-date'). - -`g k' - Move to a date specified in the Coptic calendar - (`calendar-goto-coptic-date'). - -`g e' - Move to a date specified in the Ethiopic calendar - (`calendar-goto-ethiopic-date'). - - These commands ask you for a date on the other calendar, move point -to the Gregorian calendar date equivalent to that date, and display the -other calendar's date in the echo area. Emacs uses strict completion -(*note Completion::) whenever it asks you to type a month name, so you -don't have to worry about the spelling of Hebrew, Islamic, or French -names. - - One common question concerning the Hebrew calendar is the computation -of the anniversary of a date of death, called a "yahrzeit." The Emacs -calendar includes a facility for such calculations. If you are in the -calendar, the command `M-x list-yahrzeit-dates' asks you for a range of -years and then displays a list of the yahrzeit dates for those years -for the date given by point. If you are not in the calendar, this -command first asks you for the date of death and the range of years, -and then displays the list of yahrzeit dates. - - -File: xemacs.info, Node: Mayan Calendar, Next: Diary, Prev: From Other Calendar, Up: Other Calendars - -Converting from the Mayan Calendar ----------------------------------- - - Here are the commands to select dates based on the Mayan calendar: - -`g m l' - Move to a date specified by the long count calendar - (`calendar-goto-mayan-long-count-date'). - -`g m n t' - Move to the next occurrence of a place in the tzolkin calendar - (`calendar-next-tzolkin-date'). - -`g m p t' - Move to the previous occurrence of a place in the tzolkin calendar - (`calendar-previous-tzolkin-date'). - -`g m n h' - Move to the next occurrence of a place in the haab calendar - (`calendar-next-haab-date'). - -`g m p h' - Move to the previous occurrence of a place in the haab calendar - (`calendar-previous-haab-date'). - -`g m n c' - Move to the next occurrence of a place in the calendar round - (`calendar-next-calendar-round-date'). - -`g m p c' - Move to the previous occurrence of a place in the calendar round - (`calendar-previous-calendar-round-date'). - - To understand these commands, you need to understand the Mayan -calendars. The "long count" is a counting of days with these units: - - 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal - 1 katun = 20 tun 1 baktun = 20 katun - -Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 -tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long -count dates as early as 7.17.18.13.1, but no earlier. When you use the -`g m l' command, type the Mayan long count date with the baktun, katun, -tun, uinal, and kin separated by periods. - - The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of -independent cycles of 13 and 20 days. Since this cycle repeats -endlessly, Emacs provides commands to move backward and forward to the -previous or next point in the cycle. Type `g m p t' to go to the -previous tzolkin date; Emacs asks you for a tzolkin date and moves point -to the previous occurrence of that date. Similarly, type `g m n t' to -go to the next occurrence of a tzolkin date. - - The Mayan haab calendar is a cycle of 365 days arranged as 18 months -of 20 days each, followed a 5-day monthless period. Like the tzolkin -cycle, this cycle repeats endlessly, and there are commands to move -backward and forward to the previous or next point in the cycle. Type -`g m p h' to go to the previous haab date; Emacs asks you for a haab -date and moves point to the previous occurrence of that date. -Similarly, type `g m n h' to go to the next occurrence of a haab date. - - The Maya also used the combination of the tzolkin date and the haab -date. This combination is a cycle of about 52 years called a _calendar -round_. If you type `g m p c', Emacs asks you for both a haab and a -tzolkin date and then moves point to the previous occurrence of that -combination. Use `g m n c' to move point to the next occurrence of a -combination. These commands signal an error if the haab/tzolkin date -combination you have typed is impossible. - - Emacs uses strict completion (*note Completion::) whenever it asks -you to type a Mayan name, so you don't have to worry about spelling. - - -File: xemacs.info, Node: Diary, Next: Calendar Customization, Prev: Mayan Calendar, Up: Calendar/Diary - -The Diary ---------- - - The Emacs diary keeps track of appointments or other events on a -daily basis, in conjunction with the calendar. To use the diary -feature, you must first create a "diary file" containing a list of -events and their dates. Then Emacs can automatically pick out and -display the events for today, for the immediate future, or for any -specified date. - - By default, Emacs uses `~/diary' as the diary file. This is the -same file that the `calendar' utility uses. A sample `~/diary' file is: - - 12/22/1988 Twentieth wedding anniversary!! - &1/1. Happy New Year! - 10/22 Ruth's birthday. - * 21, *: Payday - Tuesday--weekly meeting with grad students at 10am - Supowit, Shen, Bitner, and Kapoor to attend. - 1/13/89 Friday the thirteenth!! - &thu 4pm squash game with Lloyd. - mar 16 Dad's birthday - April 15, 1989 Income tax due. - &* 15 time cards due. - -This example uses extra spaces to align the event descriptions of most -of the entries. Such formatting is purely a matter of taste. - - Although you probably will start by creating a diary manually, Emacs -provides a number of commands to let you view, add, and change diary -entries. You can also share diary entries with other users (*note -Included Diary Files::). - -* Menu: - -* Diary Commands:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. - - -File: xemacs.info, Node: Diary Commands, Next: Format of Diary File, Prev: Diary, Up: Diary - -Commands Displaying Diary Entries ---------------------------------- - - Once you have created a `~/diary' file, you can use the calendar to -view it. You can also view today's events outside of Calendar mode. - -`d' - Display all diary entries for the selected date - (`view-diary-entries'). - -`Button2 Diary' - Display all diary entries for the date you click on. - -`s' - Display the entire diary file (`show-all-diary-entries'). - -`m' - Mark all visible dates that have diary entries - (`mark-diary-entries'). - -`u' - Unmark the calendar window (`calendar-unmark'). - -`M-x print-diary-entries' - Print hard copy of the diary display as it appears. - -`M-x diary' - Display all diary entries for today's date. - -`M-x diary-mail-entries' - Mail yourself email reminders about upcoming diary entries. - - Displaying the diary entries with `d' shows in a separate window the -diary entries for the selected date in the calendar. The mode line of -the new window shows the date of the diary entries and any holidays -that fall on that date. If you specify a numeric argument with `d', it -shows all the diary entries for that many successive days. Thus, `2 d' -displays all the entries for the selected date and for the following -day. - - Another way to display the diary entries for a date is to click -`Button2' on the date, and then choose `Diary' from the menu that -appears. - - To get a broader view of which days are mentioned in the diary, use -the `m' command. This displays the dates that have diary entries in a -different face (or places a `+' after these dates, if display with -multiple faces is not available). The command applies both to the -currently visible months and to other months that subsequently become -visible by scrolling. To turn marking off and erase the current marks, -type `u', which also turns off holiday marks (*note Holidays::). - - To see the full diary file, rather than just some of the entries, use -the `s' command. - - Display of selected diary entries uses the selective display feature -to hide entries that don't apply. - - The diary buffer as you see it is an illusion, so simply printing the -buffer does not print what you see on your screen. There is a special -command to print hard copy of the diary buffer _as it appears_; this -command is `M-x print-diary-entries'. It sends the data directly to -the printer. You can customize it like `lpr-region' (*note Hardcopy::). - - The command `M-x diary' displays the diary entries for the current -date, independently of the calendar display, and optionally for the next -few days as well; the variable `number-of-diary-entries' specifies how -many days to include (*note Customization::). - - If you put `(diary)' in your init file, this automatically displays -a window with the day's diary entries, when you enter Emacs. *Note -Init File::. The mode line of the displayed window shows the date and -any holidays that fall on that date. - - Many users like to receive notice of events in their diary as email. -To send such mail to yourself, use the command `M-x -diary-mail-entries'. A prefix argument specifies how many days -(starting with today) to check; otherwise, the variable -`diary-mail-days' says how many days. - - -File: xemacs.info, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary - -The Diary File --------------- - - Your "diary file" is a file that records events associated with -particular dates. The name of the diary file is specified by the -variable `diary-file'; `~/diary' is the default. The `calendar' -utility program supports a subset of the format allowed by the Emacs -diary facilities, so you can use that utility to view the diary file, -with reasonable results aside from the entries it cannot understand. - - Each entry in the diary file describes one event and consists of one -or more lines. An entry always begins with a date specification at the -left margin. The rest of the entry is simply text to describe the -event. If the entry has more than one line, then the lines after the -first must begin with whitespace to indicate they continue a previous -entry. Lines that do not begin with valid dates and do not continue a -preceding entry are ignored. - - You can inhibit the marking of certain diary entries in the calendar -window; to do this, insert an ampersand (`&') at the beginning of the -entry, before the date. This has no effect on display of the entry in -the diary window; it affects only marks on dates in the calendar -window. Nonmarking entries are especially useful for generic entries -that would otherwise mark many different dates. - - If the first line of a diary entry consists only of the date or day -name with no following blanks or punctuation, then the diary window -display doesn't include that line; only the continuation lines appear. -For example, this entry: - - 02/11/1989 - Bill B. visits Princeton today - 2pm Cognitive Studies Committee meeting - 2:30-5:30 Liz at Lawrenceville - 4:00pm Dentist appt - 7:30pm Dinner at George's - 8:00-10:00pm concert - -appears in the diary window without the date line at the beginning. -This style of entry looks neater when you display just a single day's -entries, but can cause confusion if you ask for more than one day's -entries. - - You can edit the diary entries as they appear in the window, but it -is important to remember that the buffer displayed contains the _entire_ -diary file, with portions of it concealed from view. This means, for -instance, that the `C-f' (`forward-char') command can put point at what -appears to be the end of the line, but what is in reality the middle of -some concealed line. - - _Be careful when editing the diary entries!_ Inserting additional -lines or adding/deleting characters in the middle of a visible line -cannot cause problems, but editing at the end of a line may not do what -you expect. Deleting a line may delete other invisible entries that -follow it. Before editing the diary, it is best to display the entire -file with `s' (`show-all-diary-entries'). - - -File: xemacs.info, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary - -Date Formats ------------- - - Here are some sample diary entries, illustrating different ways of -formatting a date. The examples all show dates in American order -(month, day, year), but Calendar mode supports European order (day, -month, year) as an option. - - 4/20/93 Switch-over to new tabulation system - apr. 25 Start tabulating annual results - 4/30 Results for April are due - */25 Monthly cycle finishes - Friday Don't leave without backing up files - - The first entry appears only once, on April 20, 1993. The second and -third appear every year on the specified dates, and the fourth uses a -wildcard (asterisk) for the month, so it appears on the 25th of every -month. The final entry appears every week on Friday. - - You can use just numbers to express a date, as in `MONTH/DAY' or -`MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date -itself, MONTH and DAY are numbers of one or two digits. The optional -YEAR is also a number, and may be abbreviated to the last two digits; -that is, you can use `11/12/1989' or `11/12/89'. - - Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY, -YEAR', where the month's name can be spelled in full or abbreviated to -three characters (with or without a period). Case is not significant. - - A date may be "generic"; that is, partially unspecified. Then the -entry applies to all dates that match the specification. If the date -does not contain a year, it is generic and applies to any year. -Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any -month, day, or year, respectively. Thus, a diary entry `3/*/*' matches -any day in March of any year; so does `march *'. - - If you prefer the European style of writing dates--in which the day -comes before the month--type `M-x european-calendar' while in the -calendar, or set the variable `european-calendar-style' to `t' _before_ -using any calendar or diary command. This mode interprets all dates in -the diary in the European manner, and also uses European style for -displaying diary dates. (Note that there is no comma after the -MONTHNAME in the European style.) To go back to the (default) American -style of writing dates, type `M-x american-calendar'. - - You can use the name of a day of the week as a generic date which -applies to any date falling on that day of the week. You can abbreviate -the day of the week to three letters (with or without a period) or spell -it in full; case is not significant. - diff --git a/info/xemacs.info-15 b/info/xemacs.info-15 index e790bcd..57f9bb7 100644 --- a/info/xemacs.info-15 +++ b/info/xemacs.info-15 @@ -30,6 +30,652 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary + +Times of Sunrise and Sunset +--------------------------- + + Special calendar commands can tell you, to within a minute or two, +the times of sunrise and sunset for any date. + +`S' + Display times of sunrise and sunset for the selected date + (`calendar-sunrise-sunset'). + +`Button2 Sunrise/Sunset' + Display times of sunrise and sunset for the date you click on. + +`M-x sunrise-sunset' + Display times of sunrise and sunset for today's date. + +`C-u M-x sunrise-sunset' + Display times of sunrise and sunset for a specified date. + + Within the calendar, to display the _local times_ of sunrise and +sunset in the echo area, move point to the date you want, and type `S'. +Alternatively, click `Button2' on the date, then choose +`Sunrise/Sunset' from the menu that appears. The command `M-x +sunrise-sunset' is available outside the calendar to display this +information for today's date or a specified date. To specify a date +other than today, use `C-u M-x sunrise-sunset', which prompts for the +year, month, and day. + + You can display the times of sunrise and sunset for any location and +any date with `C-u C-u M-x sunrise-sunset'. This asks you for a +longitude, latitude, number of minutes difference from Coordinated +Universal Time, and date, and then tells you the times of sunrise and +sunset for that location on that date. + + Because the times of sunrise and sunset depend on the location on +earth, you need to tell Emacs your latitude, longitude, and location +name before using these commands. Here is an example of what to set: + + (setq calendar-latitude 40.1) + (setq calendar-longitude -88.2) + (setq calendar-location-name "Urbana, IL") + +Use one decimal place in the values of `calendar-latitude' and +`calendar-longitude'. + + Your time zone also affects the local time of sunrise and sunset. +Emacs usually gets time zone information from the operating system, but +if these values are not what you want (or if the operating system does +not supply them), you must set them yourself. Here is an example: + + (setq calendar-time-zone -360) + (setq calendar-standard-time-zone-name "CST") + (setq calendar-daylight-time-zone-name "CDT") + +The value of `calendar-time-zone' is the number of minutes difference +between your local standard time and Coordinated Universal Time +(Greenwich time). The values of `calendar-standard-time-zone-name' and +`calendar-daylight-time-zone-name' are the abbreviations used in your +time zone. Emacs displays the times of sunrise and sunset _corrected +for daylight savings time_. *Note Daylight Savings::, for how daylight +savings time is determined. + + As a user, you might find it convenient to set the calendar location +variables for your usual physical location in your init file. And when +you install Emacs on a machine, you can create a `default.el' file +which sets them properly for the typical location of most users of that +machine. *Note Init File::. + + +File: xemacs.info, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary + +Phases of the Moon +------------------ + + These calendar commands display the dates and times of the phases of +the moon (new moon, first quarter, full moon, last quarter). This +feature is useful for debugging problems that "depend on the phase of +the moon." + +`M' + Display the dates and times for all the quarters of the moon for + the three-month period shown (`calendar-phases-of-moon'). + +`M-x phases-of-moon' + Display dates and times of the quarters of the moon for three + months around today's date. + + Within the calendar, use the `M' command to display a separate +buffer of the phases of the moon for the current three-month range. The +dates and times listed are accurate to within a few minutes. + + Outside the calendar, use the command `M-x phases-of-moon' to +display the list of the phases of the moon for the current month and the +preceding and succeeding months. For information about a different +month, use `C-u M-x phases-of-moon', which prompts for the month and +year. + + The dates and times given for the phases of the moon are given in +local time (corrected for daylight savings, when appropriate); but if +the variable `calendar-time-zone' is void, Coordinated Universal Time +(the Greenwich time zone) is used. *Note Daylight Savings::. + + +File: xemacs.info, Node: Other Calendars, Next: Calendar Systems, Prev: Lunar Phases, Up: Calendar/Diary + +Conversion To and From Other Calendars +-------------------------------------- + + The Emacs calendar displayed is _always_ the Gregorian calendar, +sometimes called the "new style" calendar, which is used in most of the +world today. However, this calendar did not exist before the sixteenth +century and was not widely used before the eighteenth century; it did +not fully displace the Julian calendar and gain universal acceptance +until the early twentieth century. The Emacs calendar can display any +month since January, year 1 of the current era, but the calendar +displayed is the Gregorian, even for a date at which the Gregorian +calendar did not exist. + + While Emacs cannot display other calendars, it can convert dates to +and from several other calendars. + +* Menu: + +* Calendar Systems:: The calendars Emacs understands + (aside from Gregorian). +* To Other Calendar:: Converting the selected date to various calendars. +* From Other Calendar:: Moving to a date specified in another calendar. +* Mayan Calendar:: Moving to a date specified in a Mayan calendar. + + If you are interested in these calendars, you can convert dates one +at a time. Put point on the desired date of the Gregorian calendar and +press the appropriate keys. The `p' is a mnemonic for "print" since +Emacs "prints' the equivalent date in the echo area. + + +File: xemacs.info, Node: Calendar Systems, Next: To Other Calendar, Prev: Other Calendars, Up: Other Calendars + +Supported Calendar Systems +========================== + + The ISO commercial calendar is used largely in Europe. + + The Julian calendar, named after Julius Caesar, was the one used in +Europe throughout medieval times, and in many countries up until the +nineteenth century. + + Astronomers use a simple counting of days elapsed since noon, Monday, +January 1, 4713 B.C. on the Julian calendar. The number of days elapsed +is called the _Julian day number_ or the _Astronomical day number_. + + The Hebrew calendar is used by tradition in the Jewish religion. The +Emacs calendar program uses the Hebrew calendar to determine the dates +of Jewish holidays. Hebrew calendar dates begin and end at sunset. + + The Islamic calendar is used in many predominantly Islamic countries. +Emacs uses it to determine the dates of Islamic holidays. There is no +universal agreement in the Islamic world about the calendar; Emacs uses +a widely accepted version, but the precise dates of Islamic holidays +often depend on proclamation by religious authorities, not on +calculations. As a consequence, the actual dates of observance can vary +slightly from the dates computed by Emacs. Islamic calendar dates begin +and end at sunset. + + The French Revolutionary calendar was created by the Jacobins after +the 1789 revolution, to represent a more secular and nature-based view +of the annual cycle, and to install a 10-day week in a rationalization +measure similar to the metric system. The French government officially +abandoned this calendar at the end of 1805. + + The Maya of Central America used three separate, overlapping calendar +systems, the _long count_, the _tzolkin_, and the _haab_. Emacs knows +about all three of these calendars. Experts dispute the exact +correlation between the Mayan calendar and our calendar; Emacs uses the +Goodman-Martinez-Thompson correlation in its calculations. + + The Copts use a calendar based on the ancient Egyptian solar +calendar. Their calendar consists of twelve 30-day months followed by +an extra five-day period. Once every fourth year they add a leap day +to this extra period to make it six days. The Ethiopic calendar is +identical in structure, but has different year numbers and month names. + + The Persians use a solar calendar based on a design of Omar Khayyam. +Their calendar consists of twelve months of which the first six have 31 +days, the next five have 30 days, and the last has 29 in ordinary years +and 30 in leap years. Leap years occur in a complicated pattern every +four or five years. + + The Chinese calendar is a complicated system of lunar months arranged +into solar years. The years go in cycles of sixty, each year containing +either twelve months in an ordinary year or thirteen months in a leap +year; each month has either 29 or 30 days. Years, ordinary months, and +days are named by combining one of ten "celestial stems" with one of +twelve "terrestrial branches" for a total of sixty names that are +repeated in a cycle of sixty. + + +File: xemacs.info, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars + +Converting To Other Calendars +============================= + + The following commands describe the selected date (the date at point) +in various other calendar systems: + +`Button2 Other Calendars' + Display the date that you click on, expressed in various other + calendars. + +`p c' + Display ISO commercial calendar equivalent for selected day + (`calendar-print-iso-date'). + +`p j' + Display Julian date for selected day + (`calendar-print-julian-date'). + +`p a' + Display astronomical (Julian) day number for selected day + (`calendar-print-astro-day-number'). + +`p h' + Display Hebrew date for selected day + (`calendar-print-hebrew-date'). + +`p i' + Display Islamic date for selected day + (`calendar-print-islamic-date'). + +`p f' + Display French Revolutionary date for selected day + (`calendar-print-french-date'). + +`p C' + Display Chinese date for selected day + (`calendar-print-chinese-date'). + +`p k' + Display Coptic date for selected day + (`calendar-print-coptic-date'). + +`p e' + Display Ethiopic date for selected day + (`calendar-print-ethiopic-date'). + +`p p' + Display Persian date for selected day + (`calendar-print-persian-date'). + +`p m' + Display Mayan date for selected day (`calendar-print-mayan-date'). + + If you are using X, the easiest way to translate a date into other +calendars is to click on it with `Button2', then choose `Other +Calendars' from the menu that appears. This displays the equivalent +forms of the date in all the calendars Emacs understands, in the form of +a menu. (Choosing an alternative from this menu doesn't actually do +anything--the menu is used only for display.) + + Put point on the desired date of the Gregorian calendar, then type +the appropriate keys. The `p' is a mnemonic for "print" since Emacs +"prints" the equivalent date in the echo area. + + +File: xemacs.info, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars + +Converting From Other Calendars +=============================== + + You can use the other supported calendars to specify a date to move +to. This section describes the commands for doing this using calendars +other than Mayan; for the Mayan calendar, see the following section. + +`g c' + Move to a date specified in the ISO commercial calendar + (`calendar-goto-iso-date'). + +`g j' + Move to a date specified in the Julian calendar + (`calendar-goto-julian-date'). + +`g a' + Move to a date specified in astronomical (Julian) day number + (`calendar-goto-astro-day-number'). + +`g h' + Move to a date specified in the Hebrew calendar + (`calendar-goto-hebrew-date'). + +`g i' + Move to a date specified in the Islamic calendar + (`calendar-goto-islamic-date'). + +`g f' + Move to a date specified in the French Revolutionary calendar + (`calendar-goto-french-date'). + +`g C' + Move to a date specified in the Chinese calendar + (`calendar-goto-chinese-date'). + +`g p' + Move to a date specified in the Persian calendar + (`calendar-goto-persian-date'). + +`g k' + Move to a date specified in the Coptic calendar + (`calendar-goto-coptic-date'). + +`g e' + Move to a date specified in the Ethiopic calendar + (`calendar-goto-ethiopic-date'). + + These commands ask you for a date on the other calendar, move point +to the Gregorian calendar date equivalent to that date, and display the +other calendar's date in the echo area. Emacs uses strict completion +(*note Completion::) whenever it asks you to type a month name, so you +don't have to worry about the spelling of Hebrew, Islamic, or French +names. + + One common question concerning the Hebrew calendar is the computation +of the anniversary of a date of death, called a "yahrzeit." The Emacs +calendar includes a facility for such calculations. If you are in the +calendar, the command `M-x list-yahrzeit-dates' asks you for a range of +years and then displays a list of the yahrzeit dates for those years +for the date given by point. If you are not in the calendar, this +command first asks you for the date of death and the range of years, +and then displays the list of yahrzeit dates. + + +File: xemacs.info, Node: Mayan Calendar, Next: Diary, Prev: From Other Calendar, Up: Other Calendars + +Converting from the Mayan Calendar +---------------------------------- + + Here are the commands to select dates based on the Mayan calendar: + +`g m l' + Move to a date specified by the long count calendar + (`calendar-goto-mayan-long-count-date'). + +`g m n t' + Move to the next occurrence of a place in the tzolkin calendar + (`calendar-next-tzolkin-date'). + +`g m p t' + Move to the previous occurrence of a place in the tzolkin calendar + (`calendar-previous-tzolkin-date'). + +`g m n h' + Move to the next occurrence of a place in the haab calendar + (`calendar-next-haab-date'). + +`g m p h' + Move to the previous occurrence of a place in the haab calendar + (`calendar-previous-haab-date'). + +`g m n c' + Move to the next occurrence of a place in the calendar round + (`calendar-next-calendar-round-date'). + +`g m p c' + Move to the previous occurrence of a place in the calendar round + (`calendar-previous-calendar-round-date'). + + To understand these commands, you need to understand the Mayan +calendars. The "long count" is a counting of days with these units: + + 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal + 1 katun = 20 tun 1 baktun = 20 katun + +Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 +tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long +count dates as early as 7.17.18.13.1, but no earlier. When you use the +`g m l' command, type the Mayan long count date with the baktun, katun, +tun, uinal, and kin separated by periods. + + The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of +independent cycles of 13 and 20 days. Since this cycle repeats +endlessly, Emacs provides commands to move backward and forward to the +previous or next point in the cycle. Type `g m p t' to go to the +previous tzolkin date; Emacs asks you for a tzolkin date and moves point +to the previous occurrence of that date. Similarly, type `g m n t' to +go to the next occurrence of a tzolkin date. + + The Mayan haab calendar is a cycle of 365 days arranged as 18 months +of 20 days each, followed a 5-day monthless period. Like the tzolkin +cycle, this cycle repeats endlessly, and there are commands to move +backward and forward to the previous or next point in the cycle. Type +`g m p h' to go to the previous haab date; Emacs asks you for a haab +date and moves point to the previous occurrence of that date. +Similarly, type `g m n h' to go to the next occurrence of a haab date. + + The Maya also used the combination of the tzolkin date and the haab +date. This combination is a cycle of about 52 years called a _calendar +round_. If you type `g m p c', Emacs asks you for both a haab and a +tzolkin date and then moves point to the previous occurrence of that +combination. Use `g m n c' to move point to the next occurrence of a +combination. These commands signal an error if the haab/tzolkin date +combination you have typed is impossible. + + Emacs uses strict completion (*note Completion::) whenever it asks +you to type a Mayan name, so you don't have to worry about spelling. + + +File: xemacs.info, Node: Diary, Next: Calendar Customization, Prev: Mayan Calendar, Up: Calendar/Diary + +The Diary +--------- + + The Emacs diary keeps track of appointments or other events on a +daily basis, in conjunction with the calendar. To use the diary +feature, you must first create a "diary file" containing a list of +events and their dates. Then Emacs can automatically pick out and +display the events for today, for the immediate future, or for any +specified date. + + By default, Emacs uses `~/diary' as the diary file. This is the +same file that the `calendar' utility uses. A sample `~/diary' file is: + + 12/22/1988 Twentieth wedding anniversary!! + &1/1. Happy New Year! + 10/22 Ruth's birthday. + * 21, *: Payday + Tuesday--weekly meeting with grad students at 10am + Supowit, Shen, Bitner, and Kapoor to attend. + 1/13/89 Friday the thirteenth!! + &thu 4pm squash game with Lloyd. + mar 16 Dad's birthday + April 15, 1989 Income tax due. + &* 15 time cards due. + +This example uses extra spaces to align the event descriptions of most +of the entries. Such formatting is purely a matter of taste. + + Although you probably will start by creating a diary manually, Emacs +provides a number of commands to let you view, add, and change diary +entries. You can also share diary entries with other users (*note +Included Diary Files::). + +* Menu: + +* Diary Commands:: Viewing diary entries and associated calendar dates. +* Format of Diary File:: Entering events in your diary. +* Date Formats:: Various ways you can specify dates. +* Adding to Diary:: Commands to create diary entries. +* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. + + +File: xemacs.info, Node: Diary Commands, Next: Format of Diary File, Prev: Diary, Up: Diary + +Commands Displaying Diary Entries +--------------------------------- + + Once you have created a `~/diary' file, you can use the calendar to +view it. You can also view today's events outside of Calendar mode. + +`d' + Display all diary entries for the selected date + (`view-diary-entries'). + +`Button2 Diary' + Display all diary entries for the date you click on. + +`s' + Display the entire diary file (`show-all-diary-entries'). + +`m' + Mark all visible dates that have diary entries + (`mark-diary-entries'). + +`u' + Unmark the calendar window (`calendar-unmark'). + +`M-x print-diary-entries' + Print hard copy of the diary display as it appears. + +`M-x diary' + Display all diary entries for today's date. + +`M-x diary-mail-entries' + Mail yourself email reminders about upcoming diary entries. + + Displaying the diary entries with `d' shows in a separate window the +diary entries for the selected date in the calendar. The mode line of +the new window shows the date of the diary entries and any holidays +that fall on that date. If you specify a numeric argument with `d', it +shows all the diary entries for that many successive days. Thus, `2 d' +displays all the entries for the selected date and for the following +day. + + Another way to display the diary entries for a date is to click +`Button2' on the date, and then choose `Diary' from the menu that +appears. + + To get a broader view of which days are mentioned in the diary, use +the `m' command. This displays the dates that have diary entries in a +different face (or places a `+' after these dates, if display with +multiple faces is not available). The command applies both to the +currently visible months and to other months that subsequently become +visible by scrolling. To turn marking off and erase the current marks, +type `u', which also turns off holiday marks (*note Holidays::). + + To see the full diary file, rather than just some of the entries, use +the `s' command. + + Display of selected diary entries uses the selective display feature +to hide entries that don't apply. + + The diary buffer as you see it is an illusion, so simply printing the +buffer does not print what you see on your screen. There is a special +command to print hard copy of the diary buffer _as it appears_; this +command is `M-x print-diary-entries'. It sends the data directly to +the printer. You can customize it like `lpr-region' (*note Hardcopy::). + + The command `M-x diary' displays the diary entries for the current +date, independently of the calendar display, and optionally for the next +few days as well; the variable `number-of-diary-entries' specifies how +many days to include (*note Customization::). + + If you put `(diary)' in your init file, this automatically displays +a window with the day's diary entries, when you enter Emacs. *Note +Init File::. The mode line of the displayed window shows the date and +any holidays that fall on that date. + + Many users like to receive notice of events in their diary as email. +To send such mail to yourself, use the command `M-x +diary-mail-entries'. A prefix argument specifies how many days +(starting with today) to check; otherwise, the variable +`diary-mail-days' says how many days. + + +File: xemacs.info, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary + +The Diary File +-------------- + + Your "diary file" is a file that records events associated with +particular dates. The name of the diary file is specified by the +variable `diary-file'; `~/diary' is the default. The `calendar' +utility program supports a subset of the format allowed by the Emacs +diary facilities, so you can use that utility to view the diary file, +with reasonable results aside from the entries it cannot understand. + + Each entry in the diary file describes one event and consists of one +or more lines. An entry always begins with a date specification at the +left margin. The rest of the entry is simply text to describe the +event. If the entry has more than one line, then the lines after the +first must begin with whitespace to indicate they continue a previous +entry. Lines that do not begin with valid dates and do not continue a +preceding entry are ignored. + + You can inhibit the marking of certain diary entries in the calendar +window; to do this, insert an ampersand (`&') at the beginning of the +entry, before the date. This has no effect on display of the entry in +the diary window; it affects only marks on dates in the calendar +window. Nonmarking entries are especially useful for generic entries +that would otherwise mark many different dates. + + If the first line of a diary entry consists only of the date or day +name with no following blanks or punctuation, then the diary window +display doesn't include that line; only the continuation lines appear. +For example, this entry: + + 02/11/1989 + Bill B. visits Princeton today + 2pm Cognitive Studies Committee meeting + 2:30-5:30 Liz at Lawrenceville + 4:00pm Dentist appt + 7:30pm Dinner at George's + 8:00-10:00pm concert + +appears in the diary window without the date line at the beginning. +This style of entry looks neater when you display just a single day's +entries, but can cause confusion if you ask for more than one day's +entries. + + You can edit the diary entries as they appear in the window, but it +is important to remember that the buffer displayed contains the _entire_ +diary file, with portions of it concealed from view. This means, for +instance, that the `C-f' (`forward-char') command can put point at what +appears to be the end of the line, but what is in reality the middle of +some concealed line. + + _Be careful when editing the diary entries!_ Inserting additional +lines or adding/deleting characters in the middle of a visible line +cannot cause problems, but editing at the end of a line may not do what +you expect. Deleting a line may delete other invisible entries that +follow it. Before editing the diary, it is best to display the entire +file with `s' (`show-all-diary-entries'). + + +File: xemacs.info, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary + +Date Formats +------------ + + Here are some sample diary entries, illustrating different ways of +formatting a date. The examples all show dates in American order +(month, day, year), but Calendar mode supports European order (day, +month, year) as an option. + + 4/20/93 Switch-over to new tabulation system + apr. 25 Start tabulating annual results + 4/30 Results for April are due + */25 Monthly cycle finishes + Friday Don't leave without backing up files + + The first entry appears only once, on April 20, 1993. The second and +third appear every year on the specified dates, and the fourth uses a +wildcard (asterisk) for the month, so it appears on the 25th of every +month. The final entry appears every week on Friday. + + You can use just numbers to express a date, as in `MONTH/DAY' or +`MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date +itself, MONTH and DAY are numbers of one or two digits. The optional +YEAR is also a number, and may be abbreviated to the last two digits; +that is, you can use `11/12/1989' or `11/12/89'. + + Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY, +YEAR', where the month's name can be spelled in full or abbreviated to +three characters (with or without a period). Case is not significant. + + A date may be "generic"; that is, partially unspecified. Then the +entry applies to all dates that match the specification. If the date +does not contain a year, it is generic and applies to any year. +Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any +month, day, or year, respectively. Thus, a diary entry `3/*/*' matches +any day in March of any year; so does `march *'. + + If you prefer the European style of writing dates--in which the day +comes before the month--type `M-x european-calendar' while in the +calendar, or set the variable `european-calendar-style' to `t' _before_ +using any calendar or diary command. This mode interprets all dates in +the diary in the European manner, and also uses European style for +displaying diary dates. (Note that there is no comma after the +MONTHNAME in the European style.) To go back to the (default) American +style of writing dates, type `M-x american-calendar'. + + You can use the name of a day of the week as a generic date which +applies to any date falling on that day of the week. You can abbreviate +the day of the week to three letters (with or without a period) or spell +it in full; case is not significant. + + File: xemacs.info, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary Commands to Add to the Diary @@ -564,592 +1210,3 @@ after midnight local time when the transition to and from daylight savings time should occur. For Cambridge, Massachusetts both variables' values are 120. - -File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization - -Customizing the Diary -..................... - - Ordinarily, the mode line of the diary buffer window indicates any -holidays that fall on the date of the diary entries. The process of -checking for holidays can take several seconds, so including holiday -information delays the display of the diary buffer noticeably. If you'd -prefer to have a faster display of the diary buffer but without the -holiday information, set the variable `holidays-in-diary-buffer' to -`nil'. - - The variable `number-of-diary-entries' controls the number of days -of diary entries to be displayed at one time. It affects the initial -display when `view-diary-entries-initially' is `t', as well as the -command `M-x diary'. For example, the default value is 1, which says -to display only the current day's diary entries. If the value is 2, -both the current day's and the next day's entries are displayed. The -value can also be a vector of seven elements: for example, if the value -is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the -current date's and the next day's diary entries appear Monday through -Thursday, Friday through Monday's entries appear on Friday, while on -Saturday only that day's entries appear. - - The variable `print-diary-entries-hook' is a normal hook run after -preparation of a temporary buffer containing just the diary entries -currently visible in the diary buffer. (The other, irrelevant diary -entries are really absent from the temporary buffer; in the diary -buffer, they are merely hidden.) The default value of this hook does -the printing with the command `lpr-buffer'. If you want to use a -different command to do the printing, just change the value of this -hook. Other uses might include, for example, rearranging the lines into -order by day and time. - - You can customize the form of dates in your diary file, if neither -the standard American nor European styles suits your needs, by setting -the variable `diary-date-forms'. This variable is a list of patterns -for recognizing a date. Each date pattern is a list whose elements may -be regular expressions (*note Regexps::) or the symbols `month', `day', -`year', `monthname', and `dayname'. All these elements serve as -patterns that match certain kinds of text in the diary file. In order -for the date pattern, as a whole, to match, all of its elements must -match consecutively. - - A regular expression in a date pattern matches in its usual fashion, -using the standard syntax table altered so that `*' is a word -constituent. - - The symbols `month', `day', `year', `monthname', and `dayname' match -the month number, day number, year number, month name, and day name of -the date being considered. The symbols that match numbers allow -leading zeros; those that match names allow three-letter abbreviations -and capitalization. All the symbols can match `*'; since `*' in a -diary entry means "any day", "any month", and so on, it should match -regardless of the date being considered. - - The default value of `diary-date-forms' in the American style is -this: - - ((month "/" day "[^/0-9]") - (month "/" day "/" year "[^0-9]") - (monthname " *" day "[^,0-9]") - (monthname " *" day ", *" year "[^0-9]") - (dayname "\\W")) - -Emacs matches of the diary entries with the date forms is done with the -standard syntax table from Fundamental mode (*note Syntax Tables: -(lispref)Syntax Tables.), but with the `*' changed so that it is a word -constituent. - - The date patterns in the list must be _mutually exclusive_ and must -not match any portion of the diary entry itself, just the date and one -character of whitespace. If, to be mutually exclusive, the pattern -must match a portion of the diary entry text--beyond the whitespace -that ends the date--then the first element of the date pattern _must_ -be `backup'. This causes the date recognizer to back up to the -beginning of the current word of the diary entry, after finishing the -match. Even if you use `backup', the date pattern must absolutely not -match more than a portion of the first word of the diary entry. The -default value of `diary-date-forms' in the European style is this list: - - ((day "/" month "[^/0-9]") - (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<[^*0-9]") - (day " *" monthname " *" year "[^0-9]") - (dayname "\\W")) - -Notice the use of `backup' in the third pattern, because it needs to -match part of a word beyond the date itself to distinguish it from the -fourth pattern. - - -File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization - -Hebrew- and Islamic-Date Diary Entries -...................................... - - Your diary file can have entries based on Hebrew or Islamic dates, as -well as entries based on the world-standard Gregorian calendar. -However, because recognition of such entries is time-consuming and most -people don't use them, you must explicitly enable their use. If you -want the diary to recognize Hebrew-date diary entries, for example, you -must do this: - - (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) - (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) - -If you want Islamic-date entries, do this: - - (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) - (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) - - Hebrew- and Islamic-date diary entries have the same formats as -Gregorian-date diary entries, except that `H' precedes a Hebrew date -and `I' precedes an Islamic date. Moreover, because the Hebrew and -Islamic month names are not uniquely specified by the first three -letters, you may not abbreviate them. For example, a diary entry for -the Hebrew date Heshvan 25 could look like this: - - HHeshvan 25 Happy Hebrew birthday! - -and would appear in the diary for any date that corresponds to Heshvan -25 on the Hebrew calendar. And here is Islamic-date diary entry that -matches Dhu al-Qada 25: - - IDhu al-Qada 25 Happy Islamic birthday! - -and would appear in the diary for any date that corresponds to Dhu -al-Qada 25 on the Islamic calendar. - - As with Gregorian-date diary entries, Hebrew- and Islamic-date -entries are nonmarking if they are preceded with an ampersand (`&'). - - Here is a table of commands used in the calendar to create diary -entries that match the selected date and other dates that are similar -in the Hebrew or Islamic calendar: - -`i h d' - Add a diary entry for the Hebrew date corresponding to the - selected date (`insert-hebrew-diary-entry'). - -`i h m' - Add a diary entry for the day of the Hebrew month corresponding to - the selected date (`insert-monthly-hebrew-diary-entry'). This - diary entry matches any date that has the same Hebrew - day-within-month as the selected date. - -`i h y' - Add a diary entry for the day of the Hebrew year corresponding to - the selected date (`insert-yearly-hebrew-diary-entry'). This diary - entry matches any date which has the same Hebrew month and - day-within-month as the selected date. - -`i i d' - Add a diary entry for the Islamic date corresponding to the - selected date (`insert-islamic-diary-entry'). - -`i i m' - Add a diary entry for the day of the Islamic month corresponding - to the selected date (`insert-monthly-islamic-diary-entry'). - -`i i y' - Add a diary entry for the day of the Islamic year corresponding to - the selected date (`insert-yearly-islamic-diary-entry'). - - These commands work much like the corresponding commands for ordinary -diary entries: they apply to the date that point is on in the calendar -window, and what they do is insert just the date portion of a diary -entry at the end of your diary file. You must then insert the rest of -the diary entry. - - -File: xemacs.info, Node: Fancy Diary Display, Next: Included Diary Files, Prev: Hebrew/Islamic Entries, Up: Calendar Customization - -Fancy Diary Display -................... - - Diary display works by preparing the diary buffer and then running -the hook `diary-display-hook'. The default value of this hook -(`simple-diary-display') hides the irrelevant diary entries and then -displays the buffer. However, if you specify the hook as follows, - - (add-hook 'diary-display-hook 'fancy-diary-display) - -this enables fancy diary display. It displays diary entries and -holidays by copying them into a special buffer that exists only for the -sake of display. Copying to a separate buffer provides an opportunity -to change the displayed text to make it prettier--for example, to sort -the entries by the dates they apply to. - - As with simple diary display, you can print a hard copy of the buffer -with `print-diary-entries'. To print a hard copy of a day-by-day diary -for a week by positioning point on Sunday of that week, type `7 d' and -then do `M-x print-diary-entries'. As usual, the inclusion of the -holidays slows down the display slightly; you can speed things up by -setting the variable `holidays-in-diary-buffer' to `nil'. - - Ordinarily, the fancy diary buffer does not show days for which -there are no diary entries, even if that day is a holiday. If you want -such days to be shown in the fancy diary buffer, set the variable -`diary-list-include-blanks' to `t'. - - If you use the fancy diary display, you can use the normal hook -`list-diary-entries-hook' to sort each day's diary entries by their -time of day. Add this line to your init file: - - (add-hook 'list-diary-entries-hook 'sort-diary-entries t) - - *Note Init File::. - -For each day, this sorts diary entries that begin with a recognizable -time of day according to their times. Diary entries without times come -first within each day. - - -File: xemacs.info, Node: Included Diary Files, Next: Sexp Diary Entries, Prev: Fancy Diary Display, Up: Calendar Customization - -Included Diary Files -.................... - - Fancy diary display also has the ability to process included diary -files. This permits a group of people to share a diary file for events -that apply to all of them. Lines in the diary file of this form: - - #include "FILENAME" - -includes the diary entries from the file FILENAME in the fancy diary -buffer. The include mechanism is recursive, so that included files can -include other files, and so on; you must be careful not to have a cycle -of inclusions, of course. Here is how to enable the include facility: - - (add-hook 'list-diary-entries-hook 'include-other-diary-files) - (add-hook 'mark-diary-entries-hook 'mark-included-diary-files) - - The include mechanism works only with the fancy diary display, -because ordinary diary display shows the entries directly from your -diary file. - - -File: xemacs.info, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Included Diary Files, Up: Calendar Customization - -Sexp Entries and the Fancy Diary Display -........................................ - - Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. If you use the fancy -diary display, sexp entries can generate the text of the entry depending -on the date itself. For example, an anniversary diary entry can insert -the number of years since the anniversary date into the text of the -diary entry. Thus the `%d' in this dairy entry: - - %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) - -gets replaced by the age, so on October 31, 1990 the entry appears in -the fancy diary buffer like this: - - Arthur's birthday (42 years old) - -If the diary file instead contains this entry: - - %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday - -the entry in the fancy diary buffer for October 31, 1990 appears like -this: - - Arthur's 42nd birthday - - Similarly, cyclic diary entries can interpolate the number of -repetitions that have occurred: - - %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) - -looks like this: - - Renew medication (5th time) - -in the fancy diary display on September 8, 1990. - - The generality of sexp diary entries lets you specify any diary entry -that you can describe algorithmically. A sexp diary entry contains an -expression that computes whether the entry applies to any given date. -If its value is non-`nil', the entry applies to that date; otherwise, -it does not. The expression can use the variable `date' to find the -date being considered; its value is a list (MONTH DAY YEAR) that refers -to the Gregorian calendar. - - Suppose you get paid on the 21st of the month if it is a weekday, and -on the Friday before if the 21st is on a weekend. Here is how to write -a sexp diary entry that matches those dates: - - &%%(let ((dayname (calendar-day-of-week date)) - (day (car (cdr date)))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited - -applies to just those dates. This example illustrates how the sexp can -depend on the variable `date'; this variable is a list (MONTH DAY YEAR) -that gives the Gregorian date for which the diary entries are being -found. If the value of the expression is `t', the entry applies to -that date. If the expression evaluates to `nil', the entry does _not_ -apply to that date. - - The following sexp diary entries take advantage of the ability (in -the fancy diary display) to concoct diary entries whose text varies -based on the date: - -`%%(diary-sunrise-sunset)' - Make a diary entry for the local times of today's sunrise and - sunset. - -`%%(diary-phases-of-moon)' - Make a diary entry for the phases (quarters) of the moon. - -`%%(diary-day-of-year)' - Make a diary entry with today's day number in the current year and - the number of days remaining in the current year. - -`%%(diary-iso-date)' - Make a diary entry with today's equivalent ISO commercial date. - -`%%(diary-julian-date)' - Make a diary entry with today's equivalent date on the Julian - calendar. - -`%%(diary-astro-day-number)' - Make a diary entry with today's equivalent astronomical (Julian) - day number. - -`%%(diary-hebrew-date)' - Make a diary entry with today's equivalent date on the Hebrew - calendar. - -`%%(diary-islamic-date)' - Make a diary entry with today's equivalent date on the Islamic - calendar. - -`%%(diary-french-date)' - Make a diary entry with today's equivalent date on the French - Revolutionary calendar. - -`%%(diary-mayan-date)' - Make a diary entry with today's equivalent date on the Mayan - calendar. - -Thus including the diary entry - - &%%(diary-hebrew-date) - -causes every day's diary display to contain the equivalent date on the -Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the line `&%%(diary-hebrew-date)' appears in the diary -for any date, but does nothing particularly useful.) - - These functions can be used to construct sexp diary entries based on -the Hebrew calendar in certain standard ways: - -`%%(diary-rosh-hodesh)' - Make a diary entry that tells the occurrence and ritual - announcement of each new Hebrew month. - -`%%(diary-parasha)' - Make a Saturday diary entry that tells the weekly synagogue - scripture reading. - -`%%(diary-sabbath-candles)' - Make a Friday diary entry that tells the _local time_ of Sabbath - candle lighting. - -`%%(diary-omer)' - Make a diary entry that gives the omer count, when appropriate. - -`%%(diary-yahrzeit MONTH DAY YEAR) NAME' - Make a diary entry marking the anniversary of a date of death. - The date is the _Gregorian_ (civil) date of death. The diary - entry appears on the proper Hebrew calendar anniversary and on the - day before. (In the European style, the order of the parameters - is changed to DAY, MONTH, YEAR.) - - -File: xemacs.info, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customization - -Customizing Appointment Reminders -................................. - - You can specify exactly how Emacs reminds you of an appointment, and -how far in advance it begins doing so, by setting these variables: - -`appt-message-warning-time' - The time in minutes before an appointment that the reminder - begins. The default is 10 minutes. - -`appt-audible' - If this is `t' (the default), Emacs rings the terminal bell for - appointment reminders. - -`appt-visible' - If this is `t' (the default), Emacs displays the appointment - message in echo area. - -`appt-display-mode-line' - If this is `t' (the default), Emacs displays the number of minutes - to the appointment on the mode line. - -`appt-msg-window' - If this is `t' (the default), Emacs displays the appointment - message in another window. - -`appt-display-duration' - The number of seconds an appointment message is displayed. The - default is 5 seconds. - - -File: xemacs.info, Node: Sorting, Next: Shell, Prev: Calendar/Diary, Up: Top - -Sorting Text -============ - - XEmacs provides several commands for sorting text in a buffer. All -operate on the contents of the region (the text between point and the -mark). They divide the text of the region into many "sort records", -identify a "sort key" for each record, and then reorder the records -using the order determined by the sort keys. The records are ordered so -that their keys are in alphabetical order, or, for numerical sorting, in -numerical order. In alphabetical sorting, all upper-case letters `A' -through `Z' come before lower-case `a', in accordance with the ASCII -character sequence. - - The sort commands differ in how they divide the text into sort -records and in which part of each record they use as the sort key. -Most of the commands make each line a separate sort record, but some -commands use paragraphs or pages as sort records. Most of the sort -commands use each entire sort record as its own sort key, but some use -only a portion of the record as the sort key. - -`M-x sort-lines' - Divide the region into lines and sort by comparing the entire text - of a line. A prefix argument means sort in descending order. - -`M-x sort-paragraphs' - Divide the region into paragraphs and sort by comparing the entire - text of a paragraph (except for leading blank lines). A prefix - argument means sort in descending order. - -`M-x sort-pages' - Divide the region into pages and sort by comparing the entire text - of a page (except for leading blank lines). A prefix argument - means sort in descending order. - -`M-x sort-fields' - Divide the region into lines and sort by comparing the contents of - one field in each line. Fields are defined as separated by - whitespace, so the first run of consecutive non-whitespace - characters in a line constitutes field 1, the second such run - constitutes field 2, etc. - - You specify which field to sort by with a numeric argument: 1 to - sort by field 1, etc. A negative argument means sort in descending - order. Thus, minus 2 means sort by field 2 in reverse-alphabetical - order. - -`M-x sort-numeric-fields' - Like `M-x sort-fields', except the specified field is converted to - a number for each line and the numbers are compared. `10' comes - before `2' when considered as text, but after it when considered - as a number. - -`M-x sort-columns' - Like `M-x sort-fields', except that the text within each line used - for comparison comes from a fixed range of columns. An explanation - is given below. - - For example, if the buffer contains: - - On systems where clash detection (locking of files being edited) is - implemented, XEmacs also checks the first time you modify a buffer - whether the file has changed on disk since it was last visited or - saved. If it has, you are asked to confirm that you want to change - the buffer. - -then if you apply `M-x sort-lines' to the entire buffer you get: - - On systems where clash detection (locking of files being edited) is - implemented, XEmacs also checks the first time you modify a buffer - saved. If it has, you are asked to confirm that you want to change - the buffer. - whether the file has changed on disk since it was last visited or - -where the upper case `O' comes before all lower case letters. If you -apply instead `C-u 2 M-x sort-fields' you get: - - saved. If it has, you are asked to confirm that you want to change - implemented, XEmacs also checks the first time you modify a buffer - the buffer. - On systems where clash detection (locking of files being edited) is - whether the file has changed on disk since it was last visited or - -where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'. - - `M-x sort-columns' requires more explanation. You specify the -columns by putting point at one of the columns and the mark at the other -column. Because this means you cannot put point or the mark at the -beginning of the first line to sort, this command uses an unusual -definition of `region': all of the line point is in is considered part -of the region, and so is all of the line the mark is in. - - For example, to sort a table by information found in columns 10 to -15, you could put the mark on column 10 in the first line of the table, -and point on column 15 in the last line of the table, and then use this -command. Or you could put the mark on column 15 in the first line and -point on column 10 in the last line. - - This can be thought of as sorting the rectangle specified by point -and the mark, except that the text on each line to the left or right of -the rectangle moves along with the text inside the rectangle. *Note -Rectangles::. - - -File: xemacs.info, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top - -Running Shell Commands from XEmacs -================================== - - XEmacs has commands for passing single command lines to inferior -shell processes; it can also run a shell interactively with input and -output to an XEmacs buffer `*shell*'. - -`M-!' - Run a specified shell command line and display the output - (`shell-command'). - -`M-|' - Run a specified shell command line with region contents as input; - optionally replace the region with the output - (`shell-command-on-region'). - -`M-x shell' - Run a subshell with input and output through an XEmacs buffer. - You can then give commands interactively. - -`M-x term' - Run a subshell with input and output through an XEmacs buffer. - You can then give commands interactively. Full terminal emulation - is available. - -* Menu: - -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via XEmacs. -* Shell Mode:: Special XEmacs commands used with permanent shell. -* Terminal emulator:: An XEmacs window as a terminal emulator. -* Term Mode:: Special XEmacs commands used in Term mode. -* Paging in Term:: Paging in the terminal emulator. - - -File: xemacs.info, Node: Single Shell, Next: Interactive Shell, Prev: Shell, Up: Shell - -Single Shell Commands ---------------------- - - `M-!' (`shell-command') reads a line of text using the minibuffer -and creates an inferior shell to execute the line as a command. -Standard input from the command comes from the null device. If the -shell command produces any output, the output goes to an XEmacs buffer -named `*Shell Command Output*', which is displayed in another window -but not selected. A numeric argument, as in `M-1 M-!', directs this -command to insert any output into the current buffer. In that case, -point is left before the output and the mark is set after the output. - - `M-|' (`shell-command-on-region') is like `M-!' but passes the -contents of the region as input to the shell command, instead of no -input. If a numeric argument is used to direct output to the current -buffer, then the old region is deleted first and the output replaces it -as the contents of the region. - - Both `M-!' and `M-|' use `shell-file-name' to specify the shell to -use. This variable is initialized based on your `SHELL' environment -variable when you start XEmacs. If the file name does not specify a -directory, the directories in the list `exec-path' are searched; this -list is initialized based on the `PATH' environment variable when you -start XEmacs. You can override either or both of these default -initializations in your init file. *Note Init File::. - - When you use `M-!' and `M-|', XEmacs has to wait until the shell -command completes. You can quit with `C-g'; that terminates the shell -command. - diff --git a/info/xemacs.info-16 b/info/xemacs.info-16 index 07d3445..4b02aad 100644 --- a/info/xemacs.info-16 +++ b/info/xemacs.info-16 @@ -30,6 +30,595 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Diary Customizing, Next: Hebrew/Islamic Entries, Prev: Daylight Savings, Up: Calendar Customization + +Customizing the Diary +..................... + + Ordinarily, the mode line of the diary buffer window indicates any +holidays that fall on the date of the diary entries. The process of +checking for holidays can take several seconds, so including holiday +information delays the display of the diary buffer noticeably. If you'd +prefer to have a faster display of the diary buffer but without the +holiday information, set the variable `holidays-in-diary-buffer' to +`nil'. + + The variable `number-of-diary-entries' controls the number of days +of diary entries to be displayed at one time. It affects the initial +display when `view-diary-entries-initially' is `t', as well as the +command `M-x diary'. For example, the default value is 1, which says +to display only the current day's diary entries. If the value is 2, +both the current day's and the next day's entries are displayed. The +value can also be a vector of seven elements: for example, if the value +is `[0 2 2 2 2 4 1]' then no diary entries appear on Sunday, the +current date's and the next day's diary entries appear Monday through +Thursday, Friday through Monday's entries appear on Friday, while on +Saturday only that day's entries appear. + + The variable `print-diary-entries-hook' is a normal hook run after +preparation of a temporary buffer containing just the diary entries +currently visible in the diary buffer. (The other, irrelevant diary +entries are really absent from the temporary buffer; in the diary +buffer, they are merely hidden.) The default value of this hook does +the printing with the command `lpr-buffer'. If you want to use a +different command to do the printing, just change the value of this +hook. Other uses might include, for example, rearranging the lines into +order by day and time. + + You can customize the form of dates in your diary file, if neither +the standard American nor European styles suits your needs, by setting +the variable `diary-date-forms'. This variable is a list of patterns +for recognizing a date. Each date pattern is a list whose elements may +be regular expressions (*note Regexps::) or the symbols `month', `day', +`year', `monthname', and `dayname'. All these elements serve as +patterns that match certain kinds of text in the diary file. In order +for the date pattern, as a whole, to match, all of its elements must +match consecutively. + + A regular expression in a date pattern matches in its usual fashion, +using the standard syntax table altered so that `*' is a word +constituent. + + The symbols `month', `day', `year', `monthname', and `dayname' match +the month number, day number, year number, month name, and day name of +the date being considered. The symbols that match numbers allow +leading zeros; those that match names allow three-letter abbreviations +and capitalization. All the symbols can match `*'; since `*' in a +diary entry means "any day", "any month", and so on, it should match +regardless of the date being considered. + + The default value of `diary-date-forms' in the American style is +this: + + ((month "/" day "[^/0-9]") + (month "/" day "/" year "[^0-9]") + (monthname " *" day "[^,0-9]") + (monthname " *" day ", *" year "[^0-9]") + (dayname "\\W")) + +Emacs matches of the diary entries with the date forms is done with the +standard syntax table from Fundamental mode (*note Syntax Tables: +(lispref)Syntax Tables.), but with the `*' changed so that it is a word +constituent. + + The date patterns in the list must be _mutually exclusive_ and must +not match any portion of the diary entry itself, just the date and one +character of whitespace. If, to be mutually exclusive, the pattern +must match a portion of the diary entry text--beyond the whitespace +that ends the date--then the first element of the date pattern _must_ +be `backup'. This causes the date recognizer to back up to the +beginning of the current word of the diary entry, after finishing the +match. Even if you use `backup', the date pattern must absolutely not +match more than a portion of the first word of the diary entry. The +default value of `diary-date-forms' in the European style is this list: + + ((day "/" month "[^/0-9]") + (day "/" month "/" year "[^0-9]") + (backup day " *" monthname "\\W+\\<[^*0-9]") + (day " *" monthname " *" year "[^0-9]") + (dayname "\\W")) + +Notice the use of `backup' in the third pattern, because it needs to +match part of a word beyond the date itself to distinguish it from the +fourth pattern. + + +File: xemacs.info, Node: Hebrew/Islamic Entries, Next: Fancy Diary Display, Prev: Diary Customizing, Up: Calendar Customization + +Hebrew- and Islamic-Date Diary Entries +...................................... + + Your diary file can have entries based on Hebrew or Islamic dates, as +well as entries based on the world-standard Gregorian calendar. +However, because recognition of such entries is time-consuming and most +people don't use them, you must explicitly enable their use. If you +want the diary to recognize Hebrew-date diary entries, for example, you +must do this: + + (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) + (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) + +If you want Islamic-date entries, do this: + + (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) + (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) + + Hebrew- and Islamic-date diary entries have the same formats as +Gregorian-date diary entries, except that `H' precedes a Hebrew date +and `I' precedes an Islamic date. Moreover, because the Hebrew and +Islamic month names are not uniquely specified by the first three +letters, you may not abbreviate them. For example, a diary entry for +the Hebrew date Heshvan 25 could look like this: + + HHeshvan 25 Happy Hebrew birthday! + +and would appear in the diary for any date that corresponds to Heshvan +25 on the Hebrew calendar. And here is Islamic-date diary entry that +matches Dhu al-Qada 25: + + IDhu al-Qada 25 Happy Islamic birthday! + +and would appear in the diary for any date that corresponds to Dhu +al-Qada 25 on the Islamic calendar. + + As with Gregorian-date diary entries, Hebrew- and Islamic-date +entries are nonmarking if they are preceded with an ampersand (`&'). + + Here is a table of commands used in the calendar to create diary +entries that match the selected date and other dates that are similar +in the Hebrew or Islamic calendar: + +`i h d' + Add a diary entry for the Hebrew date corresponding to the + selected date (`insert-hebrew-diary-entry'). + +`i h m' + Add a diary entry for the day of the Hebrew month corresponding to + the selected date (`insert-monthly-hebrew-diary-entry'). This + diary entry matches any date that has the same Hebrew + day-within-month as the selected date. + +`i h y' + Add a diary entry for the day of the Hebrew year corresponding to + the selected date (`insert-yearly-hebrew-diary-entry'). This diary + entry matches any date which has the same Hebrew month and + day-within-month as the selected date. + +`i i d' + Add a diary entry for the Islamic date corresponding to the + selected date (`insert-islamic-diary-entry'). + +`i i m' + Add a diary entry for the day of the Islamic month corresponding + to the selected date (`insert-monthly-islamic-diary-entry'). + +`i i y' + Add a diary entry for the day of the Islamic year corresponding to + the selected date (`insert-yearly-islamic-diary-entry'). + + These commands work much like the corresponding commands for ordinary +diary entries: they apply to the date that point is on in the calendar +window, and what they do is insert just the date portion of a diary +entry at the end of your diary file. You must then insert the rest of +the diary entry. + + +File: xemacs.info, Node: Fancy Diary Display, Next: Included Diary Files, Prev: Hebrew/Islamic Entries, Up: Calendar Customization + +Fancy Diary Display +................... + + Diary display works by preparing the diary buffer and then running +the hook `diary-display-hook'. The default value of this hook +(`simple-diary-display') hides the irrelevant diary entries and then +displays the buffer. However, if you specify the hook as follows, + + (add-hook 'diary-display-hook 'fancy-diary-display) + +this enables fancy diary display. It displays diary entries and +holidays by copying them into a special buffer that exists only for the +sake of display. Copying to a separate buffer provides an opportunity +to change the displayed text to make it prettier--for example, to sort +the entries by the dates they apply to. + + As with simple diary display, you can print a hard copy of the buffer +with `print-diary-entries'. To print a hard copy of a day-by-day diary +for a week by positioning point on Sunday of that week, type `7 d' and +then do `M-x print-diary-entries'. As usual, the inclusion of the +holidays slows down the display slightly; you can speed things up by +setting the variable `holidays-in-diary-buffer' to `nil'. + + Ordinarily, the fancy diary buffer does not show days for which +there are no diary entries, even if that day is a holiday. If you want +such days to be shown in the fancy diary buffer, set the variable +`diary-list-include-blanks' to `t'. + + If you use the fancy diary display, you can use the normal hook +`list-diary-entries-hook' to sort each day's diary entries by their +time of day. Add this line to your init file: + + (add-hook 'list-diary-entries-hook 'sort-diary-entries t) + + *Note Init File::. + +For each day, this sorts diary entries that begin with a recognizable +time of day according to their times. Diary entries without times come +first within each day. + + +File: xemacs.info, Node: Included Diary Files, Next: Sexp Diary Entries, Prev: Fancy Diary Display, Up: Calendar Customization + +Included Diary Files +.................... + + Fancy diary display also has the ability to process included diary +files. This permits a group of people to share a diary file for events +that apply to all of them. Lines in the diary file of this form: + + #include "FILENAME" + +includes the diary entries from the file FILENAME in the fancy diary +buffer. The include mechanism is recursive, so that included files can +include other files, and so on; you must be careful not to have a cycle +of inclusions, of course. Here is how to enable the include facility: + + (add-hook 'list-diary-entries-hook 'include-other-diary-files) + (add-hook 'mark-diary-entries-hook 'mark-included-diary-files) + + The include mechanism works only with the fancy diary display, +because ordinary diary display shows the entries directly from your +diary file. + + +File: xemacs.info, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Included Diary Files, Up: Calendar Customization + +Sexp Entries and the Fancy Diary Display +........................................ + + Sexp diary entries allow you to do more than just have complicated +conditions under which a diary entry applies. If you use the fancy +diary display, sexp entries can generate the text of the entry depending +on the date itself. For example, an anniversary diary entry can insert +the number of years since the anniversary date into the text of the +diary entry. Thus the `%d' in this dairy entry: + + %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) + +gets replaced by the age, so on October 31, 1990 the entry appears in +the fancy diary buffer like this: + + Arthur's birthday (42 years old) + +If the diary file instead contains this entry: + + %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday + +the entry in the fancy diary buffer for October 31, 1990 appears like +this: + + Arthur's 42nd birthday + + Similarly, cyclic diary entries can interpolate the number of +repetitions that have occurred: + + %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) + +looks like this: + + Renew medication (5th time) + +in the fancy diary display on September 8, 1990. + + The generality of sexp diary entries lets you specify any diary entry +that you can describe algorithmically. A sexp diary entry contains an +expression that computes whether the entry applies to any given date. +If its value is non-`nil', the entry applies to that date; otherwise, +it does not. The expression can use the variable `date' to find the +date being considered; its value is a list (MONTH DAY YEAR) that refers +to the Gregorian calendar. + + Suppose you get paid on the 21st of the month if it is a weekday, and +on the Friday before if the 21st is on a weekend. Here is how to write +a sexp diary entry that matches those dates: + + &%%(let ((dayname (calendar-day-of-week date)) + (day (car (cdr date)))) + (or (and (= day 21) (memq dayname '(1 2 3 4 5))) + (and (memq day '(19 20)) (= dayname 5))) + ) Pay check deposited + +applies to just those dates. This example illustrates how the sexp can +depend on the variable `date'; this variable is a list (MONTH DAY YEAR) +that gives the Gregorian date for which the diary entries are being +found. If the value of the expression is `t', the entry applies to +that date. If the expression evaluates to `nil', the entry does _not_ +apply to that date. + + The following sexp diary entries take advantage of the ability (in +the fancy diary display) to concoct diary entries whose text varies +based on the date: + +`%%(diary-sunrise-sunset)' + Make a diary entry for the local times of today's sunrise and + sunset. + +`%%(diary-phases-of-moon)' + Make a diary entry for the phases (quarters) of the moon. + +`%%(diary-day-of-year)' + Make a diary entry with today's day number in the current year and + the number of days remaining in the current year. + +`%%(diary-iso-date)' + Make a diary entry with today's equivalent ISO commercial date. + +`%%(diary-julian-date)' + Make a diary entry with today's equivalent date on the Julian + calendar. + +`%%(diary-astro-day-number)' + Make a diary entry with today's equivalent astronomical (Julian) + day number. + +`%%(diary-hebrew-date)' + Make a diary entry with today's equivalent date on the Hebrew + calendar. + +`%%(diary-islamic-date)' + Make a diary entry with today's equivalent date on the Islamic + calendar. + +`%%(diary-french-date)' + Make a diary entry with today's equivalent date on the French + Revolutionary calendar. + +`%%(diary-mayan-date)' + Make a diary entry with today's equivalent date on the Mayan + calendar. + +Thus including the diary entry + + &%%(diary-hebrew-date) + +causes every day's diary display to contain the equivalent date on the +Hebrew calendar, if you are using the fancy diary display. (With simple +diary display, the line `&%%(diary-hebrew-date)' appears in the diary +for any date, but does nothing particularly useful.) + + These functions can be used to construct sexp diary entries based on +the Hebrew calendar in certain standard ways: + +`%%(diary-rosh-hodesh)' + Make a diary entry that tells the occurrence and ritual + announcement of each new Hebrew month. + +`%%(diary-parasha)' + Make a Saturday diary entry that tells the weekly synagogue + scripture reading. + +`%%(diary-sabbath-candles)' + Make a Friday diary entry that tells the _local time_ of Sabbath + candle lighting. + +`%%(diary-omer)' + Make a diary entry that gives the omer count, when appropriate. + +`%%(diary-yahrzeit MONTH DAY YEAR) NAME' + Make a diary entry marking the anniversary of a date of death. + The date is the _Gregorian_ (civil) date of death. The diary + entry appears on the proper Hebrew calendar anniversary and on the + day before. (In the European style, the order of the parameters + is changed to DAY, MONTH, YEAR.) + + +File: xemacs.info, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customization + +Customizing Appointment Reminders +................................. + + You can specify exactly how Emacs reminds you of an appointment, and +how far in advance it begins doing so, by setting these variables: + +`appt-message-warning-time' + The time in minutes before an appointment that the reminder + begins. The default is 10 minutes. + +`appt-audible' + If this is `t' (the default), Emacs rings the terminal bell for + appointment reminders. + +`appt-visible' + If this is `t' (the default), Emacs displays the appointment + message in echo area. + +`appt-display-mode-line' + If this is `t' (the default), Emacs displays the number of minutes + to the appointment on the mode line. + +`appt-msg-window' + If this is `t' (the default), Emacs displays the appointment + message in another window. + +`appt-display-duration' + The number of seconds an appointment message is displayed. The + default is 5 seconds. + + +File: xemacs.info, Node: Sorting, Next: Shell, Prev: Calendar/Diary, Up: Top + +Sorting Text +============ + + XEmacs provides several commands for sorting text in a buffer. All +operate on the contents of the region (the text between point and the +mark). They divide the text of the region into many "sort records", +identify a "sort key" for each record, and then reorder the records +using the order determined by the sort keys. The records are ordered so +that their keys are in alphabetical order, or, for numerical sorting, in +numerical order. In alphabetical sorting, all upper-case letters `A' +through `Z' come before lower-case `a', in accordance with the ASCII +character sequence. + + The sort commands differ in how they divide the text into sort +records and in which part of each record they use as the sort key. +Most of the commands make each line a separate sort record, but some +commands use paragraphs or pages as sort records. Most of the sort +commands use each entire sort record as its own sort key, but some use +only a portion of the record as the sort key. + +`M-x sort-lines' + Divide the region into lines and sort by comparing the entire text + of a line. A prefix argument means sort in descending order. + +`M-x sort-paragraphs' + Divide the region into paragraphs and sort by comparing the entire + text of a paragraph (except for leading blank lines). A prefix + argument means sort in descending order. + +`M-x sort-pages' + Divide the region into pages and sort by comparing the entire text + of a page (except for leading blank lines). A prefix argument + means sort in descending order. + +`M-x sort-fields' + Divide the region into lines and sort by comparing the contents of + one field in each line. Fields are defined as separated by + whitespace, so the first run of consecutive non-whitespace + characters in a line constitutes field 1, the second such run + constitutes field 2, etc. + + You specify which field to sort by with a numeric argument: 1 to + sort by field 1, etc. A negative argument means sort in descending + order. Thus, minus 2 means sort by field 2 in reverse-alphabetical + order. + +`M-x sort-numeric-fields' + Like `M-x sort-fields', except the specified field is converted to + a number for each line and the numbers are compared. `10' comes + before `2' when considered as text, but after it when considered + as a number. + +`M-x sort-columns' + Like `M-x sort-fields', except that the text within each line used + for comparison comes from a fixed range of columns. An explanation + is given below. + + For example, if the buffer contains: + + On systems where clash detection (locking of files being edited) is + implemented, XEmacs also checks the first time you modify a buffer + whether the file has changed on disk since it was last visited or + saved. If it has, you are asked to confirm that you want to change + the buffer. + +then if you apply `M-x sort-lines' to the entire buffer you get: + + On systems where clash detection (locking of files being edited) is + implemented, XEmacs also checks the first time you modify a buffer + saved. If it has, you are asked to confirm that you want to change + the buffer. + whether the file has changed on disk since it was last visited or + +where the upper case `O' comes before all lower case letters. If you +apply instead `C-u 2 M-x sort-fields' you get: + + saved. If it has, you are asked to confirm that you want to change + implemented, XEmacs also checks the first time you modify a buffer + the buffer. + On systems where clash detection (locking of files being edited) is + whether the file has changed on disk since it was last visited or + +where the sort keys were `If', `XEmacs', `buffer', `systems', and `the'. + + `M-x sort-columns' requires more explanation. You specify the +columns by putting point at one of the columns and the mark at the other +column. Because this means you cannot put point or the mark at the +beginning of the first line to sort, this command uses an unusual +definition of `region': all of the line point is in is considered part +of the region, and so is all of the line the mark is in. + + For example, to sort a table by information found in columns 10 to +15, you could put the mark on column 10 in the first line of the table, +and point on column 15 in the last line of the table, and then use this +command. Or you could put the mark on column 15 in the first line and +point on column 10 in the last line. + + This can be thought of as sorting the rectangle specified by point +and the mark, except that the text on each line to the left or right of +the rectangle moves along with the text inside the rectangle. *Note +Rectangles::. + + +File: xemacs.info, Node: Shell, Next: Narrowing, Prev: Sorting, Up: Top + +Running Shell Commands from XEmacs +================================== + + XEmacs has commands for passing single command lines to inferior +shell processes; it can also run a shell interactively with input and +output to an XEmacs buffer `*shell*'. + +`M-!' + Run a specified shell command line and display the output + (`shell-command'). + +`M-|' + Run a specified shell command line with region contents as input; + optionally replace the region with the output + (`shell-command-on-region'). + +`M-x shell' + Run a subshell with input and output through an XEmacs buffer. + You can then give commands interactively. + +`M-x term' + Run a subshell with input and output through an XEmacs buffer. + You can then give commands interactively. Full terminal emulation + is available. + +* Menu: + +* Single Shell:: How to run one shell command and return. +* Interactive Shell:: Permanent shell taking input via XEmacs. +* Shell Mode:: Special XEmacs commands used with permanent shell. +* Terminal emulator:: An XEmacs window as a terminal emulator. +* Term Mode:: Special XEmacs commands used in Term mode. +* Paging in Term:: Paging in the terminal emulator. + + +File: xemacs.info, Node: Single Shell, Next: Interactive Shell, Prev: Shell, Up: Shell + +Single Shell Commands +--------------------- + + `M-!' (`shell-command') reads a line of text using the minibuffer +and creates an inferior shell to execute the line as a command. +Standard input from the command comes from the null device. If the +shell command produces any output, the output goes to an XEmacs buffer +named `*Shell Command Output*', which is displayed in another window +but not selected. A numeric argument, as in `M-1 M-!', directs this +command to insert any output into the current buffer. In that case, +point is left before the output and the mark is set after the output. + + `M-|' (`shell-command-on-region') is like `M-!' but passes the +contents of the region as input to the shell command, instead of no +input. If a numeric argument is used to direct output to the current +buffer, then the old region is deleted first and the output replaces it +as the contents of the region. + + Both `M-!' and `M-|' use `shell-file-name' to specify the shell to +use. This variable is initialized based on your `SHELL' environment +variable when you start XEmacs. If the file name does not specify a +directory, the directories in the list `exec-path' are searched; this +list is initialized based on the `PATH' environment variable when you +start XEmacs. You can override either or both of these default +initializations in your init file. *Note Init File::. + + When you use `M-!' and `M-|', XEmacs has to wait until the shell +command completes. You can quit with `C-g'; that terminates the shell +command. + + File: xemacs.info, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell Interactive Inferior Shell @@ -586,584 +1175,3 @@ file to do the customization in each session. *Note Init File::. * X Resources:: X resources controlling various aspects of the behavior of XEmacs. - -File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization - -Minor Modes -=========== - - Minor modes are options which you can use or not. For example, Auto -Fill mode is a minor mode in which breaks lines between words as -you type. All the minor modes are independent of each other and of the -selected major mode. Most minor modes inform you in the mode line when -they are on; for example, `Fill' in the mode line means that Auto Fill -mode is on. - - Append `-mode' to the name of a minor mode to get the name of a -command function that turns the mode on or off. Thus, the command to -enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These -commands are usually invoked with `M-x', but you can bind keys to them -if you wish. With no argument, the function turns the mode on if it was -off and off if it was on. This is known as "toggling". A positive -argument always turns the mode on, and an explicit zero argument or a -negative argument always turns it off. - - Auto Fill mode allows you to enter filled text without breaking lines -explicitly. Emacs inserts newlines as necessary to prevent lines from -becoming too long. *Note Filling::. - - Overwrite mode causes ordinary printing characters to replace -existing text instead of moving it to the right. For example, if point -is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite -mode, it changes to `FOOGAR', instead of `FOOGBAR'. - - Abbrev mode allows you to define abbreviations that automatically -expand as you type them. For example, `amd' might expand to `abbrev -mode'. *Note Abbrevs::, for full information. - - -File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization - -Variables -========= - - A "variable" is a Lisp symbol which has a value. Variable names can -contain any characters, but by convention they are words separated by -hyphens. A variable can also have a documentation string, which -describes what kind of value it should have and how the value will be -used. - - Lisp allows any variable to have any kind of value, but most -variables that Emacs uses require a value of a certain type. Often the -value has to be a string or a number. Sometimes we say that a certain -feature is turned on if a variable is "non-`nil'," meaning that if the -variable's value is `nil', the feature is off, but the feature is on -for any other value. The conventional value to turn on the -feature--since you have to pick one particular value when you set the -variable--is `t'. - - Emacs uses many Lisp variables for internal recordkeeping, as any -Lisp program must, but the most interesting variables for you are the -ones that exist for the sake of customization. Emacs does not -(usually) change the values of these variables; instead, you set the -values, and thereby alter and control the behavior of certain Emacs -commands. These variables are called "options". Most options are -documented in this manual and appear in the Variable Index (*note -Variable Index::). - - One example of a variable which is an option is `fill-column', which -specifies the position of the right margin (as a number of characters -from the left margin) to be used by the fill commands (*note Filling::). - -* Menu: - -* Examining:: Examining or setting one variable's value. -* Easy Customization:: Convenient and easy customization of variables. -* Edit Options:: Examining or editing list of all variables' values. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. - - -File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables - -Examining and Setting Variables -------------------------------- - -`C-h v' -`M-x describe-variable' - Print the value and documentation of a variable. - -`M-x set-variable' - Change the value of a variable. - - To examine the value of a single variable, use `C-h v' -(`describe-variable'), which reads a variable name using the -minibuffer, with completion. It prints both the value and the -documentation of the variable. - - C-h v fill-column - -prints something like: - - fill-column's value is 75 - - Documentation: - *Column beyond which automatic line-wrapping should happen. - Automatically becomes local when set in any fashion. - -The star at the beginning of the documentation indicates that this -variable is an option. `C-h v' is not restricted to options; it allows -any variable name. - - If you know which option you want to set, you can use `M-x -set-variable' to set it. This prompts for the variable name in the -minibuffer (with completion), and then prompts for a Lisp expression -for the new value using the minibuffer a second time. For example, - - M-x set-variable fill-column 75 - -sets `fill-column' to 75, as if you had executed the Lisp expression -`(setq fill-column 75)'. - - Setting variables in this way, like all means of customizing Emacs -except where explicitly stated, affects only the current Emacs session. - - -File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables - -Easy Customization Interface ----------------------------- - - A convenient way to find the user option variables that you want to -change, and then change them, is with `M-x customize'. This command -creates a "customization buffer" with which you can browse through the -Emacs user options in a logically organized structure, then edit and -set their values. You can also use the customization buffer to save -settings permanently. (Not all Emacs user options are included in this -structure as of yet, but we are adding the rest.) - -* Menu: - -* Groups: Customization Groups. - How options are classified in a structure. -* Changing an Option:: How to edit a value and set an option. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Making a customization buffer for specific - options, faces, or groups. - - -File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization - -Customization Groups -.................... - - For customization purposes, user options are organized into "groups" -to help you find them. Groups are collected into bigger groups, all -the way up to a master group called `Emacs'. - - `M-x customize' creates a customization buffer that shows the -top-level `Emacs' group and the second-level groups immediately under -it. It looks like this, in part: - - /- Emacs group: ---------------------------------------------------\ - [State]: visible group members are all at standard settings. - Customization of the One True Editor. - See also [Manual]. - - [Open] Editing group - Basic text editing facilities. - - [Open] External group - Interfacing to external utilities. - - MORE SECOND-LEVEL GROUPS - - \- Emacs group end ------------------------------------------------/ - -This says that the buffer displays the contents of the `Emacs' group. -The other groups are listed because they are its contents. But they -are listed differently, without indentation and dashes, because _their_ -contents are not included. Each group has a single-line documentation -string; the `Emacs' group also has a `[State]' line. - - Most of the text in the customization buffer is read-only, but it -typically includes some "editable fields" that you can edit. There are -also "active fields"; this means a field that does something when you -"invoke" it. To invoke an active field, either click on it with -`Mouse-1', or move point to it and type . - - For example, the phrase `[Open]' that appears in a second-level -group is an active field. Invoking the `[Open]' field for a group -opens up a new customization buffer, which shows that group and its -contents. This field is a kind of hypertext link to another group. - - The `Emacs' group does not include any user options itself, but -other groups do. By examining various groups, you will eventually find -the options and faces that belong to the feature you are interested in -customizing. Then you can use the customization buffer to set them. - - You can view the structure of customization groups on a larger scale -with `M-x customize-browse'. This command creates a special kind of -customization buffer which shows only the names of the groups (and -options and faces), and their structure. - - In this buffer, you can show the contents of a group by invoking -`[+]'. When the group contents are visible, this button changes to -`[-]'; invoking that hides the group contents. - - Each group, option or face name in this buffer has an active field -which says `[Group]', `[Option]' or `[Face]'. Invoking that active -field creates an ordinary customization buffer showing just that group -and its contents, just that option, or just that face. This is the way -to set values in it. - - -File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization - -Changing an Option -.................. - - Here is an example of what a user option looks like in the -customization buffer: - - Kill Ring Max: [Hide] 30 - [State]: this option is unchanged from its standard setting. - Maximum length of kill ring before oldest elements are thrown away. - - The text following `[Hide]', `30' in this case, indicates the -current value of the option. If you see `[Show]' instead of `[Hide]', -it means that the value is hidden; the customization buffer initially -hides values that take up several lines. Invoke `[Show]' to show the -value. - - The line after the option name indicates the "customization state" -of the option: in the example above, it says you have not changed the -option yet. The word `[State]' at the beginning of this line is -active; you can get a menu of various operations by invoking it with -`Mouse-1' or . These operations are essential for customizing the -variable. - - The line after the `[State]' line displays the beginning of the -option's documentation string. If there are more lines of -documentation, this line ends with `[More]'; invoke this to show the -full documentation string. - - To enter a new value for `Kill Ring Max', move point to the value -and edit it textually. For example, you can type `M-d', then insert -another number. - - When you begin to alter the text, you will see the `[State]' line -change to say that you have edited the value: - - [State]: you have edited the value as text, but not set the option. - - Editing the value does not actually set the option variable. To do -that, you must "set" the option. To do this, invoke the word `[State]' -and choose `Set for Current Session'. - - The state of the option changes visibly when you set it: - - [State]: you have set this option, but not saved it for future sessions. - - You don't have to worry about specifying a value that is not valid; -setting the option checks for validity and will not really install an -unacceptable value. - - While editing a value or field that is a file name, directory name, -command name, or anything else for which completion is defined, you can -type `M-' (`widget-complete') to do completion. - - Some options have a small fixed set of possible legitimate values. -These options don't let you edit the value textually. Instead, an -active field `[Value Menu]' appears before the value; invoke this field -to edit the value. For a boolean "on or off" value, the active field -says `[Toggle]', and it changes to the other value. `[Value Menu]' and -`[Toggle]' edit the buffer; the changes take effect when you use the -`Set for Current Session' operation. - - Some options have values with complex structure. For example, the -value of `load-path' is a list of directories. Here is how it appears -in the customization buffer: - - Load Path: - [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp - [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp - [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim - [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp - [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp - [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus - [INS] - [State]: this item has been changed outside the customization buffer. - List of directories to search for files to load.... - -Each directory in the list appears on a separate line, and each line has -several editable or active fields. - - You can edit any of the directory names. To delete a directory from -the list, invoke `[DEL]' on that line. To insert a new directory in -the list, invoke `[INS]' at the point where you want to insert it. - - You can also invoke `[Current dir?]' to switch between including a -specific named directory in the path, and including `nil' in the path. -(`nil' in a search path means "try the current directory.") - - Two special commands, and `S-', are useful for moving -through the customization buffer. (`widget-forward') moves -forward to the next active or editable field; `S-' -(`widget-backward') moves backward to the previous active or editable -field. - - Typing on an editable field also moves forward, just like -. The reason for this is that people have a tendency to type - when they are finished editing a field. If you have occasion to -insert a newline in an editable field, use `C-o' or `C-q C-j', - - Setting the option changes its value in the current Emacs session; -"saving" the value changes it for future sessions as well. This works -by writing code into your init file so as to set the option variable -again each time you start Emacs. *Note Init File::. To save the -option, invoke `[State]' and select the `Save for Future Sessions' -operation. - - You can also restore the option to its standard value by invoking -`[State]' and selecting the `Reset' operation. There are actually -three reset operations: - -`Reset to Current' - If you have made some modifications and not yet set the option, - this restores the text in the customization buffer to match the - actual value. - -`Reset to Saved' - This restores the value of the option to the last saved value, and - updates the text accordingly. - -`Reset to Standard Settings' - This sets the option to its standard value, and updates the text - accordingly. This also eliminates any saved value for the option, - so that you will get the standard value in future Emacs sessions. - - The state of a group indicates whether anything in that group has -been edited, set or saved. You can select `Set for Current Session', -`Save for Future Sessions' and the various kinds of `Reset' operation -for the group; these operations on the group apply to all options in -the group and its subgroups. - - Near the top of the customization buffer there are two lines -containing several active fields: - - [Set] [Save] [Reset] [Done] - -Invoking `[Done]' buries this customization buffer. Each of the other -fields performs an operation--set, save or reset--on each of the items -in the buffer that could meaningfully be set, saved or reset. - - -File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization - -Customizing Faces -................. - - In addition to user options, some customization groups also include -faces. When you show the contents of a group, both the user options and -the faces in the group appear in the customization buffer. Here is an -example of how a face looks: - - Custom Changed Face: (sample) - [State]: this face is unchanged from its standard setting. - Face used when the customize item has been changed. - Parent groups: [Custom Magic Faces] - Attributes: [ ] Bold: [Toggle] off (nil) - [ ] Italic: [Toggle] off (nil) - [ ] Underline: [Toggle] off (nil) - [ ] Foreground: white (sample) - [ ] Background: blue (sample) - [ ] Inverse: [Toggle] off (nil) - [ ] Stipple: - [ ] Font Family: - [ ] Size: - [ ] Strikethru: off - - Each face attribute has its own line. The `[X]' field before the -attribute name indicates whether the attribute is "enabled"; `X' means -that it is. You can enable or disable the attribute by invoking that -field. When the attribute is enabled, you can change the attribute -value in the usual ways. - - Setting, saving and resetting a face work like the same operations -for options (*note Changing an Option::). - - A face can specify different appearances for different types of -display. For example, a face can make text red on a color display, but -use a bold font on a monochrome display. To specify multiple -appearances for a face, select `Show Display Types' in the menu you get -from invoking `[State]'. - - -File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization - -Customizing Specific Items -.......................... - - Instead of finding the options you want to change by moving down -through the structure of groups, you can specify the particular option, -face or group that you want to customize. - -`M-x customize-option OPTION ' - Set up a customization buffer with just one option, OPTION. - -`M-x customize-face FACE ' - Set up a customization buffer with just one face, FACE. - -`M-x customize-group GROUP ' - Set up a customization buffer with just one group, GROUP. - -`M-x customize-apropos REGEXP ' - Set up a customization buffer with all the options, faces and - groups that match REGEXP. - -`M-x customize-saved' - Set up a customization buffer containing all options and faces - that you have saved with customization buffers. - -`M-x customize-customized' - Set up a customization buffer containing all options and faces - that you have customized but not saved. - - If you want to alter a particular user option variable with the -customization buffer, and you know its name, you can use the command -`M-x customize-option' and specify the option name. This sets up the -customization buffer with just one option--the one that you asked for. -Editing, setting and saving the value work as described above, but only -for the specified option. - - Likewise, you can modify a specific face, chosen by name, using `M-x -customize-face'. - - You can also set up the customization buffer with a specific group, -using `M-x customize-group'. The immediate contents of the chosen -group, including option variables, faces, and other groups, all appear -as well. However, these subgroups' own contents start out hidden. You -can show their contents in the usual way, by invoking `[Show]'. - - To control more precisely what to customize, you can use `M-x -customize-apropos'. You specify a regular expression as argument; then -all options, faces and groups whose names match this regular expression -are set up in the customization buffer. If you specify an empty regular -expression, this includes _all_ groups, options and faces in the -customization buffer (but that takes a long time). - - If you change option values and then decide the change was a mistake, -you can use two special commands to revisit your previous changes. Use -`customize-saved' to look at the options and faces that you have saved. -Use `M-x customize-customized' to look at the options and faces that -you have set but not saved. - - -File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables - -Editing Variable Values ------------------------ - -`M-x list-options' - Display a buffer listing names, values, and documentation of all - options. - -`M-x edit-options' - Change option values by editing a list of options. - - `M-x list-options' displays a list of all Emacs option variables in -an Emacs buffer named `*List Options*'. Each option is shown with its -documentation and its current value. Here is what a portion of it might -look like: - - ;; exec-path: - ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc") - *List of directories to search programs to run in subprocesses. - Each element is a string (directory name) - or nil (try the default directory). - ;; - ;; fill-column: - 75 - *Column beyond which automatic line-wrapping should happen. - Automatically becomes local when set in any fashion. - ;; - - `M-x edit-options' goes one step further and immediately selects the -`*List Options*' buffer; this buffer uses the major mode Options mode, -which provides commands that allow you to point at an option and change -its value: - -`s' - Set the variable point is in or near to a new value read using the - minibuffer. - -`x' - Toggle the variable point is in or near: if the value was `nil', - it becomes `t'; otherwise it becomes `nil'. - -`1' - Set the variable point is in or near to `t'. - -`0' - Set the variable point is in or near to `nil'. - -`n' -`p' - Move to the next or previous variable. - - -File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables - -Local Variables ---------------- - -`M-x make-local-variable' - Make a variable have a local value in the current buffer. - -`M-x kill-local-variable' - Make a variable use its global value in the current buffer. - -`M-x make-variable-buffer-local' - Mark a variable so that setting it will make it local to the - buffer that is current at that time. - - You can make any variable "local" to a specific Emacs buffer. This -means that the variable's value in that buffer is independent of its -value in other buffers. A few variables are always local in every -buffer. All other Emacs variables have a "global" value which is in -effect in all buffers that have not made the variable local. - - Major modes always make the variables they set local to the buffer. -This is why changing major modes in one buffer has no effect on other -buffers. - - `M-x make-local-variable' reads the name of a variable and makes it -local to the current buffer. Further changes in this buffer will not -affect others, and changes in the global value will not affect this -buffer. - - `M-x make-variable-buffer-local' reads the name of a variable and -changes the future behavior of the variable so that it automatically -becomes local when it is set. More precisely, once you have marked a -variable in this way, the usual ways of setting the variable will -automatically invoke `make-local-variable' first. We call such -variables "per-buffer" variables. - - Some important variables have been marked per-buffer already. They -include `abbrev-mode', `auto-fill-function', `case-fold-search', -`comment-column', `ctl-arrow', `fill-column', `fill-prefix', -`indent-tabs-mode', `left-margin', -`mode-line-format', `overwrite-mode', `selective-display-ellipses', -`selective-display', `tab-width', and `truncate-lines'. Some other -variables are always local in every buffer, but they are used for -internal purposes. - - Note: the variable `auto-fill-function' was formerly named -`auto-fill-hook'. - - If you want a variable to cease to be local to the current buffer, -call `M-x kill-local-variable' and provide the name of a variable to -the prompt. The global value of the variable is again in effect in -this buffer. Setting the major mode kills all the local variables of -the buffer. - - To set the global value of a variable, regardless of whether the -variable has a local value in the current buffer, you can use the Lisp -function `setq-default'. It works like `setq'. If there is a local -value in the current buffer, the local value is not affected by -`setq-default'; thus, the new global value may not be visible until you -switch to another buffer, as in the case of: - - (setq-default fill-column 75) - -`setq-default' is the only way to set the global value of a variable -that has been marked with `make-variable-buffer-local'. - - Programs can look at a variable's default value with `default-value'. -This function takes a symbol as an argument and returns its default -value. The argument is evaluated; usually you must quote it -explicitly, as in the case of: - - (default-value 'fill-column) - diff --git a/info/xemacs.info-17 b/info/xemacs.info-17 index 0b7a7a7..a03c890 100644 --- a/info/xemacs.info-17 +++ b/info/xemacs.info-17 @@ -30,6 +30,587 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Minor Modes, Next: Variables, Up: Customization + +Minor Modes +=========== + + Minor modes are options which you can use or not. For example, Auto +Fill mode is a minor mode in which breaks lines between words as +you type. All the minor modes are independent of each other and of the +selected major mode. Most minor modes inform you in the mode line when +they are on; for example, `Fill' in the mode line means that Auto Fill +mode is on. + + Append `-mode' to the name of a minor mode to get the name of a +command function that turns the mode on or off. Thus, the command to +enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These +commands are usually invoked with `M-x', but you can bind keys to them +if you wish. With no argument, the function turns the mode on if it was +off and off if it was on. This is known as "toggling". A positive +argument always turns the mode on, and an explicit zero argument or a +negative argument always turns it off. + + Auto Fill mode allows you to enter filled text without breaking lines +explicitly. Emacs inserts newlines as necessary to prevent lines from +becoming too long. *Note Filling::. + + Overwrite mode causes ordinary printing characters to replace +existing text instead of moving it to the right. For example, if point +is in front of the `B' in `FOOBAR', and you type a `G' in Overwrite +mode, it changes to `FOOGAR', instead of `FOOGBAR'. + + Abbrev mode allows you to define abbreviations that automatically +expand as you type them. For example, `amd' might expand to `abbrev +mode'. *Note Abbrevs::, for full information. + + +File: xemacs.info, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization + +Variables +========= + + A "variable" is a Lisp symbol which has a value. Variable names can +contain any characters, but by convention they are words separated by +hyphens. A variable can also have a documentation string, which +describes what kind of value it should have and how the value will be +used. + + Lisp allows any variable to have any kind of value, but most +variables that Emacs uses require a value of a certain type. Often the +value has to be a string or a number. Sometimes we say that a certain +feature is turned on if a variable is "non-`nil'," meaning that if the +variable's value is `nil', the feature is off, but the feature is on +for any other value. The conventional value to turn on the +feature--since you have to pick one particular value when you set the +variable--is `t'. + + Emacs uses many Lisp variables for internal recordkeeping, as any +Lisp program must, but the most interesting variables for you are the +ones that exist for the sake of customization. Emacs does not +(usually) change the values of these variables; instead, you set the +values, and thereby alter and control the behavior of certain Emacs +commands. These variables are called "options". Most options are +documented in this manual and appear in the Variable Index (*note +Variable Index::). + + One example of a variable which is an option is `fill-column', which +specifies the position of the right margin (as a number of characters +from the left margin) to be used by the fill commands (*note Filling::). + +* Menu: + +* Examining:: Examining or setting one variable's value. +* Easy Customization:: Convenient and easy customization of variables. +* Edit Options:: Examining or editing list of all variables' values. +* Locals:: Per-buffer values of variables. +* File Variables:: How files can specify variable values. + + +File: xemacs.info, Node: Examining, Next: Easy Customization, Up: Variables + +Examining and Setting Variables +------------------------------- + +`C-h v' +`M-x describe-variable' + Print the value and documentation of a variable. + +`M-x set-variable' + Change the value of a variable. + + To examine the value of a single variable, use `C-h v' +(`describe-variable'), which reads a variable name using the +minibuffer, with completion. It prints both the value and the +documentation of the variable. + + C-h v fill-column + +prints something like: + + fill-column's value is 75 + + Documentation: + *Column beyond which automatic line-wrapping should happen. + Automatically becomes local when set in any fashion. + +The star at the beginning of the documentation indicates that this +variable is an option. `C-h v' is not restricted to options; it allows +any variable name. + + If you know which option you want to set, you can use `M-x +set-variable' to set it. This prompts for the variable name in the +minibuffer (with completion), and then prompts for a Lisp expression +for the new value using the minibuffer a second time. For example, + + M-x set-variable fill-column 75 + +sets `fill-column' to 75, as if you had executed the Lisp expression +`(setq fill-column 75)'. + + Setting variables in this way, like all means of customizing Emacs +except where explicitly stated, affects only the current Emacs session. + + +File: xemacs.info, Node: Easy Customization, Next: Edit Options, Prev: Examining, Up: Variables + +Easy Customization Interface +---------------------------- + + A convenient way to find the user option variables that you want to +change, and then change them, is with `M-x customize'. This command +creates a "customization buffer" with which you can browse through the +Emacs user options in a logically organized structure, then edit and +set their values. You can also use the customization buffer to save +settings permanently. (Not all Emacs user options are included in this +structure as of yet, but we are adding the rest.) + +* Menu: + +* Groups: Customization Groups. + How options are classified in a structure. +* Changing an Option:: How to edit a value and set an option. +* Face Customization:: How to edit the attributes of a face. +* Specific Customization:: Making a customization buffer for specific + options, faces, or groups. + + +File: xemacs.info, Node: Customization Groups, Next: Changing an Option, Up: Easy Customization + +Customization Groups +.................... + + For customization purposes, user options are organized into "groups" +to help you find them. Groups are collected into bigger groups, all +the way up to a master group called `Emacs'. + + `M-x customize' creates a customization buffer that shows the +top-level `Emacs' group and the second-level groups immediately under +it. It looks like this, in part: + + /- Emacs group: ---------------------------------------------------\ + [State]: visible group members are all at standard settings. + Customization of the One True Editor. + See also [Manual]. + + [Open] Editing group + Basic text editing facilities. + + [Open] External group + Interfacing to external utilities. + + MORE SECOND-LEVEL GROUPS + + \- Emacs group end ------------------------------------------------/ + +This says that the buffer displays the contents of the `Emacs' group. +The other groups are listed because they are its contents. But they +are listed differently, without indentation and dashes, because _their_ +contents are not included. Each group has a single-line documentation +string; the `Emacs' group also has a `[State]' line. + + Most of the text in the customization buffer is read-only, but it +typically includes some "editable fields" that you can edit. There are +also "active fields"; this means a field that does something when you +"invoke" it. To invoke an active field, either click on it with +`Mouse-1', or move point to it and type . + + For example, the phrase `[Open]' that appears in a second-level +group is an active field. Invoking the `[Open]' field for a group +opens up a new customization buffer, which shows that group and its +contents. This field is a kind of hypertext link to another group. + + The `Emacs' group does not include any user options itself, but +other groups do. By examining various groups, you will eventually find +the options and faces that belong to the feature you are interested in +customizing. Then you can use the customization buffer to set them. + + You can view the structure of customization groups on a larger scale +with `M-x customize-browse'. This command creates a special kind of +customization buffer which shows only the names of the groups (and +options and faces), and their structure. + + In this buffer, you can show the contents of a group by invoking +`[+]'. When the group contents are visible, this button changes to +`[-]'; invoking that hides the group contents. + + Each group, option or face name in this buffer has an active field +which says `[Group]', `[Option]' or `[Face]'. Invoking that active +field creates an ordinary customization buffer showing just that group +and its contents, just that option, or just that face. This is the way +to set values in it. + + +File: xemacs.info, Node: Changing an Option, Next: Face Customization, Prev: Customization Groups, Up: Easy Customization + +Changing an Option +.................. + + Here is an example of what a user option looks like in the +customization buffer: + + Kill Ring Max: [Hide] 30 + [State]: this option is unchanged from its standard setting. + Maximum length of kill ring before oldest elements are thrown away. + + The text following `[Hide]', `30' in this case, indicates the +current value of the option. If you see `[Show]' instead of `[Hide]', +it means that the value is hidden; the customization buffer initially +hides values that take up several lines. Invoke `[Show]' to show the +value. + + The line after the option name indicates the "customization state" +of the option: in the example above, it says you have not changed the +option yet. The word `[State]' at the beginning of this line is +active; you can get a menu of various operations by invoking it with +`Mouse-1' or . These operations are essential for customizing the +variable. + + The line after the `[State]' line displays the beginning of the +option's documentation string. If there are more lines of +documentation, this line ends with `[More]'; invoke this to show the +full documentation string. + + To enter a new value for `Kill Ring Max', move point to the value +and edit it textually. For example, you can type `M-d', then insert +another number. + + When you begin to alter the text, you will see the `[State]' line +change to say that you have edited the value: + + [State]: you have edited the value as text, but not set the option. + + Editing the value does not actually set the option variable. To do +that, you must "set" the option. To do this, invoke the word `[State]' +and choose `Set for Current Session'. + + The state of the option changes visibly when you set it: + + [State]: you have set this option, but not saved it for future sessions. + + You don't have to worry about specifying a value that is not valid; +setting the option checks for validity and will not really install an +unacceptable value. + + While editing a value or field that is a file name, directory name, +command name, or anything else for which completion is defined, you can +type `M-' (`widget-complete') to do completion. + + Some options have a small fixed set of possible legitimate values. +These options don't let you edit the value textually. Instead, an +active field `[Value Menu]' appears before the value; invoke this field +to edit the value. For a boolean "on or off" value, the active field +says `[Toggle]', and it changes to the other value. `[Value Menu]' and +`[Toggle]' edit the buffer; the changes take effect when you use the +`Set for Current Session' operation. + + Some options have values with complex structure. For example, the +value of `load-path' is a list of directories. Here is how it appears +in the customization buffer: + + Load Path: + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim + [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp + [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp + [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus + [INS] + [State]: this item has been changed outside the customization buffer. + List of directories to search for files to load.... + +Each directory in the list appears on a separate line, and each line has +several editable or active fields. + + You can edit any of the directory names. To delete a directory from +the list, invoke `[DEL]' on that line. To insert a new directory in +the list, invoke `[INS]' at the point where you want to insert it. + + You can also invoke `[Current dir?]' to switch between including a +specific named directory in the path, and including `nil' in the path. +(`nil' in a search path means "try the current directory.") + + Two special commands, and `S-', are useful for moving +through the customization buffer. (`widget-forward') moves +forward to the next active or editable field; `S-' +(`widget-backward') moves backward to the previous active or editable +field. + + Typing on an editable field also moves forward, just like +. The reason for this is that people have a tendency to type + when they are finished editing a field. If you have occasion to +insert a newline in an editable field, use `C-o' or `C-q C-j', + + Setting the option changes its value in the current Emacs session; +"saving" the value changes it for future sessions as well. This works +by writing code into your init file so as to set the option variable +again each time you start Emacs. *Note Init File::. To save the +option, invoke `[State]' and select the `Save for Future Sessions' +operation. + + You can also restore the option to its standard value by invoking +`[State]' and selecting the `Reset' operation. There are actually +three reset operations: + +`Reset to Current' + If you have made some modifications and not yet set the option, + this restores the text in the customization buffer to match the + actual value. + +`Reset to Saved' + This restores the value of the option to the last saved value, and + updates the text accordingly. + +`Reset to Standard Settings' + This sets the option to its standard value, and updates the text + accordingly. This also eliminates any saved value for the option, + so that you will get the standard value in future Emacs sessions. + + The state of a group indicates whether anything in that group has +been edited, set or saved. You can select `Set for Current Session', +`Save for Future Sessions' and the various kinds of `Reset' operation +for the group; these operations on the group apply to all options in +the group and its subgroups. + + Near the top of the customization buffer there are two lines +containing several active fields: + + [Set] [Save] [Reset] [Done] + +Invoking `[Done]' buries this customization buffer. Each of the other +fields performs an operation--set, save or reset--on each of the items +in the buffer that could meaningfully be set, saved or reset. + + +File: xemacs.info, Node: Face Customization, Next: Specific Customization, Prev: Changing an Option, Up: Easy Customization + +Customizing Faces +................. + + In addition to user options, some customization groups also include +faces. When you show the contents of a group, both the user options and +the faces in the group appear in the customization buffer. Here is an +example of how a face looks: + + Custom Changed Face: (sample) + [State]: this face is unchanged from its standard setting. + Face used when the customize item has been changed. + Parent groups: [Custom Magic Faces] + Attributes: [ ] Bold: [Toggle] off (nil) + [ ] Italic: [Toggle] off (nil) + [ ] Underline: [Toggle] off (nil) + [ ] Foreground: white (sample) + [ ] Background: blue (sample) + [ ] Inverse: [Toggle] off (nil) + [ ] Stipple: + [ ] Font Family: + [ ] Size: + [ ] Strikethru: off + + Each face attribute has its own line. The `[X]' field before the +attribute name indicates whether the attribute is "enabled"; `X' means +that it is. You can enable or disable the attribute by invoking that +field. When the attribute is enabled, you can change the attribute +value in the usual ways. + + Setting, saving and resetting a face work like the same operations +for options (*note Changing an Option::). + + A face can specify different appearances for different types of +display. For example, a face can make text red on a color display, but +use a bold font on a monochrome display. To specify multiple +appearances for a face, select `Show Display Types' in the menu you get +from invoking `[State]'. + + +File: xemacs.info, Node: Specific Customization, Prev: Face Customization, Up: Easy Customization + +Customizing Specific Items +.......................... + + Instead of finding the options you want to change by moving down +through the structure of groups, you can specify the particular option, +face or group that you want to customize. + +`M-x customize-option OPTION ' + Set up a customization buffer with just one option, OPTION. + +`M-x customize-face FACE ' + Set up a customization buffer with just one face, FACE. + +`M-x customize-group GROUP ' + Set up a customization buffer with just one group, GROUP. + +`M-x customize-apropos REGEXP ' + Set up a customization buffer with all the options, faces and + groups that match REGEXP. + +`M-x customize-saved' + Set up a customization buffer containing all options and faces + that you have saved with customization buffers. + +`M-x customize-customized' + Set up a customization buffer containing all options and faces + that you have customized but not saved. + + If you want to alter a particular user option variable with the +customization buffer, and you know its name, you can use the command +`M-x customize-option' and specify the option name. This sets up the +customization buffer with just one option--the one that you asked for. +Editing, setting and saving the value work as described above, but only +for the specified option. + + Likewise, you can modify a specific face, chosen by name, using `M-x +customize-face'. + + You can also set up the customization buffer with a specific group, +using `M-x customize-group'. The immediate contents of the chosen +group, including option variables, faces, and other groups, all appear +as well. However, these subgroups' own contents start out hidden. You +can show their contents in the usual way, by invoking `[Show]'. + + To control more precisely what to customize, you can use `M-x +customize-apropos'. You specify a regular expression as argument; then +all options, faces and groups whose names match this regular expression +are set up in the customization buffer. If you specify an empty regular +expression, this includes _all_ groups, options and faces in the +customization buffer (but that takes a long time). + + If you change option values and then decide the change was a mistake, +you can use two special commands to revisit your previous changes. Use +`customize-saved' to look at the options and faces that you have saved. +Use `M-x customize-customized' to look at the options and faces that +you have set but not saved. + + +File: xemacs.info, Node: Edit Options, Next: Locals, Prev: Easy Customization, Up: Variables + +Editing Variable Values +----------------------- + +`M-x list-options' + Display a buffer listing names, values, and documentation of all + options. + +`M-x edit-options' + Change option values by editing a list of options. + + `M-x list-options' displays a list of all Emacs option variables in +an Emacs buffer named `*List Options*'. Each option is shown with its +documentation and its current value. Here is what a portion of it might +look like: + + ;; exec-path: + ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc") + *List of directories to search programs to run in subprocesses. + Each element is a string (directory name) + or nil (try the default directory). + ;; + ;; fill-column: + 75 + *Column beyond which automatic line-wrapping should happen. + Automatically becomes local when set in any fashion. + ;; + + `M-x edit-options' goes one step further and immediately selects the +`*List Options*' buffer; this buffer uses the major mode Options mode, +which provides commands that allow you to point at an option and change +its value: + +`s' + Set the variable point is in or near to a new value read using the + minibuffer. + +`x' + Toggle the variable point is in or near: if the value was `nil', + it becomes `t'; otherwise it becomes `nil'. + +`1' + Set the variable point is in or near to `t'. + +`0' + Set the variable point is in or near to `nil'. + +`n' +`p' + Move to the next or previous variable. + + +File: xemacs.info, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables + +Local Variables +--------------- + +`M-x make-local-variable' + Make a variable have a local value in the current buffer. + +`M-x kill-local-variable' + Make a variable use its global value in the current buffer. + +`M-x make-variable-buffer-local' + Mark a variable so that setting it will make it local to the + buffer that is current at that time. + + You can make any variable "local" to a specific Emacs buffer. This +means that the variable's value in that buffer is independent of its +value in other buffers. A few variables are always local in every +buffer. All other Emacs variables have a "global" value which is in +effect in all buffers that have not made the variable local. + + Major modes always make the variables they set local to the buffer. +This is why changing major modes in one buffer has no effect on other +buffers. + + `M-x make-local-variable' reads the name of a variable and makes it +local to the current buffer. Further changes in this buffer will not +affect others, and changes in the global value will not affect this +buffer. + + `M-x make-variable-buffer-local' reads the name of a variable and +changes the future behavior of the variable so that it automatically +becomes local when it is set. More precisely, once you have marked a +variable in this way, the usual ways of setting the variable will +automatically invoke `make-local-variable' first. We call such +variables "per-buffer" variables. + + Some important variables have been marked per-buffer already. They +include `abbrev-mode', `auto-fill-function', `case-fold-search', +`comment-column', `ctl-arrow', `fill-column', `fill-prefix', +`indent-tabs-mode', `left-margin', +`mode-line-format', `overwrite-mode', `selective-display-ellipses', +`selective-display', `tab-width', and `truncate-lines'. Some other +variables are always local in every buffer, but they are used for +internal purposes. + + Note: the variable `auto-fill-function' was formerly named +`auto-fill-hook'. + + If you want a variable to cease to be local to the current buffer, +call `M-x kill-local-variable' and provide the name of a variable to +the prompt. The global value of the variable is again in effect in +this buffer. Setting the major mode kills all the local variables of +the buffer. + + To set the global value of a variable, regardless of whether the +variable has a local value in the current buffer, you can use the Lisp +function `setq-default'. It works like `setq'. If there is a local +value in the current buffer, the local value is not affected by +`setq-default'; thus, the new global value may not be visible until you +switch to another buffer, as in the case of: + + (setq-default fill-column 75) + +`setq-default' is the only way to set the global value of a variable +that has been marked with `make-variable-buffer-local'. + + Programs can look at a variable's default value with `default-value'. +This function takes a symbol as an argument and returns its default +value. The argument is evaluated; usually you must quote it +explicitly, as in the case of: + + (default-value 'fill-column) + + File: xemacs.info, Node: File Variables, Prev: Locals, Up: Variables Local Variables in Files @@ -599,577 +1180,3 @@ fashion: control [ escape control @ control space - -File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings - -Disabling Commands ------------------- - - Disabling a command marks it as requiring confirmation before it can -be executed. The purpose of disabling a command is to prevent -beginning users from executing it by accident and being confused. - - The direct mechanism for disabling a command is to have a non-`nil' -`disabled' property on the Lisp symbol for the command. These -properties are normally set by the user's init file with Lisp -expressions such as: - - (put 'delete-region 'disabled t) - - *Note Init File::. - - If the value of the `disabled' property is a string, that string is -included in the message printed when the command is used: - - (put 'delete-region 'disabled - "Text deleted this way cannot be yanked back!\n") - - You can disable a command either by editing the init file directly -or with the command `M-x disable-command', which edits the init file -for you. *Note Init File::. - - When you attempt to invoke a disabled command interactively in Emacs, -a window is displayed containing the command's name, its documentation, -and some instructions on what to do next; then Emacs asks for input -saying whether to execute the command as requested, enable it and -execute, or cancel it. If you decide to enable the command, you are -asked whether to do this permanently or just for the current session. -Enabling permanently works by automatically editing your init file. -You can use `M-x enable-command' at any time to enable any command -permanently. - - Whether a command is disabled is independent of what key is used to -invoke it; it also applies if the command is invoked using `M-x'. -Disabling a command has no effect on calling it as a function from Lisp -programs. - - -File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization - -The Syntax Table -================ - - All the Emacs commands which parse words or balance parentheses are -controlled by the "syntax table". The syntax table specifies which -characters are opening delimiters, which are parts of words, which are -string quotes, and so on. Actually, each major mode has its own syntax -table (though sometimes related major modes use the same one) which it -installs in each buffer that uses that major mode. The syntax table -installed in the current buffer is the one that all commands use, so we -call it "the" syntax table. A syntax table is a Lisp object, a vector -of length 256 whose elements are numbers. - -* Menu: - -* Entry: Syntax Entry. What the syntax table records for each character. -* Change: Syntax Change. How to change the information. - - -File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax - -Information About Each Character --------------------------------- - - The syntax table entry for a character is a number that encodes six -pieces of information: - - * The syntactic class of the character, represented as a small - integer - - * The matching delimiter, for delimiter characters only (the - matching delimiter of `(' is `)', and vice versa) - - * A flag saying whether the character is the first character of a - two-character comment starting sequence - - * A flag saying whether the character is the second character of a - two-character comment starting sequence - - * A flag saying whether the character is the first character of a - two-character comment ending sequence - - * A flag saying whether the character is the second character of a - two-character comment ending sequence - - The syntactic classes are stored internally as small integers, but -are usually described to or by the user with characters. For example, -`(' is used to specify the syntactic class of opening delimiters. Here -is a table of syntactic classes, with the characters that specify them. - -` ' - The class of whitespace characters. - -`w' - The class of word-constituent characters. - -`_' - The class of characters that are part of symbol names but not - words. This class is represented by `_' because the character `_' - has this class in both C and Lisp. - -`.' - The class of punctuation characters that do not fit into any other - special class. - -`(' - The class of opening delimiters. - -`)' - The class of closing delimiters. - -`'' - The class of expression-adhering characters. These characters are - part of a symbol if found within or adjacent to one, and are part - of a following expression if immediately preceding one, but are - like whitespace if surrounded by whitespace. - -`"' - The class of string-quote characters. They match each other in - pairs, and the characters within the pair all lose their syntactic - significance except for the `\' and `/' classes of escape - characters, which can be used to include a string-quote inside the - string. - -`$' - The class of self-matching delimiters. This is intended for TeX's - `$', which is used both to enter and leave math mode. Thus, a - pair of matching `$' characters surround each piece of math mode - TeX input. A pair of adjacent `$' characters act like a single - one for purposes of matching. - -`/' - The class of escape characters that always just deny the following - character its special syntactic significance. The character after - one of these escapes is always treated as alphabetic. - -`\' - The class of C-style escape characters. In practice, these are - treated just like `/'-class characters, because the extra - possibilities for C escapes (such as being followed by digits) - have no effect on where the containing expression ends. - -`<' - The class of comment-starting characters. Only single-character - comment starters (such as `;' in Lisp mode) are represented this - way. - -`>' - The class of comment-ending characters. Newline has this syntax in - Lisp mode. - - The characters flagged as part of two-character comment delimiters -can have other syntactic functions most of the time. For example, `/' -and `*' in C code, when found separately, have nothing to do with -comments. The comment-delimiter significance overrides when the pair of -characters occur together in the proper order. Only the list and sexp -commands use the syntax table to find comments; the commands -specifically for comments have other variables that tell them where to -find comments. Moreover, the list and sexp commands notice comments -only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set -to `nil' in modes where comment-terminator sequences are liable to -appear where there is no comment, for example, in Lisp mode where the -comment terminator is a newline but not every newline ends a comment. - - -File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax - -Altering Syntax Information ---------------------------- - - It is possible to alter a character's syntax table entry by storing -a new number in the appropriate element of the syntax table, but it -would be hard to determine what number to use. Emacs therefore -provides a command that allows you to specify the syntactic properties -of a character in a convenient way. - - `M-x modify-syntax-entry' is the command to change a character's -syntax. It can be used interactively and is also used by major modes -to initialize their own syntax tables. Its first argument is the -character to change. The second argument is a string that specifies the -new syntax. When called from Lisp code, there is a third, optional -argument, which specifies the syntax table in which to make the change. -If not supplied, or if this command is called interactively, the third -argument defaults to the current buffer's syntax table. - - 1. The first character in the string specifies the syntactic class. - It is one of the characters in the previous table (*note Syntax - Entry::). - - 2. The second character is the matching delimiter. For a character - that is not an opening or closing delimiter, this should be a - space, and may be omitted if no following characters are needed. - - 3. The remaining characters are flags. The flag characters allowed - are: - - `1' - Flag this character as the first of a two-character comment - starting sequence. - - `2' - Flag this character as the second of a two-character comment - starting sequence. - - `3' - Flag this character as the first of a two-character comment - ending sequence. - - `4' - Flag this character as the second of a two-character comment - ending sequence. - - Use `C-h s' (`describe-syntax') to display a description of the -contents of the current syntax table. The description of each -character includes both the string you have to pass to -`modify-syntax-entry' to set up that character's current syntax, and -some English to explain that string if necessary. - - -File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization - -The Init File -============= - - When you start Emacs, it normally loads either `.xemacs/init.el' or -the file `.emacs' (whichever comes first) in your home directory. This -file, if it exists, should contain Lisp code. It is called your -initialization file or "init file". Use the command line switch `-q' -to tell Emacs whether to load an init file (*note Entering Emacs::). -Use the command line switch `-user-init-file' (*note Command -Switches::) to tell Emacs to load a different file instead of -`~/.xemacs/init.el'/`~/.emacs'. - - When the init file is read, the variable `user-init-file' says which -init file was loaded. - - At some sites there is a "default init file", which is the library -named `default.el', found via the standard search path for libraries. -The Emacs distribution contains no such library; your site may create -one for local customizations. If this library exists, it is loaded -whenever you start Emacs. But your init file, if any, is loaded first; -if it sets `inhibit-default-init' non-`nil', then `default' is not -loaded. - - If you have a large amount of code in your init file, you should -byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'. - -* Menu: - -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. - - -File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File - -Init File Syntax ----------------- - - The init file contains one or more Lisp function call expressions. -Each consists of a function name followed by arguments, all surrounded -by parentheses. For example, `(setq fill-column 60)' represents a call -to the function `setq' which is used to set the variable `fill-column' -(*note Filling::) to 60. - - The second argument to `setq' is an expression for the new value of -the variable. This can be a constant, a variable, or a function call -expression. In the init file, constants are used most of the time. -They can be: - -Numbers - Integers are written in decimal, with an optional initial minus - sign. - - If a sequence of digits is followed by a period and another - sequence of digits, it is interpreted as a floating point number. - - The number prefixes `#b', `#o', and `#x' are supported to - represent numbers in binary, octal, and hexadecimal notation (or - radix). - -Strings - Lisp string syntax is the same as C string syntax with a few extra - features. Use a double-quote character to begin and end a string - constant. - - Newlines and special characters may be present literally in - strings. They can also be represented as backslash sequences: - `\n' for newline, `\b' for backspace, `\r' for return, `\t' for - tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a - backslash, `\"' for a double-quote, or `\OOO' for the character - whose octal code is OOO. Backslash and double-quote are the only - characters for which backslash sequences are mandatory. - - You can use `\C-' as a prefix for a control character, as in - `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta - character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A. - -Characters - Lisp character constant syntax consists of a `?' followed by - either a character or an escape sequence starting with `\'. - Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and - characters are not interchangeable in Lisp; some contexts require - one and some contexts require the other. - -True - `t' stands for `true'. - -False - `nil' stands for `false'. - -Other Lisp objects - Write a single-quote (') followed by the Lisp object you want. - - -File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File - -Init File Examples ------------------- - - Here are some examples of doing certain commonly desired things with -Lisp expressions: - - * Make in C mode just insert a tab if point is in the middle - of a line. - - (setq c-tab-always-indent nil) - - Here we have a variable whose value is normally `t' for `true' and - the alternative is `nil' for `false'. - - * Make searches case sensitive by default (in all buffers that do not - override this). - - (setq-default case-fold-search nil) - - This sets the default value, which is effective in all buffers - that do not have local values for the variable. Setting - `case-fold-search' with `setq' affects only the current buffer's - local value, which is probably not what you want to do in an init - file. - - * Make Text mode the default mode for new buffers. - - (setq default-major-mode 'text-mode) - - Note that `text-mode' is used because it is the command for - entering the mode we want. A single-quote is written before it to - make a symbol constant; otherwise, `text-mode' would be treated as - a variable name. - - * Turn on Auto Fill mode automatically in Text mode and related - modes. - - (setq text-mode-hook - '(lambda () (auto-fill-mode 1))) - - Here we have a variable whose value should be a Lisp function. The - function we supply is a list starting with `lambda', and a single - quote is written in front of it to make it (for the purpose of this - `setq') a list constant rather than an expression. Lisp functions - are not explained here; for mode hooks it is enough to know that - `(auto-fill-mode 1)' is an expression that will be executed when - Text mode is entered. You could replace it with any other - expression that you like, or with several expressions in a row. - - (setq text-mode-hook 'turn-on-auto-fill) - - This is another way to accomplish the same result. - `turn-on-auto-fill' is a symbol whose function definition is - `(lambda () (auto-fill-mode 1))'. - - * Load the installed Lisp library named `foo' (actually a file - `foo.elc' or `foo.el' in a standard Emacs directory). - - (load "foo") - - When the argument to `load' is a relative pathname, not starting - with `/' or `~', `load' searches the directories in `load-path' - (*note Loading::). - - * Load the compiled Lisp file `foo.elc' from your home directory. - - (load "~/foo.elc") - - Here an absolute file name is used, so no searching is done. - - * Rebind the key `C-x l' to run the function `make-symbolic-link'. - - (global-set-key "\C-xl" 'make-symbolic-link) - - or - - (define-key global-map "\C-xl" 'make-symbolic-link) - - Note once again the single-quote used to refer to the symbol - `make-symbolic-link' instead of its value as a variable. - - * Do the same thing for C mode only. - - (define-key c-mode-map "\C-xl" 'make-symbolic-link) - - * Bind the function key to a command in C mode. Note that the - names of function keys must be lower case. - - (define-key c-mode-map 'f1 'make-symbolic-link) - - * Bind the shifted version of to a command. - - (define-key c-mode-map '(shift f1) 'make-symbolic-link) - - * Redefine all keys which now run `next-line' in Fundamental mode to - run `forward-line' instead. - - (substitute-key-definition 'next-line 'forward-line - global-map) - - * Make `C-x C-v' undefined. - - (global-unset-key "\C-x\C-v") - - One reason to undefine a key is so that you can make it a prefix. - Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix, - but `C-x C-v' must be freed of any non-prefix definition first. - - * Make `$' have the syntax of punctuation in Text mode. Note the - use of a character constant for `$'. - - (modify-syntax-entry ?\$ "." text-mode-syntax-table) - - * Enable the use of the command `eval-expression' without - confirmation. - - (put 'eval-expression 'disabled nil) - - -File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File - -Terminal-Specific Initialization --------------------------------- - - Each terminal type can have a Lisp library to be loaded into Emacs -when it is run on that type of terminal. For a terminal type named -TERMTYPE, the library is called `term/TERMTYPE' and it is found by -searching the directories `load-path' as usual and trying the suffixes -`.elc' and `.el'. Normally it appears in the subdirectory `term' of -the directory where most Emacs libraries are kept. - - The usual purpose of the terminal-specific library is to define the -escape sequences used by the terminal's function keys using the library -`keypad.el'. See the file `term/vt100.el' for an example of how this -is done. - - When the terminal type contains a hyphen, only the part of the name -before the first hyphen is significant in choosing the library name. -Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library -`term/aaa'. The code in the library can use `(getenv "TERM")' to find -the full terminal type name. - - The library's name is constructed by concatenating the value of the -variable `term-file-prefix' and the terminal type. Your init file can -prevent the loading of the terminal-specific library by setting -`term-file-prefix' to `nil'. *Note Init File::. - - The value of the variable `term-setup-hook', if not `nil', is called -as a function of no arguments at the end of Emacs initialization, after -both your init file and any terminal-specific library have been read. -*Note Init File::. You can set the value in the init file to override -part of any of the terminal-specific libraries and to define -initializations for terminals that do not have a library. - - -File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization - -Changing the Bell Sound -======================= - - You can now change how the audible bell sounds using the variable -`sound-alist'. - - `sound-alist''s value is an list associating symbols with, among -other things, strings of audio-data. When `ding' is called with one of -the symbols, the associated sound data is played instead of the -standard beep. This only works if you are logged in on the console of a -machine with audio hardware. To listen to a sound of the provided type, -call the function `play-sound' with the argument SOUND. You can also -set the volume of the sound with the optional argument VOLUME. - - Each element of `sound-alist' is a list describing a sound. The -first element of the list is the name of the sound being defined. -Subsequent elements of the list are alternating keyword/value pairs: - -`sound' - A string of raw sound data, or the name of another sound to play. - The symbol `t' here means use the default X beep. - -`volume' - An integer from 0-100, defaulting to `bell-volume'. - -`pitch' - If using the default X beep, the pitch (Hz) to generate. - -`duration' - If using the default X beep, the duration (milliseconds). - - For compatibility, elements of `sound-alist' may also be of the form: - - ( SOUND-NAME . ) - ( SOUND-NAME ) - - You should probably add things to this list by calling the function -`load-sound-file'. - - Note that you can only play audio data if running on the console -screen of a machine with audio hardware which emacs understands, which -at this time means a Sun SparcStation, SGI, or HP9000s700. - - Also note that the pitch, duration, and volume options are available -everywhere, but most X servers ignore the `pitch' option. - - The variable `bell-volume' should be an integer from 0 to 100, with -100 being loudest, which controls how loud the sounds emacs makes -should be. Elements of the `sound-alist' may override this value. -This variable applies to the standard X bell sound as well as sound -files. - - If the symbol `t' is in place of a sound-string, Emacs uses the -default X beep. This allows you to define beep-types of different -volumes even when not running on the console. - - You can add things to this list by calling the function -`load-sound-file', which reads in an audio-file and adds its data to -the sound-alist. You can specify the sound with the SOUND-NAME argument -and the file into which the sounds are loaded with the FILENAME -argument. The optional VOLUME argument sets the volume. - - `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)' - - To load and install some sound files as beep-types, use the function -`load-default-sounds' (note that this only works if you are on display -0 of a machine with audio hardware). - - The following beep-types are used by Emacs itself. Other Lisp -packages may use other beep types, but these are the ones that the C -kernel of Emacs uses. - -`auto-save-error' - An auto-save does not succeed - -`command-error' - The Emacs command loop catches an error - -`undefined-key' - You type a key that is undefined - -`undefined-click' - You use an undefined mouse-click combination - -`no-completion' - Completion was not possible - -`y-or-n-p' - You type something other than the required `y' or `n' - -`yes-or-no-p' - You type something other than `yes' or `no' - diff --git a/info/xemacs.info-18 b/info/xemacs.info-18 index 1983b65..ad966c0 100644 --- a/info/xemacs.info-18 +++ b/info/xemacs.info-18 @@ -30,6 +30,580 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Disabling, Prev: Rebinding, Up: Key Bindings + +Disabling Commands +------------------ + + Disabling a command marks it as requiring confirmation before it can +be executed. The purpose of disabling a command is to prevent +beginning users from executing it by accident and being confused. + + The direct mechanism for disabling a command is to have a non-`nil' +`disabled' property on the Lisp symbol for the command. These +properties are normally set by the user's init file with Lisp +expressions such as: + + (put 'delete-region 'disabled t) + + *Note Init File::. + + If the value of the `disabled' property is a string, that string is +included in the message printed when the command is used: + + (put 'delete-region 'disabled + "Text deleted this way cannot be yanked back!\n") + + You can disable a command either by editing the init file directly +or with the command `M-x disable-command', which edits the init file +for you. *Note Init File::. + + When you attempt to invoke a disabled command interactively in Emacs, +a window is displayed containing the command's name, its documentation, +and some instructions on what to do next; then Emacs asks for input +saying whether to execute the command as requested, enable it and +execute, or cancel it. If you decide to enable the command, you are +asked whether to do this permanently or just for the current session. +Enabling permanently works by automatically editing your init file. +You can use `M-x enable-command' at any time to enable any command +permanently. + + Whether a command is disabled is independent of what key is used to +invoke it; it also applies if the command is invoked using `M-x'. +Disabling a command has no effect on calling it as a function from Lisp +programs. + + +File: xemacs.info, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization + +The Syntax Table +================ + + All the Emacs commands which parse words or balance parentheses are +controlled by the "syntax table". The syntax table specifies which +characters are opening delimiters, which are parts of words, which are +string quotes, and so on. Actually, each major mode has its own syntax +table (though sometimes related major modes use the same one) which it +installs in each buffer that uses that major mode. The syntax table +installed in the current buffer is the one that all commands use, so we +call it "the" syntax table. A syntax table is a Lisp object, a vector +of length 256 whose elements are numbers. + +* Menu: + +* Entry: Syntax Entry. What the syntax table records for each character. +* Change: Syntax Change. How to change the information. + + +File: xemacs.info, Node: Syntax Entry, Next: Syntax Change, Up: Syntax + +Information About Each Character +-------------------------------- + + The syntax table entry for a character is a number that encodes six +pieces of information: + + * The syntactic class of the character, represented as a small + integer + + * The matching delimiter, for delimiter characters only (the + matching delimiter of `(' is `)', and vice versa) + + * A flag saying whether the character is the first character of a + two-character comment starting sequence + + * A flag saying whether the character is the second character of a + two-character comment starting sequence + + * A flag saying whether the character is the first character of a + two-character comment ending sequence + + * A flag saying whether the character is the second character of a + two-character comment ending sequence + + The syntactic classes are stored internally as small integers, but +are usually described to or by the user with characters. For example, +`(' is used to specify the syntactic class of opening delimiters. Here +is a table of syntactic classes, with the characters that specify them. + +` ' + The class of whitespace characters. + +`w' + The class of word-constituent characters. + +`_' + The class of characters that are part of symbol names but not + words. This class is represented by `_' because the character `_' + has this class in both C and Lisp. + +`.' + The class of punctuation characters that do not fit into any other + special class. + +`(' + The class of opening delimiters. + +`)' + The class of closing delimiters. + +`'' + The class of expression-adhering characters. These characters are + part of a symbol if found within or adjacent to one, and are part + of a following expression if immediately preceding one, but are + like whitespace if surrounded by whitespace. + +`"' + The class of string-quote characters. They match each other in + pairs, and the characters within the pair all lose their syntactic + significance except for the `\' and `/' classes of escape + characters, which can be used to include a string-quote inside the + string. + +`$' + The class of self-matching delimiters. This is intended for TeX's + `$', which is used both to enter and leave math mode. Thus, a + pair of matching `$' characters surround each piece of math mode + TeX input. A pair of adjacent `$' characters act like a single + one for purposes of matching. + +`/' + The class of escape characters that always just deny the following + character its special syntactic significance. The character after + one of these escapes is always treated as alphabetic. + +`\' + The class of C-style escape characters. In practice, these are + treated just like `/'-class characters, because the extra + possibilities for C escapes (such as being followed by digits) + have no effect on where the containing expression ends. + +`<' + The class of comment-starting characters. Only single-character + comment starters (such as `;' in Lisp mode) are represented this + way. + +`>' + The class of comment-ending characters. Newline has this syntax in + Lisp mode. + + The characters flagged as part of two-character comment delimiters +can have other syntactic functions most of the time. For example, `/' +and `*' in C code, when found separately, have nothing to do with +comments. The comment-delimiter significance overrides when the pair of +characters occur together in the proper order. Only the list and sexp +commands use the syntax table to find comments; the commands +specifically for comments have other variables that tell them where to +find comments. Moreover, the list and sexp commands notice comments +only if `parse-sexp-ignore-comments' is non-`nil'. This variable is set +to `nil' in modes where comment-terminator sequences are liable to +appear where there is no comment, for example, in Lisp mode where the +comment terminator is a newline but not every newline ends a comment. + + +File: xemacs.info, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax + +Altering Syntax Information +--------------------------- + + It is possible to alter a character's syntax table entry by storing +a new number in the appropriate element of the syntax table, but it +would be hard to determine what number to use. Emacs therefore +provides a command that allows you to specify the syntactic properties +of a character in a convenient way. + + `M-x modify-syntax-entry' is the command to change a character's +syntax. It can be used interactively and is also used by major modes +to initialize their own syntax tables. Its first argument is the +character to change. The second argument is a string that specifies the +new syntax. When called from Lisp code, there is a third, optional +argument, which specifies the syntax table in which to make the change. +If not supplied, or if this command is called interactively, the third +argument defaults to the current buffer's syntax table. + + 1. The first character in the string specifies the syntactic class. + It is one of the characters in the previous table (*note Syntax + Entry::). + + 2. The second character is the matching delimiter. For a character + that is not an opening or closing delimiter, this should be a + space, and may be omitted if no following characters are needed. + + 3. The remaining characters are flags. The flag characters allowed + are: + + `1' + Flag this character as the first of a two-character comment + starting sequence. + + `2' + Flag this character as the second of a two-character comment + starting sequence. + + `3' + Flag this character as the first of a two-character comment + ending sequence. + + `4' + Flag this character as the second of a two-character comment + ending sequence. + + Use `C-h s' (`describe-syntax') to display a description of the +contents of the current syntax table. The description of each +character includes both the string you have to pass to +`modify-syntax-entry' to set up that character's current syntax, and +some English to explain that string if necessary. + + +File: xemacs.info, Node: Init File, Next: Audible Bell, Prev: Syntax, Up: Customization + +The Init File +============= + + When you start Emacs, it normally loads either `.xemacs/init.el' or +the file `.emacs' (whichever comes first) in your home directory. This +file, if it exists, should contain Lisp code. It is called your +initialization file or "init file". Use the command line switch `-q' +to tell Emacs whether to load an init file (*note Entering Emacs::). +Use the command line switch `-user-init-file' (*note Command +Switches::) to tell Emacs to load a different file instead of +`~/.xemacs/init.el'/`~/.emacs'. + + When the init file is read, the variable `user-init-file' says which +init file was loaded. + + At some sites there is a "default init file", which is the library +named `default.el', found via the standard search path for libraries. +The Emacs distribution contains no such library; your site may create +one for local customizations. If this library exists, it is loaded +whenever you start Emacs. But your init file, if any, is loaded first; +if it sets `inhibit-default-init' non-`nil', then `default' is not +loaded. + + If you have a large amount of code in your init file, you should +byte-compile it to `~/.xemacs/init.elc' or `~/.emacs.elc'. + +* Menu: + +* Init Syntax:: Syntax of constants in Emacs Lisp. +* Init Examples:: How to do some things with an init file. +* Terminal Init:: Each terminal type can have an init file. + + +File: xemacs.info, Node: Init Syntax, Next: Init Examples, Up: Init File + +Init File Syntax +---------------- + + The init file contains one or more Lisp function call expressions. +Each consists of a function name followed by arguments, all surrounded +by parentheses. For example, `(setq fill-column 60)' represents a call +to the function `setq' which is used to set the variable `fill-column' +(*note Filling::) to 60. + + The second argument to `setq' is an expression for the new value of +the variable. This can be a constant, a variable, or a function call +expression. In the init file, constants are used most of the time. +They can be: + +Numbers + Integers are written in decimal, with an optional initial minus + sign. + + If a sequence of digits is followed by a period and another + sequence of digits, it is interpreted as a floating point number. + + The number prefixes `#b', `#o', and `#x' are supported to + represent numbers in binary, octal, and hexadecimal notation (or + radix). + +Strings + Lisp string syntax is the same as C string syntax with a few extra + features. Use a double-quote character to begin and end a string + constant. + + Newlines and special characters may be present literally in + strings. They can also be represented as backslash sequences: + `\n' for newline, `\b' for backspace, `\r' for return, `\t' for + tab, `\f' for formfeed (control-l), `\e' for escape, `\\' for a + backslash, `\"' for a double-quote, or `\OOO' for the character + whose octal code is OOO. Backslash and double-quote are the only + characters for which backslash sequences are mandatory. + + You can use `\C-' as a prefix for a control character, as in + `\C-s' for ASCII Control-S, and `\M-' as a prefix for a Meta + character, as in `\M-a' for Meta-A or `\M-\C-a' for Control-Meta-A. + +Characters + Lisp character constant syntax consists of a `?' followed by + either a character or an escape sequence starting with `\'. + Examples: `?x', `?\n', `?\"', `?\)'. Note that strings and + characters are not interchangeable in Lisp; some contexts require + one and some contexts require the other. + +True + `t' stands for `true'. + +False + `nil' stands for `false'. + +Other Lisp objects + Write a single-quote (') followed by the Lisp object you want. + + +File: xemacs.info, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File + +Init File Examples +------------------ + + Here are some examples of doing certain commonly desired things with +Lisp expressions: + + * Make in C mode just insert a tab if point is in the middle + of a line. + + (setq c-tab-always-indent nil) + + Here we have a variable whose value is normally `t' for `true' and + the alternative is `nil' for `false'. + + * Make searches case sensitive by default (in all buffers that do not + override this). + + (setq-default case-fold-search nil) + + This sets the default value, which is effective in all buffers + that do not have local values for the variable. Setting + `case-fold-search' with `setq' affects only the current buffer's + local value, which is probably not what you want to do in an init + file. + + * Make Text mode the default mode for new buffers. + + (setq default-major-mode 'text-mode) + + Note that `text-mode' is used because it is the command for + entering the mode we want. A single-quote is written before it to + make a symbol constant; otherwise, `text-mode' would be treated as + a variable name. + + * Turn on Auto Fill mode automatically in Text mode and related + modes. + + (setq text-mode-hook + '(lambda () (auto-fill-mode 1))) + + Here we have a variable whose value should be a Lisp function. The + function we supply is a list starting with `lambda', and a single + quote is written in front of it to make it (for the purpose of this + `setq') a list constant rather than an expression. Lisp functions + are not explained here; for mode hooks it is enough to know that + `(auto-fill-mode 1)' is an expression that will be executed when + Text mode is entered. You could replace it with any other + expression that you like, or with several expressions in a row. + + (setq text-mode-hook 'turn-on-auto-fill) + + This is another way to accomplish the same result. + `turn-on-auto-fill' is a symbol whose function definition is + `(lambda () (auto-fill-mode 1))'. + + * Load the installed Lisp library named `foo' (actually a file + `foo.elc' or `foo.el' in a standard Emacs directory). + + (load "foo") + + When the argument to `load' is a relative pathname, not starting + with `/' or `~', `load' searches the directories in `load-path' + (*note Loading::). + + * Load the compiled Lisp file `foo.elc' from your home directory. + + (load "~/foo.elc") + + Here an absolute file name is used, so no searching is done. + + * Rebind the key `C-x l' to run the function `make-symbolic-link'. + + (global-set-key "\C-xl" 'make-symbolic-link) + + or + + (define-key global-map "\C-xl" 'make-symbolic-link) + + Note once again the single-quote used to refer to the symbol + `make-symbolic-link' instead of its value as a variable. + + * Do the same thing for C mode only. + + (define-key c-mode-map "\C-xl" 'make-symbolic-link) + + * Bind the function key to a command in C mode. Note that the + names of function keys must be lower case. + + (define-key c-mode-map 'f1 'make-symbolic-link) + + * Bind the shifted version of to a command. + + (define-key c-mode-map '(shift f1) 'make-symbolic-link) + + * Redefine all keys which now run `next-line' in Fundamental mode to + run `forward-line' instead. + + (substitute-key-definition 'next-line 'forward-line + global-map) + + * Make `C-x C-v' undefined. + + (global-unset-key "\C-x\C-v") + + One reason to undefine a key is so that you can make it a prefix. + Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a prefix, + but `C-x C-v' must be freed of any non-prefix definition first. + + * Make `$' have the syntax of punctuation in Text mode. Note the + use of a character constant for `$'. + + (modify-syntax-entry ?\$ "." text-mode-syntax-table) + + * Enable the use of the command `eval-expression' without + confirmation. + + (put 'eval-expression 'disabled nil) + + +File: xemacs.info, Node: Terminal Init, Prev: Init Examples, Up: Init File + +Terminal-Specific Initialization +-------------------------------- + + Each terminal type can have a Lisp library to be loaded into Emacs +when it is run on that type of terminal. For a terminal type named +TERMTYPE, the library is called `term/TERMTYPE' and it is found by +searching the directories `load-path' as usual and trying the suffixes +`.elc' and `.el'. Normally it appears in the subdirectory `term' of +the directory where most Emacs libraries are kept. + + The usual purpose of the terminal-specific library is to define the +escape sequences used by the terminal's function keys using the library +`keypad.el'. See the file `term/vt100.el' for an example of how this +is done. + + When the terminal type contains a hyphen, only the part of the name +before the first hyphen is significant in choosing the library name. +Thus, terminal types `aaa-48' and `aaa-30-rv' both use the library +`term/aaa'. The code in the library can use `(getenv "TERM")' to find +the full terminal type name. + + The library's name is constructed by concatenating the value of the +variable `term-file-prefix' and the terminal type. Your init file can +prevent the loading of the terminal-specific library by setting +`term-file-prefix' to `nil'. *Note Init File::. + + The value of the variable `term-setup-hook', if not `nil', is called +as a function of no arguments at the end of Emacs initialization, after +both your init file and any terminal-specific library have been read. +*Note Init File::. You can set the value in the init file to override +part of any of the terminal-specific libraries and to define +initializations for terminals that do not have a library. + + +File: xemacs.info, Node: Audible Bell, Next: Faces, Prev: Init File, Up: Customization + +Changing the Bell Sound +======================= + + You can now change how the audible bell sounds using the variable +`sound-alist'. + + `sound-alist''s value is an list associating symbols with, among +other things, strings of audio-data. When `ding' is called with one of +the symbols, the associated sound data is played instead of the +standard beep. This only works if you are logged in on the console of a +machine with audio hardware. To listen to a sound of the provided type, +call the function `play-sound' with the argument SOUND. You can also +set the volume of the sound with the optional argument VOLUME. + + Each element of `sound-alist' is a list describing a sound. The +first element of the list is the name of the sound being defined. +Subsequent elements of the list are alternating keyword/value pairs: + +`sound' + A string of raw sound data, or the name of another sound to play. + The symbol `t' here means use the default X beep. + +`volume' + An integer from 0-100, defaulting to `bell-volume'. + +`pitch' + If using the default X beep, the pitch (Hz) to generate. + +`duration' + If using the default X beep, the duration (milliseconds). + + For compatibility, elements of `sound-alist' may also be of the form: + + ( SOUND-NAME . ) + ( SOUND-NAME ) + + You should probably add things to this list by calling the function +`load-sound-file'. + + Note that you can only play audio data if running on the console +screen of a machine with audio hardware which emacs understands, which +at this time means a Sun SparcStation, SGI, or HP9000s700. + + Also note that the pitch, duration, and volume options are available +everywhere, but most X servers ignore the `pitch' option. + + The variable `bell-volume' should be an integer from 0 to 100, with +100 being loudest, which controls how loud the sounds emacs makes +should be. Elements of the `sound-alist' may override this value. +This variable applies to the standard X bell sound as well as sound +files. + + If the symbol `t' is in place of a sound-string, Emacs uses the +default X beep. This allows you to define beep-types of different +volumes even when not running on the console. + + You can add things to this list by calling the function +`load-sound-file', which reads in an audio-file and adds its data to +the sound-alist. You can specify the sound with the SOUND-NAME argument +and the file into which the sounds are loaded with the FILENAME +argument. The optional VOLUME argument sets the volume. + + `load-sound-file (FILENAME SOUND-NAME &optional VOLUME)' + + To load and install some sound files as beep-types, use the function +`load-default-sounds' (note that this only works if you are on display +0 of a machine with audio hardware). + + The following beep-types are used by Emacs itself. Other Lisp +packages may use other beep types, but these are the ones that the C +kernel of Emacs uses. + +`auto-save-error' + An auto-save does not succeed + +`command-error' + The Emacs command loop catches an error + +`undefined-key' + You type a key that is undefined + +`undefined-click' + You use an undefined mouse-click combination + +`no-completion' + Completion was not possible + +`y-or-n-p' + You type something other than the required `y' or `n' + +`yes-or-no-p' + You type something other than `yes' or `no' + + File: xemacs.info, Node: Faces, Next: Frame Components, Prev: Audible Bell, Up: Customization Faces @@ -696,307 +1270,3 @@ don't understand what that means, you should just get out of the recursive editing level. To do so, type `M-x top-level'. This is called getting back to top level. *Note Recursive Edit::. - -File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage - -Garbage on the Screen ---------------------- - - If the data on the screen looks wrong, the first thing to do is see -whether the text is actually wrong. Type `C-l', to redisplay the -entire screen. If the text appears correct after this, the problem was -entirely in the previous screen update. - - Display updating problems often result from an incorrect termcap -entry for the terminal you are using. The file `etc/TERMS' in the Emacs -distribution gives the fixes for known problems of this sort. -`INSTALL' contains general advice for these problems in one of its -sections. Very likely there is simply insufficient padding for certain -display operations. To investigate the possibility that you have this -sort of problem, try Emacs on another terminal made by a different -manufacturer. If problems happen frequently on one kind of terminal but -not another kind, the real problem is likely to be a bad termcap entry, -though it could also be due to a bug in Emacs that appears for terminals -that have or lack specific features. - - -File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage - -Garbage in the Text -------------------- - - If `C-l' shows that the text is wrong, try undoing the changes to it -using `C-x u' until it gets back to a state you consider correct. Also -try `C-h l' to find out what command you typed to produce the observed -results. - - If a large portion of text appears to be missing at the beginning or -end of the buffer, check for the word `Narrow' in the mode line. If it -appears, the text is still present, but marked off-limits. To make it -visible again, type `C-x n w'. *Note Narrowing::. - - -File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage - -Spontaneous Entry to Incremental Search ---------------------------------------- - - If Emacs spontaneously displays `I-search:' at the bottom of the -screen, it means that the terminal is sending `C-s' and `C-q' according -to the poorly designed xon/xoff "flow control" protocol. You should -try to prevent this by putting the terminal in a mode where it will not -use flow control, or by giving it enough padding that it will never -send a `C-s'. If that cannot be done, you must tell Emacs to expect -flow control to be used, until you can get a properly designed terminal. - - Information on how to do these things can be found in the file -`INSTALL' in the Emacs distribution. - - -File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage - -Emergency Escape ----------------- - - Because at times there have been bugs causing Emacs to loop without -checking `quit-flag', a special feature causes Emacs to be suspended -immediately if you type a second `C-g' while the flag is already set, -so you can always get out of XEmacs. Normally Emacs recognizes and -clears `quit-flag' (and quits!) quickly enough to prevent this from -happening. - - When you resume Emacs after a suspension caused by multiple `C-g', it -asks two questions before going back to what it had been doing: - - Auto-save? (y or n) - Abort (and dump core)? (y or n) - -Answer each one with `y' or `n' followed by . - - Saying `y' to `Auto-save?' causes immediate auto-saving of all -modified buffers in which auto-saving is enabled. - - Saying `y' to `Abort (and dump core)?' causes an illegal instruction -to be executed, dumping core. This is to enable a wizard to figure out -why Emacs was failing to quit in the first place. Execution does not -continue after a core dump. If you answer `n', execution does -continue. With luck, Emacs will ultimately check `quit-flag' and quit -normally. If not, and you type another `C-g', it is suspended again. - - If Emacs is not really hung, but is just being slow, you may invoke -the double `C-g' feature without really meaning to. In that case, -simply resume and answer `n' to both questions, and you will arrive at -your former state. Presumably the quit you requested will happen soon. - - The double-`C-g' feature may be turned off when Emacs is running -under a window system, since the window system always enables you to -kill Emacs or to create another window and run another program. - - -File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage - -Help for Total Frustration --------------------------- - - If using Emacs (or something else) becomes terribly frustrating and -none of the techniques described above solve the problem, Emacs can -still help you. - - First, if the Emacs you are using is not responding to commands, type -`C-g C-g' to get out of it and then start a new one. - - Second, type `M-x doctor '. - - The doctor will make you feel better. Each time you say something to -the doctor, you must end it by typing . This lets the -doctor know you are finished. - - -File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top - -Reporting Bugs -============== - - Sometimes you will encounter a bug in Emacs. Although we cannot -promise we can or will fix the bug, and we might not even agree that it -is a bug, we want to hear about bugs you encounter in case we do want -to fix them. - - To make it possible for us to fix a bug, you must report it. In -order to do so effectively, you must know when and how to do it. - -When Is There a Bug -------------------- - - If Emacs executes an illegal instruction, or dies with an operating -system error message that indicates a problem in the program (as -opposed to something like "disk full"), then it is certainly a bug. - - If Emacs updates the display in a way that does not correspond to -what is in the buffer, then it is certainly a bug. If a command seems -to do the wrong thing but the problem corrects itself if you type -`C-l', it is a case of incorrect display updating. - - Taking forever to complete a command can be a bug, but you must make -certain that it was really Emacs's fault. Some commands simply take a -long time. Type `C-g' and then `C-h l' to see whether the input Emacs -received was what you intended to type; if the input was such that you -KNOW it should have been processed quickly, report a bug. If you don't -know whether the command should take a long time, find out by looking -in the manual or by asking for assistance. - - If a command you are familiar with causes an Emacs error message in a -case where its usual definition ought to be reasonable, it is probably a -bug. - - If a command does the wrong thing, that is a bug. But be sure you -know for certain what it ought to have done. If you aren't familiar -with the command, or don't know for certain how the command is supposed -to work, then it might actually be working right. Rather than jumping -to conclusions, show the problem to someone who knows for certain. - - Finally, a command's intended definition may not be best for editing -with. This is a very important sort of problem, but it is also a -matter of judgment. Also, it is easy to come to such a conclusion out -of ignorance of some of the existing features. It is probably best not -to complain about such a problem until you have checked the -documentation in the usual ways, feel confident that you understand it, -and know for certain that what you want is not available. If you are -not sure what the command is supposed to do after a careful reading of -the manual, check the index and glossary for any terms that may be -unclear. If you still do not understand, this indicates a bug in the -manual. The manual's job is to make everything clear. It is just as -important to report documentation bugs as program bugs. - - If the online documentation string of a function or variable -disagrees with the manual, one of them must be wrong, so report the bug. - -How to Report a Bug -------------------- - - When you decide that there is a bug, it is important to report it -and to report it in a way which is useful. What is most useful is an -exact description of what commands you type, starting with the shell -command to run Emacs, until the problem happens. Always include the -version number of Emacs that you are using; type `M-x emacs-version' to -print this. - - The most important principle in reporting a bug is to report FACTS, -not hypotheses or categorizations. It is always easier to report the -facts, but people seem to prefer to strain to posit explanations and -report them instead. If the explanations are based on guesses about -how Emacs is implemented, they will be useless; we will have to try to -figure out what the facts must have been to lead to such speculations. -Sometimes this is impossible. But in any case, it is unnecessary work -for us. - - For example, suppose that you type `C-x C-f /glorp/baz.ugh ', -visiting a file which (you know) happens to be rather large, and Emacs -prints out `I feel pretty today'. The best way to report the bug is -with a sentence like the preceding one, because it gives all the facts -and nothing but the facts. - - Do not assume that the problem is due to the size of the file and -say, "When I visit a large file, Emacs prints out `I feel pretty -today'." This is what we mean by "guessing explanations". The problem -is just as likely to be due to the fact that there is a `z' in the file -name. If this is so, then when we got your report, we would try out -the problem with some "large file", probably with no `z' in its name, -and not find anything wrong. There is no way in the world that we -could guess that we should try visiting a file with a `z' in its name. - - Alternatively, the problem might be due to the fact that the file -starts with exactly 25 spaces. For this reason, you should make sure -that you inform us of the exact contents of any file that is needed to -reproduce the bug. What if the problem only occurs when you have typed -the `C-x a l' command previously? This is why we ask you to give the -exact sequence of characters you typed since starting to use Emacs. - - You should not even say "visit a file" instead of `C-x C-f' unless -you know that it makes no difference which visiting command is used. -Similarly, rather than saying "if I have three characters on the line," -say "after I type ` A B C C-p'," if that is the way you -entered the text. - - If you are not in Fundamental mode when the problem occurs, you -should say what mode you are in. - - If the manifestation of the bug is an Emacs error message, it is -important to report not just the text of the error message but a -backtrace showing how the Lisp program in Emacs arrived at the error. -To make the backtrace, you must execute the Lisp expression `(setq -debug-on-error t)' before the error happens (that is to say, you must -execute that expression and then make the bug happen). This causes the -Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace -can be copied as text into the bug report. This use of the debugger is -possible only if you know how to make the bug happen again. Do note -the error message the first time the bug happens, so if you can't make -it happen again, you can report at least that. - - Check whether any programs you have loaded into the Lisp world, -including your init file, set any variables that may affect the -functioning of Emacs. *Note Init File::. Also, see whether the -problem happens in a freshly started Emacs without loading your init -file (start Emacs with the `-q' switch to prevent loading the init -file). If the problem does NOT occur then, it is essential that we -know the contents of any programs that you must load into the Lisp -world in order to cause the problem to occur. - - If the problem does depend on an init file or other Lisp programs -that are not part of the standard Emacs system, then you should make -sure it is not a bug in those programs by complaining to their -maintainers first. After they verify that they are using Emacs in a -way that is supposed to work, they should report the bug. - - If you can tell us a way to cause the problem without visiting any -files, please do so. This makes it much easier to debug. If you do -need files, make sure you arrange for us to see their exact contents. -For example, it can often matter whether there are spaces at the ends -of lines, or a newline after the last line in the buffer (nothing ought -to care whether the last line is terminated, but tell that to the bugs). - - The easy way to record the input to Emacs precisely is to write a -dribble file; execute the Lisp expression: - - (open-dribble-file "~/dribble") - -using `Meta-' or from the `*scratch*' buffer just after starting -Emacs. From then on, all Emacs input will be written in the specified -dribble file until the Emacs process is killed. - - For possible display bugs, it is important to report the terminal -type (the value of environment variable `TERM'), the complete termcap -entry for the terminal from `/etc/termcap' (since that file is not -identical on all machines), and the output that Emacs actually sent to -the terminal. The way to collect this output is to execute the Lisp -expression: - - (open-termscript "~/termscript") - -using `Meta-' or from the `*scratch*' buffer just after starting -Emacs. From then on, all output from Emacs to the terminal will be -written in the specified termscript file as well, until the Emacs -process is killed. If the problem happens when Emacs starts up, put -this expression into your init file so that the termscript file will be -open when Emacs displays the screen for the first time. *Note Init -File::. Be warned: it is often difficult, and sometimes impossible, to -fix a terminal-dependent bug without access to a terminal of the type -that stimulates the bug. - - The newsgroup `comp.emacs.xemacs' may be used for bug reports, other -discussions and requests for assistance. - - If you don't have access to this newgroup, you can subscribe to the -mailing list version: the newsgroup is bidirectionally gatewayed into -the mailing list `xemacs@xemacs.org'. - - To be added or removed from this mailing list, send mail to -`xemacs-request@xemacs.org'. Do not send requests for addition to the -mailing list itself. - - The mailing lists and newsgroups are archived on our anonymous FTP -server, `ftp.xemacs.org', and at various other archive sites around the -net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous -FTP server. It provides some introductory information and help for -initial configuration problems. - diff --git a/info/xemacs.info-19 b/info/xemacs.info-19 index 2ab1eed..4192a79 100644 --- a/info/xemacs.info-19 +++ b/info/xemacs.info-19 @@ -30,6 +30,310 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage + +Garbage on the Screen +--------------------- + + If the data on the screen looks wrong, the first thing to do is see +whether the text is actually wrong. Type `C-l', to redisplay the +entire screen. If the text appears correct after this, the problem was +entirely in the previous screen update. + + Display updating problems often result from an incorrect termcap +entry for the terminal you are using. The file `etc/TERMS' in the Emacs +distribution gives the fixes for known problems of this sort. +`INSTALL' contains general advice for these problems in one of its +sections. Very likely there is simply insufficient padding for certain +display operations. To investigate the possibility that you have this +sort of problem, try Emacs on another terminal made by a different +manufacturer. If problems happen frequently on one kind of terminal but +not another kind, the real problem is likely to be a bad termcap entry, +though it could also be due to a bug in Emacs that appears for terminals +that have or lack specific features. + + +File: xemacs.info, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage + +Garbage in the Text +------------------- + + If `C-l' shows that the text is wrong, try undoing the changes to it +using `C-x u' until it gets back to a state you consider correct. Also +try `C-h l' to find out what command you typed to produce the observed +results. + + If a large portion of text appears to be missing at the beginning or +end of the buffer, check for the word `Narrow' in the mode line. If it +appears, the text is still present, but marked off-limits. To make it +visible again, type `C-x n w'. *Note Narrowing::. + + +File: xemacs.info, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage + +Spontaneous Entry to Incremental Search +--------------------------------------- + + If Emacs spontaneously displays `I-search:' at the bottom of the +screen, it means that the terminal is sending `C-s' and `C-q' according +to the poorly designed xon/xoff "flow control" protocol. You should +try to prevent this by putting the terminal in a mode where it will not +use flow control, or by giving it enough padding that it will never +send a `C-s'. If that cannot be done, you must tell Emacs to expect +flow control to be used, until you can get a properly designed terminal. + + Information on how to do these things can be found in the file +`INSTALL' in the Emacs distribution. + + +File: xemacs.info, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage + +Emergency Escape +---------------- + + Because at times there have been bugs causing Emacs to loop without +checking `quit-flag', a special feature causes Emacs to be suspended +immediately if you type a second `C-g' while the flag is already set, +so you can always get out of XEmacs. Normally Emacs recognizes and +clears `quit-flag' (and quits!) quickly enough to prevent this from +happening. + + When you resume Emacs after a suspension caused by multiple `C-g', it +asks two questions before going back to what it had been doing: + + Auto-save? (y or n) + Abort (and dump core)? (y or n) + +Answer each one with `y' or `n' followed by . + + Saying `y' to `Auto-save?' causes immediate auto-saving of all +modified buffers in which auto-saving is enabled. + + Saying `y' to `Abort (and dump core)?' causes an illegal instruction +to be executed, dumping core. This is to enable a wizard to figure out +why Emacs was failing to quit in the first place. Execution does not +continue after a core dump. If you answer `n', execution does +continue. With luck, Emacs will ultimately check `quit-flag' and quit +normally. If not, and you type another `C-g', it is suspended again. + + If Emacs is not really hung, but is just being slow, you may invoke +the double `C-g' feature without really meaning to. In that case, +simply resume and answer `n' to both questions, and you will arrive at +your former state. Presumably the quit you requested will happen soon. + + The double-`C-g' feature may be turned off when Emacs is running +under a window system, since the window system always enables you to +kill Emacs or to create another window and run another program. + + +File: xemacs.info, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage + +Help for Total Frustration +-------------------------- + + If using Emacs (or something else) becomes terribly frustrating and +none of the techniques described above solve the problem, Emacs can +still help you. + + First, if the Emacs you are using is not responding to commands, type +`C-g C-g' to get out of it and then start a new one. + + Second, type `M-x doctor '. + + The doctor will make you feel better. Each time you say something to +the doctor, you must end it by typing . This lets the +doctor know you are finished. + + +File: xemacs.info, Node: Bugs, Prev: Lossage, Up: Top + +Reporting Bugs +============== + + Sometimes you will encounter a bug in Emacs. Although we cannot +promise we can or will fix the bug, and we might not even agree that it +is a bug, we want to hear about bugs you encounter in case we do want +to fix them. + + To make it possible for us to fix a bug, you must report it. In +order to do so effectively, you must know when and how to do it. + +When Is There a Bug +------------------- + + If Emacs executes an illegal instruction, or dies with an operating +system error message that indicates a problem in the program (as +opposed to something like "disk full"), then it is certainly a bug. + + If Emacs updates the display in a way that does not correspond to +what is in the buffer, then it is certainly a bug. If a command seems +to do the wrong thing but the problem corrects itself if you type +`C-l', it is a case of incorrect display updating. + + Taking forever to complete a command can be a bug, but you must make +certain that it was really Emacs's fault. Some commands simply take a +long time. Type `C-g' and then `C-h l' to see whether the input Emacs +received was what you intended to type; if the input was such that you +KNOW it should have been processed quickly, report a bug. If you don't +know whether the command should take a long time, find out by looking +in the manual or by asking for assistance. + + If a command you are familiar with causes an Emacs error message in a +case where its usual definition ought to be reasonable, it is probably a +bug. + + If a command does the wrong thing, that is a bug. But be sure you +know for certain what it ought to have done. If you aren't familiar +with the command, or don't know for certain how the command is supposed +to work, then it might actually be working right. Rather than jumping +to conclusions, show the problem to someone who knows for certain. + + Finally, a command's intended definition may not be best for editing +with. This is a very important sort of problem, but it is also a +matter of judgment. Also, it is easy to come to such a conclusion out +of ignorance of some of the existing features. It is probably best not +to complain about such a problem until you have checked the +documentation in the usual ways, feel confident that you understand it, +and know for certain that what you want is not available. If you are +not sure what the command is supposed to do after a careful reading of +the manual, check the index and glossary for any terms that may be +unclear. If you still do not understand, this indicates a bug in the +manual. The manual's job is to make everything clear. It is just as +important to report documentation bugs as program bugs. + + If the online documentation string of a function or variable +disagrees with the manual, one of them must be wrong, so report the bug. + +How to Report a Bug +------------------- + + When you decide that there is a bug, it is important to report it +and to report it in a way which is useful. What is most useful is an +exact description of what commands you type, starting with the shell +command to run Emacs, until the problem happens. Always include the +version number of Emacs that you are using; type `M-x emacs-version' to +print this. + + The most important principle in reporting a bug is to report FACTS, +not hypotheses or categorizations. It is always easier to report the +facts, but people seem to prefer to strain to posit explanations and +report them instead. If the explanations are based on guesses about +how Emacs is implemented, they will be useless; we will have to try to +figure out what the facts must have been to lead to such speculations. +Sometimes this is impossible. But in any case, it is unnecessary work +for us. + + For example, suppose that you type `C-x C-f /glorp/baz.ugh ', +visiting a file which (you know) happens to be rather large, and Emacs +prints out `I feel pretty today'. The best way to report the bug is +with a sentence like the preceding one, because it gives all the facts +and nothing but the facts. + + Do not assume that the problem is due to the size of the file and +say, "When I visit a large file, Emacs prints out `I feel pretty +today'." This is what we mean by "guessing explanations". The problem +is just as likely to be due to the fact that there is a `z' in the file +name. If this is so, then when we got your report, we would try out +the problem with some "large file", probably with no `z' in its name, +and not find anything wrong. There is no way in the world that we +could guess that we should try visiting a file with a `z' in its name. + + Alternatively, the problem might be due to the fact that the file +starts with exactly 25 spaces. For this reason, you should make sure +that you inform us of the exact contents of any file that is needed to +reproduce the bug. What if the problem only occurs when you have typed +the `C-x a l' command previously? This is why we ask you to give the +exact sequence of characters you typed since starting to use Emacs. + + You should not even say "visit a file" instead of `C-x C-f' unless +you know that it makes no difference which visiting command is used. +Similarly, rather than saying "if I have three characters on the line," +say "after I type ` A B C C-p'," if that is the way you +entered the text. + + If you are not in Fundamental mode when the problem occurs, you +should say what mode you are in. + + If the manifestation of the bug is an Emacs error message, it is +important to report not just the text of the error message but a +backtrace showing how the Lisp program in Emacs arrived at the error. +To make the backtrace, you must execute the Lisp expression `(setq +debug-on-error t)' before the error happens (that is to say, you must +execute that expression and then make the bug happen). This causes the +Lisp debugger to run (*note Lisp Debug::). The debugger's backtrace +can be copied as text into the bug report. This use of the debugger is +possible only if you know how to make the bug happen again. Do note +the error message the first time the bug happens, so if you can't make +it happen again, you can report at least that. + + Check whether any programs you have loaded into the Lisp world, +including your init file, set any variables that may affect the +functioning of Emacs. *Note Init File::. Also, see whether the +problem happens in a freshly started Emacs without loading your init +file (start Emacs with the `-q' switch to prevent loading the init +file). If the problem does NOT occur then, it is essential that we +know the contents of any programs that you must load into the Lisp +world in order to cause the problem to occur. + + If the problem does depend on an init file or other Lisp programs +that are not part of the standard Emacs system, then you should make +sure it is not a bug in those programs by complaining to their +maintainers first. After they verify that they are using Emacs in a +way that is supposed to work, they should report the bug. + + If you can tell us a way to cause the problem without visiting any +files, please do so. This makes it much easier to debug. If you do +need files, make sure you arrange for us to see their exact contents. +For example, it can often matter whether there are spaces at the ends +of lines, or a newline after the last line in the buffer (nothing ought +to care whether the last line is terminated, but tell that to the bugs). + + The easy way to record the input to Emacs precisely is to write a +dribble file; execute the Lisp expression: + + (open-dribble-file "~/dribble") + +using `Meta-' or from the `*scratch*' buffer just after starting +Emacs. From then on, all Emacs input will be written in the specified +dribble file until the Emacs process is killed. + + For possible display bugs, it is important to report the terminal +type (the value of environment variable `TERM'), the complete termcap +entry for the terminal from `/etc/termcap' (since that file is not +identical on all machines), and the output that Emacs actually sent to +the terminal. The way to collect this output is to execute the Lisp +expression: + + (open-termscript "~/termscript") + +using `Meta-' or from the `*scratch*' buffer just after starting +Emacs. From then on, all output from Emacs to the terminal will be +written in the specified termscript file as well, until the Emacs +process is killed. If the problem happens when Emacs starts up, put +this expression into your init file so that the termscript file will be +open when Emacs displays the screen for the first time. *Note Init +File::. Be warned: it is often difficult, and sometimes impossible, to +fix a terminal-dependent bug without access to a terminal of the type +that stimulates the bug. + + The newsgroup `comp.emacs.xemacs' may be used for bug reports, other +discussions and requests for assistance. + + If you don't have access to this newgroup, you can subscribe to the +mailing list version: the newsgroup is bidirectionally gatewayed into +the mailing list `xemacs@xemacs.org'. + + To be added or removed from this mailing list, send mail to +`xemacs-request@xemacs.org'. Do not send requests for addition to the +mailing list itself. + + The mailing lists and newsgroups are archived on our anonymous FTP +server, `ftp.xemacs.org', and at various other archive sites around the +net. You should also check the `FAQ' in `/pub/xemacs' on our anonymous +FTP server. It provides some introductory information and help for +initial configuration problems. + + File: xemacs.info, Node: Glossary, Next: Manifesto, Prev: Intro, Up: Top Glossary diff --git a/info/xemacs.info-5 b/info/xemacs.info-5 index 54b0a81..7a27615 100644 --- a/info/xemacs.info-5 +++ b/info/xemacs.info-5 @@ -30,6 +30,325 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Library Keywords, Next: Help Mode, Prev: Apropos, Up: Help + +Keyword Search for Lisp Libraries +================================= + + The `C-h p' command lets you search the standard Emacs Lisp +libraries by topic keywords. Here is a partial list of keywords you can +use: + + abbrev abbreviation handling, typing shortcuts, macros + bib code related to the `bib' bibliography processor + c C, C++, and Objective-C language support + calendar calendar and time management support + comm communications, networking, remote access to files + data support for editing files of data + docs support for Emacs documentation + dumped files preloaded into Emacs + emulations emulations of other editors + extensions Emacs Lisp language extensions + faces support for multiple fonts + frames support for Emacs frames and window systems + games games, jokes and amusements + hardware support for interfacing with exotic hardware + help support for on-line help systems + hypermedia support for links between text or other media types + i18n internationalization and alternate character-set support + internal code for Emacs internals, build process, defaults + languages specialized modes for editing programming languages + lisp Lisp support, including Emacs Lisp + local code local to your site + maint maintenance aids for the Emacs development group + mail modes for electronic-mail handling + matching various sorts of searching and matching + mouse mouse support + mule multi-language extensions + news support for netnews reading and posting + oop support for object-oriented programming + outlines support for hierarchical outlining + processes process, subshell, compilation, and job control support + terminals support for terminal types + tex code related to the TeX formatter + tools programming tools + unix front-ends/assistants for, or emulators of, UNIX features + vms support code for vms + wp word processing + + +File: xemacs.info, Node: Help Mode, Next: Misc Help, Prev: Library Keywords, Up: Help + +Help Mode Commands +================== + + Help buffers provide the commands of View mode (*note Misc File +Ops::), plus a few special commands of their own. + +`' + Scroll forward. + +`' +`' + Scroll backward. + + When a command name (*note Running Commands by Name: M-x.) or +variable name (*note Variables::) appears in the documentation, it +normally appears inside paired single-quotes. + + +File: xemacs.info, Node: Misc Help, Prev: Help Mode, Up: Help + +Other Help Commands +=================== + + `C-h i' (`info') runs the Info program, which is used for browsing +through structured documentation files. The entire XEmacs manual is +available within Info. Eventually all the documentation of the GNU +system will be available. Type `h' after entering Info to run a +tutorial on using Info. + + If you specify a numeric argument, `C-h i' prompts for the name of a +documentation file. This way, you can browse a file which doesn't have +an entry in the top-level Info menu. It is also handy when you need to +get to the documentation quickly, and you know the exact name of the +file. + + There are two special help commands for accessing XEmacs +documentation through Info. `C-h C-f FUNCTION ' enters Info and +goes straight to the documentation of the XEmacs function FUNCTION. +`C-h C-k KEY' enters Info and goes straight to the documentation of the +key KEY. These two keys run the commands `Info-elisp-ref' and +`Info-goto-emacs-key-command-node'. + + If something surprising happens, and you are not sure what commands +you typed, use `C-h l' (`view-lossage'). `C-h l' prints the last 100 +command characters you typed in. If you see commands that you don't +know, you can use `C-h c' to find out what they do. + + XEmacs has several major modes. Each mode redefines a few keys and +makes a few other changes in how editing works. `C-h m' +(`describe-mode') prints documentation on the current major mode, which +normally describes all the commands that are changed in this mode. + + `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax') +present information about the current XEmacs mode that is not covered +by `C-h m'. `C-h b' displays a list of all the key bindings currently +in effect, with the local bindings of the current major mode first, +followed by the global bindings (*note Key Bindings::). `C-h s' +displays the contents of the syntax table with explanations of each +character's syntax (*note Syntax::). + + You can get a similar list for a particular prefix key by typing +`C-h' after the prefix key. (There are a few prefix keys for which +this does not work--those that provide their own bindings for `C-h'. +One of these is , because ` C-h' is actually `C-M-h', which +marks a defun.) + + The other `C-h' options display various files of useful information. +`C-h C-w' (`describe-no-warranty') displays the full details on the +complete absence of warranty for XEmacs. `C-h n' (`view-emacs-news') +displays the file `xemacs/etc/NEWS', which contains documentation on +XEmacs changes arranged chronologically. `C-h F' (`xemacs-local-faq') +displays local version of the XEmacs +frequently-answered-questions-list. `C-h t' (`help-with-tutorial') +displays the learn-by-doing XEmacs tutorial. `C-h C-c' +(`describe-copying') displays the file `xemacs/etc/COPYING', which +tells you the conditions you must obey in distributing copies of +XEmacs. `C-h C-d' (`describe-distribution') displays another file named +`xemacs/etc/DISTRIB', which tells you how you can order a copy of the +latest version of XEmacs. + + +File: xemacs.info, Node: Mark, Next: Mouse Selection, Prev: Help, Up: Top + +Selecting Text +************** + + Many Emacs commands operate on an arbitrary contiguous part of the +current buffer. You can select text in two ways: + + * You use special keys to select text by defining a region between + point and the mark. + + * If you are running XEmacs under X, you can also select text with + the mouse. + +The Mark and the Region +======================= + + To specify the text for a command to operate on, set "the mark" at +one end of it, and move point to the other end. The text between point +and the mark is called "the region". You can move point or the mark to +adjust the boundaries of the region. It doesn't matter which one is +set first chronologically, or which one comes earlier in the text. + + Once the mark has been set, it remains until it is set again at +another place. The mark remains fixed with respect to the preceding +character if text is inserted or deleted in a buffer. Each Emacs +buffer has its own mark; when you return to a buffer that had been +selected previously, it has the same mark it had before. + + Many commands that insert text, such as `C-y' (`yank') and `M-x +insert-buffer', position the mark at one end of the inserted text--the +opposite end from where point is positioned, so that the region +contains the text just inserted. + + Aside from delimiting the region, the mark is useful for marking a +spot that you may want to go back to. To make this feature more useful, +Emacs remembers 16 previous locations of the mark in the `mark ring'. + +* Menu: + +* Setting Mark:: Commands to set the mark. +* Using Region:: Summary of ways to operate on contents of the region. +* Marking Objects:: Commands to put region around textual units. +* Mark Ring:: Previous mark positions saved so you can go back there. + + +File: xemacs.info, Node: Setting Mark, Next: Using Region, Prev: Mark, Up: Mark + +Setting the Mark +---------------- + + Here are some commands for setting the mark: + +`C-' + Set the mark where point is (`set-mark-command'). + +`C-@' + The same. + +`C-x C-x' + Interchange mark and point (`exchange-point-and-mark'). + +`C-<' + Pushes a mark at the beginning of the buffer. + +`C->' + Pushes a mark at the end of the buffer. + + For example, to convert part of the buffer to all upper-case, you +can use the `C-x C-u' (`upcase-region') command, which operates on the +text in the region. First go to the beginning of the text you want to +capitalize and type `C-' to put the mark there, then move to the +end, and then type `C-x C-u' to capitalize the selected region. You +can also set the mark at the end of the text, move to the beginning, +and then type `C-x C-u'. Most commands that operate on the text in the +region have the word `region' in their names. + + The most common way to set the mark is with the `C-' command +(`set-mark-command'). This command sets the mark where point is. You +can then move point away, leaving the mark behind. It is actually +incorrect to speak of the character `C-'; there is no such +character. When you type while holding down , you get the +character `C-@' on most terminals. This character is actually bound to +`set-mark-command'. But unless you are unlucky enough to have a +terminal where typing `C-' does not produce `C-@', you should +think of this character as `C-'. + + Since terminals have only one cursor, Emacs cannot show you where the +mark is located. Most people use the mark soon after they set it, before +they forget where it is. But you can see where the mark is with the +command `C-x C-x' (`exchange-point-and-mark') which puts the mark where +point was and point where the mark was. The extent of the region is +unchanged, but the cursor and point are now at the previous location of +the mark. + + Another way to set the mark is to push the mark to the beginning of a +buffer while leaving point at its original location. If you supply an +argument to `C-<' (`mark-beginning-of-buffer'), the mark is pushed N/10 +of the way from the true beginning of the buffer. You can also set the +mark at the end of a buffer with `C->' (`mark-end-of-buffer'). It +pushes the mark to the end of the buffer, leaving point alone. +Supplying an argument to the command pushes the mark N/10 of the way +from the true end of the buffer. + + If you are using XEmacs under the X window system, you can set the +variable `zmacs-regions' to `t'. This makes the current region (defined +by point and mark) highlight and makes it available as the X clipboard +selection, which means you can use the menu bar items on it. *Note +Active Regions::, for more information. + + `C-x C-x' is also useful when you are satisfied with the location of +point but want to move the mark; do `C-x C-x' to put point there and +then you can move it. A second use of `C-x C-x', if necessary, puts +the mark at the new location with point back at its original location. + + +File: xemacs.info, Node: Using Region, Next: Marking Objects, Prev: Setting Mark, Up: Mark + +Operating on the Region +----------------------- + + Once you have created an active region, you can do many things to +the text in it: + * Kill it with `C-w' (*note Killing::). + + * Save it in a register with `C-x r s' (*note Registers::). + + * Save it in a buffer or a file (*note Accumulating Text::). + + * Convert case with `C-x C-l' or `C-x C-u' + (*note Case::). + + * Evaluate it as Lisp code with `M-x eval-region' (*note Lisp + Eval::). + + * Fill it as text with `M-q' (*note Filling::). + + * Print hardcopy with `M-x print-region' (*note Hardcopy::). + + * Indent it with `C-x ' or `C-M-\' (*note Indentation::). + + +File: xemacs.info, Node: Marking Objects, Next: Mark Ring, Prev: Using Region, Up: Mark + +Commands to Mark Textual Objects +-------------------------------- + + There are commands for placing point and the mark around a textual +object such as a word, list, paragraph or page. + +`M-@' + Set mark after end of next word (`mark-word'). This command and + the following one do not move point. + +`C-M-@' + Set mark after end of next Lisp expression (`mark-sexp'). + +`M-h' + Put region around current paragraph (`mark-paragraph'). + +`C-M-h' + Put region around current Lisp defun (`mark-defun'). + +`C-x h' + Put region around entire buffer (`mark-whole-buffer'). + +`C-x C-p' + Put region around current page (`mark-page'). + + `M-@' (`mark-word') puts the mark at the end of the next word, while +`C-M-@' (`mark-sexp') puts it at the end of the next Lisp expression. +These characters sometimes save you some typing. + + A number of commands are available that set both point and mark and +thus delimit an object in the buffer. `M-h' (`mark-paragraph') moves +point to the beginning of the paragraph that surrounds or follows +point, and puts the mark at the end of that paragraph (*note +Paragraphs::). You can then indent, case-convert, or kill the whole +paragraph. In the same fashion, `C-M-h' (`mark-defun') puts point +before and the mark after the current or following defun (*note +Defuns::). `C-x C-p' (`mark-page') puts point before the current page +(or the next or previous, depending on the argument), and mark at the +end (*note Pages::). The mark goes after the terminating page +delimiter (to include it), while point goes after the preceding page +delimiter (to exclude it). Finally, `C-x h' (`mark-whole-buffer') sets +up the entire buffer as the region by putting point at the beginning +and the mark at the end. + + File: xemacs.info, Node: Mark Ring, Prev: Marking Objects, Up: Mark The Mark Ring @@ -833,406 +1152,3 @@ Emacs. Using it on a file that Emacs is visiting can produce confusing results, because the file's text inside Emacs does not change while the file itself changes. - -File: xemacs.info, Node: Rectangles, Next: Registers, Prev: Accumulating Text, Up: Top - -Rectangles -========== - - The rectangle commands affect rectangular areas of text: all -characters between a certain pair of columns, in a certain range of -lines. Commands are provided to kill rectangles, yank killed -rectangles, clear them out, or delete them. Rectangle commands are -useful with text in multicolumnar formats, like code with comments at -the right, or for changing text into or out of such formats. - - To specify the rectangle a command should work on, put the mark at -one corner and point at the opposite corner. The specified rectangle is -called the "region-rectangle" because it is controlled about the same -way the region is controlled. Remember that a given combination of -point and mark values can be interpreted either as specifying a region -or as specifying a rectangle; it is up to the command that uses them to -choose the interpretation. - -`M-x delete-rectangle' - Delete the text of the region-rectangle, moving any following text - on each line leftward to the left edge of the region-rectangle. - -`M-x kill-rectangle' - Similar, but also save the contents of the region-rectangle as the - "last killed rectangle". - -`M-x yank-rectangle' - Yank the last killed rectangle with its upper left corner at point. - -`M-x open-rectangle' - Insert blank space to fill the space of the region-rectangle. The - previous contents of the region-rectangle are pushed rightward. - -`M-x clear-rectangle' - Clear the region-rectangle by replacing its contents with spaces. - - The rectangle operations fall into two classes: commands deleting and -moving rectangles, and commands for blank rectangles. - - There are two ways to get rid of the text in a rectangle: you can -discard the text (delete it) or save it as the "last killed" rectangle. -The commands for these two ways are `M-x delete-rectangle' and `M-x -kill-rectangle'. In either case, the portion of each line that falls -inside the rectangle's boundaries is deleted, causing following text -(if any) on the line to move left. - - Note that "killing" a rectangle is not killing in the usual sense; -the rectangle is not stored in the kill ring, but in a special place -that only records the most recently killed rectangle (that is, does not -append to a killed rectangle). Different yank commands have to be used -and only one rectangle is stored, because yanking a rectangle is quite -different from yanking linear text and yank-popping commands are -difficult to make sense of. - - Inserting a rectangle is the opposite of deleting one. You specify -where to put the upper left corner by putting point there. The -rectangle's first line is inserted at point, the rectangle's second line -is inserted at a point one line vertically down, and so on. The number -of lines affected is determined by the height of the saved rectangle. - - To insert the last killed rectangle, type `M-x yank-rectangle'. -This can be used to convert single-column lists into double-column -lists; kill the second half of the list as a rectangle and then yank it -beside the first line of the list. - - There are two commands for working with blank rectangles: `M-x -clear-rectangle' erases existing text, and `M-x open-rectangle' inserts -a blank rectangle. Clearing a rectangle is equivalent to deleting it -and then inserting a blank rectangle of the same size. - - Rectangles can also be copied into and out of registers. *Note -Rectangle Registers: RegRect. - - -File: xemacs.info, Node: Registers, Next: Display, Prev: Rectangles, Up: Top - -Registers -********* - - XEmacs "registers" are places in which you can save text or -positions for later use. Once you save text or a rectangle in a -register, you can copy it into the buffer once or many times; a position -saved in a register is used by moving point to that position. -Rectangles can also be copied into and out of registers (*note -Rectangles::). - - Each register has a name which is a single character. A register can -store a piece of text, a rectangle, a position, a window configuration, -or a file name, but only one thing at any given time. Whatever you -store in a register remains there until you store something else in that -register. To see what a register R contains, use `M-x view-register'. - -`M-x view-register R' - Display a description of what register R contains. - - `M-x view-register' reads a register name as an argument and then -displays the contents of the specified register. - -* Menu: - -* Position: RegPos. Saving positions in registers. -* Text: RegText. Saving text in registers. -* Rectangle: RegRect. Saving rectangles in registers. -* Configurations: RegConfig. Saving window configurations in registers. -* Files: RegFiles. File names in registers. -* Numbers: RegNumbers. Numbers in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. - - -File: xemacs.info, Node: RegPos, Next: RegText, Prev: Registers, Up: Registers - -Saving Positions in Registers -============================= - - Saving a position records a place in a buffer so that you can move -back there later. Moving to a saved position switches to that buffer -and moves point to that place in it. - -`C-x r R' - Save position of point in register R (`point-to-register'). - -`C-x r j R' - Jump to the position saved in register R (`jump-to-register'). - - To save the current position of point in a register, choose a name R -and type `C-x r R'. The register R retains the position thus -saved until you store something else in that register. - - The command `C-x r j R' moves point to the position recorded in -register R. The register is not affected; it continues to record the -same location. You can jump to the same position using the same -register as often as you want. - - If you use `C-x r j' to go to a saved position, but the buffer it -was saved from has been killed, `C-x r j' tries to create the buffer -again by visiting the same file. Of course, this works only for buffers -that were visiting files. - - -File: xemacs.info, Node: RegText, Next: RegRect, Prev: RegPos, Up: Registers - -Saving Text in Registers -======================== - - When you want to insert a copy of the same piece of text many times, -it can be impractical to use the kill ring, since each subsequent kill -moves the piece of text further down on the ring. It becomes hard to -keep track of the argument needed to retrieve the same text with `C-y'. -An alternative is to store the text in a register with `C-x r s' -(`copy-to-register') and then retrieve it with `C-x r i' -(`insert-register'). - -`C-x r s R' - Copy region into register R (`copy-to-register'). - -`C-x r g R' -`C-x r i R' - Insert text contents of register R (`insert-register'). - - `C-x r s R' stores a copy of the text of the region into the -register named R. Given a numeric argument, `C-x r s R' deletes the -text from the buffer as well. - - `C-x r i R' inserts the text from register R in the buffer. By -default it leaves point before the text and places the mark after it. -With a numeric argument (`C-u'), it puts point after the text and the -mark before it. - - -File: xemacs.info, Node: RegRect, Next: RegConfig, Prev: RegText, Up: Registers - -Saving Rectangles in Registers -============================== - - A register can contain a rectangle instead of lines of text. The -rectangle is represented as a list of strings. *Note Rectangles::, for -basic information on rectangles and how to specify rectangles in a -buffer. - -`C-x r r R' - Copy the region-rectangle into register R - (`copy-rectangle-to-register'). With a numeric argument, delete it - as well. - -`C-x r g R' -`C-x r i R' - Insert the rectangle stored in register R (if it contains a - rectangle) (`insert-register'). - - The `C-x r i R' command inserts linear text if the register -contains that, or inserts a rectangle if the register contains one. - - See also the command `sort-columns', which you can think of as -sorting a rectangle. *Note Sorting::. - - -File: xemacs.info, Node: RegConfig, Next: RegNumbers, Prev: RegRect, Up: Registers - -Saving Window Configurations in Registers -========================================= - - You can save the window configuration of the selected frame in a -register, or even the configuration of all windows in all frames, and -restore the configuration later. - -`C-x r w R' - Save the state of the selected frame's windows in register R - (`window-configuration-to-register'). - -`M-x frame-configuration-to-register R' - Save the state of all frames, including all their windows, in - register R (`frame-configuration-to-register'). - - Use `C-x r j R' to restore a window or frame configuration. This is -the same command used to restore a cursor position. When you restore a -frame configuration, any existing frames not included in the -configuration become invisible. If you wish to delete these frames -instead, use `C-u C-x r j R'. - - -File: xemacs.info, Node: RegNumbers, Next: RegFiles, Prev: RegConfig, Up: Registers - -Keeping Numbers in Registers -============================ - - There are commands to store a number in a register, to insert the -number in the buffer in decimal, and to increment it. These commands -can be useful in keyboard macros (*note Keyboard Macros::). - -`C-u NUMBER C-x r n REG' - Store NUMBER into register REG (`number-to-register'). - -`C-u NUMBER C-x r + REG' - Increment the number in register REG by NUMBER - (`increment-register'). - -`C-x r g REG' - Insert the number from register REG into the buffer. - - `C-x r g' is the same command used to insert any other sort of -register contents into the buffer. - - -File: xemacs.info, Node: RegFiles, Next: Bookmarks, Prev: RegNumbers, Up: Registers - -Keeping File Names in Registers -=============================== - - If you visit certain file names frequently, you can visit them more -conveniently if you put their names in registers. Here's the Lisp code -used to put a file name in a register: - - (set-register ?R '(file . NAME)) - -For example, - - (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog")) - -puts the file name shown in register `z'. - - To visit the file whose name is in register R, type `C-x r j R'. -(This is the same command used to jump to a position or restore a frame -configuration.) - - -File: xemacs.info, Node: Bookmarks, Prev: RegFiles, Up: Registers - -Bookmarks -========= - - "Bookmarks" are somewhat like registers in that they record -positions you can jump to. Unlike registers, they have long names, and -they persist automatically from one Emacs session to the next. The -prototypical use of bookmarks is to record "where you were reading" in -various files. - - Note: bookmark.el is distributed in edit-utils package. You need to -install that to use bookmark facility (*note Packages::). - -`C-x r m ' - Set the bookmark for the visited file, at point. - -`C-x r m BOOKMARK ' - Set the bookmark named BOOKMARK at point (`bookmark-set'). - -`C-x r b BOOKMARK ' - Jump to the bookmark named BOOKMARK (`bookmark-jump'). - -`C-x r l' - List all bookmarks (`list-bookmarks'). - -`M-x bookmark-save' - Save all the current bookmark values in the default bookmark file. - - The prototypical use for bookmarks is to record one current position -in each of several files. So the command `C-x r m', which sets a -bookmark, uses the visited file name as the default for the bookmark -name. If you name each bookmark after the file it points to, then you -can conveniently revisit any of those files with `C-x r b', and move to -the position of the bookmark at the same time. - - To display a list of all your bookmarks in a separate buffer, type -`C-x r l' (`list-bookmarks'). If you switch to that buffer, you can -use it to edit your bookmark definitions or annotate the bookmarks. -Type `C-h m' in that buffer for more information about its special -editing commands. - - When you kill XEmacs, XEmacs offers to save your bookmark values in -your default bookmark file, `~/.emacs.bmk', if you have changed any -bookmark values. You can also save the bookmarks at any time with the -`M-x bookmark-save' command. The bookmark commands load your default -bookmark file automatically. This saving and loading is how bookmarks -persist from one XEmacs session to the next. - - If you set the variable `bookmark-save-flag' to 1, then each command -that sets a bookmark will also save your bookmarks; this way, you don't -lose any bookmark values even if XEmacs crashes. (The value, if a -number, says how many bookmark modifications should go by between -saving.) - - Bookmark position values are saved with surrounding context, so that -`bookmark-jump' can find the proper position even if the file is -modified slightly. The variable `bookmark-search-size' says how many -characters of context to record, on each side of the bookmark's -position. - - Here are some additional commands for working with bookmarks: - -`M-x bookmark-load FILENAME ' - Load a file named FILENAME that contains a list of bookmark - values. You can use this command, as well as `bookmark-write', to - work with other files of bookmark values in addition to your - default bookmark file. - -`M-x bookmark-write FILENAME ' - Save all the current bookmark values in the file FILENAME. - -`M-x bookmark-delete BOOKMARK ' - Delete the bookmark named BOOKMARK. - -`M-x bookmark-insert-location BOOKMARK ' - Insert in the buffer the name of the file that bookmark BOOKMARK - points to. - -`M-x bookmark-insert BOOKMARK ' - Insert in the buffer the _contents_ of the file that bookmark - BOOKMARK points to. - - -File: xemacs.info, Node: Display, Next: Search, Prev: Registers, Up: Top - -Controlling the Display -*********************** - - Since only part of a large buffer fits in the window, XEmacs tries -to show the part that is likely to be interesting. The display control -commands allow you to specify which part of the text you want to see. - -`C-l' - Clear frame and redisplay, scrolling the selected window to center - point vertically within it (`recenter'). - -`C-v' -`pgdn' -`next' - Scroll forward (a windowful or a specified number of lines) - (`scroll-up'). On most X keyboards, you can get this - functionality using the key labelled `Page Down', which generates - either `next' or `pgdn'. - -`M-v' -`pgup' -`prior' - Scroll backward (`scroll-down'). On most X keyboards, you can get - this functionality using the key labelled `Page Up', which - generates either `prior' or `pgup'. - -`ARG C-l' - Scroll so point is on line ARG (`recenter'). - -`C-x <' -`C-pgdn' -`C-next' - Scroll text in current window to the left (`scroll-left'). - -`C-x >' -`C-pgup' -`C-prior' - Scroll to the right (`scroll-right'). - -`C-x $' - Make deeply indented lines invisible (`set-selective-display'). - -* Menu: - -* Scrolling:: Moving text up and down in a window. -* Horizontal Scrolling:: Moving text left and right in a window. -* Selective Display:: Hiding lines with lots of indentation. -* Display Vars:: Information on variables for customizing display. - diff --git a/info/xemacs.info-6 b/info/xemacs.info-6 index 7aad804..1637f0f 100644 --- a/info/xemacs.info-6 +++ b/info/xemacs.info-6 @@ -30,6 +30,409 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Rectangles, Next: Registers, Prev: Accumulating Text, Up: Top + +Rectangles +========== + + The rectangle commands affect rectangular areas of text: all +characters between a certain pair of columns, in a certain range of +lines. Commands are provided to kill rectangles, yank killed +rectangles, clear them out, or delete them. Rectangle commands are +useful with text in multicolumnar formats, like code with comments at +the right, or for changing text into or out of such formats. + + To specify the rectangle a command should work on, put the mark at +one corner and point at the opposite corner. The specified rectangle is +called the "region-rectangle" because it is controlled about the same +way the region is controlled. Remember that a given combination of +point and mark values can be interpreted either as specifying a region +or as specifying a rectangle; it is up to the command that uses them to +choose the interpretation. + +`M-x delete-rectangle' + Delete the text of the region-rectangle, moving any following text + on each line leftward to the left edge of the region-rectangle. + +`M-x kill-rectangle' + Similar, but also save the contents of the region-rectangle as the + "last killed rectangle". + +`M-x yank-rectangle' + Yank the last killed rectangle with its upper left corner at point. + +`M-x open-rectangle' + Insert blank space to fill the space of the region-rectangle. The + previous contents of the region-rectangle are pushed rightward. + +`M-x clear-rectangle' + Clear the region-rectangle by replacing its contents with spaces. + + The rectangle operations fall into two classes: commands deleting and +moving rectangles, and commands for blank rectangles. + + There are two ways to get rid of the text in a rectangle: you can +discard the text (delete it) or save it as the "last killed" rectangle. +The commands for these two ways are `M-x delete-rectangle' and `M-x +kill-rectangle'. In either case, the portion of each line that falls +inside the rectangle's boundaries is deleted, causing following text +(if any) on the line to move left. + + Note that "killing" a rectangle is not killing in the usual sense; +the rectangle is not stored in the kill ring, but in a special place +that only records the most recently killed rectangle (that is, does not +append to a killed rectangle). Different yank commands have to be used +and only one rectangle is stored, because yanking a rectangle is quite +different from yanking linear text and yank-popping commands are +difficult to make sense of. + + Inserting a rectangle is the opposite of deleting one. You specify +where to put the upper left corner by putting point there. The +rectangle's first line is inserted at point, the rectangle's second line +is inserted at a point one line vertically down, and so on. The number +of lines affected is determined by the height of the saved rectangle. + + To insert the last killed rectangle, type `M-x yank-rectangle'. +This can be used to convert single-column lists into double-column +lists; kill the second half of the list as a rectangle and then yank it +beside the first line of the list. + + There are two commands for working with blank rectangles: `M-x +clear-rectangle' erases existing text, and `M-x open-rectangle' inserts +a blank rectangle. Clearing a rectangle is equivalent to deleting it +and then inserting a blank rectangle of the same size. + + Rectangles can also be copied into and out of registers. *Note +Rectangle Registers: RegRect. + + +File: xemacs.info, Node: Registers, Next: Display, Prev: Rectangles, Up: Top + +Registers +********* + + XEmacs "registers" are places in which you can save text or +positions for later use. Once you save text or a rectangle in a +register, you can copy it into the buffer once or many times; a position +saved in a register is used by moving point to that position. +Rectangles can also be copied into and out of registers (*note +Rectangles::). + + Each register has a name which is a single character. A register can +store a piece of text, a rectangle, a position, a window configuration, +or a file name, but only one thing at any given time. Whatever you +store in a register remains there until you store something else in that +register. To see what a register R contains, use `M-x view-register'. + +`M-x view-register R' + Display a description of what register R contains. + + `M-x view-register' reads a register name as an argument and then +displays the contents of the specified register. + +* Menu: + +* Position: RegPos. Saving positions in registers. +* Text: RegText. Saving text in registers. +* Rectangle: RegRect. Saving rectangles in registers. +* Configurations: RegConfig. Saving window configurations in registers. +* Files: RegFiles. File names in registers. +* Numbers: RegNumbers. Numbers in registers. +* Bookmarks:: Bookmarks are like registers, but persistent. + + +File: xemacs.info, Node: RegPos, Next: RegText, Prev: Registers, Up: Registers + +Saving Positions in Registers +============================= + + Saving a position records a place in a buffer so that you can move +back there later. Moving to a saved position switches to that buffer +and moves point to that place in it. + +`C-x r R' + Save position of point in register R (`point-to-register'). + +`C-x r j R' + Jump to the position saved in register R (`jump-to-register'). + + To save the current position of point in a register, choose a name R +and type `C-x r R'. The register R retains the position thus +saved until you store something else in that register. + + The command `C-x r j R' moves point to the position recorded in +register R. The register is not affected; it continues to record the +same location. You can jump to the same position using the same +register as often as you want. + + If you use `C-x r j' to go to a saved position, but the buffer it +was saved from has been killed, `C-x r j' tries to create the buffer +again by visiting the same file. Of course, this works only for buffers +that were visiting files. + + +File: xemacs.info, Node: RegText, Next: RegRect, Prev: RegPos, Up: Registers + +Saving Text in Registers +======================== + + When you want to insert a copy of the same piece of text many times, +it can be impractical to use the kill ring, since each subsequent kill +moves the piece of text further down on the ring. It becomes hard to +keep track of the argument needed to retrieve the same text with `C-y'. +An alternative is to store the text in a register with `C-x r s' +(`copy-to-register') and then retrieve it with `C-x r i' +(`insert-register'). + +`C-x r s R' + Copy region into register R (`copy-to-register'). + +`C-x r g R' +`C-x r i R' + Insert text contents of register R (`insert-register'). + + `C-x r s R' stores a copy of the text of the region into the +register named R. Given a numeric argument, `C-x r s R' deletes the +text from the buffer as well. + + `C-x r i R' inserts the text from register R in the buffer. By +default it leaves point before the text and places the mark after it. +With a numeric argument (`C-u'), it puts point after the text and the +mark before it. + + +File: xemacs.info, Node: RegRect, Next: RegConfig, Prev: RegText, Up: Registers + +Saving Rectangles in Registers +============================== + + A register can contain a rectangle instead of lines of text. The +rectangle is represented as a list of strings. *Note Rectangles::, for +basic information on rectangles and how to specify rectangles in a +buffer. + +`C-x r r R' + Copy the region-rectangle into register R + (`copy-rectangle-to-register'). With a numeric argument, delete it + as well. + +`C-x r g R' +`C-x r i R' + Insert the rectangle stored in register R (if it contains a + rectangle) (`insert-register'). + + The `C-x r i R' command inserts linear text if the register +contains that, or inserts a rectangle if the register contains one. + + See also the command `sort-columns', which you can think of as +sorting a rectangle. *Note Sorting::. + + +File: xemacs.info, Node: RegConfig, Next: RegNumbers, Prev: RegRect, Up: Registers + +Saving Window Configurations in Registers +========================================= + + You can save the window configuration of the selected frame in a +register, or even the configuration of all windows in all frames, and +restore the configuration later. + +`C-x r w R' + Save the state of the selected frame's windows in register R + (`window-configuration-to-register'). + +`M-x frame-configuration-to-register R' + Save the state of all frames, including all their windows, in + register R (`frame-configuration-to-register'). + + Use `C-x r j R' to restore a window or frame configuration. This is +the same command used to restore a cursor position. When you restore a +frame configuration, any existing frames not included in the +configuration become invisible. If you wish to delete these frames +instead, use `C-u C-x r j R'. + + +File: xemacs.info, Node: RegNumbers, Next: RegFiles, Prev: RegConfig, Up: Registers + +Keeping Numbers in Registers +============================ + + There are commands to store a number in a register, to insert the +number in the buffer in decimal, and to increment it. These commands +can be useful in keyboard macros (*note Keyboard Macros::). + +`C-u NUMBER C-x r n REG' + Store NUMBER into register REG (`number-to-register'). + +`C-u NUMBER C-x r + REG' + Increment the number in register REG by NUMBER + (`increment-register'). + +`C-x r g REG' + Insert the number from register REG into the buffer. + + `C-x r g' is the same command used to insert any other sort of +register contents into the buffer. + + +File: xemacs.info, Node: RegFiles, Next: Bookmarks, Prev: RegNumbers, Up: Registers + +Keeping File Names in Registers +=============================== + + If you visit certain file names frequently, you can visit them more +conveniently if you put their names in registers. Here's the Lisp code +used to put a file name in a register: + + (set-register ?R '(file . NAME)) + +For example, + + (set-register ?z '(file . "/usr/src/xemacs/src/ChangeLog")) + +puts the file name shown in register `z'. + + To visit the file whose name is in register R, type `C-x r j R'. +(This is the same command used to jump to a position or restore a frame +configuration.) + + +File: xemacs.info, Node: Bookmarks, Prev: RegFiles, Up: Registers + +Bookmarks +========= + + "Bookmarks" are somewhat like registers in that they record +positions you can jump to. Unlike registers, they have long names, and +they persist automatically from one Emacs session to the next. The +prototypical use of bookmarks is to record "where you were reading" in +various files. + + Note: bookmark.el is distributed in edit-utils package. You need to +install that to use bookmark facility (*note Packages::). + +`C-x r m ' + Set the bookmark for the visited file, at point. + +`C-x r m BOOKMARK ' + Set the bookmark named BOOKMARK at point (`bookmark-set'). + +`C-x r b BOOKMARK ' + Jump to the bookmark named BOOKMARK (`bookmark-jump'). + +`C-x r l' + List all bookmarks (`list-bookmarks'). + +`M-x bookmark-save' + Save all the current bookmark values in the default bookmark file. + + The prototypical use for bookmarks is to record one current position +in each of several files. So the command `C-x r m', which sets a +bookmark, uses the visited file name as the default for the bookmark +name. If you name each bookmark after the file it points to, then you +can conveniently revisit any of those files with `C-x r b', and move to +the position of the bookmark at the same time. + + To display a list of all your bookmarks in a separate buffer, type +`C-x r l' (`list-bookmarks'). If you switch to that buffer, you can +use it to edit your bookmark definitions or annotate the bookmarks. +Type `C-h m' in that buffer for more information about its special +editing commands. + + When you kill XEmacs, XEmacs offers to save your bookmark values in +your default bookmark file, `~/.emacs.bmk', if you have changed any +bookmark values. You can also save the bookmarks at any time with the +`M-x bookmark-save' command. The bookmark commands load your default +bookmark file automatically. This saving and loading is how bookmarks +persist from one XEmacs session to the next. + + If you set the variable `bookmark-save-flag' to 1, then each command +that sets a bookmark will also save your bookmarks; this way, you don't +lose any bookmark values even if XEmacs crashes. (The value, if a +number, says how many bookmark modifications should go by between +saving.) + + Bookmark position values are saved with surrounding context, so that +`bookmark-jump' can find the proper position even if the file is +modified slightly. The variable `bookmark-search-size' says how many +characters of context to record, on each side of the bookmark's +position. + + Here are some additional commands for working with bookmarks: + +`M-x bookmark-load FILENAME ' + Load a file named FILENAME that contains a list of bookmark + values. You can use this command, as well as `bookmark-write', to + work with other files of bookmark values in addition to your + default bookmark file. + +`M-x bookmark-write FILENAME ' + Save all the current bookmark values in the file FILENAME. + +`M-x bookmark-delete BOOKMARK ' + Delete the bookmark named BOOKMARK. + +`M-x bookmark-insert-location BOOKMARK ' + Insert in the buffer the name of the file that bookmark BOOKMARK + points to. + +`M-x bookmark-insert BOOKMARK ' + Insert in the buffer the _contents_ of the file that bookmark + BOOKMARK points to. + + +File: xemacs.info, Node: Display, Next: Search, Prev: Registers, Up: Top + +Controlling the Display +*********************** + + Since only part of a large buffer fits in the window, XEmacs tries +to show the part that is likely to be interesting. The display control +commands allow you to specify which part of the text you want to see. + +`C-l' + Clear frame and redisplay, scrolling the selected window to center + point vertically within it (`recenter'). + +`C-v' +`pgdn' +`next' + Scroll forward (a windowful or a specified number of lines) + (`scroll-up'). On most X keyboards, you can get this + functionality using the key labelled `Page Down', which generates + either `next' or `pgdn'. + +`M-v' +`pgup' +`prior' + Scroll backward (`scroll-down'). On most X keyboards, you can get + this functionality using the key labelled `Page Up', which + generates either `prior' or `pgup'. + +`ARG C-l' + Scroll so point is on line ARG (`recenter'). + +`C-x <' +`C-pgdn' +`C-next' + Scroll text in current window to the left (`scroll-left'). + +`C-x >' +`C-pgup' +`C-prior' + Scroll to the right (`scroll-right'). + +`C-x $' + Make deeply indented lines invisible (`set-selective-display'). + +* Menu: + +* Scrolling:: Moving text up and down in a window. +* Horizontal Scrolling:: Moving text left and right in a window. +* Selective Display:: Hiding lines with lots of indentation. +* Display Vars:: Information on variables for customizing display. + + File: xemacs.info, Node: Scrolling, Next: Horizontal Scrolling, Prev: Display, Up: Display Scrolling @@ -582,612 +985,3 @@ regexp and non-regexp searches have independent defaults. way of incremental regexp search with `M-C-s '; similarly for `re-search-backward' with `M-C-r '. - -File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search - -Syntax of Regular Expressions -============================= - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are "ordinary". An ordinary character -is a simple regular expression that matches that character and nothing -else. The special characters are `.', `*', `+', `?', `[', `]', `^', -`$', and `\'; no new special characters will be defined in the future. -Any other character appearing in a regular expression is ordinary, -unless a `\' precedes it. - - For example, `f' is not a special character, so it is ordinary, and -therefore `f' is a regular expression that matches the string `f' and -no other string. (It does _not_ match the string `ff'.) Likewise, `o' -is a regular expression that matches only `o'. - - Any two regular expressions A and B can be concatenated. The result -is a regular expression that matches a string if A matches some amount -of the beginning of that string and B matches the rest of the string. - - As a simple example, we can concatenate the regular expressions `f' -and `o' to get the regular expression `fo', which matches only the -string `fo'. Still trivial. To do something more powerful, you need -to use one of the special characters. Here is a list of them: - -`. (Period)' - is a special character that matches any single character except a - newline. Using concatenation, we can make regular expressions - like `a.b', which matches any three-character string that begins - with `a' and ends with `b'. - -`*' - is not a construct by itself; it is a quantifying suffix operator - that means to repeat the preceding regular expression as many - times as possible. In `fo*', the `*' applies to the `o', so `fo*' - matches one `f' followed by any number of `o's. The case of zero - `o's is allowed: `fo*' does match `f'. - - `*' always applies to the _smallest_ possible preceding - expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. - - The matcher processes a `*' construct by matching, immediately, as - many repetitions as can be found; it is "greedy". Then it - continues with the rest of the pattern. If that fails, - backtracking occurs, discarding some of the matches of the - `*'-modified construct in case that makes it possible to match the - rest of the pattern. For example, in matching `ca*ar' against the - string `caaar', the `a*' first tries to match all three `a's; but - the rest of the pattern is `ar' and there is only `r' left to - match, so this try fails. The next alternative is for `a*' to - match only two `a's. With this choice, the rest of the regexp - matches successfully. - - Nested repetition operators can be extremely slow if they specify - backtracking loops. For example, it could take hours for the - regular expression `\(x+y*\)*a' to match the sequence - `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because - Emacs must try each imaginable way of grouping the 35 `x''s before - concluding that none of them can work. To make sure your regular - expressions run fast, check nested repetitions carefully. - -`+' - is a quantifying suffix operator similar to `*' except that the - preceding expression must match at least once. It is also - "greedy". So, for example, `ca+r' matches the strings `car' and - `caaaar' but not the string `cr', whereas `ca*r' matches all three - strings. - -`?' - is a quantifying suffix operator similar to `*', except that the - preceding expression can match either once or not at all. For - example, `ca?r' matches `car' or `cr', but does not match anything - else. - -`*?' - works just like `*', except that rather than matching the longest - match, it matches the shortest match. `*?' is known as a - "non-greedy" quantifier, a regexp construct borrowed from Perl. - - This construct is very useful for when you want to match the text - inside a pair of delimiters. For instance, `/\*.*?\*/' will match - C comments in a string. This could not easily be achieved without - the use of a non-greedy quantifier. - - This construct has not been available prior to XEmacs 20.4. It is - not available in FSF Emacs. - -`+?' - is the non-greedy version of `+'. - -`??' - is the non-greedy version of `?'. - -`\{n,m\}' - serves as an interval quantifier, analogous to `*' or `+', but - specifies that the expression must match at least N times, but no - more than M times. This syntax is supported by most Unix regexp - utilities, and has been introduced to XEmacs for the version 20.3. - - Unfortunately, the non-greedy version of this quantifier does not - exist currently, although it does in Perl. - -`[ ... ]' - `[' begins a "character set", which is terminated by a `]'. In - the simplest case, the characters between the two brackets form - the set. Thus, `[ad]' matches either one `a' or one `d', and - `[ad]*' matches any string composed of just `a's and `d's - (including the empty string), from which it follows that `c[ad]*r' - matches `cr', `car', `cdr', `caddaar', etc. - - The usual regular expression special characters are not special - inside a character set. A completely different set of special - characters exists inside character sets: `]', `-' and `^'. - - `-' is used for ranges of characters. To write a range, write two - characters with a `-' between them. Thus, `[a-z]' matches any - lower case letter. Ranges may be intermixed freely with individual - characters, as in `[a-z$%.]', which matches any lower case letter - or `$', `%', or a period. - - To include a `]' in a character set, make it the first character. - For example, `[]a]' matches `]' or `a'. To include a `-', write - `-' as the first character in the set, or put it immediately after - a range. (You can replace one individual character C with the - range `C-C' to make a place to put the `-'.) There is no way to - write a set containing just `-' and `]'. - - To include `^' in a set, put it anywhere but at the beginning of - the set. - -`[^ ... ]' - `[^' begins a "complement character set", which matches any - character except the ones specified. Thus, `[^a-z0-9A-Z]' matches - all characters _except_ letters and digits. - - `^' is not special in a character set unless it is the first - character. The character following the `^' is treated as if it - were first (thus, `-' and `]' are not special there). - - Note that a complement character set can match a newline, unless - newline is mentioned as one of the characters not to match. - -`^' - is a special character that matches the empty string, but only at - the beginning of a line in the text being matched. Otherwise it - fails to match anything. Thus, `^foo' matches a `foo' that occurs - at the beginning of a line. - - When matching a string instead of a buffer, `^' matches at the - beginning of the string or after a newline character `\n'. - -`$' - is similar to `^' but matches only at the end of a line. Thus, - `x+$' matches a string of one `x' or more at the end of a line. - - When matching a string instead of a buffer, `$' matches at the end - of the string or before a newline character `\n'. - -`\' - has two functions: it quotes the special characters (including - `\'), and it introduces additional special constructs. - - Because `\' quotes special characters, `\$' is a regular - expression that matches only `$', and `\[' is a regular expression - that matches only `[', and so on. - - *Please note:* For historical compatibility, special characters are -treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, `*foo' treats `*' as ordinary -since there is no preceding expression on which the `*' can act. It is -poor practice to depend on this behavior; quote the special character -anyway, regardless of where it appears. - - For the most part, `\' followed by any character matches only that -character. However, there are several exceptions: characters that, -when preceded by `\', are special constructs. Such characters are -always ordinary when encountered on their own. Here is a table of `\' -constructs: - -`\|' - specifies an alternative. Two regular expressions A and B with - `\|' in between form an expression that matches anything that - either A or B matches. - - Thus, `foo\|bar' matches either `foo' or `bar' but no other string. - - `\|' applies to the largest possible surrounding expressions. - Only a surrounding `\( ... \)' grouping can limit the grouping - power of `\|'. - - Full backtracking capability exists to handle multiple uses of - `\|'. - -`\( ... \)' - is a grouping construct that serves three purposes: - - 1. To enclose a set of `\|' alternatives for other operations. - Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. - - 2. To enclose an expression for a suffix operator such as `*' to - act on. Thus, `ba\(na\)*' matches `bananana', etc., with any - (zero or more) number of `na' strings. - - 3. To record a matched substring for future reference. - - This last application is not a consequence of the idea of a - parenthetical grouping; it is a separate feature that happens to be - assigned as a second meaning to the same `\( ... \)' construct - because there is no conflict in practice between the two meanings. - Here is an explanation of this feature: - -`\DIGIT' - matches the same text that matched the DIGITth occurrence of a `\( - ... \)' construct. - - In other words, after the end of a `\( ... \)' construct. the - matcher remembers the beginning and end of the text matched by that - construct. Then, later on in the regular expression, you can use - `\' followed by DIGIT to match that same text, whatever it may - have been. - - The strings matching the first nine `\( ... \)' constructs - appearing in a regular expression are assigned numbers 1 through 9 - in the order that the open parentheses appear in the regular - expression. So you can use `\1' through `\9' to refer to the text - matched by the corresponding `\( ... \)' constructs. - - For example, `\(.*\)\1' matches any newline-free string that is - composed of two identical halves. The `\(.*\)' matches the first - half, which may be anything, but the `\1' that follows must match - the same exact text. - -`\(?: ... \)' - is called a "shy" grouping operator, and it is used just like `\( - ... \)', except that it does not cause the matched substring to be - recorded for future reference. - - This is useful when you need a lot of grouping `\( ... \)' - constructs, but only want to remember one or two - or if you have - more than nine groupings and need to use backreferences to refer to - the groupings at the end. - - Using `\(?: ... \)' rather than `\( ... \)' when you don't need - the captured substrings ought to speed up your programs some, - since it shortens the code path followed by the regular expression - engine, as well as the amount of memory allocation and string - copying it must do. The actual performance gain to be observed - has not been measured or quantified as of this writing. - - The shy grouping operator has been borrowed from Perl, and has not - been available prior to XEmacs 20.3, nor is it available in FSF - Emacs. - -`\w' - matches any word-constituent character. The editor syntax table - determines which characters these are. *Note Syntax::. - -`\W' - matches any character that is not a word constituent. - -`\sCODE' - matches any character whose syntax is CODE. Here CODE is a - character that represents a syntax code: thus, `w' for word - constituent, `-' for whitespace, `(' for open parenthesis, etc. - *Note Syntax::, for a list of syntax codes and the characters that - stand for them. - -`\SCODE' - matches any character whose syntax is not CODE. - - The following regular expression constructs match the empty -string--that is, they don't use up any characters--but whether they -match depends on the context. - -`\`' - matches the empty string, but only at the beginning of the buffer - or string being matched against. - -`\'' - matches the empty string, but only at the end of the buffer or - string being matched against. - -`\=' - matches the empty string, but only at point. (This construct is - not defined when matching against a string.) - -`\b' - matches the empty string, but only at the beginning or end of a - word. Thus, `\bfoo\b' matches any occurrence of `foo' as a - separate word. `\bballs?\b' matches `ball' or `balls' as a - separate word. - -`\B' - matches the empty string, but _not_ at the beginning or end of a - word. - -`\<' - matches the empty string, but only at the beginning of a word. - -`\>' - matches the empty string, but only at the end of a word. - - Here is a complicated regexp used by Emacs to recognize the end of a -sentence together with any whitespace that follows. It is given in Lisp -syntax to enable you to distinguish the spaces from the tab characters. -In Lisp syntax, the string constant begins and ends with a -double-quote. `\"' stands for a double-quote as part of the regexp, -`\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for -a newline. - - "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" - -This regexp contains four parts: a character set matching period, `?' -or `!'; a character set matching close-brackets, quotes or parentheses, -repeated any number of times; an alternative in backslash-parentheses -that matches end-of-line, a tab or two spaces; and a character set -matching whitespace characters, repeated any number of times. - - -File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search - -Searching and Case -================== - - All searches in Emacs normally ignore the case of the text they are -searching through; if you specify searching for `FOO', `Foo' and `foo' -are also considered a match. Regexps, and in particular character -sets, are included: `[aB]' matches `a' or `A' or `b' or `B'. - - If you want a case-sensitive search, set the variable -`case-fold-search' to `nil'. Then all letters must match exactly, -including case. `case-fold-search' is a per-buffer variable; altering -it affects only the current buffer, but there is a default value which -you can change as well. *Note Locals::. You can also use Case -Sensitive Search from the Options menu on your screen. - - -File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search - -Replacement Commands -==================== - - Global search-and-replace operations are not needed as often in -Emacs as they are in other editors, but they are available. In -addition to the simple `replace-string' command which is like that -found in most editors, there is a `query-replace' command which asks -you, for each occurrence of a pattern, whether to replace it. - - The replace commands all replace one string (or regexp) with one -replacement string. It is possible to perform several replacements in -parallel using the command `expand-region-abbrevs'. *Note Expanding -Abbrevs::. - -* Menu: - -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. - - -File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace - -Unconditional Replacement -------------------------- - -`M-x replace-string STRING NEWSTRING ' - Replace every occurrence of STRING with NEWSTRING. - -`M-x replace-regexp REGEXP NEWSTRING ' - Replace every match for REGEXP with NEWSTRING. - - To replace every instance of `foo' after point with `bar', use the -command `M-x replace-string' with the two arguments `foo' and `bar'. -Replacement occurs only after point: if you want to cover the whole -buffer you must go to the beginning first. By default, all occurrences -up to the end of the buffer are replaced. To limit replacement to part -of the buffer, narrow to that part of the buffer before doing the -replacement (*note Narrowing::). - - When `replace-string' exits, point is left at the last occurrence -replaced. The value of point when the `replace-string' command was -issued is remembered on the mark ring; `C-u C-' moves back there. - - A numeric argument restricts replacement to matches that are -surrounded by word boundaries. - - -File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace - -Regexp Replacement ------------------- - - `replace-string' replaces exact matches for a single string. The -similar command `replace-regexp' replaces any match for a specified -pattern. - - In `replace-regexp', the NEWSTRING need not be constant. It can -refer to all or part of what is matched by the REGEXP. `\&' in -NEWSTRING stands for the entire text being replaced. `\D' in -NEWSTRING, where D is a digit, stands for whatever matched the D'th -parenthesized grouping in REGEXP. For example, - - M-x replace-regexp c[ad]+r \&-safe - -would replace (for example) `cadr' with `cadr-safe' and `cddr' with -`cddr-safe'. - - M-x replace-regexp \(c[ad]+r\)-safe \1 - -would perform exactly the opposite replacements. To include a `\' in -the text to replace with, you must give `\\'. - - -File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace - -Replace Commands and Case -------------------------- - - If the arguments to a replace command are in lower case, the command -preserves case when it makes a replacement. Thus, the following -command: - - M-x replace-string foo bar - -replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR', -and `Foo' with `Bar'. If upper-case letters are used in the second -argument, they remain upper-case every time that argument is inserted. -If upper-case letters are used in the first argument, the second -argument is always substituted exactly as given, with no case -conversion. Likewise, if the variable `case-replace' is set to `nil', -replacement is done without case conversion. If `case-fold-search' is -set to `nil', case is significant in matching occurrences of `foo' to -replace; also, case conversion of the replacement string is not done. - - -File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace - -Query Replace -------------- - -`M-% STRING NEWSTRING ' -`M-x query-replace STRING NEWSTRING ' - Replace some occurrences of STRING with NEWSTRING. - -`M-x query-replace-regexp REGEXP NEWSTRING ' - Replace some matches for REGEXP with NEWSTRING. - - If you want to change only some of the occurrences of `foo' to -`bar', not all of them, you can use `query-replace' instead of `M-%'. -This command finds occurrences of `foo' one by one, displays each -occurrence, and asks you whether to replace it. A numeric argument to -`query-replace' tells it to consider only occurrences that are bounded -by word-delimiter characters. - - Aside from querying, `query-replace' works just like -`replace-string', and `query-replace-regexp' works just like -`replace-regexp'. - - The things you can type when you are shown an occurrence of STRING -or a match for REGEXP are: - -`' - to replace the occurrence with NEWSTRING. This preserves case, - just like `replace-string', provided `case-replace' is non-`nil', - as it normally is. - -`' - to skip to the next occurrence without replacing this one. - -`, (Comma)' - to replace this occurrence and display the result. You are then - prompted for another input character. However, since the - replacement has already been made, and are equivalent. - At this point, you can type `C-r' (see below) to alter the - replaced text. To undo the replacement, you can type `C-x u'. - This exits the `query-replace'. If you want to do further - replacement you must use `C-x ESC' to restart (*note Repetition::). - -`' - to exit without doing any more replacements. - -`. (Period)' - to replace this occurrence and then exit. - -`!' - to replace all remaining occurrences without asking again. - -`^' - to go back to the location of the previous occurrence (or what - used to be an occurrence), in case you changed it by mistake. - This works by popping the mark ring. Only one `^' in a row is - allowed, because only one previous replacement location is kept - during `query-replace'. - -`C-r' - to enter a recursive editing level, in case the occurrence needs - to be edited rather than just replaced with NEWSTRING. When you - are done, exit the recursive editing level with `C-M-c' and the - next occurrence will be displayed. *Note Recursive Edit::. - -`C-w' - to delete the occurrence, and then enter a recursive editing level - as in `C-r'. Use the recursive edit to insert text to replace the - deleted occurrence of STRING. When done, exit the recursive - editing level with `C-M-c' and the next occurrence will be - displayed. - -`C-l' - to redisplay the screen and then give another answer. - -`C-h' - to display a message summarizing these options, then give another - answer. - - If you type any other character, Emacs exits the `query-replace', and -executes the character as a command. To restart the `query-replace', -use `C-x ', which repeats the `query-replace' because it used the -minibuffer to read its arguments. *Note C-x ESC: Repetition. - - -File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search - -Other Search-and-Loop Commands -============================== - - Here are some other commands that find matches for a regular -expression. They all operate from point to the end of the buffer. - -`M-x occur' - Print each line that follows point and contains a match for the - specified regexp. A numeric argument specifies the number of - context lines to print before and after each matching line; the - default is none. - - The buffer `*Occur*' containing the output serves as a menu for - finding occurrences in their original context. Find an occurrence - as listed in `*Occur*', position point there, and type `C-c C-c'; - this switches to the buffer that was searched and moves point to - the original of the same occurrence. - -`M-x list-matching-lines' - Synonym for `M-x occur'. - -`M-x count-matches' - Print the number of matches following point for the specified - regexp. - -`M-x delete-non-matching-lines' - Delete each line that follows point and does not contain a match - for the specified regexp. - -`M-x delete-matching-lines' - Delete each line that follows point and contains a match for the - specified regexp. - - -File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top - -Commands for Fixing Typos -************************* - - This chapter describes commands that are especially useful when you -catch a mistake in your text just after you have made it, or when you -change your mind while composing text on line. - -* Menu: - -* Kill Errors:: Commands to kill a batch of recently entered text. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. - - -File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit - -Killing Your Mistakes -===================== - -`' - Delete last character (`delete-backward-char'). - -`M-' - Kill last word (`backward-kill-word'). - -`C-x ' - Kill to beginning of sentence (`backward-kill-sentence'). - - The character (`delete-backward-char') is the most important -correction command. When used among graphic (self-inserting) -characters, it can be thought of as canceling the last character typed. - - When your mistake is longer than a couple of characters, it might be -more convenient to use `M-' or `C-x '. `M-' kills back -to the start of the last word, and `C-x ' kills back to the start -of the last sentence. `C-x ' is particularly useful when you are -thinking of what to write as you type it, in case you change your mind -about phrasing. `M-' and `C-x ' save the killed text for -`C-y' and `M-y' to retrieve. *Note Yanking::. - - `M-' is often useful even when you have typed only a few -characters wrong, if you know you are confused in your typing and aren't -sure exactly what you typed. At such a time, you cannot correct with - except by looking at the screen to see what you did. It requires -less thought to kill the whole word and start over. - diff --git a/info/xemacs.info-7 b/info/xemacs.info-7 index ceaf16b..eb360e0 100644 --- a/info/xemacs.info-7 +++ b/info/xemacs.info-7 @@ -30,6 +30,615 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search + +Syntax of Regular Expressions +============================= + + Regular expressions have a syntax in which a few characters are +special constructs and the rest are "ordinary". An ordinary character +is a simple regular expression that matches that character and nothing +else. The special characters are `.', `*', `+', `?', `[', `]', `^', +`$', and `\'; no new special characters will be defined in the future. +Any other character appearing in a regular expression is ordinary, +unless a `\' precedes it. + + For example, `f' is not a special character, so it is ordinary, and +therefore `f' is a regular expression that matches the string `f' and +no other string. (It does _not_ match the string `ff'.) Likewise, `o' +is a regular expression that matches only `o'. + + Any two regular expressions A and B can be concatenated. The result +is a regular expression that matches a string if A matches some amount +of the beginning of that string and B matches the rest of the string. + + As a simple example, we can concatenate the regular expressions `f' +and `o' to get the regular expression `fo', which matches only the +string `fo'. Still trivial. To do something more powerful, you need +to use one of the special characters. Here is a list of them: + +`. (Period)' + is a special character that matches any single character except a + newline. Using concatenation, we can make regular expressions + like `a.b', which matches any three-character string that begins + with `a' and ends with `b'. + +`*' + is not a construct by itself; it is a quantifying suffix operator + that means to repeat the preceding regular expression as many + times as possible. In `fo*', the `*' applies to the `o', so `fo*' + matches one `f' followed by any number of `o's. The case of zero + `o's is allowed: `fo*' does match `f'. + + `*' always applies to the _smallest_ possible preceding + expression. Thus, `fo*' has a repeating `o', not a repeating `fo'. + + The matcher processes a `*' construct by matching, immediately, as + many repetitions as can be found; it is "greedy". Then it + continues with the rest of the pattern. If that fails, + backtracking occurs, discarding some of the matches of the + `*'-modified construct in case that makes it possible to match the + rest of the pattern. For example, in matching `ca*ar' against the + string `caaar', the `a*' first tries to match all three `a's; but + the rest of the pattern is `ar' and there is only `r' left to + match, so this try fails. The next alternative is for `a*' to + match only two `a's. With this choice, the rest of the regexp + matches successfully. + + Nested repetition operators can be extremely slow if they specify + backtracking loops. For example, it could take hours for the + regular expression `\(x+y*\)*a' to match the sequence + `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because + Emacs must try each imaginable way of grouping the 35 `x''s before + concluding that none of them can work. To make sure your regular + expressions run fast, check nested repetitions carefully. + +`+' + is a quantifying suffix operator similar to `*' except that the + preceding expression must match at least once. It is also + "greedy". So, for example, `ca+r' matches the strings `car' and + `caaaar' but not the string `cr', whereas `ca*r' matches all three + strings. + +`?' + is a quantifying suffix operator similar to `*', except that the + preceding expression can match either once or not at all. For + example, `ca?r' matches `car' or `cr', but does not match anything + else. + +`*?' + works just like `*', except that rather than matching the longest + match, it matches the shortest match. `*?' is known as a + "non-greedy" quantifier, a regexp construct borrowed from Perl. + + This construct is very useful for when you want to match the text + inside a pair of delimiters. For instance, `/\*.*?\*/' will match + C comments in a string. This could not easily be achieved without + the use of a non-greedy quantifier. + + This construct has not been available prior to XEmacs 20.4. It is + not available in FSF Emacs. + +`+?' + is the non-greedy version of `+'. + +`??' + is the non-greedy version of `?'. + +`\{n,m\}' + serves as an interval quantifier, analogous to `*' or `+', but + specifies that the expression must match at least N times, but no + more than M times. This syntax is supported by most Unix regexp + utilities, and has been introduced to XEmacs for the version 20.3. + + Unfortunately, the non-greedy version of this quantifier does not + exist currently, although it does in Perl. + +`[ ... ]' + `[' begins a "character set", which is terminated by a `]'. In + the simplest case, the characters between the two brackets form + the set. Thus, `[ad]' matches either one `a' or one `d', and + `[ad]*' matches any string composed of just `a's and `d's + (including the empty string), from which it follows that `c[ad]*r' + matches `cr', `car', `cdr', `caddaar', etc. + + The usual regular expression special characters are not special + inside a character set. A completely different set of special + characters exists inside character sets: `]', `-' and `^'. + + `-' is used for ranges of characters. To write a range, write two + characters with a `-' between them. Thus, `[a-z]' matches any + lower case letter. Ranges may be intermixed freely with individual + characters, as in `[a-z$%.]', which matches any lower case letter + or `$', `%', or a period. + + To include a `]' in a character set, make it the first character. + For example, `[]a]' matches `]' or `a'. To include a `-', write + `-' as the first character in the set, or put it immediately after + a range. (You can replace one individual character C with the + range `C-C' to make a place to put the `-'.) There is no way to + write a set containing just `-' and `]'. + + To include `^' in a set, put it anywhere but at the beginning of + the set. + +`[^ ... ]' + `[^' begins a "complement character set", which matches any + character except the ones specified. Thus, `[^a-z0-9A-Z]' matches + all characters _except_ letters and digits. + + `^' is not special in a character set unless it is the first + character. The character following the `^' is treated as if it + were first (thus, `-' and `]' are not special there). + + Note that a complement character set can match a newline, unless + newline is mentioned as one of the characters not to match. + +`^' + is a special character that matches the empty string, but only at + the beginning of a line in the text being matched. Otherwise it + fails to match anything. Thus, `^foo' matches a `foo' that occurs + at the beginning of a line. + + When matching a string instead of a buffer, `^' matches at the + beginning of the string or after a newline character `\n'. + +`$' + is similar to `^' but matches only at the end of a line. Thus, + `x+$' matches a string of one `x' or more at the end of a line. + + When matching a string instead of a buffer, `$' matches at the end + of the string or before a newline character `\n'. + +`\' + has two functions: it quotes the special characters (including + `\'), and it introduces additional special constructs. + + Because `\' quotes special characters, `\$' is a regular + expression that matches only `$', and `\[' is a regular expression + that matches only `[', and so on. + + *Please note:* For historical compatibility, special characters are +treated as ordinary ones if they are in contexts where their special +meanings make no sense. For example, `*foo' treats `*' as ordinary +since there is no preceding expression on which the `*' can act. It is +poor practice to depend on this behavior; quote the special character +anyway, regardless of where it appears. + + For the most part, `\' followed by any character matches only that +character. However, there are several exceptions: characters that, +when preceded by `\', are special constructs. Such characters are +always ordinary when encountered on their own. Here is a table of `\' +constructs: + +`\|' + specifies an alternative. Two regular expressions A and B with + `\|' in between form an expression that matches anything that + either A or B matches. + + Thus, `foo\|bar' matches either `foo' or `bar' but no other string. + + `\|' applies to the largest possible surrounding expressions. + Only a surrounding `\( ... \)' grouping can limit the grouping + power of `\|'. + + Full backtracking capability exists to handle multiple uses of + `\|'. + +`\( ... \)' + is a grouping construct that serves three purposes: + + 1. To enclose a set of `\|' alternatives for other operations. + Thus, `\(foo\|bar\)x' matches either `foox' or `barx'. + + 2. To enclose an expression for a suffix operator such as `*' to + act on. Thus, `ba\(na\)*' matches `bananana', etc., with any + (zero or more) number of `na' strings. + + 3. To record a matched substring for future reference. + + This last application is not a consequence of the idea of a + parenthetical grouping; it is a separate feature that happens to be + assigned as a second meaning to the same `\( ... \)' construct + because there is no conflict in practice between the two meanings. + Here is an explanation of this feature: + +`\DIGIT' + matches the same text that matched the DIGITth occurrence of a `\( + ... \)' construct. + + In other words, after the end of a `\( ... \)' construct. the + matcher remembers the beginning and end of the text matched by that + construct. Then, later on in the regular expression, you can use + `\' followed by DIGIT to match that same text, whatever it may + have been. + + The strings matching the first nine `\( ... \)' constructs + appearing in a regular expression are assigned numbers 1 through 9 + in the order that the open parentheses appear in the regular + expression. So you can use `\1' through `\9' to refer to the text + matched by the corresponding `\( ... \)' constructs. + + For example, `\(.*\)\1' matches any newline-free string that is + composed of two identical halves. The `\(.*\)' matches the first + half, which may be anything, but the `\1' that follows must match + the same exact text. + +`\(?: ... \)' + is called a "shy" grouping operator, and it is used just like `\( + ... \)', except that it does not cause the matched substring to be + recorded for future reference. + + This is useful when you need a lot of grouping `\( ... \)' + constructs, but only want to remember one or two - or if you have + more than nine groupings and need to use backreferences to refer to + the groupings at the end. + + Using `\(?: ... \)' rather than `\( ... \)' when you don't need + the captured substrings ought to speed up your programs some, + since it shortens the code path followed by the regular expression + engine, as well as the amount of memory allocation and string + copying it must do. The actual performance gain to be observed + has not been measured or quantified as of this writing. + + The shy grouping operator has been borrowed from Perl, and has not + been available prior to XEmacs 20.3, nor is it available in FSF + Emacs. + +`\w' + matches any word-constituent character. The editor syntax table + determines which characters these are. *Note Syntax::. + +`\W' + matches any character that is not a word constituent. + +`\sCODE' + matches any character whose syntax is CODE. Here CODE is a + character that represents a syntax code: thus, `w' for word + constituent, `-' for whitespace, `(' for open parenthesis, etc. + *Note Syntax::, for a list of syntax codes and the characters that + stand for them. + +`\SCODE' + matches any character whose syntax is not CODE. + + The following regular expression constructs match the empty +string--that is, they don't use up any characters--but whether they +match depends on the context. + +`\`' + matches the empty string, but only at the beginning of the buffer + or string being matched against. + +`\'' + matches the empty string, but only at the end of the buffer or + string being matched against. + +`\=' + matches the empty string, but only at point. (This construct is + not defined when matching against a string.) + +`\b' + matches the empty string, but only at the beginning or end of a + word. Thus, `\bfoo\b' matches any occurrence of `foo' as a + separate word. `\bballs?\b' matches `ball' or `balls' as a + separate word. + +`\B' + matches the empty string, but _not_ at the beginning or end of a + word. + +`\<' + matches the empty string, but only at the beginning of a word. + +`\>' + matches the empty string, but only at the end of a word. + + Here is a complicated regexp used by Emacs to recognize the end of a +sentence together with any whitespace that follows. It is given in Lisp +syntax to enable you to distinguish the spaces from the tab characters. +In Lisp syntax, the string constant begins and ends with a +double-quote. `\"' stands for a double-quote as part of the regexp, +`\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for +a newline. + + "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" + +This regexp contains four parts: a character set matching period, `?' +or `!'; a character set matching close-brackets, quotes or parentheses, +repeated any number of times; an alternative in backslash-parentheses +that matches end-of-line, a tab or two spaces; and a character set +matching whitespace characters, repeated any number of times. + + +File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search + +Searching and Case +================== + + All searches in Emacs normally ignore the case of the text they are +searching through; if you specify searching for `FOO', `Foo' and `foo' +are also considered a match. Regexps, and in particular character +sets, are included: `[aB]' matches `a' or `A' or `b' or `B'. + + If you want a case-sensitive search, set the variable +`case-fold-search' to `nil'. Then all letters must match exactly, +including case. `case-fold-search' is a per-buffer variable; altering +it affects only the current buffer, but there is a default value which +you can change as well. *Note Locals::. You can also use Case +Sensitive Search from the Options menu on your screen. + + +File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search + +Replacement Commands +==================== + + Global search-and-replace operations are not needed as often in +Emacs as they are in other editors, but they are available. In +addition to the simple `replace-string' command which is like that +found in most editors, there is a `query-replace' command which asks +you, for each occurrence of a pattern, whether to replace it. + + The replace commands all replace one string (or regexp) with one +replacement string. It is possible to perform several replacements in +parallel using the command `expand-region-abbrevs'. *Note Expanding +Abbrevs::. + +* Menu: + +* Unconditional Replace:: Replacing all matches for a string. +* Regexp Replace:: Replacing all matches for a regexp. +* Replacement and Case:: How replacements preserve case of letters. +* Query Replace:: How to use querying. + + +File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace + +Unconditional Replacement +------------------------- + +`M-x replace-string STRING NEWSTRING ' + Replace every occurrence of STRING with NEWSTRING. + +`M-x replace-regexp REGEXP NEWSTRING ' + Replace every match for REGEXP with NEWSTRING. + + To replace every instance of `foo' after point with `bar', use the +command `M-x replace-string' with the two arguments `foo' and `bar'. +Replacement occurs only after point: if you want to cover the whole +buffer you must go to the beginning first. By default, all occurrences +up to the end of the buffer are replaced. To limit replacement to part +of the buffer, narrow to that part of the buffer before doing the +replacement (*note Narrowing::). + + When `replace-string' exits, point is left at the last occurrence +replaced. The value of point when the `replace-string' command was +issued is remembered on the mark ring; `C-u C-' moves back there. + + A numeric argument restricts replacement to matches that are +surrounded by word boundaries. + + +File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace + +Regexp Replacement +------------------ + + `replace-string' replaces exact matches for a single string. The +similar command `replace-regexp' replaces any match for a specified +pattern. + + In `replace-regexp', the NEWSTRING need not be constant. It can +refer to all or part of what is matched by the REGEXP. `\&' in +NEWSTRING stands for the entire text being replaced. `\D' in +NEWSTRING, where D is a digit, stands for whatever matched the D'th +parenthesized grouping in REGEXP. For example, + + M-x replace-regexp c[ad]+r \&-safe + +would replace (for example) `cadr' with `cadr-safe' and `cddr' with +`cddr-safe'. + + M-x replace-regexp \(c[ad]+r\)-safe \1 + +would perform exactly the opposite replacements. To include a `\' in +the text to replace with, you must give `\\'. + + +File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace + +Replace Commands and Case +------------------------- + + If the arguments to a replace command are in lower case, the command +preserves case when it makes a replacement. Thus, the following +command: + + M-x replace-string foo bar + +replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR', +and `Foo' with `Bar'. If upper-case letters are used in the second +argument, they remain upper-case every time that argument is inserted. +If upper-case letters are used in the first argument, the second +argument is always substituted exactly as given, with no case +conversion. Likewise, if the variable `case-replace' is set to `nil', +replacement is done without case conversion. If `case-fold-search' is +set to `nil', case is significant in matching occurrences of `foo' to +replace; also, case conversion of the replacement string is not done. + + +File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace + +Query Replace +------------- + +`M-% STRING NEWSTRING ' +`M-x query-replace STRING NEWSTRING ' + Replace some occurrences of STRING with NEWSTRING. + +`M-x query-replace-regexp REGEXP NEWSTRING ' + Replace some matches for REGEXP with NEWSTRING. + + If you want to change only some of the occurrences of `foo' to +`bar', not all of them, you can use `query-replace' instead of `M-%'. +This command finds occurrences of `foo' one by one, displays each +occurrence, and asks you whether to replace it. A numeric argument to +`query-replace' tells it to consider only occurrences that are bounded +by word-delimiter characters. + + Aside from querying, `query-replace' works just like +`replace-string', and `query-replace-regexp' works just like +`replace-regexp'. + + The things you can type when you are shown an occurrence of STRING +or a match for REGEXP are: + +`' + to replace the occurrence with NEWSTRING. This preserves case, + just like `replace-string', provided `case-replace' is non-`nil', + as it normally is. + +`' + to skip to the next occurrence without replacing this one. + +`, (Comma)' + to replace this occurrence and display the result. You are then + prompted for another input character. However, since the + replacement has already been made, and are equivalent. + At this point, you can type `C-r' (see below) to alter the + replaced text. To undo the replacement, you can type `C-x u'. + This exits the `query-replace'. If you want to do further + replacement you must use `C-x ESC' to restart (*note Repetition::). + +`' + to exit without doing any more replacements. + +`. (Period)' + to replace this occurrence and then exit. + +`!' + to replace all remaining occurrences without asking again. + +`^' + to go back to the location of the previous occurrence (or what + used to be an occurrence), in case you changed it by mistake. + This works by popping the mark ring. Only one `^' in a row is + allowed, because only one previous replacement location is kept + during `query-replace'. + +`C-r' + to enter a recursive editing level, in case the occurrence needs + to be edited rather than just replaced with NEWSTRING. When you + are done, exit the recursive editing level with `C-M-c' and the + next occurrence will be displayed. *Note Recursive Edit::. + +`C-w' + to delete the occurrence, and then enter a recursive editing level + as in `C-r'. Use the recursive edit to insert text to replace the + deleted occurrence of STRING. When done, exit the recursive + editing level with `C-M-c' and the next occurrence will be + displayed. + +`C-l' + to redisplay the screen and then give another answer. + +`C-h' + to display a message summarizing these options, then give another + answer. + + If you type any other character, Emacs exits the `query-replace', and +executes the character as a command. To restart the `query-replace', +use `C-x ', which repeats the `query-replace' because it used the +minibuffer to read its arguments. *Note C-x ESC: Repetition. + + +File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search + +Other Search-and-Loop Commands +============================== + + Here are some other commands that find matches for a regular +expression. They all operate from point to the end of the buffer. + +`M-x occur' + Print each line that follows point and contains a match for the + specified regexp. A numeric argument specifies the number of + context lines to print before and after each matching line; the + default is none. + + The buffer `*Occur*' containing the output serves as a menu for + finding occurrences in their original context. Find an occurrence + as listed in `*Occur*', position point there, and type `C-c C-c'; + this switches to the buffer that was searched and moves point to + the original of the same occurrence. + +`M-x list-matching-lines' + Synonym for `M-x occur'. + +`M-x count-matches' + Print the number of matches following point for the specified + regexp. + +`M-x delete-non-matching-lines' + Delete each line that follows point and does not contain a match + for the specified regexp. + +`M-x delete-matching-lines' + Delete each line that follows point and contains a match for the + specified regexp. + + +File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top + +Commands for Fixing Typos +************************* + + This chapter describes commands that are especially useful when you +catch a mistake in your text just after you have made it, or when you +change your mind while composing text on line. + +* Menu: + +* Kill Errors:: Commands to kill a batch of recently entered text. +* Transpose:: Exchanging two characters, words, lines, lists... +* Fixing Case:: Correcting case of last word entered. +* Spelling:: Apply spelling checker to a word, or a whole file. + + +File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit + +Killing Your Mistakes +===================== + +`' + Delete last character (`delete-backward-char'). + +`M-' + Kill last word (`backward-kill-word'). + +`C-x ' + Kill to beginning of sentence (`backward-kill-sentence'). + + The character (`delete-backward-char') is the most important +correction command. When used among graphic (self-inserting) +characters, it can be thought of as canceling the last character typed. + + When your mistake is longer than a couple of characters, it might be +more convenient to use `M-' or `C-x '. `M-' kills back +to the start of the last word, and `C-x ' kills back to the start +of the last sentence. `C-x ' is particularly useful when you are +thinking of what to write as you type it, in case you change your mind +about phrasing. `M-' and `C-x ' save the killed text for +`C-y' and `M-y' to retrieve. *Note Yanking::. + + `M-' is often useful even when you have typed only a few +characters wrong, if you know you are confused in your typing and aren't +sure exactly what you typed. At such a time, you cannot correct with + except by looking at the screen to see what you did. It requires +less thought to kill the whole word and start over. + + File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit Transposing Text @@ -574,496 +1183,3 @@ the making of backups for that buffer's file. For example, Rmail mode locally sets `version-control' to `never' to make sure that there is only one backup for an Rmail file. *Note Locals::. - -File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup - -Automatic Deletion of Backups -............................. - - To prevent unlimited consumption of disk space, Emacs can delete -numbered backup versions automatically. Generally Emacs keeps the -first few backups and the latest few backups, deleting any in between. -This happens every time a new backup is made. The two variables that -control the deletion are `kept-old-versions' and `kept-new-versions'. -Their values are, respectively the number of oldest (lowest-numbered) -backups to keep and the number of newest (highest-numbered) ones to -keep, each time a new backup is made. The values are used just after a -new backup version is made; that newly made backup is included in the -count in `kept-new-versions'. By default, both variables are 2. - - If `delete-old-versions' is non-`nil', excess middle versions are -deleted without notification. If it is `nil', the default, you are -asked whether the excess middle versions should really be deleted. - - You can also use Dired's `.' (Period) command to delete old versions. -*Note Dired::. - - -File: xemacs.info, Node: Backup Copying, Prev: Backup Deletion, Up: Backup - -Copying vs. Renaming -.................... - - You can make backup files by copying the old file or by renaming it. -This makes a difference when the old file has multiple names. If you -rename the old file into the backup file, the alternate names become -names for the backup file. If you copy the old file instead, the -alternate names remain names for the file that you are editing, and the -contents accessed by those names will be the new contents. - - How you make a backup file may also affect the file's owner and -group. If you use copying, they do not change. If renaming is used, -you become the file's owner, and the file's group becomes the default -(different operating systems have different defaults for the group). - - Having the owner change is usually a good idea, because then the -owner is always the person who last edited the file. Occasionally -there is a file whose owner should not change. Since most files should -change owners, it is a good idea to use local variable lists to set -`backup-by-copying-when-mismatch' for the special cases where the owner -should not change (*note File Variables::). - - Three variables control the choice of renaming or copying. -Normally, renaming is done. If the variable `backup-by-copying' is -non-`nil', copying is used. Otherwise, if the variable -`backup-by-copying-when-linked' is non-`nil', copying is done for files -that have multiple names, but renaming may still be done when the file -being edited has only one name. If the variable -`backup-by-copying-when-mismatch' is non-`nil', copying is done if -renaming would cause the file's owner or group to change. - - -File: xemacs.info, Node: Interlocking, Prev: Backup, Up: Saving - -Protection Against Simultaneous Editing ---------------------------------------- - - Simultaneous editing occurs when two users visit the same file, both -make changes, and both save their changes. If no one was informed that -this was happening, and you saved first, you would later find that your -changes were lost. On some systems, Emacs notices immediately when the -second user starts to change a file already being edited, and issues a -warning. When this is not possible, or if the second user has started -to change the file despite the warning, Emacs checks when the file is -saved, and issues a second warning when a user is about to overwrite a -file containing another user's changes. If you are the user editing the -file, you can take corrective action at this point and prevent actual -loss of work. - - When you make the first modification in an Emacs buffer that is -visiting a file, Emacs records that you have locked the file. (It does -this by writing another file in a directory reserved for this purpose.) -The lock is removed when you save the changes. The idea is that the -file is locked whenever the buffer is modified. If you begin to modify -the buffer while the visited file is locked by someone else, this -constitutes a collision, and Emacs asks you what to do. It does this -by calling the Lisp function `ask-user-about-lock', which you can -redefine to customize what it does. The standard definition of this -function asks you a question and accepts three possible answers: - -`s' - Steal the lock. Whoever was already changing the file loses the - lock, and you get the lock. - -`p' - Proceed. Go ahead and edit the file despite its being locked by - someone else. - -`q' - Quit. This causes an error (`file-locked') and the modification - you were trying to make in the buffer does not actually take place. - - Note that locking works on the basis of a file name; if a file has -multiple names, Emacs does not realize that the two names are the same -file and cannot prevent two users from editing it simultaneously under -different names. However, basing locking on names means that Emacs can -interlock the editing of new files that do not really exist until they -are saved. - - Some systems are not configured to allow Emacs to make locks. On -these systems, Emacs cannot detect trouble in advance, but it can still -detect it in time to prevent you from overwriting someone else's -changes. - - Every time Emacs saves a buffer, it first checks the -last-modification date of the existing file on disk to see that it has -not changed since the file was last visited or saved. If the date does -not match, it implies that changes were made in the file in some other -way, and these changes are about to be lost if Emacs actually does -save. To prevent this, Emacs prints a warning message and asks for -confirmation before saving. Occasionally you will know why the file -was changed and know that it does not matter; then you can answer `yes' -and proceed. Otherwise, you should cancel the save with `C-g' and -investigate the situation. - - The first thing you should do when notified that simultaneous editing -has already taken place is to list the directory with `C-u C-x C-d' -(*note Directory Listing: ListDir.). This will show the file's current -author. You should attempt to contact that person and ask him not to -continue editing. Often the next step is to save the contents of your -Emacs buffer under a different name, and use `diff' to compare the two -files. - - Simultaneous editing checks are also made when you visit a file that -is already visited with `C-x C-f' and when you start to modify a file. -This is not strictly necessary, but it is useful to find out about such -a problem as early as possible, when corrective action takes less work. - - Another way to protect your file is to set the read, write, and -executable permissions for the file. Use the function -`set-default-file-modes' to set the UNIX `umask' value to the NMASK -argument. The `umask' value is the default protection mode for new -files. - - -File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files - -Reverting a Buffer -================== - - If you have made extensive changes to a file and then change your -mind about them, you can get rid of all changes by reading in the -previous version of the file. To do this, use `M-x revert-buffer', -which operates on the current buffer. Since reverting a buffer can -result in very extensive changes, you must confirm it with `yes'. - - If the current buffer has been auto-saved more recently than it has -been saved explicitly, `revert-buffer' offers to read the auto save file -instead of the visited file (*note Auto Save::). Emacs asks you about -the auto-save file before the request for confirmation of the -`revert-buffer' operation, and demands `y' or `n' as an answer. If you -have started to type `yes' for confirmation without realizing that the -auto-save question was going to be asked, the `y' will answer that -question, but the `es' will not be valid confirmation. This gives you -a chance to cancel the operation with `C-g' and try again with the -answers you really intend. - - `revert-buffer' keeps point at the same distance (measured in -characters) from the beginning of the file. If the file was edited only -slightly, you will be at approximately the same piece of text after -reverting as before. If you have made more extensive changes, the -value of point in the old file may bring you to a totally different -piece of text than your last editing point. - - A buffer reverted from its visited file is marked "not modified" -until you make a change. - - Some kinds of buffers whose contents reflect data bases other than -files, such as Dired buffers, can also be reverted. For them, -reverting means recalculating their contents from the appropriate data. -Buffers created randomly with `C-x b' cannot be reverted; -`revert-buffer' reports an error when asked to do so. - - -File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files - -Auto-Saving: Protection Against Disasters -========================================= - - Emacs saves all the visited files from time to time (based on -counting your keystrokes) without being asked. This is called -"auto-saving". It prevents you from losing more than a limited amount -of work if the system crashes. - - When Emacs determines it is time for auto-saving, each buffer is -considered and is auto-saved if auto-saving is turned on for it and it -has changed since the last time it was auto-saved. If any auto-saving -is done, the message `Auto-saving...' is displayed in the echo area -until auto-saving is finished. Errors occurring during auto-saving are -caught so that they do not interfere with the execution of commands you -have been typing. - -* Menu: - -* Files: Auto Save Files. -* Control: Auto Save Control. -* Recover:: Recovering text from auto-save files. - - -File: xemacs.info, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save - -Auto-Save Files ---------------- - - Auto-saving does not normally write to the files you visited, because -it can be undesirable to save a program that is in an inconsistent -state when you have made only half of a planned change. Instead, -auto-saving is done in a different file called the "auto-save file", -and the visited file is changed only when you save explicitly, for -example, with `C-x C-s'. - - Normally, the name of the auto-save file is generated by appending -`#' to the front and back of the visited file name. Thus, a buffer -visiting file `foo.c' would be auto-saved in a file `#foo.c#'. Most -buffers that are not visiting files are auto-saved only if you request -it explicitly; when they are auto-saved, the auto-save file name is -generated by appending `#%' to the front and `#' to the back of buffer -name. For example, the `*mail*' buffer in which you compose messages -to be sent is auto-saved in a file named `#%*mail*#'. Names of -auto-save files are generated this way unless you customize the -functions `make-auto-save-file-name' and `auto-save-file-name-p' to do -something different. The file name to be used for auto-saving a buffer -is calculated at the time auto-saving is turned on in that buffer. - - If you want auto-saving to be done in the visited file, set the -variable `auto-save-visited-file-name' to be non-`nil'. In this mode, -there is really no difference between auto-saving and explicit saving. - - Emacs deletes a buffer's auto-save file when you explicitly save the -buffer. To inhibit the deletion, set the variable -`delete-auto-save-files' to `nil'. Changing the visited file name with -`C-x C-w' or `set-visited-file-name' renames any auto-save file to -correspond to the new visited name. - - -File: xemacs.info, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save - -Controlling Auto-Saving ------------------------ - - Each time you visit a file, auto-saving is turned on for that file's -buffer if the variable `auto-save-default' is non-`nil' (but not in -batch mode; *note Entering Emacs::). The default for this variable is -`t', so Emacs auto-saves buffers that visit files by default. You can -use the command `M-x auto-save-mode' to turn auto-saving for a buffer -on or off. Like other minor mode commands, `M-x auto-save-mode' turns -auto-saving on with a positive argument, off with a zero or negative -argument; with no argument, it toggles. - - Emacs performs auto-saving periodically based on counting how many -characters you have typed since the last time auto-saving happened. The -variable `auto-save-interval' specifies the number of characters -between auto-saves. By default, it is 300. Emacs also auto-saves -whenever you call the function `do-auto-save'. - - Emacs also does auto-saving whenever it gets a fatal error. This -includes killing the Emacs job with a shell command such as `kill --emacs', or disconnecting a phone line or network connection. - - You can set the number of seconds of idle time before an auto-save is -done. Setting the value of the variable `auto-save-timeout' to zero or -`nil' will disable auto-saving due to idleness. - - The actual amount of idle time between auto-saves is logarithmically -related to the size of the current buffer. This variable is the number -of seconds after which an auto-save will happen when the current buffer -is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3 -3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k -buffer. - - For this variable to have any effect, you must do `(require 'timer)'. - - -File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save - -Recovering Data from Auto-Saves -------------------------------- - - If you want to use the contents of an auto-save file to recover from -a loss of data, use the command `M-x recover-file FILE '. -Emacs visits FILE and then (after your confirmation) restores the -contents from the auto-save file `#FILE#'. You can then save the file -with `C-x C-s' to put the recovered text into FILE itself. For -example, to recover file `foo.c' from its auto-save file `#foo.c#', do: - - M-x recover-file foo.c - C-x C-s - - Before asking for confirmation, `M-x recover-file' displays a -directory listing describing the specified file and the auto-save file, -so you can compare their sizes and dates. If the auto-save file is -older, `M-x recover-file' does not offer to read it. - - Auto-saving is disabled by `M-x recover-file' because using this -command implies that the auto-save file contains valuable data from a -past session. If you save the data in the visited file and then go on -to make new changes, turn auto-saving back on with `M-x auto-save-mode'. - - -File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files - -Version Control -=============== - - "Version control systems" are packages that can record multiple -versions of a source file, usually storing the unchanged parts of the -file just once. Version control systems also record history information -such as the creation time of each version, who created it, and a -description of what was changed in that version. - - The GNU project recommends the version control system known as RCS, -which is free software and available from the Free Software Foundation. -Emacs supports use of either RCS or SCCS (a proprietary, but widely -used, version control system that is not quite as powerful as RCS) -through a facility called VC. The same Emacs commands work with either -RCS or SCCS, so you hardly have to know which one of them you are using. - -* Menu: - -* Concepts of VC:: Basic version control information; - checking files in and out. -* Editing with VC:: Commands for editing a file maintained - with version control. -* Variables for Check-in/out:: Variables that affect the commands used - to check files in or out. -* Log Entries:: Logging your changes. -* Change Logs and VC:: Generating a change log file from log - entries. -* Old Versions:: Examining and comparing old versions. -* VC Status:: Commands to view the VC status of files and - look at log entries. -* Renaming and VC:: A command to rename both the source and - master file correctly. -* Snapshots:: How to make and use snapshots, a set of - file versions that can be treated as a unit. -* Version Headers:: Inserting version control headers into - working files. - - -File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control - -Concepts of Version Control ---------------------------- - - When a file is under version control, we also say that it is -"registered" in the version control system. Each registered file has a -corresponding "master file" which represents the file's present state -plus its change history, so that you can reconstruct from it either the -current version or any specified earlier version. Usually the master -file also records a "log entry" for each version describing what was -changed in that version. - - The file that is maintained under version control is sometimes called -the "work file" corresponding to its master file. - - To examine a file, you "check it out". This extracts a version of -the source file (typically, the most recent) from the master file. If -you want to edit the file, you must check it out "locked". Only one -user can do this at a time for any given source file. (This kind of -locking is completely unrelated to the locking that Emacs uses to -detect simultaneous editing of a file.) - - When you are done with your editing, you must "check in" the new -version. This records the new version in the master file, and unlocks -the source file so that other people can lock it and thus modify it. - - Checkin and checkout are the basic operations of version control. -You can do both of them with a single Emacs command: `C-x C-q' -(`vc-toggle-read-only'). - - A "snapshot" is a coherent collection of versions of the various -files that make up a program. *Note Snapshots::. - - -File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control - -Editing with Version Control ----------------------------- - - When you visit a file that is maintained using version control, the -mode line displays `RCS' or `SCCS' to inform you that version control -is in use, and also (in case you care) which low-level system the file -is actually stored in. Normally, such a source file is read-only, and -the mode line indicates this with `%%'. With RCS, the mode line also -indicates the number of the head version, which is normally also the -version you are looking at. - - These are the commands for editing a file maintained with version -control: - -`C-x C-q' - Check the visited file in or out. - -`C-x v u' - Revert the buffer and the file to the last checked in version. - -`C-x v c' - Remove the last-entered change from the master for the visited - file. This undoes your last check-in. - -`C-x v i' - Register the visited file in version control. - -(`C-x v' is the prefix key for version control commands; all of these -commands except for `C-x C-q' start with `C-x v'.) - - When you want to modify a file maintained with version control, type -`C-x C-q' (`vc-toggle-read-only'). This "checks out" the file, and -tells RCS or SCCS to lock the file. This means making the file -writable for you (but not for anyone else). - - When you are finished editing the file, type `C-x C-q' again. When -used on a file that is checked out, this command checks the file in. -But check-in does not start immediately; first, you must enter the "log -entry"--a description of the changes in the new version. `C-x C-q' -pops up a buffer for you to enter this in. When you are finished -typing in the log entry, type `C-c C-c' to terminate it; this is when -actual check-in takes place. - - Once you have checked in your changes, the file is unlocked, so that -other users can lock it and modify it. - - Emacs does not save backup files for source files that are maintained -with version control. If you want to make backup files despite version -control, set the variable `vc-make-backup-files' to a non-`nil' value. - - Normally the work file exists all the time, whether it is locked or -not. If you set `vc-keep-workfiles' to `nil', then checking in a new -version with `C-x C-q' deletes the work file; but any attempt to visit -the file with Emacs creates it again. - - It is not impossible to lock a file that someone else has locked. If -you try to check out a file that is locked, `C-x C-q' asks you whether -you want to "steal the lock." If you say yes, the file becomes locked -by you, but a message is sent to the person who had formerly locked the -file, to inform him of what has happened. The mode line indicates that -a file is locked by someone else by displaying the login name of that -person, before the version number. - - If you want to discard your current set of changes and revert to the -last version checked in, use `C-x v u' (`vc-revert-buffer'). This -cancels your last check-out, leaving the file unlocked. If you want to -make a different set of changes, you must first check the file out -again. `C-x v u' requires confirmation, unless it sees that you -haven't made any changes since the last checked-in version. - - `C-x v u' is also the command to use if you lock a file and then -don't actually change it. - - You can cancel a change after checking it in, with `C-x v c' -(`vc-cancel-version'). This command discards all record of the most -recent checked in version, so be careful about using it. It requires -confirmation with `yes'. By default, `C-x v c' reverts your workfile -and buffer to the previous version (the one that precedes the version -that is deleted), but you can prevent the reversion by giving the -command a prefix argument. Then the buffer does not change. - - This command with a prefix argument is useful when you have checked -in a change and then discover a trivial error in it; you can cancel the -erroneous check-in, fix the error, and repeat the check-in. - - Be careful when invoking `C-x v c', as it is easy to throw away a -lot of work with it. To help you be careful, this command always -requires confirmation with `yes'. - - You can register the visited file for version control using -`C-x v i' (`vc-register'). If the variable `vc-default-back-end' is -non-`nil', it specifies which version control system to use; otherwise, -this uses RCS if it is installed on your system and SCCS if not. After -`C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you -wish to edit it. - - By default, the initial version number is 1.1. If you want to use a -different number, give `C-x v i' a prefix argument; then it reads the -initial version number using the minibuffer. - - If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial -comment (much like a log entry) to describe the purpose of this source -file. - - To specify the version number for a subsequent checkin, use the -command `C-u C-x v v'. `C-x v v' (`vc-next-action') is the command -that `C-x C-q' uses to do the "real work" when the visited file uses -version control. When used for checkin, and given a prefix argument, -it reads the version number with the minibuffer. - diff --git a/info/xemacs.info-8 b/info/xemacs.info-8 index ceb42a9..e72246b 100644 --- a/info/xemacs.info-8 +++ b/info/xemacs.info-8 @@ -30,6 +30,499 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Backup Deletion, Next: Backup Copying, Prev: Backup Names, Up: Backup + +Automatic Deletion of Backups +............................. + + To prevent unlimited consumption of disk space, Emacs can delete +numbered backup versions automatically. Generally Emacs keeps the +first few backups and the latest few backups, deleting any in between. +This happens every time a new backup is made. The two variables that +control the deletion are `kept-old-versions' and `kept-new-versions'. +Their values are, respectively the number of oldest (lowest-numbered) +backups to keep and the number of newest (highest-numbered) ones to +keep, each time a new backup is made. The values are used just after a +new backup version is made; that newly made backup is included in the +count in `kept-new-versions'. By default, both variables are 2. + + If `delete-old-versions' is non-`nil', excess middle versions are +deleted without notification. If it is `nil', the default, you are +asked whether the excess middle versions should really be deleted. + + You can also use Dired's `.' (Period) command to delete old versions. +*Note Dired::. + + +File: xemacs.info, Node: Backup Copying, Prev: Backup Deletion, Up: Backup + +Copying vs. Renaming +.................... + + You can make backup files by copying the old file or by renaming it. +This makes a difference when the old file has multiple names. If you +rename the old file into the backup file, the alternate names become +names for the backup file. If you copy the old file instead, the +alternate names remain names for the file that you are editing, and the +contents accessed by those names will be the new contents. + + How you make a backup file may also affect the file's owner and +group. If you use copying, they do not change. If renaming is used, +you become the file's owner, and the file's group becomes the default +(different operating systems have different defaults for the group). + + Having the owner change is usually a good idea, because then the +owner is always the person who last edited the file. Occasionally +there is a file whose owner should not change. Since most files should +change owners, it is a good idea to use local variable lists to set +`backup-by-copying-when-mismatch' for the special cases where the owner +should not change (*note File Variables::). + + Three variables control the choice of renaming or copying. +Normally, renaming is done. If the variable `backup-by-copying' is +non-`nil', copying is used. Otherwise, if the variable +`backup-by-copying-when-linked' is non-`nil', copying is done for files +that have multiple names, but renaming may still be done when the file +being edited has only one name. If the variable +`backup-by-copying-when-mismatch' is non-`nil', copying is done if +renaming would cause the file's owner or group to change. + + +File: xemacs.info, Node: Interlocking, Prev: Backup, Up: Saving + +Protection Against Simultaneous Editing +--------------------------------------- + + Simultaneous editing occurs when two users visit the same file, both +make changes, and both save their changes. If no one was informed that +this was happening, and you saved first, you would later find that your +changes were lost. On some systems, Emacs notices immediately when the +second user starts to change a file already being edited, and issues a +warning. When this is not possible, or if the second user has started +to change the file despite the warning, Emacs checks when the file is +saved, and issues a second warning when a user is about to overwrite a +file containing another user's changes. If you are the user editing the +file, you can take corrective action at this point and prevent actual +loss of work. + + When you make the first modification in an Emacs buffer that is +visiting a file, Emacs records that you have locked the file. (It does +this by writing another file in a directory reserved for this purpose.) +The lock is removed when you save the changes. The idea is that the +file is locked whenever the buffer is modified. If you begin to modify +the buffer while the visited file is locked by someone else, this +constitutes a collision, and Emacs asks you what to do. It does this +by calling the Lisp function `ask-user-about-lock', which you can +redefine to customize what it does. The standard definition of this +function asks you a question and accepts three possible answers: + +`s' + Steal the lock. Whoever was already changing the file loses the + lock, and you get the lock. + +`p' + Proceed. Go ahead and edit the file despite its being locked by + someone else. + +`q' + Quit. This causes an error (`file-locked') and the modification + you were trying to make in the buffer does not actually take place. + + Note that locking works on the basis of a file name; if a file has +multiple names, Emacs does not realize that the two names are the same +file and cannot prevent two users from editing it simultaneously under +different names. However, basing locking on names means that Emacs can +interlock the editing of new files that do not really exist until they +are saved. + + Some systems are not configured to allow Emacs to make locks. On +these systems, Emacs cannot detect trouble in advance, but it can still +detect it in time to prevent you from overwriting someone else's +changes. + + Every time Emacs saves a buffer, it first checks the +last-modification date of the existing file on disk to see that it has +not changed since the file was last visited or saved. If the date does +not match, it implies that changes were made in the file in some other +way, and these changes are about to be lost if Emacs actually does +save. To prevent this, Emacs prints a warning message and asks for +confirmation before saving. Occasionally you will know why the file +was changed and know that it does not matter; then you can answer `yes' +and proceed. Otherwise, you should cancel the save with `C-g' and +investigate the situation. + + The first thing you should do when notified that simultaneous editing +has already taken place is to list the directory with `C-u C-x C-d' +(*note Directory Listing: ListDir.). This will show the file's current +author. You should attempt to contact that person and ask him not to +continue editing. Often the next step is to save the contents of your +Emacs buffer under a different name, and use `diff' to compare the two +files. + + Simultaneous editing checks are also made when you visit a file that +is already visited with `C-x C-f' and when you start to modify a file. +This is not strictly necessary, but it is useful to find out about such +a problem as early as possible, when corrective action takes less work. + + Another way to protect your file is to set the read, write, and +executable permissions for the file. Use the function +`set-default-file-modes' to set the UNIX `umask' value to the NMASK +argument. The `umask' value is the default protection mode for new +files. + + +File: xemacs.info, Node: Reverting, Next: Auto Save, Prev: Saving, Up: Files + +Reverting a Buffer +================== + + If you have made extensive changes to a file and then change your +mind about them, you can get rid of all changes by reading in the +previous version of the file. To do this, use `M-x revert-buffer', +which operates on the current buffer. Since reverting a buffer can +result in very extensive changes, you must confirm it with `yes'. + + If the current buffer has been auto-saved more recently than it has +been saved explicitly, `revert-buffer' offers to read the auto save file +instead of the visited file (*note Auto Save::). Emacs asks you about +the auto-save file before the request for confirmation of the +`revert-buffer' operation, and demands `y' or `n' as an answer. If you +have started to type `yes' for confirmation without realizing that the +auto-save question was going to be asked, the `y' will answer that +question, but the `es' will not be valid confirmation. This gives you +a chance to cancel the operation with `C-g' and try again with the +answers you really intend. + + `revert-buffer' keeps point at the same distance (measured in +characters) from the beginning of the file. If the file was edited only +slightly, you will be at approximately the same piece of text after +reverting as before. If you have made more extensive changes, the +value of point in the old file may bring you to a totally different +piece of text than your last editing point. + + A buffer reverted from its visited file is marked "not modified" +until you make a change. + + Some kinds of buffers whose contents reflect data bases other than +files, such as Dired buffers, can also be reverted. For them, +reverting means recalculating their contents from the appropriate data. +Buffers created randomly with `C-x b' cannot be reverted; +`revert-buffer' reports an error when asked to do so. + + +File: xemacs.info, Node: Auto Save, Next: Version Control, Prev: Reverting, Up: Files + +Auto-Saving: Protection Against Disasters +========================================= + + Emacs saves all the visited files from time to time (based on +counting your keystrokes) without being asked. This is called +"auto-saving". It prevents you from losing more than a limited amount +of work if the system crashes. + + When Emacs determines it is time for auto-saving, each buffer is +considered and is auto-saved if auto-saving is turned on for it and it +has changed since the last time it was auto-saved. If any auto-saving +is done, the message `Auto-saving...' is displayed in the echo area +until auto-saving is finished. Errors occurring during auto-saving are +caught so that they do not interfere with the execution of commands you +have been typing. + +* Menu: + +* Files: Auto Save Files. +* Control: Auto Save Control. +* Recover:: Recovering text from auto-save files. + + +File: xemacs.info, Node: Auto Save Files, Next: Auto Save Control, Prev: Auto Save, Up: Auto Save + +Auto-Save Files +--------------- + + Auto-saving does not normally write to the files you visited, because +it can be undesirable to save a program that is in an inconsistent +state when you have made only half of a planned change. Instead, +auto-saving is done in a different file called the "auto-save file", +and the visited file is changed only when you save explicitly, for +example, with `C-x C-s'. + + Normally, the name of the auto-save file is generated by appending +`#' to the front and back of the visited file name. Thus, a buffer +visiting file `foo.c' would be auto-saved in a file `#foo.c#'. Most +buffers that are not visiting files are auto-saved only if you request +it explicitly; when they are auto-saved, the auto-save file name is +generated by appending `#%' to the front and `#' to the back of buffer +name. For example, the `*mail*' buffer in which you compose messages +to be sent is auto-saved in a file named `#%*mail*#'. Names of +auto-save files are generated this way unless you customize the +functions `make-auto-save-file-name' and `auto-save-file-name-p' to do +something different. The file name to be used for auto-saving a buffer +is calculated at the time auto-saving is turned on in that buffer. + + If you want auto-saving to be done in the visited file, set the +variable `auto-save-visited-file-name' to be non-`nil'. In this mode, +there is really no difference between auto-saving and explicit saving. + + Emacs deletes a buffer's auto-save file when you explicitly save the +buffer. To inhibit the deletion, set the variable +`delete-auto-save-files' to `nil'. Changing the visited file name with +`C-x C-w' or `set-visited-file-name' renames any auto-save file to +correspond to the new visited name. + + +File: xemacs.info, Node: Auto Save Control, Next: Recover, Prev: Auto Save Files, Up: Auto Save + +Controlling Auto-Saving +----------------------- + + Each time you visit a file, auto-saving is turned on for that file's +buffer if the variable `auto-save-default' is non-`nil' (but not in +batch mode; *note Entering Emacs::). The default for this variable is +`t', so Emacs auto-saves buffers that visit files by default. You can +use the command `M-x auto-save-mode' to turn auto-saving for a buffer +on or off. Like other minor mode commands, `M-x auto-save-mode' turns +auto-saving on with a positive argument, off with a zero or negative +argument; with no argument, it toggles. + + Emacs performs auto-saving periodically based on counting how many +characters you have typed since the last time auto-saving happened. The +variable `auto-save-interval' specifies the number of characters +between auto-saves. By default, it is 300. Emacs also auto-saves +whenever you call the function `do-auto-save'. + + Emacs also does auto-saving whenever it gets a fatal error. This +includes killing the Emacs job with a shell command such as `kill +-emacs', or disconnecting a phone line or network connection. + + You can set the number of seconds of idle time before an auto-save is +done. Setting the value of the variable `auto-save-timeout' to zero or +`nil' will disable auto-saving due to idleness. + + The actual amount of idle time between auto-saves is logarithmically +related to the size of the current buffer. This variable is the number +of seconds after which an auto-save will happen when the current buffer +is 50k or less; the timeout will be 2 1/4 times this in a 200k buffer, 3 +3/4 times this in a 1000k buffer, and 4 1/2 times this in a 2000k +buffer. + + For this variable to have any effect, you must do `(require 'timer)'. + + +File: xemacs.info, Node: Recover, Prev: Auto Save Control, Up: Auto Save + +Recovering Data from Auto-Saves +------------------------------- + + If you want to use the contents of an auto-save file to recover from +a loss of data, use the command `M-x recover-file FILE '. +Emacs visits FILE and then (after your confirmation) restores the +contents from the auto-save file `#FILE#'. You can then save the file +with `C-x C-s' to put the recovered text into FILE itself. For +example, to recover file `foo.c' from its auto-save file `#foo.c#', do: + + M-x recover-file foo.c + C-x C-s + + Before asking for confirmation, `M-x recover-file' displays a +directory listing describing the specified file and the auto-save file, +so you can compare their sizes and dates. If the auto-save file is +older, `M-x recover-file' does not offer to read it. + + Auto-saving is disabled by `M-x recover-file' because using this +command implies that the auto-save file contains valuable data from a +past session. If you save the data in the visited file and then go on +to make new changes, turn auto-saving back on with `M-x auto-save-mode'. + + +File: xemacs.info, Node: Version Control, Next: ListDir, Prev: Auto Save, Up: Files + +Version Control +=============== + + "Version control systems" are packages that can record multiple +versions of a source file, usually storing the unchanged parts of the +file just once. Version control systems also record history information +such as the creation time of each version, who created it, and a +description of what was changed in that version. + + The GNU project recommends the version control system known as RCS, +which is free software and available from the Free Software Foundation. +Emacs supports use of either RCS or SCCS (a proprietary, but widely +used, version control system that is not quite as powerful as RCS) +through a facility called VC. The same Emacs commands work with either +RCS or SCCS, so you hardly have to know which one of them you are using. + +* Menu: + +* Concepts of VC:: Basic version control information; + checking files in and out. +* Editing with VC:: Commands for editing a file maintained + with version control. +* Variables for Check-in/out:: Variables that affect the commands used + to check files in or out. +* Log Entries:: Logging your changes. +* Change Logs and VC:: Generating a change log file from log + entries. +* Old Versions:: Examining and comparing old versions. +* VC Status:: Commands to view the VC status of files and + look at log entries. +* Renaming and VC:: A command to rename both the source and + master file correctly. +* Snapshots:: How to make and use snapshots, a set of + file versions that can be treated as a unit. +* Version Headers:: Inserting version control headers into + working files. + + +File: xemacs.info, Node: Concepts of VC, Next: Editing with VC, Prev: Version Control, Up: Version Control + +Concepts of Version Control +--------------------------- + + When a file is under version control, we also say that it is +"registered" in the version control system. Each registered file has a +corresponding "master file" which represents the file's present state +plus its change history, so that you can reconstruct from it either the +current version or any specified earlier version. Usually the master +file also records a "log entry" for each version describing what was +changed in that version. + + The file that is maintained under version control is sometimes called +the "work file" corresponding to its master file. + + To examine a file, you "check it out". This extracts a version of +the source file (typically, the most recent) from the master file. If +you want to edit the file, you must check it out "locked". Only one +user can do this at a time for any given source file. (This kind of +locking is completely unrelated to the locking that Emacs uses to +detect simultaneous editing of a file.) + + When you are done with your editing, you must "check in" the new +version. This records the new version in the master file, and unlocks +the source file so that other people can lock it and thus modify it. + + Checkin and checkout are the basic operations of version control. +You can do both of them with a single Emacs command: `C-x C-q' +(`vc-toggle-read-only'). + + A "snapshot" is a coherent collection of versions of the various +files that make up a program. *Note Snapshots::. + + +File: xemacs.info, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control + +Editing with Version Control +---------------------------- + + When you visit a file that is maintained using version control, the +mode line displays `RCS' or `SCCS' to inform you that version control +is in use, and also (in case you care) which low-level system the file +is actually stored in. Normally, such a source file is read-only, and +the mode line indicates this with `%%'. With RCS, the mode line also +indicates the number of the head version, which is normally also the +version you are looking at. + + These are the commands for editing a file maintained with version +control: + +`C-x C-q' + Check the visited file in or out. + +`C-x v u' + Revert the buffer and the file to the last checked in version. + +`C-x v c' + Remove the last-entered change from the master for the visited + file. This undoes your last check-in. + +`C-x v i' + Register the visited file in version control. + +(`C-x v' is the prefix key for version control commands; all of these +commands except for `C-x C-q' start with `C-x v'.) + + When you want to modify a file maintained with version control, type +`C-x C-q' (`vc-toggle-read-only'). This "checks out" the file, and +tells RCS or SCCS to lock the file. This means making the file +writable for you (but not for anyone else). + + When you are finished editing the file, type `C-x C-q' again. When +used on a file that is checked out, this command checks the file in. +But check-in does not start immediately; first, you must enter the "log +entry"--a description of the changes in the new version. `C-x C-q' +pops up a buffer for you to enter this in. When you are finished +typing in the log entry, type `C-c C-c' to terminate it; this is when +actual check-in takes place. + + Once you have checked in your changes, the file is unlocked, so that +other users can lock it and modify it. + + Emacs does not save backup files for source files that are maintained +with version control. If you want to make backup files despite version +control, set the variable `vc-make-backup-files' to a non-`nil' value. + + Normally the work file exists all the time, whether it is locked or +not. If you set `vc-keep-workfiles' to `nil', then checking in a new +version with `C-x C-q' deletes the work file; but any attempt to visit +the file with Emacs creates it again. + + It is not impossible to lock a file that someone else has locked. If +you try to check out a file that is locked, `C-x C-q' asks you whether +you want to "steal the lock." If you say yes, the file becomes locked +by you, but a message is sent to the person who had formerly locked the +file, to inform him of what has happened. The mode line indicates that +a file is locked by someone else by displaying the login name of that +person, before the version number. + + If you want to discard your current set of changes and revert to the +last version checked in, use `C-x v u' (`vc-revert-buffer'). This +cancels your last check-out, leaving the file unlocked. If you want to +make a different set of changes, you must first check the file out +again. `C-x v u' requires confirmation, unless it sees that you +haven't made any changes since the last checked-in version. + + `C-x v u' is also the command to use if you lock a file and then +don't actually change it. + + You can cancel a change after checking it in, with `C-x v c' +(`vc-cancel-version'). This command discards all record of the most +recent checked in version, so be careful about using it. It requires +confirmation with `yes'. By default, `C-x v c' reverts your workfile +and buffer to the previous version (the one that precedes the version +that is deleted), but you can prevent the reversion by giving the +command a prefix argument. Then the buffer does not change. + + This command with a prefix argument is useful when you have checked +in a change and then discover a trivial error in it; you can cancel the +erroneous check-in, fix the error, and repeat the check-in. + + Be careful when invoking `C-x v c', as it is easy to throw away a +lot of work with it. To help you be careful, this command always +requires confirmation with `yes'. + + You can register the visited file for version control using +`C-x v i' (`vc-register'). If the variable `vc-default-back-end' is +non-`nil', it specifies which version control system to use; otherwise, +this uses RCS if it is installed on your system and SCCS if not. After +`C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you +wish to edit it. + + By default, the initial version number is 1.1. If you want to use a +different number, give `C-x v i' a prefix argument; then it reads the +initial version number using the minibuffer. + + If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial +comment (much like a log entry) to describe the purpose of this source +file. + + To specify the version number for a subsequent checkin, use the +command `C-u C-x v v'. `C-x v v' (`vc-next-action') is the command +that `C-x C-q' uses to do the "real work" when the visited file uses +version control. When used for checkin, and given a prefix argument, +it reads the version number with the minibuffer. + + File: xemacs.info, Node: Variables for Check-in/out, Next: Log Entries, Prev: Editing with VC, Up: Version Control Variables Affecting Check-in and Check-out @@ -591,570 +1084,3 @@ buffer from the actual disk directory and show any changes made in the directory by programs other than Dired. All deletion flags in the Dired buffer are lost when this is done. - -File: xemacs.info, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired - -Deleting Files With Dired -------------------------- - - The primary use of Dired is to flag files for deletion and then -delete them. - -`d' - Flag this file for deletion. - -`u' - Remove deletion-flag on this line. - -`' - Remove deletion-flag on previous line, moving point to that line. - -`x' - Delete the files that are flagged for deletion. - -`#' - Flag all auto-save files (files whose names start and end with `#') - for deletion (*note Auto Save::). - -`~' - Flag all backup files (files whose names end with `~') for deletion - (*note Backup::). - -`. (Period)' - Flag excess numeric backup files for deletion. The oldest and - newest few backup files of any one file are exempt; the middle - ones are flagged. - - You can flag a file for deletion by moving to the line describing the -file and typing `d' or `C-d'. The deletion flag is visible as a `D' at -the beginning of the line. Point is moved to the beginning of the next -line, so that repeated `d' commands flag successive files. - - The files are flagged for deletion rather than deleted immediately to -avoid the danger of deleting a file accidentally. Until you direct -Dired to delete the flagged files, you can remove deletion flags using -the commands `u' and . `u' works just like `d', but removes flags -rather than making flags. moves upward, removing flags; it is -like `u' with numeric argument automatically negated. - - To delete the flagged files, type `x'. This command first displays a -list of all the file names flagged for deletion, and requests -confirmation with `yes'. Once you confirm, all the flagged files are -deleted, and their lines are deleted from the text of the Dired buffer. -The shortened Dired buffer remains selected. If you answer `no' or -quit with `C-g', you return immediately to Dired, with the deletion -flags still present and no files actually deleted. - - The `#', `~', and `.' commands flag many files for deletion, based -on their names. These commands are useful precisely because they do -not actually delete any files; you can remove the deletion flags from -any flagged files that you really wish to keep. - - `#' flags for deletion all files that appear to have been made by -auto-saving (that is, files whose names begin and end with `#'). `~' -flags for deletion all files that appear to have been made as backups -for files that were edited (that is, files whose names end with `~'). - - `.' (Period) flags just some of the backup files for deletion: only -numeric backups that are not among the oldest few nor the newest few -backups of any one file. Normally `dired-kept-versions' (not -`kept-new-versions'; that applies only when saving) specifies the -number of newest versions of each file to keep, and `kept-old-versions' -specifies the number of oldest versions to keep. Period with a -positive numeric argument, as in `C-u 3 .', specifies the number of -newest versions to keep, overriding `dired-kept-versions'. A negative -numeric argument overrides `kept-old-versions', using minus the value -of the argument to specify the number of oldest versions of each file -to keep. - - -File: xemacs.info, Node: Dired Immed, Prev: Dired Deletion, Up: Dired - -Immediate File Operations in Dired ----------------------------------- - - Some file operations in Dired take place immediately when they are -requested. - -`C' - Copies the file described on the current line. You must supply a - file name to copy to, using the minibuffer. - -`f' - Visits the file described on the current line. It is just like - typing `C-x C-f' and supplying that file name. If the file on - this line is a subdirectory, `f' actually causes Dired to be - invoked on that subdirectory. *Note Visiting::. - -`o' - Like `f', but uses another window to display the file's buffer. - The Dired buffer remains visible in the first window. This is - like using `C-x 4 C-f' to visit the file. *Note Windows::. - -`R' - Renames the file described on the current line. You must supply a - file name to rename to, using the minibuffer. - -`v' - Views the file described on this line using `M-x view-file'. - Viewing a file is like visiting it, but is slanted toward moving - around in the file conveniently and does not allow changing the - file. *Note View File: Misc File Ops. Viewing a file that is a - directory runs Dired on that directory. - - -File: xemacs.info, Node: Misc File Ops, Prev: Dired, Up: Files - -Miscellaneous File Operations -============================= - - Emacs has commands for performing many other operations on files. -All operate on one file; they do not accept wildcard file names. - - You can use the command `M-x add-name-to-file' to add a name to an -existing file without removing the old name. The new name must belong -on the file system that the file is on. - - `M-x append-to-file' adds the text of the region to the end of the -specified file. - - `M-x copy-file' reads the file OLD and writes a new file named NEW -with the same contents. Confirmation is required if a file named NEW -already exists, because copying overwrites the old contents of the file -NEW. - - `M-x delete-file' deletes a specified file, like the `rm' command in -the shell. If you are deleting many files in one directory, it may be -more convenient to use Dired (*note Dired::). - - `M-x insert-file' inserts a copy of the contents of a specified file -into the current buffer at point, leaving point unchanged before the -contents and the mark after them. *Note Mark::. - - `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and -then creates a symbolic link named LINKNAME and pointing at OLD. -Future attempts to open file LINKNAME will then refer to the file named -OLD at the time the opening is done, or will result in an error if the -name OLD is not in use at that time. Confirmation is required if you -create the link while LINKNAME is in use. Note that not all systems -support symbolic links. - - `M-x rename-file' reads two file names OLD and NEW using the -minibuffer, then renames file OLD as NEW. If a file named NEW already -exists, you must confirm with `yes' or renaming is not done; this is -because renaming causes the previous meaning of the name NEW to be -lost. If OLD and NEW are on different file systems, the file OLD is -copied and deleted. - - `M-x view-file' allows you to scan or read a file by sequential -screenfuls. It reads a file name argument using the minibuffer. After -reading the file into an Emacs buffer, `view-file' reads and displays -one windowful. You can then type to scroll forward one window, -or to scroll backward. Various other commands are provided for -moving around in the file, but none for changing it; type `C-h' while -viewing a file for a list of them. Most commands are the default Emacs -cursor motion commands. To exit from viewing, type `C-c'. - - -File: xemacs.info, Node: Buffers, Next: Windows, Prev: Files, Up: Top - -Using Multiple Buffers -********************** - - Text you are editing in Emacs resides in an object called a -"buffer". Each time you visit a file, Emacs creates a buffer to hold -the file's text. Each time you invoke Dired, Emacs creates a buffer to -hold the directory listing. If you send a message with `C-x m', a -buffer named `*mail*' is used to hold the text of the message. When -you ask for a command's documentation, it appears in a buffer called -`*Help*'. - - At any time, one and only one buffer is "selected". It is also -called the "current buffer". Saying a command operates on "the buffer" -really means that the command operates on the selected buffer, as most -commands do. - - When Emacs creates multiple windows, each window has a chosen buffer -which is displayed there, but at any time only one of the windows is -selected and its chosen buffer is the selected buffer. Each window's -mode line displays the name of the buffer the window is displaying -(*note Windows::). - - Each buffer has a name which can be of any length but is -case-sensitive. You can select a buffer using its name. Most buffers -are created when you visit files; their names are derived from the -files' names. You can also create an empty buffer with any name you -want. A newly started Emacs has a buffer named `*scratch*' which you -can use for evaluating Lisp expressions in Emacs. - - Each buffer records what file it is visiting, whether it is -modified, and what major mode and minor modes are in effect in it -(*note Major Modes::). Any Emacs variable can be made "local to" a -particular buffer, meaning its value in that buffer can be different -from the value in other buffers. *Note Locals::. - -* Menu: - -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onliness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. - - -File: xemacs.info, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers - -Creating and Selecting Buffers -============================== - -`C-x b BUFFER ' - Select or create a buffer named BUFFER (`switch-to-buffer'). - -`C-x 4 b BUFFER ' - Similar, but select a buffer named BUFFER in another window - (`switch-to-buffer-other-window'). - -`M-x switch-to-other-buffer N' - Switch to the previous buffer. - - To select a buffer named BUFNAME, type `C-x b BUFNAME '. This -is the command `switch-to-buffer' with argument BUFNAME. You can use -completion on an abbreviation for the buffer name you want (*note -Completion::). An empty argument to `C-x b' specifies the most -recently selected buffer that is not displayed in any window. - - Most buffers are created when you visit files, or use Emacs commands -that display text. You can also create a buffer explicitly by typing -`C-x b BUFNAME ', which creates a new, empty buffer that is not -visiting any file, and selects it for editing. The new buffer's major -mode is determined by the value of `default-major-mode' (*note Major -Modes::). Buffers not visiting files are usually used for making notes -to yourself. If you try to save one, you are asked for the file name -to use. - - The function `switch-to-buffer-other-frame' is similar to -`switch-to-buffer' except that it creates a new frame in which to -display the selected buffer. - - Use `M-x switch-to-other-buffer' to visit the previous buffer. If -you supply a positive integer N, the Nth most recent buffer is -displayed. If you supply an argument of 0, the current buffer is moved -to the bottom of the buffer stack. - - Note that you can also use `C-x C-f' and any other command for -visiting a file to switch buffers. *Note Visiting::. - - -File: xemacs.info, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers - -Listing Existing Buffers -======================== - -`C-x C-b' - List the existing buffers (`list-buffers'). - - To print a list of all existing buffers, type `C-x C-b'. Each line -in the list shows one buffer's name, major mode, and visited file. A -`*' at the beginning of a line indicates the buffer has been -"modified". If several buffers are modified, it may be time to save -some with `C-x s' (*note Saving::). A `%' indicates a read-only -buffer. A `.' marks the selected buffer. Here is an example of a -buffer list: - - MR Buffer Size Mode File - -- ------ ---- ---- ---- - .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex - *Help* 1287 Fundamental - files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el - % RMAIL 64042 RMAIL /u/rms/RMAIL - *% man 747 Dired /u2/emacs/man/ - net.emacs 343885 Fundamental /u/rms/net.emacs - fileio.c 27691 C /u2/emacs/src/fileio.c - NEWS 67340 Text /u2/emacs/etc/NEWS - *scratch* 0 Lisp Interaction - -Note that the buffer `*Help*' was made by a help request; it is not -visiting any file. The buffer `man' was made by Dired on the directory -`/u2/emacs/man/'. - - As you move the mouse over the `*Buffer List*' buffer, the lines are -highlighted. This visual cue indicates that clicking the right mouse -button (`button3') will pop up a menu of commands on the buffer -represented by this line. This menu duplicates most of those commands -which are bound to keys in the `*Buffer List*' buffer. - - -File: xemacs.info, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers - -Miscellaneous Buffer Operations -=============================== - -`C-x C-q' - Toggle read-only status of buffer (`toggle-read-only'). - -`M-x rename-buffer' - Change the name of the current buffer. - -`M-x view-buffer' - Scroll through a buffer. - - A buffer can be "read-only", which means that commands to change its -text are not allowed. Normally, read-only buffers are created by -subsystems such as Dired and Rmail that have special commands to operate -on the text. Emacs also creates a read-only buffer if you visit a file -that is protected. To make changes in a read-only buffer, use the -command `C-x C-q' (`toggle-read-only'). It makes a read-only buffer -writable, and makes a writable buffer read-only. This works by setting -the variable `buffer-read-only', which has a local value in each buffer -and makes a buffer read-only if its value is non-`nil'. - - `M-x rename-buffer' changes the name of the current buffer, -prompting for the new name in the minibuffer. There is no default. If -you specify a name that is used by a different buffer, an error is -signalled and renaming is not done. - - `M-x view-buffer' is similar to `M-x view-file' (*note Misc File -Ops::), but it examines an already existing Emacs buffer. View mode -provides convenient commands for scrolling through the buffer but not -for changing it. When you exit View mode, the resulting value of point -remains in effect. - - To copy text from one buffer to another, use the commands `M-x -append-to-buffer' and `M-x insert-buffer'. *Note Accumulating Text::. - - -File: xemacs.info, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers - -Killing Buffers -=============== - - After using Emacs for a while, you may accumulate a large number of -buffers and may want to eliminate the ones you no longer need. There -are several commands for doing this. - -`C-x k' - Kill a buffer, specified by name (`kill-buffer'). - -`M-x kill-some-buffers' - Offer to kill each buffer, one by one. - - `C-x k' (`kill-buffer') kills one buffer, whose name you specify in -the minibuffer. If you type just in the minibuffer, the default, -killing the current buffer, is used. If the current buffer is killed, -the buffer that has been selected recently but does not appear in any -window now is selected. If the buffer being killed contains unsaved -changes, you are asked to confirm with `yes' before the buffer is -killed. - - The command `M-x kill-some-buffers' asks about each buffer, one by -one. An answer of `y' means to kill the buffer. Killing the current -buffer or a buffer containing unsaved changes selects a new buffer or -asks for confirmation just like `kill-buffer'. - - -File: xemacs.info, Node: Several Buffers, Prev: Kill Buffer, Up: Buffers - -Operating on Several Buffers -============================ - - The "buffer-menu" facility is like a "Dired for buffers"; it allows -you to request operations on various Emacs buffers by editing a buffer -containing a list of them. You can save buffers, kill them (here -called "deleting" them, for consistency with Dired), or display them. - -`M-x buffer-menu' - Begin editing a buffer listing all Emacs buffers. - - The command `buffer-menu' writes a list of all Emacs buffers into -the buffer `*Buffer List*', and selects that buffer in Buffer Menu -mode. The buffer is read-only. You can only change it using the -special commands described in this section. Most of the commands are -graphic characters. You can use Emacs cursor motion commands in the -`*Buffer List*' buffer. If the cursor is on a line describing a -buffer, the following special commands apply to that buffer: - -`d' - Request to delete (kill) the buffer, then move down. A `D' before - the buffer name on a line indicates a deletion request. Requested - deletions actually take place when you use the `x' command. - -`k' - Synonym for `d'. - -`C-d' - Like `d' but move up afterwards instead of down. - -`s' - Request to save the buffer. An `S' before the buffer name on a - line indicates the request. Requested saves actually take place - when you use the `x' command. You can request both saving and - deletion for the same buffer. - -`~' - Mark buffer "unmodified". The command `~' does this immediately - when typed. - -`x' - Perform previously requested deletions and saves. - -`u' - Remove any request made for the current line, and move down. - -`' - Move to previous line and remove any request made for that line. - - All commands that add or remove flags to request later operations -also move down a line. They accept a numeric argument as a repeat -count, unless otherwise specified. - - There are also special commands to use the buffer list to select -another buffer, and to specify one or more other buffers for display in -additional windows. - -`1' - Select the buffer in a full-frame window. This command takes - effect immediately. - -`2' - Immediately set up two windows, with this buffer in one and the - buffer selected before `*Buffer List*' in the other. - -`f' - Immediately select the buffer in place of the `*Buffer List*' - buffer. - -`o' - Immediately select the buffer in another window as if by `C-x 4 b', - leaving `*Buffer List*' visible. - -`q' - Immediately select this buffer, and display any buffers previously - flagged with the `m' command in other windows. If there are no - buffers flagged with `m', this command is equivalent to `1'. - -`m' - Flag this buffer to be displayed in another window if the `q' - command is used. The request shows as a `>' at the beginning of - the line. The same buffer may not have both a delete request and a - display request. - - Going back between a `buffer-menu' buffer and other Emacs buffers is -easy. You can, for example, switch from the `*Buffer List*' buffer to -another Emacs buffer, and edit there. You can then reselect the -`buffer-menu' buffer and perform operations already requested, or you -can kill that buffer or pay no further attention to it. All that -`buffer-menu' does directly is create and select a suitable buffer, and -turn on Buffer Menu mode. All the other capabilities of the buffer -menu are implemented by special commands provided in Buffer Menu mode. - - The only difference between `buffer-menu' and `list-buffers' is that -`buffer-menu' selects the `*Buffer List*' buffer and `list-buffers' -does not. If you run `list-buffers' (that is, type `C-x C-b') and -select the buffer list manually, you can use all the commands described -here. - - -File: xemacs.info, Node: Windows, Next: Mule, Prev: Buffers, Up: Top - -Multiple Windows -**************** - - Emacs can split the frame into two or many windows, which can display -parts of different buffers or different parts of one buffer. If you are -running XEmacs under X, that means you can have the X window that -contains the Emacs frame have multiple subwindows. - -* Menu: - -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Change Window:: Deleting windows and changing their sizes. - - -File: xemacs.info, Node: Basic Window, Next: Split Window, Prev: Windows, Up: Windows - -Concepts of Emacs Windows -========================= - - When Emacs displays multiple windows, each window has one Emacs -buffer designated for display. The same buffer may appear in more than -one window; if it does, any changes in its text are displayed in all -the windows that display it. Windows showing the same buffer can show -different parts of it, because each window has its own value of point. - - At any time, one window is the "selected window"; the buffer -displayed by that window is the current buffer. The cursor shows the -location of point in that window. Each other window has a location of -point as well, but since the terminal has only one cursor, it cannot -show the location of point in the other windows. - - Commands to move point affect the value of point for the selected -Emacs window only. They do not change the value of point in any other -Emacs window, including those showing the same buffer. The same is -true for commands such as `C-x b' to change the selected buffer in the -selected window; they do not affect other windows at all. However, -there are other commands such as `C-x 4 b' that select a different -window and switch buffers in it. Also, all commands that display -information in a window, including (for example) `C-h f' -(`describe-function') and `C-x C-b' (`list-buffers'), work by switching -buffers in a non-selected window without affecting the selected window. - - Each window has its own mode line, which displays the buffer name, -modification status, and major and minor modes of the buffer that is -displayed in the window. *Note Mode Line::, for details on the mode -line. - - -File: xemacs.info, Node: Split Window, Next: Other Window, Prev: Basic Window, Up: Windows - -Splitting Windows -================= - -`C-x 2' - Split the selected window into two windows, one above the other - (`split-window-vertically'). - -`C-x 3' - Split the selected window into two windows positioned side by side - (`split-window-horizontally'). - -`C-x 6' - Save the current window configuration in register REG (a letter). - -`C-x 7' - Restore (make current) the window configuration in register REG (a - letter). Use with a register previously set with `C-x 6'. - - The command `C-x 2' (`split-window-vertically') breaks the selected -window into two windows, one above the other. Both windows start out -displaying the same buffer, with the same value of point. By default -each of the two windows gets half the height of the window that was -split. A numeric argument specifies how many lines to give to the top -window. - - `C-x 3' (`split-window-horizontally') breaks the selected window -into two side-by-side windows. A numeric argument specifies how many -columns to give the one on the left. A line of vertical bars separates -the two windows. Windows that are not the full width of the frame have -truncated mode lines which do not always appear in inverse video, -because Emacs display routines cannot display a region of inverse video -that is only part of a line on the screen. - - When a window is less than the full width, many text lines are too -long to fit. Continuing all those lines might be confusing. Set the -variable `truncate-partial-width-windows' to non-`nil' to force -truncation in all windows less than the full width of the frame, -independent of the buffer and its value for `truncate-lines'. *Note -Continuation Lines::. - - Horizontal scrolling is often used in side-by-side windows. *Note -Display::. - - You can resize a window and store that configuration in a register by -supplying a REGISTER argument to `window-configuration-to-register' -(`C-x 6'). To return to the window configuration established with -`window-configuration-to-register', use `jump-to-register' (`C-x j'). - diff --git a/info/xemacs.info-9 b/info/xemacs.info-9 index fd04303..0d949e6 100644 --- a/info/xemacs.info-9 +++ b/info/xemacs.info-9 @@ -30,6 +30,573 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  +File: xemacs.info, Node: Dired Deletion, Next: Dired Immed, Prev: Dired Edit, Up: Dired + +Deleting Files With Dired +------------------------- + + The primary use of Dired is to flag files for deletion and then +delete them. + +`d' + Flag this file for deletion. + +`u' + Remove deletion-flag on this line. + +`' + Remove deletion-flag on previous line, moving point to that line. + +`x' + Delete the files that are flagged for deletion. + +`#' + Flag all auto-save files (files whose names start and end with `#') + for deletion (*note Auto Save::). + +`~' + Flag all backup files (files whose names end with `~') for deletion + (*note Backup::). + +`. (Period)' + Flag excess numeric backup files for deletion. The oldest and + newest few backup files of any one file are exempt; the middle + ones are flagged. + + You can flag a file for deletion by moving to the line describing the +file and typing `d' or `C-d'. The deletion flag is visible as a `D' at +the beginning of the line. Point is moved to the beginning of the next +line, so that repeated `d' commands flag successive files. + + The files are flagged for deletion rather than deleted immediately to +avoid the danger of deleting a file accidentally. Until you direct +Dired to delete the flagged files, you can remove deletion flags using +the commands `u' and . `u' works just like `d', but removes flags +rather than making flags. moves upward, removing flags; it is +like `u' with numeric argument automatically negated. + + To delete the flagged files, type `x'. This command first displays a +list of all the file names flagged for deletion, and requests +confirmation with `yes'. Once you confirm, all the flagged files are +deleted, and their lines are deleted from the text of the Dired buffer. +The shortened Dired buffer remains selected. If you answer `no' or +quit with `C-g', you return immediately to Dired, with the deletion +flags still present and no files actually deleted. + + The `#', `~', and `.' commands flag many files for deletion, based +on their names. These commands are useful precisely because they do +not actually delete any files; you can remove the deletion flags from +any flagged files that you really wish to keep. + + `#' flags for deletion all files that appear to have been made by +auto-saving (that is, files whose names begin and end with `#'). `~' +flags for deletion all files that appear to have been made as backups +for files that were edited (that is, files whose names end with `~'). + + `.' (Period) flags just some of the backup files for deletion: only +numeric backups that are not among the oldest few nor the newest few +backups of any one file. Normally `dired-kept-versions' (not +`kept-new-versions'; that applies only when saving) specifies the +number of newest versions of each file to keep, and `kept-old-versions' +specifies the number of oldest versions to keep. Period with a +positive numeric argument, as in `C-u 3 .', specifies the number of +newest versions to keep, overriding `dired-kept-versions'. A negative +numeric argument overrides `kept-old-versions', using minus the value +of the argument to specify the number of oldest versions of each file +to keep. + + +File: xemacs.info, Node: Dired Immed, Prev: Dired Deletion, Up: Dired + +Immediate File Operations in Dired +---------------------------------- + + Some file operations in Dired take place immediately when they are +requested. + +`C' + Copies the file described on the current line. You must supply a + file name to copy to, using the minibuffer. + +`f' + Visits the file described on the current line. It is just like + typing `C-x C-f' and supplying that file name. If the file on + this line is a subdirectory, `f' actually causes Dired to be + invoked on that subdirectory. *Note Visiting::. + +`o' + Like `f', but uses another window to display the file's buffer. + The Dired buffer remains visible in the first window. This is + like using `C-x 4 C-f' to visit the file. *Note Windows::. + +`R' + Renames the file described on the current line. You must supply a + file name to rename to, using the minibuffer. + +`v' + Views the file described on this line using `M-x view-file'. + Viewing a file is like visiting it, but is slanted toward moving + around in the file conveniently and does not allow changing the + file. *Note View File: Misc File Ops. Viewing a file that is a + directory runs Dired on that directory. + + +File: xemacs.info, Node: Misc File Ops, Prev: Dired, Up: Files + +Miscellaneous File Operations +============================= + + Emacs has commands for performing many other operations on files. +All operate on one file; they do not accept wildcard file names. + + You can use the command `M-x add-name-to-file' to add a name to an +existing file without removing the old name. The new name must belong +on the file system that the file is on. + + `M-x append-to-file' adds the text of the region to the end of the +specified file. + + `M-x copy-file' reads the file OLD and writes a new file named NEW +with the same contents. Confirmation is required if a file named NEW +already exists, because copying overwrites the old contents of the file +NEW. + + `M-x delete-file' deletes a specified file, like the `rm' command in +the shell. If you are deleting many files in one directory, it may be +more convenient to use Dired (*note Dired::). + + `M-x insert-file' inserts a copy of the contents of a specified file +into the current buffer at point, leaving point unchanged before the +contents and the mark after them. *Note Mark::. + + `M-x make-symbolic-link' reads two file names OLD and LINKNAME, and +then creates a symbolic link named LINKNAME and pointing at OLD. +Future attempts to open file LINKNAME will then refer to the file named +OLD at the time the opening is done, or will result in an error if the +name OLD is not in use at that time. Confirmation is required if you +create the link while LINKNAME is in use. Note that not all systems +support symbolic links. + + `M-x rename-file' reads two file names OLD and NEW using the +minibuffer, then renames file OLD as NEW. If a file named NEW already +exists, you must confirm with `yes' or renaming is not done; this is +because renaming causes the previous meaning of the name NEW to be +lost. If OLD and NEW are on different file systems, the file OLD is +copied and deleted. + + `M-x view-file' allows you to scan or read a file by sequential +screenfuls. It reads a file name argument using the minibuffer. After +reading the file into an Emacs buffer, `view-file' reads and displays +one windowful. You can then type to scroll forward one window, +or to scroll backward. Various other commands are provided for +moving around in the file, but none for changing it; type `C-h' while +viewing a file for a list of them. Most commands are the default Emacs +cursor motion commands. To exit from viewing, type `C-c'. + + +File: xemacs.info, Node: Buffers, Next: Windows, Prev: Files, Up: Top + +Using Multiple Buffers +********************** + + Text you are editing in Emacs resides in an object called a +"buffer". Each time you visit a file, Emacs creates a buffer to hold +the file's text. Each time you invoke Dired, Emacs creates a buffer to +hold the directory listing. If you send a message with `C-x m', a +buffer named `*mail*' is used to hold the text of the message. When +you ask for a command's documentation, it appears in a buffer called +`*Help*'. + + At any time, one and only one buffer is "selected". It is also +called the "current buffer". Saying a command operates on "the buffer" +really means that the command operates on the selected buffer, as most +commands do. + + When Emacs creates multiple windows, each window has a chosen buffer +which is displayed there, but at any time only one of the windows is +selected and its chosen buffer is the selected buffer. Each window's +mode line displays the name of the buffer the window is displaying +(*note Windows::). + + Each buffer has a name which can be of any length but is +case-sensitive. You can select a buffer using its name. Most buffers +are created when you visit files; their names are derived from the +files' names. You can also create an empty buffer with any name you +want. A newly started Emacs has a buffer named `*scratch*' which you +can use for evaluating Lisp expressions in Emacs. + + Each buffer records what file it is visiting, whether it is +modified, and what major mode and minor modes are in effect in it +(*note Major Modes::). Any Emacs variable can be made "local to" a +particular buffer, meaning its value in that buffer can be different +from the value in other buffers. *Note Locals::. + +* Menu: + +* Select Buffer:: Creating a new buffer or reselecting an old one. +* List Buffers:: Getting a list of buffers that exist. +* Misc Buffer:: Renaming; changing read-onliness; copying text. +* Kill Buffer:: Killing buffers you no longer need. +* Several Buffers:: How to go through the list of all buffers + and operate variously on several of them. + + +File: xemacs.info, Node: Select Buffer, Next: List Buffers, Prev: Buffers, Up: Buffers + +Creating and Selecting Buffers +============================== + +`C-x b BUFFER ' + Select or create a buffer named BUFFER (`switch-to-buffer'). + +`C-x 4 b BUFFER ' + Similar, but select a buffer named BUFFER in another window + (`switch-to-buffer-other-window'). + +`M-x switch-to-other-buffer N' + Switch to the previous buffer. + + To select a buffer named BUFNAME, type `C-x b BUFNAME '. This +is the command `switch-to-buffer' with argument BUFNAME. You can use +completion on an abbreviation for the buffer name you want (*note +Completion::). An empty argument to `C-x b' specifies the most +recently selected buffer that is not displayed in any window. + + Most buffers are created when you visit files, or use Emacs commands +that display text. You can also create a buffer explicitly by typing +`C-x b BUFNAME ', which creates a new, empty buffer that is not +visiting any file, and selects it for editing. The new buffer's major +mode is determined by the value of `default-major-mode' (*note Major +Modes::). Buffers not visiting files are usually used for making notes +to yourself. If you try to save one, you are asked for the file name +to use. + + The function `switch-to-buffer-other-frame' is similar to +`switch-to-buffer' except that it creates a new frame in which to +display the selected buffer. + + Use `M-x switch-to-other-buffer' to visit the previous buffer. If +you supply a positive integer N, the Nth most recent buffer is +displayed. If you supply an argument of 0, the current buffer is moved +to the bottom of the buffer stack. + + Note that you can also use `C-x C-f' and any other command for +visiting a file to switch buffers. *Note Visiting::. + + +File: xemacs.info, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers + +Listing Existing Buffers +======================== + +`C-x C-b' + List the existing buffers (`list-buffers'). + + To print a list of all existing buffers, type `C-x C-b'. Each line +in the list shows one buffer's name, major mode, and visited file. A +`*' at the beginning of a line indicates the buffer has been +"modified". If several buffers are modified, it may be time to save +some with `C-x s' (*note Saving::). A `%' indicates a read-only +buffer. A `.' marks the selected buffer. Here is an example of a +buffer list: + + MR Buffer Size Mode File + -- ------ ---- ---- ---- + .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex + *Help* 1287 Fundamental + files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el + % RMAIL 64042 RMAIL /u/rms/RMAIL + *% man 747 Dired /u2/emacs/man/ + net.emacs 343885 Fundamental /u/rms/net.emacs + fileio.c 27691 C /u2/emacs/src/fileio.c + NEWS 67340 Text /u2/emacs/etc/NEWS + *scratch* 0 Lisp Interaction + +Note that the buffer `*Help*' was made by a help request; it is not +visiting any file. The buffer `man' was made by Dired on the directory +`/u2/emacs/man/'. + + As you move the mouse over the `*Buffer List*' buffer, the lines are +highlighted. This visual cue indicates that clicking the right mouse +button (`button3') will pop up a menu of commands on the buffer +represented by this line. This menu duplicates most of those commands +which are bound to keys in the `*Buffer List*' buffer. + + +File: xemacs.info, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers + +Miscellaneous Buffer Operations +=============================== + +`C-x C-q' + Toggle read-only status of buffer (`toggle-read-only'). + +`M-x rename-buffer' + Change the name of the current buffer. + +`M-x view-buffer' + Scroll through a buffer. + + A buffer can be "read-only", which means that commands to change its +text are not allowed. Normally, read-only buffers are created by +subsystems such as Dired and Rmail that have special commands to operate +on the text. Emacs also creates a read-only buffer if you visit a file +that is protected. To make changes in a read-only buffer, use the +command `C-x C-q' (`toggle-read-only'). It makes a read-only buffer +writable, and makes a writable buffer read-only. This works by setting +the variable `buffer-read-only', which has a local value in each buffer +and makes a buffer read-only if its value is non-`nil'. + + `M-x rename-buffer' changes the name of the current buffer, +prompting for the new name in the minibuffer. There is no default. If +you specify a name that is used by a different buffer, an error is +signalled and renaming is not done. + + `M-x view-buffer' is similar to `M-x view-file' (*note Misc File +Ops::), but it examines an already existing Emacs buffer. View mode +provides convenient commands for scrolling through the buffer but not +for changing it. When you exit View mode, the resulting value of point +remains in effect. + + To copy text from one buffer to another, use the commands `M-x +append-to-buffer' and `M-x insert-buffer'. *Note Accumulating Text::. + + +File: xemacs.info, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers + +Killing Buffers +=============== + + After using Emacs for a while, you may accumulate a large number of +buffers and may want to eliminate the ones you no longer need. There +are several commands for doing this. + +`C-x k' + Kill a buffer, specified by name (`kill-buffer'). + +`M-x kill-some-buffers' + Offer to kill each buffer, one by one. + + `C-x k' (`kill-buffer') kills one buffer, whose name you specify in +the minibuffer. If you type just in the minibuffer, the default, +killing the current buffer, is used. If the current buffer is killed, +the buffer that has been selected recently but does not appear in any +window now is selected. If the buffer being killed contains unsaved +changes, you are asked to confirm with `yes' before the buffer is +killed. + + The command `M-x kill-some-buffers' asks about each buffer, one by +one. An answer of `y' means to kill the buffer. Killing the current +buffer or a buffer containing unsaved changes selects a new buffer or +asks for confirmation just like `kill-buffer'. + + +File: xemacs.info, Node: Several Buffers, Prev: Kill Buffer, Up: Buffers + +Operating on Several Buffers +============================ + + The "buffer-menu" facility is like a "Dired for buffers"; it allows +you to request operations on various Emacs buffers by editing a buffer +containing a list of them. You can save buffers, kill them (here +called "deleting" them, for consistency with Dired), or display them. + +`M-x buffer-menu' + Begin editing a buffer listing all Emacs buffers. + + The command `buffer-menu' writes a list of all Emacs buffers into +the buffer `*Buffer List*', and selects that buffer in Buffer Menu +mode. The buffer is read-only. You can only change it using the +special commands described in this section. Most of the commands are +graphic characters. You can use Emacs cursor motion commands in the +`*Buffer List*' buffer. If the cursor is on a line describing a +buffer, the following special commands apply to that buffer: + +`d' + Request to delete (kill) the buffer, then move down. A `D' before + the buffer name on a line indicates a deletion request. Requested + deletions actually take place when you use the `x' command. + +`k' + Synonym for `d'. + +`C-d' + Like `d' but move up afterwards instead of down. + +`s' + Request to save the buffer. An `S' before the buffer name on a + line indicates the request. Requested saves actually take place + when you use the `x' command. You can request both saving and + deletion for the same buffer. + +`~' + Mark buffer "unmodified". The command `~' does this immediately + when typed. + +`x' + Perform previously requested deletions and saves. + +`u' + Remove any request made for the current line, and move down. + +`' + Move to previous line and remove any request made for that line. + + All commands that add or remove flags to request later operations +also move down a line. They accept a numeric argument as a repeat +count, unless otherwise specified. + + There are also special commands to use the buffer list to select +another buffer, and to specify one or more other buffers for display in +additional windows. + +`1' + Select the buffer in a full-frame window. This command takes + effect immediately. + +`2' + Immediately set up two windows, with this buffer in one and the + buffer selected before `*Buffer List*' in the other. + +`f' + Immediately select the buffer in place of the `*Buffer List*' + buffer. + +`o' + Immediately select the buffer in another window as if by `C-x 4 b', + leaving `*Buffer List*' visible. + +`q' + Immediately select this buffer, and display any buffers previously + flagged with the `m' command in other windows. If there are no + buffers flagged with `m', this command is equivalent to `1'. + +`m' + Flag this buffer to be displayed in another window if the `q' + command is used. The request shows as a `>' at the beginning of + the line. The same buffer may not have both a delete request and a + display request. + + Going back between a `buffer-menu' buffer and other Emacs buffers is +easy. You can, for example, switch from the `*Buffer List*' buffer to +another Emacs buffer, and edit there. You can then reselect the +`buffer-menu' buffer and perform operations already requested, or you +can kill that buffer or pay no further attention to it. All that +`buffer-menu' does directly is create and select a suitable buffer, and +turn on Buffer Menu mode. All the other capabilities of the buffer +menu are implemented by special commands provided in Buffer Menu mode. + + The only difference between `buffer-menu' and `list-buffers' is that +`buffer-menu' selects the `*Buffer List*' buffer and `list-buffers' +does not. If you run `list-buffers' (that is, type `C-x C-b') and +select the buffer list manually, you can use all the commands described +here. + + +File: xemacs.info, Node: Windows, Next: Mule, Prev: Buffers, Up: Top + +Multiple Windows +**************** + + Emacs can split the frame into two or many windows, which can display +parts of different buffers or different parts of one buffer. If you are +running XEmacs under X, that means you can have the X window that +contains the Emacs frame have multiple subwindows. + +* Menu: + +* Basic Window:: Introduction to Emacs windows. +* Split Window:: New windows are made by splitting existing windows. +* Other Window:: Moving to another window or doing something to it. +* Pop Up Window:: Finding a file or buffer in another window. +* Change Window:: Deleting windows and changing their sizes. + + +File: xemacs.info, Node: Basic Window, Next: Split Window, Prev: Windows, Up: Windows + +Concepts of Emacs Windows +========================= + + When Emacs displays multiple windows, each window has one Emacs +buffer designated for display. The same buffer may appear in more than +one window; if it does, any changes in its text are displayed in all +the windows that display it. Windows showing the same buffer can show +different parts of it, because each window has its own value of point. + + At any time, one window is the "selected window"; the buffer +displayed by that window is the current buffer. The cursor shows the +location of point in that window. Each other window has a location of +point as well, but since the terminal has only one cursor, it cannot +show the location of point in the other windows. + + Commands to move point affect the value of point for the selected +Emacs window only. They do not change the value of point in any other +Emacs window, including those showing the same buffer. The same is +true for commands such as `C-x b' to change the selected buffer in the +selected window; they do not affect other windows at all. However, +there are other commands such as `C-x 4 b' that select a different +window and switch buffers in it. Also, all commands that display +information in a window, including (for example) `C-h f' +(`describe-function') and `C-x C-b' (`list-buffers'), work by switching +buffers in a non-selected window without affecting the selected window. + + Each window has its own mode line, which displays the buffer name, +modification status, and major and minor modes of the buffer that is +displayed in the window. *Note Mode Line::, for details on the mode +line. + + +File: xemacs.info, Node: Split Window, Next: Other Window, Prev: Basic Window, Up: Windows + +Splitting Windows +================= + +`C-x 2' + Split the selected window into two windows, one above the other + (`split-window-vertically'). + +`C-x 3' + Split the selected window into two windows positioned side by side + (`split-window-horizontally'). + +`C-x 6' + Save the current window configuration in register REG (a letter). + +`C-x 7' + Restore (make current) the window configuration in register REG (a + letter). Use with a register previously set with `C-x 6'. + + The command `C-x 2' (`split-window-vertically') breaks the selected +window into two windows, one above the other. Both windows start out +displaying the same buffer, with the same value of point. By default +each of the two windows gets half the height of the window that was +split. A numeric argument specifies how many lines to give to the top +window. + + `C-x 3' (`split-window-horizontally') breaks the selected window +into two side-by-side windows. A numeric argument specifies how many +columns to give the one on the left. A line of vertical bars separates +the two windows. Windows that are not the full width of the frame have +truncated mode lines which do not always appear in inverse video, +because Emacs display routines cannot display a region of inverse video +that is only part of a line on the screen. + + When a window is less than the full width, many text lines are too +long to fit. Continuing all those lines might be confusing. Set the +variable `truncate-partial-width-windows' to non-`nil' to force +truncation in all windows less than the full width of the frame, +independent of the buffer and its value for `truncate-lines'. *Note +Continuation Lines::. + + Horizontal scrolling is often used in side-by-side windows. *Note +Display::. + + You can resize a window and store that configuration in a register by +supplying a REGISTER argument to `window-configuration-to-register' +(`C-x 6'). To return to the window configuration established with +`window-configuration-to-register', use `jump-to-register' (`C-x j'). + + File: xemacs.info, Node: Other Window, Next: Pop Up Window, Prev: Split Window, Up: Windows Using Other Windows @@ -575,576 +1142,3 @@ you want to write files from this buffer using a different coding system, you can specify a different coding system for the buffer using `set-buffer-file-coding-system' (*note Specify Coding::). - -File: xemacs.info, Node: Specify Coding, Prev: Recognize Coding, Up: Mule - -Specifying a Coding System -========================== - - In cases where XEmacs does not automatically choose the right coding -system, you can use these commands to specify one: - -`C-x f CODING ' - Use coding system CODING for the visited file in the current - buffer. - -`C-x c CODING ' - Specify coding system CODING for the immediately following command. - -`C-x k CODING ' - Use coding system CODING for keyboard input. - -`C-x t CODING ' - Use coding system CODING for terminal output. - -`C-x p CODING ' - Use coding system CODING for subprocess input and output in the - current buffer. - - The command `C-x RET f' (`set-buffer-file-coding-system') specifies -the file coding system for the current buffer--in other words, which -coding system to use when saving or rereading the visited file. You -specify which coding system using the minibuffer. Since this command -applies to a file you have already visited, it affects only the way the -file is saved. - - Another way to specify the coding system for a file is when you visit -the file. First use the command `C-x c' -(`universal-coding-system-argument'); this command uses the minibuffer -to read a coding system name. After you exit the minibuffer, the -specified coding system is used for _the immediately following command_. - - So if the immediately following command is `C-x C-f', for example, -it reads the file using that coding system (and records the coding -system for when the file is saved). Or if the immediately following -command is `C-x C-w', it writes the file using that coding system. -Other file commands affected by a specified coding system include `C-x -C-i' and `C-x C-v', as well as the other-window variants of `C-x C-f'. - - In addition, if you run some file input commands with the precedent -`C-u', you can specify coding system to read from minibuffer. So if -the immediately following command is `C-x C-f', for example, it reads -the file using that coding system (and records the coding system for -when the file is saved). Other file commands affected by a specified -coding system include `C-x C-i' and `C-x C-v', as well as the -other-window variants of `C-x C-f'. - - The variable `default-buffer-file-coding-system' specifies the -choice of coding system to use when you create a new file. It applies -when you find a new file, and when you create a buffer and then save it -in a file. Selecting a language environment typically sets this -variable to a good choice of default coding system for that language -environment. - - The command `C-x t' (`set-terminal-coding-system') specifies -the coding system for terminal output. If you specify a character code -for terminal output, all characters output to the terminal are -translated into that coding system. - - This feature is useful for certain character-only terminals built to -support specific languages or character sets--for example, European -terminals that support one of the ISO Latin character sets. - - By default, output to the terminal is not translated at all. - - The command `C-x k' (`set-keyboard-coding-system') specifies -the coding system for keyboard input. Character-code translation of -keyboard input is useful for terminals with keys that send non-ASCII -graphic characters--for example, some terminals designed for ISO -Latin-1 or subsets of it. - - By default, keyboard input is not translated at all. - - There is a similarity between using a coding system translation for -keyboard input, and using an input method: both define sequences of -keyboard input that translate into single characters. However, input -methods are designed to be convenient for interactive use by humans, and -the sequences that are translated are typically sequences of ASCII -printing characters. Coding systems typically translate sequences of -non-graphic characters. - - The command `C-x p' (`set-buffer-process-coding-system') -specifies the coding system for input and output to a subprocess. This -command applies to the current buffer; normally, each subprocess has its -own buffer, and thus you can use this command to specify translation to -and from a particular subprocess by giving the command in the -corresponding buffer. - - By default, process input and output are not translated at all. - - The variable `file-name-coding-system' specifies a coding system to -use for encoding file names. If you set the variable to a coding -system name (as a Lisp symbol or a string), XEmacs encodes file names -using that coding system for all file operations. This makes it -possible to use non-Latin-1 characters in file names--or, at least, -those non-Latin-1 characters which the specified coding system can -encode. By default, this variable is `nil', which implies that you -cannot use non-Latin-1 characters in file names. - - -File: xemacs.info, Node: Major Modes, Next: Indentation, Prev: Mule, Up: Top - -Major Modes -*********** - - Emacs has many different "major modes", each of which customizes -Emacs for editing text of a particular sort. The major modes are -mutually exclusive; at any time, each buffer has one major mode. The -mode line normally contains the name of the current major mode in -parentheses. *Note Mode Line::. - - The least specialized major mode is called "Fundamental mode". This -mode has no mode-specific redefinitions or variable settings. Each -Emacs command behaves in its most general manner, and each option is in -its default state. For editing any specific type of text, such as Lisp -code or English text, you should switch to the appropriate major mode, -such as Lisp mode or Text mode. - - Selecting a major mode changes the meanings of a few keys to become -more specifically adapted to the language being edited. , , -and are changed frequently. In addition, commands which handle -comments use the mode to determine how to delimit comments. Many major -modes redefine the syntactical properties of characters appearing in -the buffer. *Note Syntax::. - - The major modes fall into three major groups. Lisp mode (which has -several variants), C mode, and Muddle mode are for specific programming -languages. Text mode, Nroff mode, TeX mode, and Outline mode are for -editing English text. The remaining major modes are not intended for -use on users' files; they are used in buffers created by Emacs for -specific purposes and include Dired mode for buffers made by Dired -(*note Dired::), Mail mode for buffers made by `C-x m' (*note Sending -Mail::), and Shell mode for buffers used for communicating with an -inferior shell process (*note Interactive Shell::). - - Most programming language major modes specify that only blank lines -separate paragraphs. This is so that the paragraph commands remain -useful. *Note Paragraphs::. They also cause Auto Fill mode to use the -definition of to indent the new lines it creates. This is -because most lines in a program are usually indented. *Note -Indentation::. - -* Menu: - -* Choosing Modes:: How major modes are specified or chosen. - - -File: xemacs.info, Node: Choosing Modes, Prev: Major Modes, Up: Major Modes - -Choosing Major Modes -==================== - - You can select a major mode explicitly for the current buffer, but -most of the time Emacs determines which mode to use based on the file -name or some text in the file. - - Use a `M-x' command to explicitly select a new major mode. Add -`-mode' to the name of a major mode to get the name of a command to -select that mode. For example, to enter Lisp mode, execute `M-x -lisp-mode'. - - When you visit a file, Emacs usually chooses the right major mode -based on the file's name. For example, files whose names end in `.c' -are edited in C mode. The variable `auto-mode-alist' controls the -correspondence between file names and major mode. Its value is a list -in which each element has the form: - - (REGEXP . MODE-FUNCTION) - -For example, one element normally found in the list has the form -`("\\.c$" . c-mode)'. It is responsible for selecting C mode for files -whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to -include a `\' in the string, which is needed to suppress the special -meaning of `.' in regexps.) The only practical way to change this -variable is with Lisp code. - - You can specify which major mode should be used for editing a certain -file by a special sort of text in the first non-blank line of the file. -The mode name should appear in this line both preceded and followed by -`-*-'. Other text may appear on the line as well. For example, - - ;-*-Lisp-*- - -tells Emacs to use Lisp mode. Note how the semicolon is used to make -Lisp treat this line as a comment. Such an explicit specification -overrides any default mode based on the file name. - - Another format of mode specification is: - - -*-Mode: MODENAME;-*- - -which allows other things besides the major mode name to be specified. -However, Emacs does not look for anything except the mode name. - - The major mode can also be specified in a local variables list. -*Note File Variables::. - - When you visit a file that does not specify a major mode to use, or -when you create a new buffer with `C-x b', Emacs uses the major mode -specified by the variable `default-major-mode'. Normally this value is -the symbol `fundamental-mode', which specifies Fundamental mode. If -`default-major-mode' is `nil', the major mode is taken from the -previously selected buffer. - - -File: xemacs.info, Node: Indentation, Next: Text, Prev: Major Modes, Up: Top - -Indentation -*********** - -`' - Indent current line "appropriately" in a mode-dependent fashion. - -`' - Perform followed by (`newline-and-indent'). - -`M-^' - Merge two lines (`delete-indentation'). This would cancel out the - effect of . - -`C-M-o' - Split line at point; text on the line after point becomes a new - line indented to the same column that it now starts in - (`split-line'). - -`M-m' - Move (forward or back) to the first non-blank character on the - current line (`back-to-indentation'). - -`C-M-\' - Indent several lines to same column (`indent-region'). - -`C-x ' - Shift block of lines rigidly right or left (`indent-rigidly'). - -`M-i' - Indent from point to the next prespecified tab stop column - (`tab-to-tab-stop'). - -`M-x indent-relative' - Indent from point to under an indentation point in the previous - line. - - Most programming languages have some indentation convention. For -Lisp code, lines are indented according to their nesting in -parentheses. The same general idea is used for C code, though details -differ. - - Use the command to indent a line whatever the language. Each -major mode defines this command to perform indentation appropriate for -the particular language. In Lisp mode, aligns a line according -to its depth in parentheses. No matter where in the line you are when -you type , it aligns the line as a whole. In C mode, -implements a subtle and sophisticated indentation style that knows -about many aspects of C syntax. - - In Text mode, runs the command `tab-to-tab-stop', which -indents to the next tab stop column. You can set the tab stops with -`M-x edit-tab-stops'. - -* 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. - - -File: xemacs.info, Node: Indentation Commands, Next: Tab Stops, Prev: Indentation, Up: Indentation - -Indentation Commands and Techniques -=================================== - - If you just want to insert a tab character in the buffer, you can -type `C-q '. - - To move over the indentation on a line, type `Meta-m' -(`back-to-indentation'). This command, given anywhere on a line, -positions point at the first non-blank character on the line. - - To insert an indented line before the current line, type `C-a C-o -'. To make an indented line after the current line, use `C-e -'. - - `C-M-o' (`split-line') moves the text from point to the end of the -line vertically down, so that the current line becomes two lines. -`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, `C-M-o' resembles `C-o'. - - To join two lines cleanly, use the `Meta-^' (`delete-indentation') -command to delete the indentation at the front of the current line, and -the line boundary as well. Empty spaces are replaced by a single -space, or by no space if at the beginning of a line, before a close -parenthesis, or after an open parenthesis. To delete just the -indentation of a line, go to the beginning of the line and use `Meta-\' -(`delete-horizontal-space'), which deletes all spaces and tabs around -the cursor. - - There are also commands for changing the indentation of several -lines at once. `Control-Meta-\' (`indent-region') gives each line which -begins in the region the "usual" indentation by invoking at the -beginning of the line. A numeric argument specifies the column to -indent to. Each line is shifted left or right so that its first -non-blank character appears in that column. `C-x ' -(`indent-rigidly') moves all 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. - - `M-x indent-relative' indents at point based on the previous line -(actually, the last non-empty line.) It inserts whitespace at point, -moving point, until it is underneath an 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, the whitespace before point is -deleted and the first indentation point then applicable is used. If no -indentation point is applicable even then, `tab-to-tab-stop' is run -(see next section). - - `indent-relative' is the definition of in Indented Text mode. -*Note Text::. - - -File: xemacs.info, Node: Tab Stops, Next: Just Spaces, Prev: Indentation Commands, Up: Indentation - -Tab Stops -========= - - For typing in tables, you can use Text mode's definition of , -`tab-to-tab-stop'. This command inserts indentation before point, -enough to reach the next tab stop column. Even if you are not in Text -mode, this function is associated with `M-i' anyway. - - You can arbitrarily set the tab stops used by `M-i'. They are -stored as a list of column-numbers in increasing order in the variable -`tab-stop-list'. - - The convenient way to set the tab stops is using `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 `C-c C-c' to make those new -tab stops take effect. In the tab stop buffer, `C-c C-c' runs the -function `edit-tab-stops-note-changes' rather than the default -`save-buffer'. `edit-tab-stops' records which buffer was current when -you invoked it, and stores the tab stops in that buffer. Normally all -buffers share the same tab stops and changing them in one buffer -affects all. If you make `tab-stop-list' local in one buffer -`edit-tab-stops' in that buffer edits only the local settings. - - Below is the text representing ordinary tab stops every eight -columns: - - : : : : : : - 0 1 2 3 4 - 0123456789012345678901234567890123456789012345678 - To install changes, type C-c C-c - - The first line contains a colon at each tab stop. The remaining -lines help you see where the colons are and tell you what to do. - - Note that the tab stops that control `tab-to-tab-stop' have nothing -to do with displaying tab characters in the buffer. *Note Display -Vars::, for more information on that. - - -File: xemacs.info, Node: Just Spaces, Prev: Tab Stops, Up: Indentation - -Tabs vs. Spaces -=============== - - 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 `indent-tabs-mode' to `nil'. This is a per-buffer variable; -altering the variable affects only the current buffer, but there is a -default value which you can change as well. *Note Locals::. - - There are also commands to convert tabs to spaces or vice versa, -always preserving the columns of all non-blank text. `M-x tabify' -scans the region for sequences of spaces, and converts sequences of at -least three spaces to tabs if that is possible without changing -indentation. `M-x untabify' changes all tabs in the region to -corresponding numbers of spaces. - - -File: xemacs.info, Node: Text, Next: Programs, Prev: Indentation, Up: Top - -Commands for Human Languages -**************************** - - The term "text" has two widespread meanings in our area of the -computer field. One is data that is a sequence of characters. In this -sense of the word any file that you edit with Emacs is text. The other -meaning is more restrictive: a sequence of characters in a human -language for humans to read (possibly after processing by a text -formatter), as opposed to a program or commands for a program. - - Human languages have syntactic and stylistic conventions that editor -commands should support or use to advantage: conventions involving -words, sentences, paragraphs, and capital letters. This chapter -describes Emacs commands for all these things. There are also commands -for "filling", or rearranging paragraphs into lines of approximately -equal length. The commands for moving over and killing words, -sentences, and paragraphs, while intended primarily for editing text, -are also often useful for editing programs. - - Emacs has several major modes for editing human language text. If a -file contains plain text, use Text mode, which customizes Emacs in -small ways for the syntactic conventions of text. For text which -contains embedded commands for text formatters, Emacs has other major -modes, each for a particular text formatter. Thus, for input to TeX, -you can use TeX mode; for input to nroff, Nroff mode. - -* Menu: - -* Text Mode:: The major modes for editing text files. -* Nroff Mode:: The major mode for editing input to the formatter nroff. -* TeX Mode:: The major modes for editing input to the formatter TeX. -* Outline Mode:: The major mode for editing outlines. -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text -* Case:: Changing the case of text - - -File: xemacs.info, Node: Text Mode, Next: Words, Prev: Text, Up: Text - -Text Mode -========= - - You should use Text mode--rather than Fundamental or Lisp mode--to -edit files of text in a human language. Invoke `M-x text-mode' to -enter Text mode. In Text mode, runs the function -`tab-to-tab-stop', which allows you to use arbitrary tab stops set with -`M-x edit-tab-stops' (*note Tab Stops::). Features concerned with -comments in programs are turned off unless they are explicitly invoked. -The syntax table is changed so that periods are not considered part of a -word, while apostrophes, backspaces and underlines are. - - A similar variant mode is Indented Text mode, intended for editing -text in which most lines are indented. This mode defines to run -`indent-relative' (*note Indentation::), and makes Auto Fill indent the -lines it creates. As a result, a line made by Auto Filling, or by -, is normally indented just like the previous line. Use `M-x -indented-text-mode' to select this mode. - - Entering Text mode or Indented Text mode calls the value of the -variable `text-mode-hook' with no arguments, if that value exists and -is not `nil'. This value is also called when modes related to Text -mode are entered; this includes Nroff mode, TeX mode, Outline mode, and -Mail mode. Your hook can look at the value of `major-mode' to see -which of these modes is actually being entered. - - Two modes similar to Text mode are of use for editing text that is to -be passed through a text formatter before achieving its final readable -form. - -* Menu: - -* Nroff Mode:: The major mode for editing input to the formatter nroff. -* TeX Mode:: The major modes for editing input to the formatter TeX. - - - Another similar mode is used for editing outlines. It allows you -to view the text at various levels of detail. You can view either -the outline headings alone or both headings and text; you can also -hide some of the headings at lower levels from view to make the high -level structure more visible. - - -* Outline Mode:: The major mode for editing outlines. - - -File: xemacs.info, Node: Nroff Mode, Next: TeX Mode, Prev: Text Mode, Up: Text Mode - -Nroff Mode ----------- - - Nroff mode is a mode like Text mode but modified to handle nroff -commands present in the text. Invoke `M-x nroff-mode' to enter this -mode. Nroff mode differs from Text mode in only a few ways. All nroff -command lines are considered paragraph separators, so that filling never -garbles the nroff commands. Pages are separated by `.bp' commands. -Comments start with backslash-doublequote. There are also three special -commands that are not available in Text mode: - -`M-n' - Move to the beginning of the next line that isn't an nroff command - (`forward-text-line'). An argument is a repeat count. - -`M-p' - Like `M-n' but move up (`backward-text-line'). - -`M-?' - Prints in the echo area the number of text lines (lines that are - not nroff commands) in the region (`count-text-lines'). - - The other feature of Nroff mode is Electric Nroff newline mode. -This is a minor mode that you can turn on or off with `M-x -electric-nroff-mode' (*note Minor Modes::). When the mode is on and -you use to end a line containing an nroff command that opens a -kind of grouping, Emacs automatically inserts the matching nroff -command to close that grouping on the following line. For example, if -you are at the beginning of a line and type `.(b ', the matching -command `.)b' will be inserted on a new line following point. - - Entering Nroff mode calls the value of the variable `text-mode-hook' -with no arguments, if that value exists and is not `nil'; then it does -the same with the variable `nroff-mode-hook'. - - -File: xemacs.info, Node: TeX Mode, Next: Outline Mode, Prev: Nroff Mode, Up: Text Mode - -TeX Mode --------- - - TeX is a powerful text formatter written by Donald Knuth; like GNU -Emacs, it is free. LaTeX is a simplified input format for TeX, -implemented by TeX macros. It is part of TeX. - - Emacs has a special TeX mode for editing TeX input files. It -provides facilities for checking the balance of delimiters and for -invoking TeX on all or part of the file. - - TeX mode has two variants, Plain TeX mode and LaTeX mode, which are -two distinct major modes that differ only slightly. These modes are -designed for editing the two different input formats. The command `M-x -tex-mode' looks at the contents of a buffer to determine whether it -appears to be LaTeX input or not; it then selects the appropriate mode. -If it can't tell which is right (e.g., the buffer is empty), the -variable `tex-default-mode' controls which mode is used. - - The commands `M-x plain-tex-mode' and `M-x latex-mode' explicitly -select one of the variants of TeX mode. Use these commands when `M-x -tex-mode' does not guess right. - -* Menu: - -* Editing: TeX Editing. Special commands for editing in TeX mode. -* Printing: TeX Print. Commands for printing part of a file with TeX. - - TeX for Unix systems can be obtained from the University of -Washington for a distribution fee. - - To order a full distribution, send $140.00 for a 1/2 inch 9-track -tape, $165.00 for two 4-track 1/4 inch cartridge tapes (foreign sites -$150.00, for 1/2 inch, $175.00 for 1/4 inch, to cover the extra -postage) payable to the University of Washington to: - - The Director - Northwest Computer Support Group, DW-10 - University of Washington - Seattle, Washington 98195 - -Purchase orders are acceptable, but there is an extra charge of $10.00 -to pay for processing charges. (The total cost comes to $150 for -domestic sites, $175 for foreign sites). - - The normal distribution is a tar tape, blocked 20, 1600 bpi, on an -industry standard 2400 foot half-inch reel. The physical format for -the 1/4 inch streamer cartridges uses QIC-11, 8000 bpi, 4-track -serpentine recording for the SUN. Also, SystemV tapes can be written -in cpio format, blocked 5120 bytes, ASCII headers. -