X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-22;h=fd881c34e6e66f376ec3ff8dcacf2d002fb5f9d3;hb=4ed57cfee6165320a51f1dd2432f2cc610d0bfcf;hp=b11b775c93a6ae50ffedca0ce60c9d56ec36fd38;hpb=7d6edaefa00e7b7e102354283824a4f6a721b71a;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-22 b/info/lispref.info-22 index b11b775..fd881c3 100644 --- a/info/lispref.info-22 +++ b/info/lispref.info-22 @@ -50,6 +50,969 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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 +`modeline-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 string, symbol, glyph, generic +specifier, list or cons cell. + +`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 processed 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. + +`GLYPH' + A glyph is displayed as is. + +`GENERIC-SPECIFIER' + A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands + for its instance. The instance of GENERIC-SPECIFIER is computed + in the current window using the equivalent of `specifier-instance' + and the value is processed. + +`(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")'. + +`(EXTENT REST...)' + A list whose car is an extent means the cdr of the list is + processed normally but the results are displayed using the face of + the extent, and mouse clicks over this section are processed using + the keymap of the extent. (In addition, if the extent has a + help-echo property, that string will be echoed when the mouse + moves over this section.) If extents are nested, all keymaps are + properly consulted when processing mouse clicks, but multiple + faces are not correctly merged (only the first face is used), and + lists of faces are not correctly handled. + + 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::). + +`%C' + Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'. + +`%[' + 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. + + File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation Substituting Key Bindings in Documentation @@ -116,14 +1079,14 @@ XEmacs Lisp. (substitute-command-keys "Substrings of the form \\=\\{MAPVAR} are replaced by summaries - \(made by describe-bindings) of the value of MAPVAR, taken as a keymap. + \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \\=\\ specify to use the value of MAPVAR as the keymap for future \\=\\[COMMAND] substrings. \\=\\= quotes the following character and is discarded; thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.") => "Substrings of the form \{MAPVAR} are replaced by summaries - (made by describe-bindings) of the value of MAPVAR, taken as a keymap. + (made by `describe-bindings') of the value of MAPVAR, taken as a keymap. Substrings of the form \ specify to use the value of MAPVAR as the keymap for future \[COMMAND] substrings. \= quotes the following character and is discarded; @@ -182,930 +1145,3 @@ the character itself. (text-char-description ?\C-\M-m) => "M-^M" - -File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation - -Help Functions -============== - - XEmacs provides a variety of on-line help functions, all accessible -to the user as subcommands of the prefix `C-h', or on some keyboards, -`help'. For more information about them, see *Note Help: (emacs)Help. -Here we describe some program-level interfaces to the same information. - - - Command: apropos regexp &optional do-all predicate - This function finds all symbols whose names contain a match for the - regular expression REGEXP, and returns a list of them (*note - Regular Expressions::). It also displays the symbols in a buffer - named `*Help*', each with a one-line description. - - If DO-ALL is non-`nil', then `apropos' also shows key bindings for - the functions that are found. - - If PREDICATE is non-`nil', it should be a function to be called on - each symbol that has matched REGEXP. Only symbols for which - PREDICATE returns a non-`nil' value are listed or displayed. - - In the first of the following examples, `apropos' finds all the - symbols with names containing `exec'. In the second example, it - finds and returns only those symbols that are also commands. (We - don't show the output that results in the `*Help*' buffer.) - - (apropos "exec") - => (Buffer-menu-execute command-execute exec-directory - exec-path execute-extended-command execute-kbd-macro - executing-kbd-macro executing-macro) - - (apropos "exec" nil 'commandp) - => (Buffer-menu-execute execute-extended-command) - - `apropos' is used by various user-level commands, such as `C-h a' - (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A' - (`command-apropos'), which does an apropos over only those - functions which are user commands. `command-apropos' calls - `apropos', specifying a PREDICATE to restrict the output to - symbols that are commands. The call to `apropos' looks like this: - - (apropos string t 'commandp) - - - Variable: help-map - The value of this variable is a local keymap for characters - following the Help key, `C-h'. - - - Prefix Command: help-command - This symbol is not a function; its function definition is actually - the keymap known as `help-map'. It is defined in `help.el' as - follows: - - (define-key global-map "\C-h" 'help-command) - (fset 'help-command help-map) - - - Function: print-help-return-message &optional function - This function builds a string that explains how to restore the - previous state of the windows after a help command. After - building the message, it applies FUNCTION to it if FUNCTION is - non-`nil'. Otherwise it calls `message' to display it in the echo - area. - - This function expects to be called inside a - `with-output-to-temp-buffer' special form, and expects - `standard-output' to have the value bound by that special form. - For an example of its use, see the long example in *Note Accessing - Documentation::. - - - Variable: help-char - The value of this variable is the help character--the character - that XEmacs recognizes as meaning Help. By default, it is the - character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this - character, if `help-form' is non-`nil' Lisp expression, it - evaluates that expression, and displays the result in a window if - it is a string. - - `help-char' can be a character or a key description such as `help' - or `(meta h)'. - - Usually the value of `help-form''s value is `nil'. Then the help - character has no special meaning at the level of command input, and - it becomes part of a key sequence in the normal way. The standard - key binding of `C-h' is a prefix key for several general-purpose - help features. - - The help character is special after prefix keys, too. If it has no - binding as a subcommand of the prefix key, it runs - `describe-prefix-bindings', which displays a list of all the - subcommands of the prefix key. - - - Variable: help-form - If this variable is non-`nil', its value is a form to evaluate - whenever the character `help-char' is read. If evaluating the form - produces a string, that string is displayed. - - A command that calls `next-command-event' or `next-event' probably - should bind `help-form' to a non-`nil' expression while it does - input. (The exception is when `C-h' is meaningful input.) - Evaluating this expression should result in a string that explains - what the input is for and how to enter it properly. - - Entry to the minibuffer binds this variable to the value of - `minibuffer-help-form' (*note Minibuffer Misc::). - - - Variable: prefix-help-command - This variable holds a function to print help for a prefix - character. The function is called when the user types a prefix - key followed by the help character, and the help character has no - binding after that prefix. The variable's default value is - `describe-prefix-bindings'. - - - Function: describe-prefix-bindings - This function calls `describe-bindings' to display a list of all - the subcommands of the prefix key of the most recent key sequence. - The prefix described consists of all but the last event of that - key sequence. (The last event is, presumably, the help character.) - - The following two functions are found in the library `helper'. They -are for modes that want to provide help without relinquishing control, -such as the "electric" modes. You must load that library with -`(require 'helper)' in order to use them. Their names begin with -`Helper' to distinguish them from the ordinary help functions. - - - Command: Helper-describe-bindings - This command pops up a window displaying a help buffer containing a - listing of all of the key bindings from both the local and global - keymaps. It works by calling `describe-bindings'. - - - Command: Helper-help - This command provides help for the current mode. It prompts the - user in the minibuffer with the message `Help (Type ? for further - options)', and then provides assistance in finding out what the key - bindings are, and what the mode is intended for. It returns `nil'. - - This can be customized by changing the map `Helper-help-map'. - - -File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation - -Obsoleteness -============ - - As you add functionality to a package, you may at times want to -replace an older function with a new one. To preserve compatibility -with existing code, the older function needs to still exist; but users -of that function should be told to use the newer one instead. XEmacs -Lisp lets you mark a function or variable as "obsolete", and indicate -what should be used instead. - - - Function: make-obsolete function new - This function indicates that FUNCTION is an obsolete function, and - the function NEW should be used instead. The byte compiler will - issue a warning to this effect when it encounters a usage of the - older function, and the help system will also note this in the - function's documentation. NEW can also be a string (if there is - not a single function with the same functionality any more), and - should be a descriptive statement, such as "use FOO or BAR - instead" or "this function is unnecessary". - - - Function: make-obsolete-variable variable new - This is like `make-obsolete' but is for variables instead of - functions. - - - Function: define-obsolete-function-alias oldfun newfun - This function combines `make-obsolete' and `define-function', - declaring OLDFUN to be an obsolete variant of NEWFUN and defining - OLDFUN as an alias for NEWFUN. - - - Function: define-obsolete-variable-alias oldvar newvar - This is like `define-obsolete-function-alias' but for variables. - - Note that you should not normally put obsoleteness information -explicitly in a function or variable's doc string. The obsoleteness -information that you specify using the above functions will be displayed -whenever the doc string is displayed, and by adding it explicitly the -result is redundancy. - - Also, if an obsolete function is substantially the same as a newer -one but is not actually an alias, you should consider omitting the doc -string entirely (use a null string `""' as the doc string). That way, -the user is told about the obsoleteness and is forced to look at the -documentation of the new function, making it more likely that he will -use the new function. - - - Function: function-obsoleteness-doc function - If FUNCTION is obsolete, this function returns a string describing - this. This is the message that is printed out during byte - compilation or in the function's documentation. If FUNCTION is - not obsolete, `nil' is returned. - - - Function: variable-obsoleteness-doc variable - This is like `function-obsoleteness-doc' but for variables. - - The obsoleteness information is stored internally by putting a -property `byte-obsolete-info' (for functions) or -`byte-obsolete-variable' (for variables) on the symbol that specifies -the obsolete function or variable. For more information, see the -implementation of `make-obsolete' and `make-obsolete-variable' in -`lisp/bytecomp/bytecomp-runtime.el'. - - -File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top - -Files -***** - - In XEmacs, you can find, create, view, save, and otherwise work with -files and file directories. This chapter describes most of the -file-related functions of XEmacs Lisp, but a few others are described in -*Note Buffers::, and those related to backups and auto-saving are -described in *Note Backups and Auto-Saving::. - - Many of the file functions take one or more arguments that are file -names. A file name is actually a string. Most of these functions -expand file name arguments using `expand-file-name', so that `~' is -handled correctly, as are relative file names (including `../'). These -functions don't recognize environment variable substitutions such as -`$HOME'. *Note File Name Expansion::. - -* Menu: - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing File Attributes:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Defining "magic" special handling - for certain file names. -* Partial Files:: Treating a section of a buffer as a file. -* Format Conversion:: Conversion to and from various file formats. -* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS. - - -File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files - -Visiting Files -============== - - Visiting a file means reading a file into a buffer. Once this is -done, we say that the buffer is "visiting" that file, and call the file -"the visited file" of the buffer. - - A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of XEmacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; then we -say the buffer is visiting that file. The copy in the buffer is what -you modify with editing commands. Such changes to the buffer do not -change the file; therefore, to make the changes permanent, you must -"save" the buffer, which means copying the altered buffer contents back -into the file. - - In spite of the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we say, -"I am editing a file," rather than, "I am editing a buffer that I will -soon save as a file of the same name." Humans do not usually need to -make the distinction explicit. When dealing with a computer program, -however, it is good to keep the distinction in mind. - -* Menu: - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - - -File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files - -Functions for Visiting Files ----------------------------- - - This section describes the functions normally used to visit files. -For historical reasons, these functions have names starting with -`find-' rather than `visit-'. *Note Buffer File Name::, for functions -and variables that access the visited file name of a buffer or that -find an existing buffer by its visited file name. - - In a Lisp program, if you want to look at the contents of a file but -not alter it, the fastest way is to use `insert-file-contents' in a -temporary buffer. Visiting the file is not necessary and takes longer. -*Note Reading from Files::. - - - Command: find-file filename - This command selects a buffer visiting the file FILENAME, using an - existing buffer if there is one, and otherwise creating a new - buffer and reading the file into it. It also returns that buffer. - - The body of the `find-file' function is very simple and looks like - this: - - (switch-to-buffer (find-file-noselect filename)) - - (See `switch-to-buffer' in *Note Displaying Buffers::.) - - When `find-file' is called interactively, it prompts for FILENAME - in the minibuffer. - - - Function: find-file-noselect filename &optional nowarn - This function is the guts of all the file-visiting functions. It - finds or creates a buffer visiting the file FILENAME, and returns - it. It uses an existing buffer if there is one, and otherwise - creates a new buffer and reads the file into it. You may make the - buffer current or display it in a window if you wish, but this - function does not do so. - - When `find-file-noselect' uses an existing buffer, it first - verifies that the file has not changed since it was last visited or - saved in that buffer. If the file has changed, then this function - asks the user whether to reread the changed file. If the user says - `yes', any changes previously made in the buffer are lost. - - If `find-file-noselect' needs to create a buffer, and there is no - file named FILENAME, it displays the message `New file' in the - echo area, and leaves the buffer empty. - - If NO-WARN is non-`nil', various warnings that XEmacs normally - gives (e.g. if another buffer is already visiting FILENAME but - FILENAME has been removed from disk since that buffer was created) - are suppressed. - - The `find-file-noselect' function calls `after-find-file' after - reading the file (*note Subroutines of Visiting::). That function - sets the buffer major mode, parses local variables, warns the user - if there exists an auto-save file more recent than the file just - visited, and finishes by running the functions in - `find-file-hooks'. - - The `find-file-noselect' function returns the buffer that is - visiting the file FILENAME. - - (find-file-noselect "/etc/fstab") - => # - - - Command: find-file-other-window filename - This command selects a buffer visiting the file FILENAME, but does - so in a window other than the selected window. It may use another - existing window or split a window; see *Note Displaying Buffers::. - - When this command is called interactively, it prompts for FILENAME. - - - Command: find-file-read-only filename - This command selects a buffer visiting the file FILENAME, like - `find-file', but it marks the buffer as read-only. *Note Read - Only Buffers::, for related functions and variables. - - When this command is called interactively, it prompts for FILENAME. - - - Command: view-file filename - This command visits FILENAME in View mode, and displays it in a - recursive edit, returning to the previous buffer when done. View - mode is a mode that allows you to skim rapidly through the file - but does not let you modify it. Entering View mode runs the - normal hook `view-mode-hook'. *Note Hooks::. - - When `view-file' is called interactively, it prompts for FILENAME. - - - Variable: find-file-hooks - The value of this variable is a list of functions to be called - after a file is visited. The file's local-variables specification - (if any) will have been processed before the hooks are run. The - buffer visiting the file is current when the hook functions are - run. - - This variable works just like a normal hook, but we think that - renaming it would not be advisable. - - - Variable: find-file-not-found-hooks - The value of this variable is a list of functions to be called when - `find-file' or `find-file-noselect' is passed a nonexistent file - name. `find-file-noselect' calls these functions as soon as it - detects a nonexistent file. It calls them in the order of the - list, until one of them returns non-`nil'. `buffer-file-name' is - already set up. - - This is not a normal hook because the values of the functions are - used and they may not all be called. - - -File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files - -Subroutines of Visiting ------------------------ - - The `find-file-noselect' function uses the `create-file-buffer' and -`after-find-file' functions as subroutines. Sometimes it is useful to -call them directly. - - - Function: create-file-buffer filename - This function creates a suitably named buffer for visiting - FILENAME, and returns it. It uses FILENAME (sans directory) as - the name if that name is free; otherwise, it appends a string such - as `<2>' to get an unused name. See also *Note Creating Buffers::. - - *Please note:* `create-file-buffer' does _not_ associate the new - buffer with a file and does not select the buffer. It also does - not use the default major mode. - - (create-file-buffer "foo") - => # - (create-file-buffer "foo") - => #> - (create-file-buffer "foo") - => #> - - This function is used by `find-file-noselect'. It uses - `generate-new-buffer' (*note Creating Buffers::). - - - Function: after-find-file &optional error warn noauto - This function sets the buffer major mode, and parses local - variables (*note Auto Major Mode::). It is called by - `find-file-noselect' and by the default revert function (*note - Reverting::). - - If reading the file got an error because the file does not exist, - but its directory does exist, the caller should pass a non-`nil' - value for ERROR. In that case, `after-find-file' issues a warning: - `(New File)'. For more serious errors, the caller should usually - not call `after-find-file'. - - If WARN is non-`nil', then this function issues a warning if an - auto-save file exists and is more recent than the visited file. - - If NOAUTO is non-`nil', then this function does not turn on - auto-save mode; otherwise, it does. - - The last thing `after-find-file' does is call all the functions in - `find-file-hooks'. - - -File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files - -Saving Buffers -============== - - When you edit a file in XEmacs, you are actually working on a buffer -that is visiting that file--that is, the contents of the file are -copied into the buffer and the copy is what you edit. Changes to the -buffer do not change the file until you "save" the buffer, which means -copying the contents of the buffer into the file. - - - Command: save-buffer &optional backup-option - This function saves the contents of the current buffer in its - visited file if the buffer has been modified since it was last - visited or saved. Otherwise it does nothing. - - `save-buffer' is responsible for making backup files. Normally, - BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only - if this is the first save since visiting the file. Other values - for BACKUP-OPTION request the making of backup files in other - circumstances: - - * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the - `save-buffer' function marks this version of the file to be - backed up when the buffer is next saved. - - * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the - `save-buffer' function unconditionally backs up the previous - version of the file before saving it. - - - Command: save-some-buffers &optional save-silently-p exiting - This command saves some modified file-visiting buffers. Normally - it asks the user about each buffer. But if SAVE-SILENTLY-P is - non-`nil', it saves all the file-visiting buffers without querying - the user. - - The optional EXITING argument, if non-`nil', requests this - function to offer also to save certain other buffers that are not - visiting files. These are buffers that have a non-`nil' local - value of `buffer-offer-save'. (A user who says yes to saving one - of these is asked to specify a file name to use.) The - `save-buffers-kill-emacs' function passes a non-`nil' value for - this argument. - - - Variable: buffer-offer-save - When this variable is non-`nil' in a buffer, XEmacs offers to save - the buffer on exit even if the buffer is not visiting a file. The - variable is automatically local in all buffers. Normally, Mail - mode (used for editing outgoing mail) sets this to `t'. - - - Command: write-file filename - This function writes the current buffer into file FILENAME, makes - the buffer visit that file, and marks it not modified. Then it - renames the buffer based on FILENAME, appending a string like `<2>' - if necessary to make a unique buffer name. It does most of this - work by calling `set-visited-file-name' and `save-buffer'. - - - Variable: write-file-hooks - The value of this variable is a list of functions to be called - before writing out a buffer to its visited file. If one of them - returns non-`nil', the file is considered already written and the - rest of the functions are not called, nor is the usual code for - writing the file executed. - - If a function in `write-file-hooks' returns non-`nil', it is - responsible for making a backup file (if that is appropriate). To - do so, execute the following code: - - (or buffer-backed-up (backup-buffer)) - - You might wish to save the file modes value returned by - `backup-buffer' and use that to set the mode bits of the file that - you write. This is what `save-buffer' normally does. - - Even though this is not a normal hook, you can use `add-hook' and - `remove-hook' to manipulate the list. *Note Hooks::. - - - Variable: local-write-file-hooks - This works just like `write-file-hooks', but it is intended to be - made local to particular buffers. It's not a good idea to make - `write-file-hooks' local to a buffer--use this variable instead. - - The variable is marked as a permanent local, so that changing the - major mode does not alter a buffer-local value. This is - convenient for packages that read "file" contents in special ways, - and set up hooks to save the data in a corresponding way. - - - Variable: write-contents-hooks - This works just like `write-file-hooks', but it is intended for - hooks that pertain to the contents of the file, as opposed to - hooks that pertain to where the file came from. Such hooks are - usually set up by major modes, as buffer-local bindings for this - variable. Switching to a new major mode always resets this - variable. - - - Variable: after-save-hook - This normal hook runs after a buffer has been saved in its visited - file. - - - Variable: file-precious-flag - If this variable is non-`nil', then `save-buffer' protects against - I/O errors while saving by writing the new file to a temporary - name instead of the name it is supposed to have, and then renaming - it to the intended name after it is clear there are no errors. - This procedure prevents problems such as a lack of disk space from - resulting in an invalid file. - - As a side effect, backups are necessarily made by copying. *Note - Rename or Copy::. Yet, at the same time, saving a precious file - always breaks all hard links between the file you save and other - file names. - - Some modes set this variable non-`nil' locally in particular - buffers. - - - User Option: require-final-newline - This variable determines whether files may be written out that do - _not_ end with a newline. If the value of the variable is `t', - then `save-buffer' silently adds a newline at the end of the file - whenever the buffer being saved does not already end in one. If - the value of the variable is non-`nil', but not `t', then - `save-buffer' asks the user whether to add a newline each time the - case arises. - - If the value of the variable is `nil', then `save-buffer' doesn't - add newlines at all. `nil' is the default value, but a few major - modes set it to `t' in particular buffers. - - -File: lispref.info, Node: Reading from Files, Next: Writing to Files, Prev: Saving Buffers, Up: Files - -Reading from Files -================== - - You can copy a file from the disk and insert it into a buffer using -the `insert-file-contents' function. Don't use the user-level command -`insert-file' in a Lisp program, as that sets the mark. - - - Function: insert-file-contents filename &optional visit beg end - replace - This function inserts the contents of file FILENAME into the - current buffer after point. It returns a list of the absolute - file name and the length of the data inserted. An error is - signaled if FILENAME is not the name of a file that can be read. - - The function `insert-file-contents' checks the file contents - against the defined file formats, and converts the file contents if - appropriate. *Note Format Conversion::. It also calls the - functions in the list `after-insert-file-functions'; see *Note - Saving Properties::. - - If VISIT is non-`nil', this function additionally marks the buffer - as unmodified and sets up various fields in the buffer so that it - is visiting the file FILENAME: these include the buffer's visited - file name and its last save file modtime. This feature is used by - `find-file-noselect' and you probably should not use it yourself. - - If BEG and END are non-`nil', they should be integers specifying - the portion of the file to insert. In this case, VISIT must be - `nil'. For example, - - (insert-file-contents filename nil 0 500) - - inserts the first 500 characters of a file. - - If the argument REPLACE is non-`nil', it means to replace the - contents of the buffer (actually, just the accessible portion) - with the contents of the file. This is better than simply - deleting the buffer contents and inserting the whole file, because - (1) it preserves some marker positions and (2) it puts less data - in the undo list. - - If you want to pass a file name to another process so that another -program can read the file, use the function `file-local-copy'; see -*Note Magic File Names::. - - -File: lispref.info, Node: Writing to Files, Next: File Locks, Prev: Reading from Files, Up: Files - -Writing to Files -================ - - You can write the contents of a buffer, or part of a buffer, directly -to a file on disk using the `append-to-file' and `write-region' -functions. Don't use these functions to write to files that are being -visited; that could cause confusion in the mechanisms for visiting. - - - Command: append-to-file start end filename - This function appends the contents of the region delimited by - START and END in the current buffer to the end of file FILENAME. - If that file does not exist, it is created. If that file exists - it is overwritten. This function returns `nil'. - - An error is signaled if FILENAME specifies a nonwritable file, or - a nonexistent file in a directory where files cannot be created. - - - Command: write-region start end filename &optional append visit - This function writes the region delimited by START and END in the - current buffer into the file specified by FILENAME. - - If START is a string, then `write-region' writes or appends that - string, rather than text from the buffer. - - If APPEND is non-`nil', then the specified text is appended to the - existing file contents (if any). - - If VISIT is `t', then XEmacs establishes an association between - the buffer and the file: the buffer is then visiting that file. - It also sets the last file modification time for the current - buffer to FILENAME's modtime, and marks the buffer as not - modified. This feature is used by `save-buffer', but you probably - should not use it yourself. - - If VISIT is a string, it specifies the file name to visit. This - way, you can write the data to one file (FILENAME) while recording - the buffer as visiting another file (VISIT). The argument VISIT - is used in the echo area message and also for file locking; VISIT - is stored in `buffer-file-name'. This feature is used to - implement `file-precious-flag'; don't use it yourself unless you - really know what you're doing. - - The function `write-region' converts the data which it writes to - the appropriate file formats specified by `buffer-file-format'. - *Note Format Conversion::. It also calls the functions in the list - `write-region-annotate-functions'; see *Note Saving Properties::. - - Normally, `write-region' displays a message `Wrote file FILENAME' - in the echo area. If VISIT is neither `t' nor `nil' nor a string, - then this message is inhibited. This feature is useful for - programs that use files for internal purposes, files that the user - does not need to know about. - - -File: lispref.info, Node: File Locks, Next: Information about Files, Prev: Writing to Files, Up: Files - -File Locks -========== - - When two users edit the same file at the same time, they are likely -to interfere with each other. XEmacs tries to prevent this situation -from arising by recording a "file lock" when a file is being modified. -XEmacs can then detect the first attempt to modify a buffer visiting a -file that is locked by another XEmacs process, and ask the user what to -do. - - File locks do not work properly when multiple machines can share -file systems, such as with NFS. Perhaps a better file locking system -will be implemented in the future. When file locks do not work, it is -possible for two users to make changes simultaneously, but XEmacs can -still warn the user who saves second. Also, the detection of -modification of a buffer visiting a file changed on disk catches some -cases of simultaneous editing; see *Note Modification Time::. - - - Function: file-locked-p &optional filename - This function returns `nil' if the file FILENAME is not locked by - this XEmacs process. It returns `t' if it is locked by this - XEmacs, and it returns the name of the user who has locked it if it - is locked by someone else. - - (file-locked-p "foo") - => nil - - - Function: lock-buffer &optional filename - This function locks the file FILENAME, if the current buffer is - modified. The argument FILENAME defaults to the current buffer's - visited file. Nothing is done if the current buffer is not - visiting a file, or is not modified. - - - Function: unlock-buffer - This function unlocks the file being visited in the current buffer, - if the buffer is modified. If the buffer is not modified, then - the file should not be locked, so this function does nothing. It - also does nothing if the current buffer is not visiting a file. - - - Function: ask-user-about-lock file other-user - This function is called when the user tries to modify FILE, but it - is locked by another user named OTHER-USER. The value it returns - determines what happens next: - - * A value of `t' says to grab the lock on the file. Then this - user may edit the file and OTHER-USER loses the lock. - - * A value of `nil' says to ignore the lock and let this user - edit the file anyway. - - * This function may instead signal a `file-locked' error, in - which case the change that the user was about to make does - not take place. - - The error message for this error looks like this: - - error--> File is locked: FILE OTHER-USER - - where `file' is the name of the file and OTHER-USER is the - name of the user who has locked the file. - - The default definition of this function asks the user to choose - what to do. If you wish, you can replace the `ask-user-about-lock' - function with your own version that decides in another way. The - code for its usual definition is in `userlock.el'. - - -File: lispref.info, Node: Information about Files, Next: Changing File Attributes, Prev: File Locks, Up: Files - -Information about Files -======================= - - The functions described in this section all operate on strings that -designate file names. All the functions have names that begin with the -word `file'. These functions all return information about actual files -or directories, so their arguments must all exist as actual files or -directories unless otherwise noted. - -* Menu: - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. - - -File: lispref.info, Node: Testing Accessibility, Next: Kinds of Files, Up: Information about Files - -Testing Accessibility ---------------------- - - These functions test for permission to access a file in specific -ways. - - - Function: file-exists-p filename - This function returns `t' if a file named FILENAME appears to - exist. This does not mean you can necessarily read the file, only - that you can find out its attributes. (On Unix, this is true if - the file exists and you have execute permission on the containing - directories, regardless of the protection of the file itself.) - - If the file does not exist, or if fascist access control policies - prevent you from finding the attributes of the file, this function - returns `nil'. - - - Function: file-readable-p filename - This function returns `t' if a file named FILENAME exists and you - can read it. It returns `nil' otherwise. - - (file-readable-p "files.texi") - => t - (file-exists-p "/usr/spool/mqueue") - => t - (file-readable-p "/usr/spool/mqueue") - => nil - - - Function: file-executable-p filename - This function returns `t' if a file named FILENAME exists and you - can execute it. It returns `nil' otherwise. If the file is a - directory, execute permission means you can check the existence and - attributes of files inside the directory, and open those files if - their modes permit. - - - Function: file-writable-p filename - This function returns `t' if the file FILENAME can be written or - created by you, and `nil' otherwise. A file is writable if the - file exists and you can write it. It is creatable if it does not - exist, but the specified directory does exist and you can write in - that directory. - - In the third example below, `foo' is not writable because the - parent directory does not exist, even though the user could create - such a directory. - - (file-writable-p "~/foo") - => t - (file-writable-p "/foo") - => nil - (file-writable-p "~/no-such-dir/foo") - => nil - - - Function: file-accessible-directory-p dirname - This function returns `t' if you have permission to open existing - files in the directory whose name as a file is DIRNAME; otherwise - (or if there is no such directory), it returns `nil'. The value - of DIRNAME may be either a directory name or the file name of a - directory. - - Example: after the following, - - (file-accessible-directory-p "/foo") - => nil - - we can deduce that any attempt to read a file in `/foo/' will give - an error. - - - Function: file-ownership-preserved-p filename - This function returns `t' if deleting the file FILENAME and then - creating it anew would keep the file's owner unchanged. - - - Function: file-newer-than-file-p filename1 filename2 - This function returns `t' if the file FILENAME1 is newer than file - FILENAME2. If FILENAME1 does not exist, it returns `nil'. If - FILENAME2 does not exist, it returns `t'. - - In the following example, assume that the file `aug-19' was written - on the 19th, `aug-20' was written on the 20th, and the file - `no-file' doesn't exist at all. - - (file-newer-than-file-p "aug-19" "aug-20") - => nil - (file-newer-than-file-p "aug-20" "aug-19") - => t - (file-newer-than-file-p "aug-19" "no-file") - => t - (file-newer-than-file-p "no-file" "aug-19") - => nil - - You can use `file-attributes' to get a file's last modification - time as a list of two numbers. *Note File Attributes::. - - -File: lispref.info, Node: Kinds of Files, Next: Truenames, Prev: Testing Accessibility, Up: Information about Files - -Distinguishing Kinds of Files ------------------------------ - - This section describes how to distinguish various kinds of files, -such as directories, symbolic links, and ordinary files. - - - Function: file-symlink-p filename - If the file FILENAME is a symbolic link, the `file-symlink-p' - function returns the file name to which it is linked. This may be - the name of a text file, a directory, or even another symbolic - link, or it may be a nonexistent file name. - - If the file FILENAME is not a symbolic link (or there is no such - file), `file-symlink-p' returns `nil'. - - (file-symlink-p "foo") - => nil - (file-symlink-p "sym-link") - => "foo" - (file-symlink-p "sym-link2") - => "sym-link" - (file-symlink-p "/bin") - => "/pub/bin" - - - - Function: file-directory-p filename - This function returns `t' if FILENAME is the name of an existing - directory, `nil' otherwise. - - (file-directory-p "~rms") - => t - (file-directory-p "~rms/lewis/files.texi") - => nil - (file-directory-p "~rms/lewis/no-such-file") - => nil - (file-directory-p "$HOME") - => nil - (file-directory-p - (substitute-in-file-name "$HOME")) - => t - - - Function: file-regular-p filename - This function returns `t' if the file FILENAME exists and is a - regular file (not a directory, symbolic link, named pipe, - terminal, or other I/O device). - - -File: lispref.info, Node: Truenames, Next: File Attributes, Prev: Kinds of Files, Up: Information about Files - -Truenames ---------- - - The "truename" of a file is the name that you get by following -symbolic links until none remain, then expanding to get rid of `.' and -`..' as components. Strictly speaking, a file need not have a unique -truename; the number of distinct truenames a file has is equal to the -number of hard links to the file. However, truenames are useful -because they eliminate symbolic links as a cause of name variation. - - - Function: file-truename filename &optional default - The function `file-truename' returns the true name of the file - FILENAME. This is the name that you get by following symbolic - links until none remain. - - If the filename is relative, DEFAULT is the directory to start - with. If DEFAULT is `nil' or missing, the current buffer's value - of `default-directory' is used. - - *Note Buffer File Name::, for related information. -