Commit 81c7d631 authored by Chong Yidong's avatar Chong Yidong

More doc updates.

* backups.texi (Making Backups): Document backup-buffer change.

* commands.texi (Defining Commands): Document the interactive-form
property more carefully.  Document interactive-only.

* compile.texi (Compiler Errors): Copyedits.  Note that the
details for byte-compile-warnings are in its docstring.

* customize.texi (Variable Definitions): Likewise.

* files.texi (Visiting Files): Copyedits.
(Testing Accessibility): Mention ACLs.  Move file-modes here from
File Attributes.
(Truenames): Move file-equal-p here from Kinds of Files.
(File Attributes): Move file-newer-than-file-p here from Testing
Accessibility.
(Extended Attributes): New node.  Add file-extended-attributes.
(Changing Files): Document set-file-extended-attributes.

* minibuf.texi (Minibuffer Contents): Remove obsolete function
minibuffer-completion-contents.

* variables.texi (Defining Variables): Note that defvar acts
always on the dynamic value.
parent 0215e125
2014-01-05 Chong Yidong <cyd@gnu.org>
* backups.texi (Making Backups): Document backup-buffer change.
* files.texi (Visiting Files): Copyedits.
(Testing Accessibility): Mention ACLs. Move file-modes here from
File Attributes.
(Truenames): Move file-equal-p here from Kinds of Files.
(File Attributes): Move file-newer-than-file-p here from Testing
Accessibility.
(Extended Attributes): New node. Add file-extended-attributes.
(Changing Files): Document set-file-extended-attributes.
* commands.texi (Defining Commands): Document the interactive-form
property more carefully. Document interactive-only.
* compile.texi (Compiler Errors): Copyedits. Note that the
details for byte-compile-warnings are in its docstring.
* minibuf.texi (Minibuffer Contents): Remove obsolete function
minibuffer-completion-contents.
* variables.texi (Defining Variables): Note that defvar acts
always on the dynamic value.
* customize.texi (Variable Definitions): Likewise.
2014-01-05 Paul Eggert <eggert@cs.ucla.edu>
Document vconcat and the empty vector (Bug#16246).
......
......@@ -57,13 +57,15 @@ buffer, if appropriate. It is called by @code{save-buffer} before
saving the buffer the first time.
If a backup was made by renaming, the return value is a cons cell of
the form (@var{modes} @var{context} @var{backupname}), where
the form (@var{modes} @var{extra-alist} @var{backupname}), where
@var{modes} are the mode bits of the original file, as returned by
@code{file-modes} (@pxref{File Attributes,, Other Information about
Files}), @var{context} is a list describing the original file's
SELinux context (@pxref{File Attributes}), and @var{backupname} is the
name of the backup. In all other cases, that is, if a backup was made
by copying or if no backup was made, this function returns @code{nil}.
@code{file-modes} (@pxref{Testing Accessibility}), @var{extra-alist}
is an alist describing the original file's extended attributes, as
returned by @code{file-extended-attributes} (@pxref{Extended
Attributes}), and @var{backupname} is the name of the backup.
In all other cases (i.e., if a backup was made by copying or if no
backup was made), this function returns @code{nil}.
@end defun
@defvar buffer-backed-up
......
......@@ -108,13 +108,26 @@ command does.
The special form @code{interactive} turns a Lisp function into a
command. The @code{interactive} form must be located at top-level in
the function body (usually as the first form in the body), or in the
@code{interactive-form} property of the function symbol. When the
@code{interactive} form is located in the function body, it does
nothing when actually executed. Its presence serves as a flag, which
tells the Emacs command loop that the function can be called
interactively. The argument of the @code{interactive} form controls
the reading of arguments for an interactive call.
the function body, usually as the first form in the body; this applies
to both lambda expressions (@pxref{Lambda Expressions}) and
@code{defun} forms (@pxref{Defining Functions}). This form does
nothing during the actual execution of the function; its presence
serves as a flag, telling the Emacs command loop that the function can
be called interactively. The argument of the @code{interactive} form
specifies how the arguments for an interactive call should be read.
@cindex @code{interactive-form} property
Alternatively, an @code{interactive} form may be specified in a
function symbol's @code{interactive-form} property. A non-@code{nil}
value for this property takes precedence over any @code{interactive}
form in the function body itself. This feature is seldom used.
@cindex @code{interactive-only} property
Sometimes, a named command is only intended to be called
interactively, never directly from Lisp. In that case, give it a
non-@code{nil} @code{interactive-only} property. In that case, the
byte compiler will print a warning message if the command is called
from Lisp.
@menu
* Using Interactive:: General rules for @code{interactive}.
......
......@@ -430,29 +430,35 @@ to what @code{eval-when-compile} does.
@section Compiler Errors
@cindex compiler errors
Byte compilation outputs all errors and warnings into the buffer
@file{*Compile-Log*}. The messages include file names and line
numbers that identify the location of the problem. The usual Emacs
commands for operating on compiler diagnostics work properly on these
Error and warning messages from byte compilation are printed in a
buffer named @file{*Compile-Log*}. These messages include file names
and line numbers identifying the location of the problem. The usual
Emacs commands for operating on compiler output can be used on these
messages.
When an error is due to invalid syntax in the program, the byte
compiler might get confused about the errors' exact location. One way
to investigate is to switch to the buffer @w{@file{ *Compiler Input*}}.
(This buffer name starts with a space, so it does not show up in
@kbd{M-x list-buffers}.) This buffer contains the program being
to investigate is to switch to the buffer @w{@file{ *Compiler
Input*}}. (This buffer name starts with a space, so it does not show
up in the Buffer Menu.) This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read;
the cause of the error might be nearby. @xref{Syntax Errors}, for
some tips for locating syntax errors.
When the byte compiler warns about functions that were used but not
defined, it always reports the line number for the end of the file,
not the locations where the missing functions were called. To find
the latter, you must search for the function names.
A common type of warning issued by the byte compiler is for
functions and variables that were used but not defined. Such warnings
report the line number for the end of the file, not the locations
where the missing functions or variables were used; to find these, you
must search the file manually.
You can suppress the compiler warning for calling an undefined
function @var{func} by conditionalizing the function call on an
@code{fboundp} test, like this:
If you are sure that a warning message about a missing function or
variable is unjustified, there are several ways to suppress it:
@itemize @bullet
@item
You can suppress the warning for a specific call to a function
@var{func} by conditionalizing it on an @code{fboundp} test, like
this:
@example
(if (fboundp '@var{func}) ...(@var{func} ...)...)
......@@ -463,14 +469,10 @@ The call to @var{func} must be in the @var{then-form} of the
@code{if}, and @var{func} must appear quoted in the call to
@code{fboundp}. (This feature operates for @code{cond} as well.)
You can tell the compiler that a function is defined using
@code{declare-function} (@pxref{Declaring Functions}). Likewise, you
can tell the compiler that a variable is defined using @code{defvar}
with no initial value.
You can suppress the compiler warning for a specific use of an
undefined variable @var{variable} by conditionalizing its use on a
@code{boundp} test, like this:
@item
Likewise, you can suppress the warning for a specific use of a
variable @var{variable} by conditionalizing it on a @code{boundp}
test:
@example
(if (boundp '@var{variable}) ...@var{variable}...)
......@@ -481,7 +483,17 @@ The reference to @var{variable} must be in the @var{then-form} of the
@code{if}, and @var{variable} must appear quoted in the call to
@code{boundp}.
You can suppress any and all compiler warnings within a certain
@item
You can tell the compiler that a function is defined using
@code{declare-function}. @xref{Declaring Functions}.
@item
Likewise, you can tell the compiler that a variable is defined using
@code{defvar} with no initial value. (Note that this marks the
variable as special.) @xref{Defining Variables}.
@end itemize
You can also suppress any and all compiler warnings within a certain
expression using the construct @code{with-no-warnings}:
@c This is implemented with a defun, but conceptually it is
......@@ -497,8 +509,9 @@ possible piece of code, to avoid missing possible warnings other than
one you intend to suppress.
@end defspec
More precise control of warnings is possible by setting the variable
@code{byte-compile-warnings}.
Byte compiler warnings can be controlled more precisely by setting
the variable @code{byte-compile-warnings}. See its documentation
string for details.
@node Byte-Code Objects
@section Byte-Code Function Objects
......
......@@ -287,13 +287,17 @@ customizable variable). You should not quote @var{option}.
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
evaluates @var{standard}, but does not necessarily install the
standard value. If @var{option} already has a default value,
@code{defcustom} does not change it. If the user has saved a
customization for @var{option}, @code{defcustom} installs the user's
customized value as @var{option}'s default value. If neither of those
cases applies, @code{defcustom} installs the result of evaluating
@var{standard} as the default value.
evaluates @var{standard}, but does not necessarily bind the option to
that value. If @var{option} already has a default value, it is left
unchanged. If the user has already saved a customization for
@var{option}, the user's customized value is installed as the default
value. Otherwise, the result of evaluating @var{standard} is
installed as the default value.
Like @code{defvar}, this macro marks @code{option} as a special
variable, meaning that it should always be dynamically bound. If
@var{option} is already lexically bound, that lexical binding remains
in effect until the binding construct exits. @xref{Variable Scoping}.
The expression @var{standard} can be evaluated at various other times,
too---whenever the customization facility needs to know @var{option}'s
......
......@@ -951,7 +951,8 @@ Information about Files
* 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 Attributes:: File sizes, modification times, etc.
* Extended Attributes:: Extended file attributes for access control.
* Locating Files:: How to find a file in standard places.
File Names
......
This diff is collapsed.
......@@ -2224,12 +2224,6 @@ This is like @code{minibuffer-contents}, except that it does not copy text
properties, just the characters themselves. @xref{Text Properties}.
@end defun
@defun minibuffer-completion-contents
This is like @code{minibuffer-contents}, except that it returns only
the contents before point. That is the part that completion commands
operate on. @xref{Minibuffer Completion}.
@end defun
@defun delete-minibuffer-contents
This function erases the editable contents of the minibuffer (that is,
everything except the prompt), if a minibuffer is current. Otherwise,
......
......@@ -416,18 +416,23 @@ explicitly in the @code{defvar} form. The variable is marked as
@dfn{special}, meaning that it should always be dynamically bound
(@pxref{Variable Scoping}).
If @var{symbol} is void and @var{value} is specified, @code{defvar}
evaluates @var{value} and sets @var{symbol} to the result. But if
@var{symbol} already has a value (i.e., it is not void), @var{value}
is not even evaluated, and @var{symbol}'s value remains unchanged. If
@var{value} is omitted, the value of @var{symbol} is not changed in
any case.
If @var{value} is specified, and @var{symbol} is void (i.e., it has no
dynamically bound value; @pxref{Void Variables}), then @var{value} is
evaluated and @var{symbol} is set to the result. But if @var{symbol}
is not void, @var{value} is not evaluated, and @var{symbol}'s value is
left unchanged. If @var{value} is omitted, the value of @var{symbol}
is not changed in any case.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} operates on the default value, which is buffer-independent,
not the current (buffer-local) binding. It sets the default value if
@code{defvar} acts on the default value, which is buffer-independent,
rather than the buffer-local binding. It sets the default value if
the default value is void. @xref{Buffer-Local Variables}.
If @var{symbol} is already lexically bound (e.g., if the @code{defvar}
form occurs in a @code{let} form with lexical binding enabled), then
@code{defvar} sets the dynamic value. The lexical binding remains in
effect until its binding construct exits. @xref{Variable Scoping}.
When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
Emacs Lisp mode (@code{eval-defun}), a special feature of
@code{eval-defun} arranges to set the variable unconditionally, without
......
......@@ -904,6 +904,7 @@ low-level libraries gfilenotify.c, inotify.c or w32notify.c.
** `(input-pending-p)' no longer runs other timers which are ready to
run. The new optional CHECK-TIMERS param allows for the prior behavior.
+++
** `defvar' and `defcustom' in a let-binding affect the "external" default.
---
......@@ -958,6 +959,7 @@ special-forms any more.
when lexical binding is enabled. Previously, VAR was bound to nil,
which often led to spurious unused-variable warnings.
+++
** The return value of `backup-buffer' has changed.
The second argument is no longer an SELinux context, instead it is an
alist of extended attributes as returned by the new function
......@@ -1083,6 +1085,7 @@ displaying the buffer in a window.
*** `string-remove-prefix'
*** `string-remove-suffix'
+++
** Obsoleted functions:
*** `log10'
*** `dont-compile'
......@@ -1100,8 +1103,10 @@ The few hooks that used with-wrapper-hook are replaced as follows:
*** `completion-in-region-function' obsoletes `completion-in-region-functions'.
*** `filter-buffer-substring-function' obsoletes `filter-buffer-substring-functions'.
+++
** `byte-compile-interactive-only-functions' is now obsolete.
It has been replaced by the symbol property 'interactive-only.
To specify that a command should only be called interactively, give it
a non-nil `interactive-only' property.
+++
** `split-string' now takes an optional argument TRIM.
......
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