Commit b22f3a19 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

*** empty log message ***

parent ec221d13
This diff is collapsed.
......@@ -193,10 +193,14 @@ string. See @code{format} in @ref{String Conversion}, for the details
on the conversion specifications. @code{message} returns the
constructed string.
In batch mode, @code{message} prints the message text on the standard
error stream, followed by a newline.
@c Emacs 19 feature
If @var{string} is @code{nil}, @code{message} clears the echo area. If
the minibuffer is active, this brings the minibuffer contents back onto
the screen immediately.
@example
@group
(message "Minibuffer depth is %d."
......@@ -881,7 +885,7 @@ The value of @code{blink-paren-function} may be @code{nil}, in which
case nothing is done.
@quotation
@strong{Please note:} this variable was named @code{blink-paren-hook} in
@strong{Please note:} This variable was named @code{blink-paren-hook} in
older Emacs versions, but since it is not called with the standard
convention for hooks, it was renamed to @code{blink-paren-function} in
version 19.
......
......@@ -13,6 +13,13 @@ file-related functions of Emacs Lisp, but a few others are described in
@ref{Buffers}, and those related to backups and auto-saving are
described in @ref{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 @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
@samp{../}). These functions don't recognize environment variable
substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
@menu
* Visiting Files:: Reading files into Emacs buffers for editing.
* Saving Buffers:: Writing changed buffers back into files.
......@@ -52,7 +59,7 @@ 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 which I
``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.
......@@ -153,7 +160,7 @@ When this command is called interactively, it prompts for
@end deffn
@deffn Command view-file filename
This command views @var{filename} in View mode, returning to the
This command visits @var{filename} in View mode, 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 @code{view-mode-hook}. @xref{Hooks}.
......@@ -256,9 +263,9 @@ Otherwise it does nothing.
@code{save-buffer} is responsible for making backup files. Normally,
@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
file only if this is the first save or if the buffer was previously
modified. Other values for @var{backup-option} request the making of
backup files in other circumstances:
file only if this is the first save since visiting the file. Other
values for @var{backup-option} request the making of backup files in
other circumstances:
@itemize @bullet
@item
......@@ -479,7 +486,7 @@ Normally, @code{write-region} displays a message @samp{Wrote file
@var{filename}} in the echo area. If @var{visit} is neither @code{t}
nor @code{nil} nor a string, then this message is inhibited. This
feature is useful for programs that use files for internal purposes,
files which the user does not need to know about.
files that the user does not need to know about.
@end deffn
@node File Locks
......@@ -530,7 +537,7 @@ does nothing if the current buffer is not visiting a file.
@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
is locked by another user name @var{other-user}. The value it returns
is locked by another user named @var{other-user}. The value it returns
determines what happens next:
@itemize @bullet
......@@ -567,19 +574,11 @@ for its usual definition is in @file{userlock.el}.
@node Information about Files
@section Information about Files
The functions described in this section are similar in as much as
they all operate on strings which are interpreted as file names. All
have names that begin with the word @samp{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.
Most of the file-oriented functions take a single argument,
@var{filename}, which must be a string. The file name is expanded using
@code{expand-file-name}, so @file{~} is handled correctly, as are
relative file names (including @samp{../}). These functions don't
recognize environment variable substitutions such as @samp{$HOME}.
@xref{File Name Expansion}.
The functions described in this section all operate on strings that
designate file names. All the functions have names that begin with the
word @samp{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?
......@@ -638,11 +637,11 @@ modes permit.
@end defun
@defun file-writable-p filename
This function returns @code{t} if the file @var{filename} can be written or
created by you. It is writable if the file exists and you can write it.
It is creatable if the file does not exist, but the specified directory
does exist and you can write in that directory. @code{file-writable-p}
returns @code{nil} otherwise.
This function returns @code{t} if the file @var{filename} can be written
or created by you, and @code{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, @file{foo} is not writable because the
parent directory does not exist, even though the user could create such
......@@ -667,9 +666,10 @@ a directory.
@c Emacs 19 feature
@defun file-accessible-directory-p dirname
This function returns @code{t} if you have permission to open existing
files in directory @var{dirname}; otherwise (and if there is no such
directory), it returns @code{nil}. The value of @var{dirname} may be
either a directory name or the file name of a directory.
files in the directory whose name as a file is @var{dirname}; otherwise
(or if there is no such directory), it returns @code{nil}. The value
of @var{dirname} may be either a directory name or the file name of a
directory.
Example: after the following,
......@@ -686,14 +686,14 @@ give an error.
@defun file-newer-than-file-p filename1 filename2
@cindex file age
@cindex file modification time
This functions returns @code{t} if the file @var{filename1} is
This function returns @code{t} if the file @var{filename1} is
newer than file @var{filename2}. If @var{filename1} does not
exist, it returns @code{nil}. If @var{filename2} does not exist,
it returns @code{t}.
In the following example, assume that the file @file{aug-19} was
written on the 19th, and @file{aug-20} was written on the 20th. The
file @file{no-file} doesn't exist at all.
In the following example, assume that the file @file{aug-19} was written
on the 19th, @file{aug-20} was written on the 20th, and the file
@file{no-file} doesn't exist at all.
@example
@group
......@@ -729,8 +729,8 @@ links from ordinary files.
@cindex file symbolic links
If the file @var{filename} is a symbolic link, the @code{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 of
no file at all.
name of a text file, a directory, or even another symbolic link, or it
may be a nonexistent file name.
If the file @var{filename} is not a symbolic link (or there is no such file),
@code{file-symlink-p} returns @code{nil}.
......@@ -822,7 +822,7 @@ and modification.
This function returns the mode bits of @var{filename}, as an integer.
The mode bits are also called the file permissions, and they specify
access control in the usual Unix fashion. If the low-order bit is 1,
then the file is executable by all users, if the second lowest-order bit
then the file is executable by all users, if the second-lowest-order bit
is 1, then the file is writable by all users, etc.
The highest value returnable is 4095 (7777 octal), meaning that
......@@ -920,7 +920,7 @@ The time of last status change as a list of two integers (as above).
The size of the file in bytes.
@item
The file's modes, as a string of ten letters or dashes
The file's modes, as a string of ten letters or dashes,
as in @samp{ls -l}.
@item
......@@ -932,9 +932,9 @@ The file's inode number.
@item
The file system number of the file system that the file is in. This
element together with the file's inode number, give enough information
to distinguish any two files on the system---no two files can have the
same values for both of these numbers.
element and the file's inode number together give enough information to
distinguish any two files on the system---no two files can have the same
values for both of these numbers.
@end enumerate
For example, here are the file attributes for @file{files.texi}:
......@@ -1142,9 +1142,9 @@ This command makes a symbolic link to @var{filename}, named
@var{newname}. This is like the shell command @samp{ln -s
@var{filename} @var{newname}}.
In an interactive call, @var{filename} and @var{newname} are read in the
minibuffer; it requests confirmation if the file @var{newname} already
exists.
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
@end deffn
@defun define-logical-name varname string
......@@ -1154,7 +1154,7 @@ This function defines the logical name @var{name} to have the value
@defun set-file-modes filename mode
This function sets mode bits of @var{filename} to @var{mode} (which must
be an integer). Only the 12 low bits of @var{mode} are used.
be an integer). Only the low 12 bits of @var{mode} are used.
@end defun
@c Emacs 19 feature
......@@ -1164,7 +1164,7 @@ Emacs and its subprocesses. Every file created with Emacs initially has
this protection. On Unix, the default protection is the bitwise
complement of the ``umask'' value.
The argument @var{mode} must be an integer. Only the 9 low bits of
The argument @var{mode} must be an integer. Only the low 9 bits of
@var{mode} are used.
Saving a modified version of an existing file does not count as creating
......@@ -1200,10 +1200,10 @@ how to manipulate file names.
can operate on file names that do not refer to an existing file or
directory.
On VMS, all these functions understand both VMS file name syntax and
On VMS, all these functions understand both VMS file-name syntax and
Unix syntax. This is so that all the standard Lisp libraries can
specify file names in Unix syntax and work properly on VMS without
change. On MS-DOS, these functions understand MS-DOS file name syntax
change. On MS-DOS, these functions understand MS-DOS file-name syntax
as well as Unix syntax.
@menu
......@@ -1223,11 +1223,11 @@ as well as Unix syntax.
@cindex version number (in file name)
The operating system groups files into directories. To specify a
file, you must specify the directory, and the file's name in that
directory. Therefore, a file name in Emacs is considered to have two
main parts: the @dfn{directory name} part, and the @dfn{nondirectory}
part (or @dfn{file name within the directory}). Either part may be
empty. Concatenating these two parts reproduces the original file name.
file, you must specify the directory and the file's name within that
directory. Therefore, Emacs considers a file name as having two main
parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
(or @dfn{file name within the directory}). Either part may be empty.
Concatenating these two parts reproduces the original file name.
On Unix, the directory part is everything up to and including the last
slash; the nondirectory part is the rest. The rules in VMS syntax are
......@@ -1327,9 +1327,9 @@ subtle but crucial. When an Emacs variable or function argument is
described as being a directory name, a file name of a directory is not
acceptable.
These two functions convert between directory names and file names.
They do nothing special with environment variable substitutions such as
@samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
The following two functions convert between directory names and file
names. They do nothing special with environment variable substitutions
such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
@defun file-name-as-directory filename
This function returns a string representing @var{filename} in a form
......@@ -1510,7 +1510,7 @@ variables; only @code{substitute-in-file-name} does that.
@c Emacs 19 feature
@defun file-relative-name filename directory
This function does the inverse of expansion---it tries to return a
relative name which is equivalent to @var{filename} when interpreted
relative name that is equivalent to @var{filename} when interpreted
relative to @var{directory}. (If such a relative name would be longer
than the absolute name, it returns the absolute name instead.)
......@@ -1598,8 +1598,8 @@ the same name.
@defun make-temp-name string
This function generates string that can be used as a unique name. The
name starts with the prefix @var{string}, and ends with a number that
is different in each Emacs job.
name starts with @var{string}, and ends with a number that is different
in each Emacs job.
@example
@group
......@@ -1756,18 +1756,20 @@ This function returns a list of all versions of the file named
@end defun
@defun insert-directory file switches &optional wildcard full-directory-p
This function inserts a directory listing for directory @var{dir},
formatted with @code{ls} according to @var{switches}. It leaves point
after the inserted text.
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to
@var{switches}. It leaves point after the inserted text.
The argument @var{dir} may be either a directory name or a file
The argument @var{file} may be either a directory name or a file
specification including wildcard characters. If @var{wildcard} is
non-@code{nil}, that means treat @var{file} as a file specification with
wildcards.
If @var{full-directory-p} is non-@code{nil}, that means @var{file} is a
directory and switches do not contain @samp{d}, so that a full listing
is expected.
directory and switches do not contain @samp{-d}, so that the listing
should show the full contents of the directory. (The @samp{-d} option
to @code{ls} says to describe a directory itself rather than its
contents.)
This function works by running a directory listing program whose name is
in the variable @code{insert-directory-program}. If @var{wildcard} is
......@@ -1784,6 +1786,11 @@ for the function @code{insert-directory}.
@section Creating and Deleting Directories
@c Emacs 19 features
Most Emacs Lisp file-manipulation functions get errors when used on
files that are directories. For example, you cannot delete a directory
with @code{delete-file}. These special functions exist to create and
delete directories.
@defun make-directory dirname
This function creates a directory named @var{dirname}.
@end defun
......@@ -1801,11 +1808,11 @@ must use @code{delete-directory} in that case.
@c Emacs 19 feature
You can implement special handling for certain file names. This is
called making those names @dfn{magic}. You must supply a regular
expression to define the class of names (all those which match the
expression to define the class of names (all those that match the
regular expression), plus a handler that implements all the primitive
Emacs file operations for file names that do match.
The value of @code{file-name-handler-alist} is a list of handlers,
The variable @code{file-name-handler-alist} holds a list of handlers,
together with regular expressions that determine when to apply each
handler. Each element has this form:
......@@ -1836,7 +1843,7 @@ called like this:
(funcall @var{handler} 'file-exists-p @var{filename})
@end example
Here are the operations that you can handle for a magic file name:
Here are the operations that a magic file name handler gets to handle:
@noindent
@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
......@@ -1853,17 +1860,18 @@ Here are the operations that you can handle for a magic file name:
@code{file-name-directory}, @code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-readable-p}, @code{file-symlink-p}, @code{file-truename},
@code{file-writable-p},@*
@code{insert-directory},
@code{file-writable-p}, @code{insert-directory},@*
@code{insert-file-contents}, @code{load}, @code{make-directory},
@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
@code{set-visited-file-modtime}, @code{unhandled-file-name-directory},
@code{verify-visited-file-modtime}, @code{write-region}.
The handler function must handle all of the above operations, and
possibly others to be added in the future. Therefore, it should always
reinvoke the ordinary Lisp primitive when it receives an operation it
does not recognize. Here's one way to do this:
possibly others to be added in the future. It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
operation ``in the usual way''. It should always reinvoke the primitive
for an operation it does not recognize. Here's one way to do this:
@smallexample
(defun my-file-handler (operation &rest args)
......@@ -1874,7 +1882,7 @@ does not recognize. Here's one way to do this:
@dots{}
;; @r{Handle any operation we don't know about.}
(t (let ((inhibit-file-name-handlers
(cons 'ange-ftp-file-handler
(cons 'my-file-handler
(and (eq inhibit-file-name-operation operation)
inhibit-file-name-handlers)))
(inhibit-file-name-operation operation))
......@@ -1909,10 +1917,12 @@ for comparison with @code{inhibit-file-name-operation}.
@end defun
@defun file-local-copy filename
This function copies file @var{filename} to the local site, if it isn't
there already. If @var{filename} specifies a ``magic'' file name which
programs outside Emacs cannot directly read or write, this copies the
contents to an ordinary file and returns that file's name.
This function copies file @var{filename} to an ordinary non-magic file,
if it isn't one already.
If @var{filename} specifies a ``magic'' file name, which programs
outside Emacs cannot directly read or write, this copies the contents to
an ordinary file and returns that file's name.
If @var{filename} is an ordinary file name, not magic, then this function
does nothing and returns @code{nil}.
......@@ -1936,18 +1946,21 @@ is a good way to come up with one.
@cindex binary files and text files
Emacs on MS-DOS makes a distinction between text files and binary
files. This is necessary because ordinary text files on MS-DOS use two
characters between lines: carriage-return and linefeed. Emacs expects
just a newline character (a linefeed) between lines. When Emacs reads
or writes a text file on MS-DOS, it needs to convert the line
separators. This means it needs to know which files are text files and
which are binary. It makes this decision when visiting a file, and
records the decision in the variable @code{buffer-file-type} for when
the file is saved.
files. This is necessary because ordinary text files on MS-DOS use a
two character sequence between lines: carriage-return and linefeed
(CRLF). Emacs expects just a newline character (a linefeed) between
lines. When Emacs reads or writes a text file on MS-DOS, it needs to
convert the line separators. This means it needs to know which files
are text files and which are binary. It makes this decision when
visiting a file, and records the decision in the variable
@code{buffer-file-type} for use when the file is saved.
@xref{MS-DOS Subprocesses}, for a related feature for subprocesses.
@defvar buffer-file-type
This variable, automatically local in each buffer, records the file type
of the buffer's visited file.
of the buffer's visited file. The value is @code{nil} for text,
@code{t} for binary.
@end defvar
@defun find-buffer-file-type filename
......
......@@ -1311,10 +1311,10 @@ have very long file names or display the time and load.)
(add-hook 'text-mode-hook
(function (lambda ()
(setq mode-line-format
@end group
'(mode-line-modified
"Emacs: %14b"
" "
@end group
default-directory
" "
global-mode-string
......
......@@ -93,7 +93,7 @@ supplied to @var{program} as separate command line arguments. Wildcard
characters and other shell constructs are not allowed in these strings,
since they are passed directly to the specified program.
@strong{Please note:} the argument @var{program} contains only the
@strong{Please note:} The argument @var{program} contains only the
name of the program; it may not contain any command-line arguments. You
must use @var{args} to provide those.
......
......@@ -318,7 +318,7 @@ example, the regular expression that matches the @samp{\} character is
@samp{\} is @code{"\\\\"}.@refill
@end table
@strong{Please note:} for historical compatibility, special characters
@strong{Please note:} For historical compatibility, special characters
are treated as ordinary ones if they are in contexts where their special
meanings make no sense. For example, @samp{*foo} treats @samp{*} as
ordinary since there is no preceding expression on which the @samp{*}
......
......@@ -48,6 +48,7 @@ buffer.
* Case Changes:: Case conversion of parts of the buffer.
* Text Properties:: Assigning Lisp property lists to text characters.
* Substitution:: Replacing a given character wherever it appears.
* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
* Change Hooks:: Supplying functions to be run when text is changed.
......@@ -520,17 +521,21 @@ In the example below, point is located on the line starting
in the preceding line.
@smallexample
@group
---------- Buffer: foo ----------
When in the course of human
@point{} events, it becomes necessary
---------- Buffer: foo ----------
@end group
(delete-indentation)
@result{} nil
@group
---------- Buffer: foo ----------
When in the course of human@point{} events, it becomes necessary
---------- Buffer: foo ----------
@end group
@end smallexample
After the lines are joined, the function @code{fixup-whitespace} is
......@@ -2615,6 +2620,25 @@ This function stores the current frame configuration in register
@end deffn
@end ignore
@node Transposition
@section Transposition of Text
This subroutine is used by the transposition commands.
@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
This function exchanges two nonoverlapping portions of the buffer.
Arguments @var{start1} and @var{end1} specify the bounds of one portion
and arguments @var{start2} and @var{end2} specify the bounds of the
other portion.
Normally, @code{transpose-regions} relocates markers with the transposed
text; a marker previously positioned within one of the two transposed
portions moves along with that portion, thus remaining between the same
two characters in their new position. However, if @var{leave-markers}
is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
all markers unrelocated.
@end defun
@node Change Hooks
@section Change Hooks
@cindex change hooks
......@@ -2665,6 +2689,25 @@ functions. If you do want a hook function to make changes that run
these functions, make it bind these variables back to their usual
values.
One inconvenient result of this protective feature is that you cannot
have a function in @code{after-change-functions} or
@code{before-change-functions} which changes the value of that variable.
But that's not a real limitation. If you want those functions to change
the list of functions to run, simply add one fixed function to the hook,
and code that function to look in another variable for other functions
to call. Here is an example:
@example
(setq my-own-after-change-functions nil)
(defun indirect-after-change-function (beg end len)
(let ((list my-own-after-change-functions))
(while list
(funcall (car list) beg end len)
(setq list (cdr list)))))
(add-hooks 'after-change-functions
'indirect-after-change-function)
@end example
@defvar first-change-hook
This variable is a normal hook that is run whenever a buffer is changed
that was previously in the unmodified state.
......
......@@ -492,7 +492,7 @@ of @var{symbol} to the result, provided @var{value} is given. If
@var{symbol} has a buffer-local binding in the current buffer,
@code{defconst} sets the default value, not the local value.
@strong{Please note:} don't use @code{defconst} for user option
@strong{Please note:} Don't use @code{defconst} for user option
variables in libraries that are not standardly preloaded. The user
should be able to specify a value for such a variable in the
@file{.emacs} file, so that it will be in effect if and when the library
......@@ -536,7 +536,7 @@ then the variable is a user option.
the variable. The property's value is used as if it were the argument
to @code{interactive}.
@strong{Warning:} if the @code{defconst} and @code{defvar} special
@strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
local binding's value; the global binding is not changed. This is not
what we really want. To prevent it, use these special forms at top
......@@ -734,7 +734,7 @@ located textually within the function or block that binds the variable.
@cindex CL note---special variables
@quotation
@b{Common Lisp note:} variables declared ``special'' in Common Lisp
@b{Common Lisp note:} Variables declared ``special'' in Common Lisp
are dynamically scoped, like variables in Emacs Lisp.
@end quotation
......@@ -973,7 +973,7 @@ the (default) global binding untouched. The global value can no longer
be changed with @code{setq}; you need to use @code{setq-default} to do
that.
@strong{Warning:} when a variable has local values in one or more
@strong{Warning:} When a variable has local values in one or more
buffers, you can get Emacs very confused by binding the variable with
@code{let}, changing to a different current buffer in which a different
binding is in effect, and then exiting the @code{let}. This can
......
......@@ -321,7 +321,7 @@ among all the siblings.)
This function returns @code{nil} if @var{window} is deleted, and
@code{t} otherwise.
@strong{Warning:} erroneous information or fatal errors may result from
@strong{Warning:} Erroneous information or fatal errors may result from
using a deleted window as if it were live.
@end defun
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment