-\1f
-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'.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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")
- => #<buffer 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.
-
-\1f
-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")
- => #<buffer foo>
- (create-file-buffer "foo")
- => #<buffer foo<2>>
- (create-file-buffer "foo")
- => #<buffer foo<3>>
-
- 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'.
-