X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-21;h=b1e4ad2c99a5631e400207d19a9cbc2161439e3e;hb=d1099d83853ef66f415fbb5928243e0835dbdf79;hp=4ade6a938bed3261c74a773e07228ebaa393cad8;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-21 b/info/lispref.info-21 index 4ade6a9..b1e4ad2 100644 --- a/info/lispref.info-21 +++ b/info/lispref.info-21 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,6 +50,947 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, Up: Gutter + +Gutter Intro +============ + + A "gutter" is a rectangle displayed along one edge of a frame. It +can contain arbitrary text or graphics. It could be considered a +generalization of a toolbar, although toolbars are not currently +implemented using gutters. + + In XEmacs, a gutter can be displayed along any of the four edges of +the frame, and two or more different edges can be displaying gutters +simultaneously. The contents, thickness, and visibility of the gutters +can be controlled separately, and the values can be per-buffer, +per-frame, etc., using specifiers (*note Specifiers::). + + Normally, there is one gutter displayed in a frame. Usually, this is +the default gutter, containing buffer tabs, but modes cab override this +and substitute their own gutter. This default gutter is usually +positioned along the top of the frame, but this can be changed using +`set-default-gutter-position'. + + Note that, for each of the gutter properties (contents, thickness, +and visibility), there is a separate specifier for each of the four +gutter positions (top, bottom, left, and right), and an additional +specifier for the "default" gutter, i.e. the gutter whose position is +controlled by `set-default-gutter-position'. The way this works is +that `set-default-gutter-position' arranges things so that the +appropriate position-specific specifiers for the default position +inherit from the corresponding default specifiers. That way, if the +position-specific specifier does not give a value (which it usually +doesn't), then the value from the default specifier applies. If you +want to control the default gutter, you just change the default +specifiers, and everything works. A package such as VM that wants to +put its own gutter in a different location from the default just sets +the position-specific specifiers, and if the user sets the default +gutter to the same position, it will just not be visible. + + +File: lispref.info, Node: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter + +Creating Gutter +=============== + + - Function: make-gutter-specifier spec-list + Return a new `gutter' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter specifiers are used to specify the format of a gutter. The + values of the variables `default-gutter', `top-gutter', + `left-gutter', `right-gutter', and `bottom-gutter' are always + gutter specifiers. + + Valid gutter instantiators are called "gutter descriptors" and are + either strings or property-lists of strings. See `default-gutter' + for a description of the exact format. + + - Function: make-gutter-size-specifier spec-list + Return a new `gutter-size' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter-size specifiers are used to specify the size of a gutter. + The values of the variables `default-gutter-size', + `top-gutter-size', `left-gutter-size', `right-gutter-size', and + `bottom-gutter-size' are always gutter-size specifiers. + + Valid gutter-size instantiators are either integers or the special + symbol `autodetect'. If a gutter-size is set to `autodetect' them + the size of the gutter will be adjusted to just accommodate the + gutters contents. `autodetect' only works for top and bottom + gutters. + + - Function: make-gutter-visible-specifier spec-list + Return a new `gutter-visible' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. *Note Specifiers::, for + more information about specifiers. + + Gutter-visible specifiers are used to specify the visibility of a + gutter. The values of the variables `default-gutter-visible-p', + `top-gutter-visible-p', `left-gutter-visible-p', + `right-gutter-visible-p', and `bottom-gutter-visible-p' are always + gutter-visible specifiers. + + Valid gutter-visible instantiators are `t', `nil' or a list of + symbols. If a gutter-visible instantiator is set to a list of + symbols, and the corresponding gutter specification is a + property-list strings, then elements of the gutter specification + will only be visible if the corresponding symbol occurs in the + gutter-visible instantiator. + + +File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter + +Gutter Descriptor Format +======================== + + The contents of a gutter are specified using a "gutter descriptor". +The format of a gutter descriptor is a list of "gutter button +descriptors". Each gutter button descriptor is a vector in one of the +following formats: + + * `[GLYPH-LIST FUNCTION ENABLED-P HELP]' + + * `[:style 2D-OR-3D]' + + * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]' + + * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]' + + Optionally, one of the gutter button descriptors may be `nil' +instead of a vector; this signifies the division between the gutter +buttons that are to be displayed flush-left, and the buttons to be +displayed flush-right. + + The first vector format above specifies a normal gutter button; the +others specify blank areas in the gutter. + + For the first vector format: + + * GLYPH-LIST should be a list of one to six glyphs (as created by + `make-glyph') or a symbol whose value is such a list. The first + glyph, which must be provided, is the glyph used to display the + gutter button when it is in the "up" (not pressed) state. The + optional second glyph is for displaying the button when it is in + the "down" (pressed) state. The optional third glyph is for when + the button is disabled. The last three glyphs are for displaying + the button in the "up", "down", and "disabled" states, + respectively, but are used when the user has called for captioned + gutter buttons (using `gutter-buttons-captioned-p'). The function + `gutter-make-button-list' is useful in creating these glyph lists. + + * Even if you do not provide separate down-state and disabled-state + glyphs, the user will still get visual feedback to indicate which + state the button is in. Buttons in the up-state are displayed + with a shadowed border that gives a raised appearance to the + button. Buttons in the down-state are displayed with shadows that + give a recessed appearance. Buttons in the disabled state are + displayed with no shadows, giving a 2-d effect. + + * If some of the gutter glyphs are not provided, they inherit as + follows: + + UP: up + DOWN: down -> up + DISABLED: disabled -> up + CAP-UP: cap-up -> up + CAP-DOWN: cap-down -> cap-up -> down -> up + CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up + + * The second element FUNCTION is a function to be called when the + gutter button is activated (i.e. when the mouse is released over + the gutter button, if the press occurred in the gutter). It can + be any form accepted by `call-interactively', since this is how it + is invoked. + + * The third element ENABLED-P specifies whether the gutter button is + enabled (disabled buttons do nothing when they are activated, and + are displayed differently; see above). It should be either a + boolean or a form that evaluates to a boolean. + + * The fourth element HELP, if non-`nil', should be a string. This + string is displayed in the echo area when the mouse passes over the + gutter button. + + For the other vector formats (specifying blank areas of the gutter): + + * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating + whether the area is displayed with shadows (giving it a raised, + 3-d appearance) or without shadows (giving it a flat appearance). + + * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank + area. If omitted, it defaults to a device-specific value (8 + pixels for X devices). + + - Function: gutter-make-button-list up &optional down disabled cap-up + cap-down cap-disabled + This function calls `make-glyph' on each arg and returns a list of + the results. This is useful for setting the first argument of a + gutter button descriptor (typically, the result of this function + is assigned to a symbol, which is specified as the first argument + of the gutter button descriptor). + + - Function: check-gutter-button-syntax button &optional noerror + Verify the syntax of entry BUTTON in a gutter description list. + If you want to verify the syntax of a gutter description list as a + whole, use `check-valid-instantiator' with a specifier type of + `gutter'. + + +File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter + +Specifying a Gutter +=================== + + In order to specify the contents of a gutter, set one of the +specifier variables `default-gutter', `top-gutter', `bottom-gutter', +`left-gutter', or `right-gutter'. These are specifiers, which means +you set them with `set-specifier' and query them with `specifier-specs' +or `specifier-instance'. You will get an error if you try to set them +using `setq'. The valid instantiators for these specifiers are gutter +descriptors, as described above. *Note Specifiers::, for more +information. + + Most of the time, you will set `default-gutter', which allows the +user to choose where the gutter should go. + + - Specifier: default-gutter + The position of this gutter is specified in the function + `default-gutter-position'. If the corresponding position-specific + gutter (e.g. `top-gutter' if `default-gutter-position' is `top') + does not specify a gutter in a particular domain, then the value + of `default-gutter' in that domain, of any, will be used instead. + + Note that the gutter at any particular position will not be displayed +unless its thickness (width or height, depending on orientation) is +non-zero and its visibility status is true. The thickness is controlled +by the specifiers `top-gutter-height', `bottom-gutter-height', +`left-gutter-width', and `right-gutter-width', and the visibility +status is controlled by the specifiers `top-gutter-visible-p', +`bottom-gutter-visible-p', `left-gutter-visible-p', and +`right-gutter-visible-p' (*note Other Gutter Variables::). + + - Function: set-default-gutter-position position + This function sets the position that the `default-gutter' will be + displayed at. Valid positions are the symbols `top', `bottom', + `left' and `right'. What this actually does is set the fallback + specifier for the position-specific specifier corresponding to the + given position to `default-gutter', and set the fallbacks for the + other position-specific specifiers to `nil'. It also does the + same thing for the position-specific thickness and visibility + specifiers, which inherit from one of `default-gutter-height' or + `default-gutter-width', and from `default-gutter-visible-p', + respectively (*note Other Gutter Variables::). + + - Function: default-gutter-position + This function returns the position that the `default-gutter' will + be displayed at. + + You can also explicitly set a gutter at a particular position. When +redisplay determines what to display at a particular position in a +particular domain (i.e. window), it first consults the position-specific +gutter. If that does not yield a gutter descriptor, the +`default-gutter' is consulted if `default-gutter-position' indicates +this position. + + - Specifier: top-gutter + Specifier for the gutter at the top of the frame. + + - Specifier: bottom-gutter + Specifier for the gutter at the bottom of the frame. + + - Specifier: left-gutter + Specifier for the gutter at the left edge of the frame. + + - Specifier: right-gutter + Specifier for the gutter at the right edge of the frame. + + - Function: gutter-specifier-p object + This function returns non-`nil' if OBJECT is a gutter specifier. + Gutter specifiers are the actual objects contained in the gutter + variables described above, and their valid instantiators are + gutter descriptors (*note Gutter Descriptor Format::). + + +File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter + +Other Gutter Variables +====================== + + The variables to control the gutter thickness, visibility status, and +captioned status are all specifiers. *Note Specifiers::. + + - Specifier: default-gutter-height + This specifies the height of the default gutter, if it's oriented + horizontally. The position of the default gutter is specified by + the function `set-default-gutter-position'. If the corresponding + position-specific gutter thickness specifier (e.g. + `top-gutter-height' if `default-gutter-position' is `top') does + not specify a thickness in a particular domain (a window or a + frame), then the value of `default-gutter-height' or + `default-gutter-width' (depending on the gutter orientation) in + that domain, if any, will be used instead. + + - Specifier: default-gutter-width + This specifies the width of the default gutter, if it's oriented + vertically. This behaves like `default-gutter-height'. + + Note that `default-gutter-height' is only used when +`default-gutter-position' is `top' or `bottom', and +`default-gutter-width' is only used when `default-gutter-position' is +`left' or `right'. + + - Specifier: top-gutter-height + This specifies the height of the top gutter. + + - Specifier: bottom-gutter-height + This specifies the height of the bottom gutter. + + - Specifier: left-gutter-width + This specifies the width of the left gutter. + + - Specifier: right-gutter-width + This specifies the width of the right gutter. + + Note that all of the position-specific gutter thickness specifiers +have a fallback value of zero when they do not correspond to the +default gutter. Therefore, you will have to set a non-zero thickness +value if you want a position-specific gutter to be displayed. + + - Specifier: default-gutter-visible-p + This specifies whether the default gutter is visible. The + position of the default gutter is specified by the function + `set-default-gutter-position'. If the corresponding + position-specific gutter visibility specifier (e.g. + `top-gutter-visible-p' if `default-gutter-position' is `top') does + not specify a visible-p value in a particular domain (a window or + a frame), then the value of `default-gutter-visible-p' in that + domain, if any, will be used instead. + + - Specifier: top-gutter-visible-p + This specifies whether the top gutter is visible. + + - Specifier: bottom-gutter-visible-p + This specifies whether the bottom gutter is visible. + + - Specifier: left-gutter-visible-p + This specifies whether the left gutter is visible. + + - Specifier: right-gutter-visible-p + This specifies whether the right gutter is visible. + + `default-gutter-visible-p' and all of the position-specific gutter +visibility specifiers have a fallback value of true. + + Internally, gutter thickness and visibility specifiers are +instantiated in both window and frame domains, for different purposes. +The value in the domain of a frame's selected window specifies the +actual gutter thickness or visibility that you will see in that frame. +The value in the domain of a frame itself specifies the gutter +thickness or visibility that is used in frame geometry calculations. + + Thus, for example, if you set the frame width to 80 characters and +the left gutter width for that frame to 68 pixels, then the frame will +be sized to fit 80 characters plus a 68-pixel left gutter. If you then +set the left gutter width to 0 for a particular buffer (or if that +buffer does not specify a left gutter or has a `nil' value specified for +`left-gutter-visible-p'), you will find that, when that buffer is +displayed in the selected window, the window will have a width of 86 or +87 characters - the frame is sized for a 68-pixel left gutter but the +selected window specifies that the left gutter is not visible, so it is +expanded to take up the slack. + + - Specifier: gutter-buttons-captioned-p + Whether gutter buttons are captioned. This affects which glyphs + from a gutter button descriptor are chosen. *Note Gutter + Descriptor Format::. + + You can also reset the gutter to what it was when XEmacs started up. + + - Constant: initial-gutter-spec + The gutter descriptor used to initialize `default-gutter' at + startup. + + +File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter + +Common Gutter Widgets +===================== + + A gutter can contain arbitrary text. So, for example, in an Info +buffer you could put the title of the current node in the top gutter, +and it would not scroll out of view in a long node. (This is an +artificial example, since usually the node name is sufficiently +descriptive, and Info puts that in the mode line.) + + A more common use for the gutter is to hold some kind of active +widget. The buffer-tab facility, available in all XEmacs frames, +creates an array of file-folder-like tabs, which the user can click with +the mouse to switch buffers. W3 uses a progress-bar widget in the +bottom gutter to give a visual indication of the progress of +time-consuming operations like downloading. + +* Menu: + +* Buffer Tabs:: Tabbed divider index metaphor for switching buffers. +* Progress Bars:: Visual indication of operation progress. + + +File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets + +Buffer Tabs +----------- + + Not documented yet. + + +File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets + +Progress Bars +------------- + + Not documented yet. + + +File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top + +Scrollbars +********** + + Not yet documented. + + +File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top + +Drag and Drop +************* + + _WARNING_: the Drag'n'Drop API is still under development and the +interface may change! The current implementation is considered +experimental. + + Drag'n'drop is a way to transfer information between multiple +applications. To do this several GUIs define their own protocols. +Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more. +To catch all these protocols, XEmacs provides a generic API. + + One prime idea behind the API is to use a data interface that is +transparent for all systems. The author thinks that this is best +archived by using URL and MIME data, cause any internet enabled system +must support these for email already. XEmacs also already provides +powerful interfaces to support these types of data (tm and w3). + +* Menu: + +* Supported Protocols:: Which low-level protocols are supported. +* Drop Interface:: How XEmacs handles a drop from another application. +* Drag Interface:: Calls to initiate a drag from XEmacs. + + +File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop + +Supported Protocols +=================== + + The current release of XEmacs only support a small set of Drag'n'drop +protocols. Some of these only support limited options available in the +API. + +* Menu: + +* OffiX DND:: A generic X based protocol. +* CDE dt:: Common Desktop Environment used on suns. +* MSWindows OLE:: Mr. Gates way of live. +* Loose ends:: The other protocols. + + +File: lispref.info, Node: OffiX DND, Next: CDE dt, Up: Supported Protocols + +OffiX DND +--------- + + _WARNING_: If you compile in OffiX, you may not be able to use +multiple X displays successfully. If the two servers are from +different vendors, the results may be unpredictable. + + The OffiX Drag'n'Drop protocol is part of a X API/Widget library +created by Cesar Crusius. It is based on X-Atoms and ClientMessage +events, and works with any X platform supporting them. + + OffiX is supported if 'offix is member of the variable +dragdrop-protocols, or the feature 'offix is defined. + + Unfortunately it uses it's own data types. Examples are: File, Files, +Exe, Link, URL, MIME. The API tries to choose the right type for the +data that is dragged from XEmacs (well, not yet...). + + XEmacs supports both MIME and URL drags and drops using this API. No +application interaction is possible while dragging is in progress. + + For information about the OffiX project have a look at +http://leb.net/~offix/ + + +File: lispref.info, Node: CDE dt, Next: MSWindows OLE, Prev: OffiX DND, Up: Supported Protocols + +CDE dt +------ + + CDE stands for Common Desktop Environment. It is based on the Motif +widget library. It's drag'n'drop protocol is also an abstraction of the +Motif protocol (so it might be possible, that XEmacs will also support +the Motif protocol soon). + + CDE has three different types: file, buffer, and text. XEmacs only +uses file and buffer drags. The API will disallow full URL drags, only +file method URLs are passed through. + + Buffer drags are always converted to plain text. + + +File: lispref.info, Node: MSWindows OLE, Next: Loose ends, Prev: CDE dt, Up: Supported Protocols + +MSWindows OLE +------------- + + Only allows file drags and drops. + + +File: lispref.info, Node: Loose ends, Prev: MSWindows OLE, Up: Supported Protocols + +Loose ends +---------- + + The following protocols will be supported soon: Xdnd, Motif, Xde (if +I get some specs), KDE OffiX (if KDE can find XEmacs windows). + + In particular Xdnd will be one of the protocols that can benefit from +the XEmacs API, cause it also uses MIME types to encode dragged data. + + +File: lispref.info, Node: Drop Interface, Next: Drag Interface, Prev: Supported Protocols, Up: Drag and Drop + +Drop Interface +============== + + For each activated low-level protocol, a internal routine will catch +incoming drops and convert them to a dragdrop-drop type misc-user-event. + + This misc-user-event has its function argument set to +`dragdrop-drop-dispatch' and the object contains the data of the drop +(converted to URL/MIME specific data). This function will search the +variable `experimental-dragdrop-drop-functions' for a function that can +handle the dropped data. + + To modify the drop behavior, the user can modify the variable +`experimental-dragdrop-drop-functions'. Each element of this list +specifies a possible handler for dropped data. The first one that can +handle the data will return `t' and exit. Another possibility is to set +a extent-property with the same name. Extents are checked prior to the +variable. + + The customization group `drag-n-drop' shows all variables of user +interest. + + +File: lispref.info, Node: Drag Interface, Prev: Drop Interface, Up: Drag and Drop + +Drag Interface +============== + + This describes the drag API (not implemented yet). + + +File: lispref.info, Node: Modes, Next: Documentation, Prev: Drag and Drop, Up: Top + +Major and Minor Modes +********************* + + A "mode" is a set of definitions that customize XEmacs and can be +turned on and off while you edit. There are two varieties of modes: +"major modes", which are mutually exclusive and used for editing +particular kinds of text, and "minor modes", which provide features +that users can enable individually. + + This chapter describes how to write both major and minor modes, how +to indicate them in the modeline, and how they run hooks supplied by the +user. For related topics such as keymaps and syntax tables, see *Note +Keymaps::, and *Note Syntax Tables::. + +* Menu: + +* Major Modes:: Defining major modes. +* Minor Modes:: Defining minor modes. +* Modeline Format:: Customizing the text that appears in the modeline. +* Hooks:: How to use hooks; how to write code that provides hooks. + + +File: lispref.info, Node: Major Modes, Next: Minor Modes, Up: Modes + +Major Modes +=========== + + Major modes specialize XEmacs for editing particular kinds of text. +Each buffer has only one major mode at a time. + + The least specialized major mode is called "Fundamental mode". This +mode has no mode-specific definitions or variable settings, so each +XEmacs command behaves in its default manner, and each option is in its +default state. All other major modes redefine various keys and options. +For example, Lisp Interaction mode provides special key bindings for + (`eval-print-last-sexp'), (`lisp-indent-line'), and other +keys. + + When you need to write several editing commands to help you perform a +specialized editing task, creating a new major mode is usually a good +idea. In practice, writing a major mode is easy (in contrast to +writing a minor mode, which is often difficult). + + If the new mode is similar to an old one, it is often unwise to +modify the old one to serve two purposes, since it may become harder to +use and maintain. Instead, copy and rename an existing major mode +definition and alter the copy--or define a "derived mode" (*note +Derived Modes::). For example, Rmail Edit mode, which is in +`emacs/lisp/rmailedit.el', is a major mode that is very similar to Text +mode except that it provides three additional commands. Its definition +is distinct from that of Text mode, but was derived from it. + + Rmail Edit mode is an example of a case where one piece of text is +put temporarily into a different major mode so it can be edited in a +different way (with ordinary XEmacs commands rather than Rmail). In +such cases, the temporary major mode usually has a command to switch +back to the buffer's usual mode (Rmail mode, in this case). You might +be tempted to present the temporary redefinitions inside a recursive +edit and restore the usual ones when the user exits; but this is a bad +idea because it constrains the user's options when it is done in more +than one buffer: recursive edits must be exited most-recently-entered +first. Using alternative major modes avoids this limitation. *Note +Recursive Editing::. + + The standard XEmacs Lisp library directory contains the code for +several major modes, in files including `text-mode.el', `texinfo.el', +`lisp-mode.el', `c-mode.el', and `rmail.el'. You can look at these +libraries to see how modes are written. Text mode is perhaps the +simplest major mode aside from Fundamental mode. Rmail mode is a +complicated and specialized mode. + +* Menu: + +* Major Mode Conventions:: Coding conventions for keymaps, etc. +* Example Major Modes:: Text mode and Lisp modes. +* Auto Major Mode:: How XEmacs chooses the major mode automatically. +* Mode Help:: Finding out how to use a mode. +* Derived Modes:: Defining a new major mode based on another major + mode. + + +File: lispref.info, Node: Major Mode Conventions, Next: Example Major Modes, Up: Major Modes + +Major Mode Conventions +---------------------- + + The code for existing major modes follows various coding conventions, +including conventions for local keymap and syntax table initialization, +global names, and hooks. Please follow these conventions when you +define a new major mode: + + * Define a command whose name ends in `-mode', with no arguments, + that switches to the new mode in the current buffer. This command + should set up the keymap, syntax table, and local variables in an + existing buffer without changing the buffer's text. + + * Write a documentation string for this command that describes the + special commands available in this mode. `C-h m' + (`describe-mode') in your mode will display this string. + + The documentation string may include the special documentation + substrings, `\[COMMAND]', `\{KEYMAP}', and `\', that + enable the documentation to adapt automatically to the user's own + key bindings. *Note Keys in Documentation::. + + * The major mode command should start by calling + `kill-all-local-variables'. This is what gets rid of the local + variables of the major mode previously in effect. + + * The major mode command should set the variable `major-mode' to the + major mode command symbol. This is how `describe-mode' discovers + which documentation to print. + + * The major mode command should set the variable `mode-name' to the + "pretty" name of the mode, as a string. This appears in the mode + line. + + * Since all global names are in the same name space, all the global + variables, constants, and functions that are part of the mode + should have names that start with the major mode name (or with an + abbreviation of it if the name is long). *Note Style Tips::. + + * The major mode should usually have its own keymap, which is used + as the local keymap in all buffers in that mode. The major mode + function should call `use-local-map' to install this local map. + *Note Active Keymaps::, for more information. + + This keymap should be kept in a global variable named + `MODENAME-mode-map'. Normally the library that defines the mode + sets this variable. + + * The mode may have its own syntax table or may share one with other + related modes. If it has its own syntax table, it should store + this in a variable named `MODENAME-mode-syntax-table'. *Note + Syntax Tables::. + + * The mode may have its own abbrev table or may share one with other + related modes. If it has its own abbrev table, it should store + this in a variable named `MODENAME-mode-abbrev-table'. *Note + Abbrev Tables::. + + * Use `defvar' to set mode-related variables, so that they are not + reinitialized if they already have a value. (Such reinitialization + could discard customizations made by the user.) + + * To make a buffer-local binding for an Emacs customization + variable, use `make-local-variable' in the major mode command, not + `make-variable-buffer-local'. The latter function would make the + variable local to every buffer in which it is subsequently set, + which would affect buffers that do not use this mode. It is + undesirable for a mode to have such global effects. *Note + Buffer-Local Variables::. + + It's ok to use `make-variable-buffer-local', if you wish, for a + variable used only within a single Lisp package. + + * Each major mode should have a "mode hook" named + `MODENAME-mode-hook'. The major mode command should run that + hook, with `run-hooks', as the very last thing it does. *Note + Hooks::. + + * The major mode command may also run the hooks of some more basic + modes. For example, `indented-text-mode' runs `text-mode-hook' as + well as `indented-text-mode-hook'. It may run these other hooks + immediately before the mode's own hook (that is, after everything + else), or it may run them earlier. + + * If something special should be done if the user switches a buffer + from this mode to any other major mode, the mode can set a local + value for `change-major-mode-hook'. + + * If this mode is appropriate only for specially-prepared text, then + the major mode command symbol should have a property named + `mode-class' with value `special', put on as follows: + + (put 'funny-mode 'mode-class 'special) + + This tells XEmacs that new buffers created while the current + buffer has Funny mode should not inherit Funny mode. Modes such + as Dired, Rmail, and Buffer List use this feature. + + * If you want to make the new mode the default for files with certain + recognizable names, add an element to `auto-mode-alist' to select + the mode for those file names. If you define the mode command to + autoload, you should add this element in the same file that calls + `autoload'. Otherwise, it is sufficient to add the element in the + file that contains the mode definition. *Note Auto Major Mode::. + + * In the documentation, you should provide a sample `autoload' form + and an example of how to add to `auto-mode-alist', that users can + include in their `.emacs' files. + + * The top-level forms in the file defining the mode should be + written so that they may be evaluated more than once without + adverse consequences. Even if you never load the file more than + once, someone else will. + + - Variable: change-major-mode-hook + This normal hook is run by `kill-all-local-variables' before it + does anything else. This gives major modes a way to arrange for + something special to be done if the user switches to a different + major mode. For best results, make this variable buffer-local, so + that it will disappear after doing its job and will not interfere + with the subsequent major mode. *Note Hooks::. + + +File: lispref.info, Node: Example Major Modes, Next: Auto Major Mode, Prev: Major Mode Conventions, Up: Major Modes + +Major Mode Examples +------------------- + + Text mode is perhaps the simplest mode besides Fundamental mode. +Here are excerpts from `text-mode.el' that illustrate many of the +conventions listed above: + + ;; Create mode-specific tables. + (defvar text-mode-syntax-table nil + "Syntax table used while in text mode.") + + (if text-mode-syntax-table + () ; Do not change the table if it is already set up. + (setq text-mode-syntax-table (make-syntax-table)) + (modify-syntax-entry ?\" ". " text-mode-syntax-table) + (modify-syntax-entry ?\\ ". " text-mode-syntax-table) + (modify-syntax-entry ?' "w " text-mode-syntax-table)) + + (defvar text-mode-abbrev-table nil + "Abbrev table used while in text mode.") + (define-abbrev-table 'text-mode-abbrev-table ()) + + (defvar text-mode-map nil) ; Create a mode-specific keymap. + + (if text-mode-map + () ; Do not change the keymap if it is already set up. + (setq text-mode-map (make-sparse-keymap)) + (define-key text-mode-map "\t" 'tab-to-tab-stop) + (define-key text-mode-map "\es" 'center-line) + (define-key text-mode-map "\eS" 'center-paragraph)) + + Here is the complete major mode function definition for Text mode: + + (defun text-mode () + "Major mode for editing text intended for humans to read. + Special commands: \\{text-mode-map} + Turning on text-mode runs the hook `text-mode-hook'." + (interactive) + (kill-all-local-variables) + (use-local-map text-mode-map) ; This provides the local keymap. + (setq mode-name "Text") ; This name goes into the modeline. + (setq major-mode 'text-mode) ; This is how `describe-mode' + ; finds the doc string to print. + (setq local-abbrev-table text-mode-abbrev-table) + (set-syntax-table text-mode-syntax-table) + (run-hooks 'text-mode-hook)) ; Finally, this permits the user to + ; customize the mode with a hook. + + The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp +Interaction mode) have more features than Text mode and the code is +correspondingly more complicated. Here are excerpts from +`lisp-mode.el' that illustrate how these modes are written. + + ;; Create mode-specific table variables. + (defvar lisp-mode-syntax-table nil "") + (defvar emacs-lisp-mode-syntax-table nil "") + (defvar lisp-mode-abbrev-table nil "") + + (if (not emacs-lisp-mode-syntax-table) ; Do not change the table + ; if it is already set. + (let ((i 0)) + (setq emacs-lisp-mode-syntax-table (make-syntax-table)) + + ;; Set syntax of chars up to 0 to class of chars that are + ;; part of symbol names but not words. + ;; (The number 0 is `48' in the ASCII character set.) + (while (< i ?0) + (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table) + (setq i (1+ i))) + ... + ;; Set the syntax for other characters. + (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table) + (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table) + ... + (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table) + (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table) + ...)) + ;; Create an abbrev table for lisp-mode. + (define-abbrev-table 'lisp-mode-abbrev-table ()) + + Much code is shared among the three Lisp modes. The following +function sets various variables; it is called by each of the major Lisp +mode functions: + + (defun lisp-mode-variables (lisp-syntax) + ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode, + ;; and `t' in the other two Lisp modes. + (cond (lisp-syntax + (if (not lisp-mode-syntax-table) + ;; The Emacs Lisp mode syntax table always exists, but + ;; the Lisp Mode syntax table is created the first time a + ;; mode that needs it is called. This is to save space. + (progn (setq lisp-mode-syntax-table + (copy-syntax-table emacs-lisp-mode-syntax-table)) + ;; Change some entries for Lisp mode. + (modify-syntax-entry ?\| "\" " + lisp-mode-syntax-table) + (modify-syntax-entry ?\[ "_ " + lisp-mode-syntax-table) + (modify-syntax-entry ?\] "_ " + lisp-mode-syntax-table))) + (set-syntax-table lisp-mode-syntax-table))) + (setq local-abbrev-table lisp-mode-abbrev-table) + ...) + + Functions such as `forward-paragraph' use the value of the +`paragraph-start' variable. Since Lisp code is different from ordinary +text, the `paragraph-start' variable needs to be set specially to +handle Lisp. Also, comments are indented in a special fashion in Lisp +and the Lisp modes need their own mode-specific +`comment-indent-function'. The code to set these variables is the rest +of `lisp-mode-variables'. + + (make-local-variable 'paragraph-start) + ;; Having `^' is not clean, but `page-delimiter' + ;; has them too, and removing those is a pain. + (setq paragraph-start (concat "^$\\|" page-delimiter)) + ... + (make-local-variable 'comment-indent-function) + (setq comment-indent-function 'lisp-comment-indent)) + + Each of the different Lisp modes has a slightly different keymap. +For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other +Lisp modes do not. However, all Lisp modes have some commands in +common. The following function adds these common commands to a given +keymap. + + (defun lisp-mode-commands (map) + (define-key map "\e\C-q" 'indent-sexp) + (define-key map "\177" 'backward-delete-char-untabify) + (define-key map "\t" 'lisp-indent-line)) + + Here is an example of using `lisp-mode-commands' to initialize a +keymap, as part of the code for Emacs Lisp mode. First we declare a +variable with `defvar' to hold the mode-specific keymap. When this +`defvar' executes, it sets the variable to `nil' if it was void. Then +we set up the keymap if the variable is `nil'. + + This code avoids changing the keymap or the variable if it is already +set up. This lets the user customize the keymap. + + (defvar emacs-lisp-mode-map () "") + (if emacs-lisp-mode-map + () + (setq emacs-lisp-mode-map (make-sparse-keymap)) + (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun) + (lisp-mode-commands emacs-lisp-mode-map)) + + Finally, here is the complete major mode function definition for +Emacs Lisp mode. + + (defun emacs-lisp-mode () + "Major mode for editing Lisp code to run in XEmacs. + Commands: + Delete converts tabs to spaces as it moves back. + Blank lines separate paragraphs. Semicolons start comments. + \\{emacs-lisp-mode-map} + Entry to this mode runs the hook `emacs-lisp-mode-hook'." + (interactive) + (kill-all-local-variables) + (use-local-map emacs-lisp-mode-map) ; This provides the local keymap. + (set-syntax-table emacs-lisp-mode-syntax-table) + (setq major-mode 'emacs-lisp-mode) ; This is how `describe-mode' + ; finds out what to describe. + (setq mode-name "Emacs-Lisp") ; This goes into the modeline. + (lisp-mode-variables nil) ; This defines various variables. + (run-hooks 'emacs-lisp-mode-hook)) ; This permits the user to use a + ; hook to customize the mode. + + File: lispref.info, Node: Auto Major Mode, Next: Mode Help, Prev: Example Major Modes, Up: Major Modes How XEmacs Chooses a Major Mode @@ -83,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 @@ -117,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 @@ -210,943 +1151,3 @@ visited. `normal-mode' actually takes place here. The argument FORCE usually comes from the argument FIND-FILE given to `normal-mode'. - -File: lispref.info, Node: Mode Help, Next: Derived Modes, Prev: Auto Major Mode, Up: Major Modes - -Getting Help about a Major Mode -------------------------------- - - The `describe-mode' function is used to provide information about -major modes. It is normally called with `C-h m'. The `describe-mode' -function uses the value of `major-mode', which is why every major mode -function needs to set the `major-mode' variable. - - - Command: describe-mode - This function displays the documentation of the current major mode. - - The `describe-mode' function calls the `documentation' function - using the value of `major-mode' as an argument. Thus, it displays - the documentation string of the major mode function. (*Note - Accessing Documentation::.) - - - Variable: major-mode - This variable holds the symbol for the current buffer's major mode. - This symbol should have a function definition that is the command - to switch to that major mode. The `describe-mode' function uses - the documentation string of the function as the documentation of - the major mode. - - -File: lispref.info, Node: Derived Modes, Prev: Mode Help, Up: Major Modes - -Defining Derived Modes ----------------------- - - It's often useful to define a new major mode in terms of an existing -one. An easy way to do this is to use `define-derived-mode'. - - - Macro: define-derived-mode variant parent name docstring body... - This construct defines VARIANT as a major mode command, using NAME - as the string form of the mode name. - - The new command VARIANT is defined to call the function PARENT, - then override certain aspects of that parent mode: - - * The new mode has its own keymap, named `VARIANT-map'. - `define-derived-mode' initializes this map to inherit from - `PARENT-map', if it is not already set. - - * The new mode has its own syntax table, kept in the variable - `VARIANT-syntax-table'. `define-derived-mode' initializes - this variable by copying `PARENT-syntax-table', if it is not - already set. - - * The new mode has its own abbrev table, kept in the variable - `VARIANT-abbrev-table'. `define-derived-mode' initializes - this variable by copying `PARENT-abbrev-table', if it is not - already set. - - * The new mode has its own mode hook, `VARIANT-hook', which it - runs in standard fashion as the very last thing that it does. - (The new mode also runs the mode hook of PARENT as part of - calling PARENT.) - - In addition, you can specify how to override other aspects of - PARENT with BODY. The command VARIANT evaluates the forms in BODY - after setting up all its usual overrides, just before running - `VARIANT-hook'. - - The argument DOCSTRING specifies the documentation string for the - new mode. If you omit DOCSTRING, `define-derived-mode' generates - a documentation string. - - Here is a hypothetical example: - - (define-derived-mode hypertext-mode - text-mode "Hypertext" - "Major mode for hypertext. - \\{hypertext-mode-map}" - (setq case-fold-search nil)) - - (define-key hypertext-mode-map - [down-mouse-3] 'do-hyper-link) - - -File: lispref.info, Node: Minor Modes, Next: Modeline Format, Prev: Major Modes, Up: Modes - -Minor Modes -=========== - - A "minor mode" provides features that users may enable or disable -independently of the choice of major mode. Minor modes can be enabled -individually or in combination. Minor modes would be better named -"Generally available, optional feature modes" except that such a name is -unwieldy. - - A minor mode is not usually a modification of single major mode. For -example, Auto Fill mode may be used in any major mode that permits text -insertion. To be general, a minor mode must be effectively independent -of the things major modes do. - - A minor mode is often much more difficult to implement than a major -mode. One reason is that you should be able to activate and deactivate -minor modes in any order. A minor mode should be able to have its -desired effect regardless of the major mode and regardless of the other -minor modes in effect. - - Often the biggest problem in implementing a minor mode is finding a -way to insert the necessary hook into the rest of XEmacs. Minor mode -keymaps make this easier than it used to be. - -* Menu: - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. - - -File: lispref.info, Node: Minor Mode Conventions, Next: Keymaps and Minor Modes, Up: Minor Modes - -Conventions for Writing Minor Modes ------------------------------------ - - There are conventions for writing minor modes just as there are for -major modes. Several of the major mode conventions apply to minor -modes as well: those regarding the name of the mode initialization -function, the names of global symbols, and the use of keymaps and other -tables. - - In addition, there are several conventions that are specific to -minor modes. - - * Make a variable whose name ends in `-mode' to represent the minor - mode. Its value should enable or disable the mode (`nil' to - disable; anything else to enable.) We call this the "mode - variable". - - This variable is used in conjunction with the `minor-mode-alist' to - display the minor mode name in the modeline. It can also enable - or disable a minor mode keymap. Individual commands or hooks can - also check the variable's value. - - If you want the minor mode to be enabled separately in each buffer, - make the variable buffer-local. - - * Define a command whose name is the same as the mode variable. Its - job is to enable and disable the mode by setting the variable. - - The command should accept one optional argument. If the argument - is `nil', it should toggle the mode (turn it on if it is off, and - off if it is on). Otherwise, it should turn the mode on if the - argument is a positive integer, a symbol other than `nil' or `-', - or a list whose CAR is such an integer or symbol; it should turn - the mode off otherwise. - - Here is an example taken from the definition of - `transient-mark-mode'. It shows the use of `transient-mark-mode' - as a variable that enables or disables the mode's behavior, and - also shows the proper way to toggle, enable or disable the minor - mode based on the raw prefix argument value. - - (setq transient-mark-mode - (if (null arg) (not transient-mark-mode) - (> (prefix-numeric-value arg) 0))) - - * Add an element to `minor-mode-alist' for each minor mode (*note - Modeline Variables::). This element should be a list of the - following form: - - (MODE-VARIABLE STRING) - - Here MODE-VARIABLE is the variable that controls enabling of the - minor mode, and STRING is a short string, starting with a space, - to represent the mode in the modeline. These strings must be - short so that there is room for several of them at once. - - When you add an element to `minor-mode-alist', use `assq' to check - for an existing element, to avoid duplication. For example: - - (or (assq 'leif-mode minor-mode-alist) - (setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist))) - - -File: lispref.info, Node: Keymaps and Minor Modes, Prev: Minor Mode Conventions, Up: Minor Modes - -Keymaps and Minor Modes ------------------------ - - Each minor mode can have its own keymap, which is active when the -mode is enabled. To set up a keymap for a minor mode, add an element -to the alist `minor-mode-map-alist'. *Note Active Keymaps::. - - One use of minor mode keymaps is to modify the behavior of certain -self-inserting characters so that they do something else as well as -self-insert. In general, this is the only way to do that, since the -facilities for customizing `self-insert-command' are limited to special -cases (designed for abbrevs and Auto Fill mode). (Do not try -substituting your own definition of `self-insert-command' for the -standard one. The editor command loop handles this function specially.) - - -File: lispref.info, Node: Modeline Format, Next: Hooks, Prev: Minor Modes, Up: Modes - -Modeline Format -=============== - - Each Emacs window (aside from minibuffer windows) includes a -modeline, which displays status information about the buffer displayed -in the window. The modeline contains information about the buffer, -such as its name, associated file, depth of recursive editing, and the -major and minor modes. - - This section describes how the contents of the modeline are -controlled. It is in the chapter on modes because much of the -information displayed in the modeline relates to the enabled major and -minor modes. - - `modeline-format' is a buffer-local variable that holds a template -used to display the modeline of the current buffer. All windows for -the same buffer use the same `modeline-format' and their modelines -appear the same (except for scrolling percentages and line numbers). - - The modeline of a window is normally updated whenever a different -buffer is shown in the window, or when the buffer's modified-status -changes from `nil' to `t' or vice-versa. If you modify any of the -variables referenced by `modeline-format' (*note Modeline Variables::), -you may want to force an update of the modeline so as to display the -new information. - - - Function: redraw-modeline &optional all - Force redisplay of the current buffer's modeline. If ALL is - non-`nil', then force redisplay of all modelines. - - The modeline is usually displayed in inverse video. This is -controlled using the `modeline' face. *Note Faces::. - -* Menu: - -* Modeline Data:: The data structure that controls the modeline. -* Modeline Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a modeline. - - -File: lispref.info, Node: Modeline Data, Next: Modeline Variables, Up: Modeline Format - -The Data Structure of the Modeline ----------------------------------- - - The modeline contents are controlled by a data structure of lists, -strings, symbols, and numbers kept in the buffer-local variable -`mode-line-format'. The data structure is called a "modeline -construct", and it is built in recursive fashion out of simpler modeline -constructs. The same data structure is used for constructing frame -titles (*note Frame Titles::). - - - Variable: modeline-format - The value of this variable is a modeline construct with overall - responsibility for the modeline format. The value of this variable - controls which other variables are used to form the modeline text, - and where they appear. - - A modeline construct may be as simple as a fixed string of text, but -it usually specifies how to use other variables to construct the text. -Many of these variables are themselves defined to have modeline -constructs as their values. - - The default value of `modeline-format' incorporates the values of -variables such as `mode-name' and `minor-mode-alist'. Because of this, -very few modes need to alter `modeline-format'. For most purposes, it -is sufficient to alter the variables referenced by `modeline-format'. - - A modeline construct may be a list, a symbol, or a string. If the -value is a list, each element may be a list, a symbol, or a string. - -`STRING' - A string as a modeline construct is displayed verbatim in the mode - line except for "`%'-constructs". Decimal digits after the `%' - specify the field width for space filling on the right (i.e., the - data is left justified). *Note %-Constructs::. - -`SYMBOL' - A symbol as a modeline construct stands for its value. The value - of SYMBOL is used as a modeline construct, in place of SYMBOL. - However, the symbols `t' and `nil' are ignored; so is any symbol - whose value is void. - - There is one exception: if the value of SYMBOL is a string, it is - displayed verbatim: the `%'-constructs are not recognized. - -`(STRING REST...) or (LIST REST...)' - A list whose first element is a string or list means to process - all the elements recursively and concatenate the results. This is - the most common form of mode line construct. - -`(SYMBOL THEN ELSE)' - A list whose first element is a symbol is a conditional. Its - meaning depends on the value of SYMBOL. If the value is non-`nil', - the second element, THEN, is processed recursively as a modeline - element. But if the value of SYMBOL is `nil', the third element, - ELSE, is processed recursively. You may omit ELSE; then the mode - line element displays nothing if the value of SYMBOL is `nil'. - -`(WIDTH REST...)' - A list whose first element is an integer specifies truncation or - padding of the results of REST. The remaining elements REST are - processed recursively as modeline constructs and concatenated - together. Then the result is space filled (if WIDTH is positive) - or truncated (to -WIDTH columns, if WIDTH is negative) on the - right. - - For example, the usual way to show what percentage of a buffer is - above the top of the window is to use a list like this: `(-3 - "%p")'. - - If you do alter `modeline-format' itself, the new value should use -the same variables that appear in the default value (*note Modeline -Variables::), rather than duplicating their contents or displaying the -information in another fashion. This way, customizations made by the -user or by Lisp programs (such as `display-time' and major modes) via -changes to those variables remain effective. - - Here is an example of a `modeline-format' that might be useful for -`shell-mode', since it contains the hostname and default directory. - - (setq modeline-format - (list "" - 'modeline-modified - "%b--" - (getenv "HOST") ; One element is not constant. - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - 'mode-name - 'modeline-process - 'minor-mode-alist - "%n" - ")%]----" - '(line-number-mode "L%l--") - '(-3 . "%p") - "-%-")) - - -File: lispref.info, Node: Modeline Variables, Next: %-Constructs, Prev: Modeline Data, Up: Modeline Format - -Variables Used in the Modeline ------------------------------- - - This section describes variables incorporated by the standard value -of `modeline-format' into the text of the mode line. There is nothing -inherently special about these variables; any other variables could -have the same effects on the modeline if `modeline-format' were changed -to use them. - - - Variable: modeline-modified - This variable holds the value of the modeline construct that - displays whether the current buffer is modified. - - The default value of `modeline-modified' is `("--%1*%1+-")'. This - means that the modeline displays `--**-' if the buffer is - modified, `-----' if the buffer is not modified, `--%%-' if the - buffer is read only, and `--%*--' if the buffer is read only and - modified. - - Changing this variable does not force an update of the modeline. - - - Variable: modeline-buffer-identification - This variable identifies the buffer being displayed in the window. - Its default value is `("%F: %17b")', which means that it usually - displays `Emacs:' followed by seventeen characters of the buffer - name. (In a terminal frame, it displays the frame name instead of - `Emacs'; this has the effect of showing the frame number.) You may - want to change this in modes such as Rmail that do not behave like - a "normal" XEmacs. - - - Variable: global-mode-string - This variable holds a modeline spec that appears in the mode line - by default, just after the buffer name. The command `display-time' - sets `global-mode-string' to refer to the variable - `display-time-string', which holds a string containing the time and - load information. - - The `%M' construct substitutes the value of `global-mode-string', - but this is obsolete, since the variable is included directly in - the modeline. - - - Variable: mode-name - This buffer-local variable holds the "pretty" name of the current - buffer's major mode. Each major mode should set this variable so - that the mode name will appear in the modeline. - - - Variable: minor-mode-alist - This variable holds an association list whose elements specify how - the modeline should indicate that a minor mode is active. Each - element of the `minor-mode-alist' should be a two-element list: - - (MINOR-MODE-VARIABLE MODELINE-STRING) - - More generally, MODELINE-STRING can be any mode line spec. It - appears in the mode line when the value of MINOR-MODE-VARIABLE is - non-`nil', and not otherwise. These strings should begin with - spaces so that they don't run together. Conventionally, the - MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil' - value when that minor mode is activated. - - The default value of `minor-mode-alist' is: - - minor-mode-alist - => ((vc-mode vc-mode) - (abbrev-mode " Abbrev") - (overwrite-mode overwrite-mode) - (auto-fill-function " Fill") - (defining-kbd-macro " Def") - (isearch-mode isearch-mode)) - - `minor-mode-alist' is not buffer-local. The variables mentioned - in the alist should be buffer-local if the minor mode can be - enabled separately in each buffer. - - - Variable: modeline-process - This buffer-local variable contains the modeline information on - process status in modes used for communicating with subprocesses. - It is displayed immediately following the major mode name, with no - intervening space. For example, its value in the `*shell*' buffer - is `(": %s")', which allows the shell to display its status along - with the major mode as: `(Shell: run)'. Normally this variable is - `nil'. - - - Variable: default-modeline-format - This variable holds the default `modeline-format' for buffers that - do not override it. This is the same as `(default-value - 'modeline-format)'. - - The default value of `default-modeline-format' is: - - ("" - modeline-modified - modeline-buffer-identification - " " - global-mode-string - " %[(" - mode-name - modeline-process - minor-mode-alist - "%n" - ")%]----" - (line-number-mode "L%l--") - (-3 . "%p") - "-%-") - - - Variable: vc-mode - The variable `vc-mode', local in each buffer, records whether the - buffer's visited file is maintained with version control, and, if - so, which kind. Its value is `nil' for no version control, or a - string that appears in the mode line. - - -File: lispref.info, Node: %-Constructs, Prev: Modeline Variables, Up: Modeline Format - -`%'-Constructs in the ModeLine ------------------------------- - - The following table lists the recognized `%'-constructs and what -they mean. In any construct except `%%', you can add a decimal integer -after the `%' to specify how many characters to display. - -`%b' - The current buffer name, obtained with the `buffer-name' function. - *Note Buffer Names::. - -`%f' - The visited file name, obtained with the `buffer-file-name' - function. *Note Buffer File Name::. - -`%F' - The name of the selected frame. - -`%c' - The current column number of point. - -`%l' - The current line number of point. - -`%*' - `%' if the buffer is read only (see `buffer-read-only'); - `*' if the buffer is modified (see `buffer-modified-p'); - `-' otherwise. *Note Buffer Modification::. - -`%+' - `*' if the buffer is modified (see `buffer-modified-p'); - `%' if the buffer is read only (see `buffer-read-only'); - `-' otherwise. This differs from `%*' only for a modified - read-only buffer. *Note Buffer Modification::. - -`%&' - `*' if the buffer is modified, and `-' otherwise. - -`%s' - The status of the subprocess belonging to the current buffer, - obtained with `process-status'. *Note Process Information::. - -`%l' - the current line number. - -`%S' - the name of the selected frame; this is only meaningful under the - X Window System. *Note Frame Name::. - -`%t' - Whether the visited file is a text file or a binary file. (This - is a meaningful distinction only on certain operating systems.) - -`%p' - The percentage of the buffer text above the *top* of window, or - `Top', `Bottom' or `All'. - -`%P' - The percentage of the buffer text that is above the *bottom* of - the window (which includes the text visible in the window, as well - as the text above the top), plus `Top' if the top of the buffer is - visible on screen; or `Bottom' or `All'. - -`%n' - `Narrow' when narrowing is in effect; nothing otherwise (see - `narrow-to-region' in *Note Narrowing::). - -`%[' - An indication of the depth of recursive editing levels (not - counting minibuffer levels): one `[' for each editing level. - *Note Recursive Editing::. - -`%]' - One `]' for each recursive editing level (not counting minibuffer - levels). - -`%%' - The character `%'--this is how to include a literal `%' in a - string in which `%'-constructs are allowed. - -`%-' - Dashes sufficient to fill the remainder of the modeline. - - The following two `%'-constructs are still supported, but they are -obsolete, since you can get the same results with the variables -`mode-name' and `global-mode-string'. - -`%m' - The value of `mode-name'. - -`%M' - The value of `global-mode-string'. Currently, only `display-time' - modifies the value of `global-mode-string'. - - -File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes - -Hooks -===== - - A "hook" is a variable where you can store a function or functions -to be called on a particular occasion by an existing program. XEmacs -provides hooks for the sake of customization. Most often, hooks are set -up in the `.emacs' file, but Lisp programs can set them also. *Note -Standard Hooks::, for a list of standard hook variables. - - Most of the hooks in XEmacs are "normal hooks". These variables -contain lists of functions to be called with no arguments. The reason -most hooks are normal hooks is so that you can use them in a uniform -way. You can usually tell when a hook is a normal hook, because its -name ends in `-hook'. - - The recommended way to add a hook function to a normal hook is by -calling `add-hook' (see below). The hook functions may be any of the -valid kinds of functions that `funcall' accepts (*note What Is a -Function::). Most normal hook variables are initially void; `add-hook' -knows how to deal with this. - - As for abnormal hooks, those whose names end in `-function' have a -value that is a single function. Those whose names end in `-hooks' -have a value that is a list of functions. Any hook that is abnormal is -abnormal because a normal hook won't do the job; either the functions -are called with arguments, or their values are meaningful. The name -shows you that the hook is abnormal and that you should look at its -documentation string to see how to use it properly. - - Major mode functions are supposed to run a hook called the "mode -hook" as the last step of initialization. This makes it easy for a user -to customize the behavior of the mode, by overriding the local variable -assignments already made by the mode. But hooks are used in other -contexts too. For example, the hook `suspend-hook' runs just before -XEmacs suspends itself (*note Suspending XEmacs::). - - Here's an expression that uses a mode hook to turn on Auto Fill mode -when in Lisp Interaction mode: - - (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) - - The next example shows how to use a hook to customize the way XEmacs -formats C code. (People often have strong personal preferences for one -format or another.) Here the hook function is an anonymous lambda -expression. - - (add-hook 'c-mode-hook - (function (lambda () - (setq c-indent-level 4 - c-argdecl-indent 0 - c-label-offset -4 - c-continued-statement-indent 0 - c-brace-offset 0 - comment-column 40)))) - - (setq c++-mode-hook c-mode-hook) - - The final example shows how the appearance of the modeline can be -modified for a particular class of buffers only. - - (add-hook 'text-mode-hook - (function (lambda () - (setq modeline-format - '(modeline-modified - "Emacs: %14b" - " " - default-directory - " " - global-mode-string - "%[(" - mode-name - minor-mode-alist - "%n" - modeline-process - ") %]---" - (-3 . "%p") - "-%-"))))) - - At the appropriate time, XEmacs uses the `run-hooks' function to run -particular hooks. This function calls the hook functions you have -added with `add-hooks'. - - - Function: run-hooks &rest hookvar - This function takes one or more hook variable names as arguments, - and runs each hook in turn. Each HOOKVAR argument should be a - symbol that is a hook variable. These arguments are processed in - the order specified. - - If a hook variable has a non-`nil' value, that value may be a - function or a list of functions. If the value is a function - (either a lambda expression or a symbol with a function - definition), it is called. If it is a list, the elements are - called, in order. The hook functions are called with no arguments. - - For example, here's how `emacs-lisp-mode' runs its mode hook: - - (run-hooks 'emacs-lisp-mode-hook) - - - Function: add-hook hook function &optional append local - This function is the handy way to add function FUNCTION to hook - variable HOOK. The argument FUNCTION may be any valid Lisp - function with the proper number of arguments. For example, - - (add-hook 'text-mode-hook 'my-text-hook-function) - - adds `my-text-hook-function' to the hook called `text-mode-hook'. - - You can use `add-hook' for abnormal hooks as well as for normal - hooks. - - It is best to design your hook functions so that the order in - which they are executed does not matter. Any dependence on the - order is "asking for trouble." However, the order is predictable: - normally, FUNCTION goes at the front of the hook list, so it will - be executed first (barring another `add-hook' call). - - If the optional argument APPEND is non-`nil', the new hook - function goes at the end of the hook list and will be executed - last. - - If LOCAL is non-`nil', that says to make the new hook function - local to the current buffer. Before you can do this, you must - make the hook itself buffer-local by calling `make-local-hook' - (*not* `make-local-variable'). If the hook itself is not - buffer-local, then the value of LOCAL makes no difference--the - hook function is always global. - - - Function: remove-hook hook function &optional local - This function removes FUNCTION from the hook variable HOOK. - - If LOCAL is non-`nil', that says to remove FUNCTION from the local - hook list instead of from the global hook list. If the hook - itself is not buffer-local, then the value of LOCAL makes no - difference. - - - Function: make-local-hook hook - This function makes the hook variable `hook' local to the current - buffer. When a hook variable is local, it can have local and - global hook functions, and `run-hooks' runs all of them. - - This function works by making `t' an element of the buffer-local - value. That serves as a flag to use the hook functions in the - default value of the hook variable as well as those in the local - value. Since `run-hooks' understands this flag, `make-local-hook' - works with all normal hooks. It works for only some non-normal - hooks--those whose callers have been updated to understand this - meaning of `t'. - - Do not use `make-local-variable' directly for hook variables; it is - not sufficient. - - -File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top - -Documentation -************* - - XEmacs Lisp has convenient on-line help facilities, most of which -derive their information from the documentation strings associated with -functions and variables. This chapter describes how to write good -documentation strings for your Lisp programs, as well as how to write -programs to access documentation. - - Note that the documentation strings for XEmacs are not the same thing -as the XEmacs manual. Manuals have their own source files, written in -the Texinfo language; documentation strings are specified in the -definitions of the functions and variables they apply to. A collection -of documentation strings is not sufficient as a manual because a good -manual is not organized in that fashion; it is organized in terms of -topics of discussion. - -* Menu: - -* Documentation Basics:: Good style for doc strings. - Where to put them. How XEmacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by XEmacs help facilities. -* Obsoleteness:: Upgrading Lisp functionality over time. - - -File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation - -Documentation Basics -==================== - - A documentation string is written using the Lisp syntax for strings, -with double-quote characters surrounding the text of the string. This -is because it really is a Lisp string object. The string serves as -documentation when it is written in the proper place in the definition -of a function or variable. In a function definition, the documentation -string follows the argument list. In a variable definition, the -documentation string follows the initial value of the variable. - - When you write a documentation string, make the first line a complete -sentence (or two complete sentences) since some commands, such as -`apropos', show only the first line of a multi-line documentation -string. Also, you should not indent the second line of a documentation -string, if you have one, because that looks odd when you use `C-h f' -(`describe-function') or `C-h v' (`describe-variable'). *Note -Documentation Tips::. - - Documentation strings may contain several special substrings, which -stand for key bindings to be looked up in the current keymaps when the -documentation is displayed. This allows documentation strings to refer -to the keys for related commands and be accurate even when a user -rearranges the key bindings. (*Note Accessing Documentation::.) - - Within the Lisp world, a documentation string is accessible through -the function or variable that it describes: - - * The documentation for a function is stored in the function - definition itself (*note Lambda Expressions::). The function - `documentation' knows how to extract it. - - * The documentation for a variable is stored in the variable's - property list under the property name `variable-documentation'. - The function `documentation-property' knows how to extract it. - - To save space, the documentation for preloaded functions and -variables (including primitive functions and autoloaded functions) is -stored in the "internal doc file" `DOC'. The documentation for -functions and variables loaded during the XEmacs session from -byte-compiled files is stored in those very same byte-compiled files -(*note Docs and Compilation::). - - XEmacs does not keep documentation strings in memory unless -necessary. Instead, XEmacs maintains, for preloaded symbols, an -integer offset into the internal doc file, and for symbols loaded from -byte-compiled files, a list containing the filename of the -byte-compiled file and an integer offset, in place of the documentation -string. The functions `documentation' and `documentation-property' use -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. - - The `emacs/lib-src' directory contains two utilities that you can -use to print nice-looking hardcopy for the file -`emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'. - - -File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation - -Access to Documentation Strings -=============================== - - - Function: documentation-property symbol property &optional verbatim - This function returns the documentation string that is recorded in - SYMBOL's property list under property PROPERTY. It retrieves the - text from a file if necessary, and runs `substitute-command-keys' - to substitute actual key bindings. (This substitution is not done - if VERBATIM is non-`nil'; the VERBATIM argument exists only as of - Emacs 19.) - - (documentation-property 'command-line-processed - 'variable-documentation) - => "t once command line has been processed" - (symbol-plist 'command-line-processed) - => (variable-documentation 188902) - - - Function: documentation function &optional verbatim - This function returns the documentation string of FUNCTION. It - reads the text from a file if necessary. Then (unless VERBATIM is - non-`nil') it calls `substitute-command-keys', to return a value - containing the actual (current) key bindings. - - The function `documentation' signals a `void-function' error if - FUNCTION has no function definition. However, it is ok if the - function definition has no documentation string. In that case, - `documentation' returns `nil'. - - Here is an example of using the two functions, `documentation' and -`documentation-property', to display the documentation strings for -several symbols in a `*Help*' buffer. - - (defun describe-symbols (pattern) - "Describe the XEmacs Lisp symbols matching PATTERN. - All symbols that have PATTERN in their name are described - in the `*Help*' buffer." - (interactive "sDescribe symbols matching: ") - (let ((describe-func - (function - (lambda (s) - ;; Print description of symbol. - (if (fboundp s) ; It is a function. - (princ - (format "%s\t%s\n%s\n\n" s - (if (commandp s) - (let ((keys (where-is-internal s))) - (if keys - (concat - "Keys: " - (mapconcat 'key-description - keys " ")) - "Keys: none")) - "Function") - (or (documentation s) - "not documented")))) - - (if (boundp s) ; It is a variable. - (princ - (format "%s\t%s\n%s\n\n" s - (if (user-variable-p s) - "Option " "Variable") - (or (documentation-property - s 'variable-documentation) - "not documented"))))))) - sym-list) - - ;; Build a list of symbols that match pattern. - (mapatoms (function - (lambda (sym) - (if (string-match pattern (symbol-name sym)) - (setq sym-list (cons sym sym-list)))))) - - ;; Display the data. - (with-output-to-temp-buffer "*Help*" - (mapcar describe-func (sort sym-list 'string<)) - (print-help-return-message)))) - - The `describe-symbols' function works like `apropos', but provides -more information. - - (describe-symbols "goal") - - ---------- Buffer: *Help* ---------- - goal-column Option - *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil. - - set-goal-column Command: C-x C-n - Set the current horizontal position as a goal for C-n and C-p. - Those commands will move to this position in the line moved to - rather than trying to keep the same horizontal position. - With a non-nil argument, clears out the goal column - so that C-n and C-p resume vertical motion. - The goal column is stored in the variable `goal-column'. - - temporary-goal-column Variable - Current goal column for vertical motion. - It is the column where point was - at the start of current run of vertical motion commands. - When the `track-eol' feature is doing its job, the value is 9999. - ---------- Buffer: *Help* ---------- - - - Function: Snarf-documentation filename - This function is used only during XEmacs initialization, just - before the runnable XEmacs is dumped. It finds the file offsets - of the documentation strings stored in the file FILENAME, and - records them in the in-core function definitions and variable - property lists in place of the actual strings. *Note Building - XEmacs::. - - XEmacs finds the file FILENAME in the `lib-src' directory. When - the dumped XEmacs is later executed, the same file is found in the - directory `doc-directory'. The usual value for FILENAME is `DOC', - but this can be changed by modifying the variable - `internal-doc-file-name'. - - - Variable: internal-doc-file-name - This variable holds the name of the file containing documentation - strings of built-in symbols, usually `DOC'. The full pathname of - the internal doc file is `(concat doc-directory - internal-doc-file-name)'. - - - Variable: doc-directory - This variable holds the name of the directory which contains the - "internal doc file" that contains documentation strings for - built-in and preloaded functions and variables. - - In most cases, this is the same as `exec-directory'. They may be - different when you run XEmacs from the directory where you built - it, without actually installing it. See `exec-directory' in *Note - Help Functions::. - - In older Emacs versions, `exec-directory' was used for this. - - - Variable: data-directory - This variable holds the name of the directory in which XEmacs finds - certain system independent documentation and text files that come - with XEmacs. In older Emacs versions, `exec-directory' was used - for this. -