procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Emacs Lisp manual updates.

Browse source 
* doc/lispref/intro.texi (A Sample Function Description): Special notation
used for macros too.

* doc/lispref/objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits.
(Symbol Type): Add xref for keyword symbols.
(Sequence Type): Clarify differences between sequence types.
(Cons Cell Type): Add "linked list" index entry.
(Non-ASCII in Strings): Copyedits.
(Equality Predicates): Symbols with same name need not be eq.

* doc/lispref/numbers.texi (Float Basics): Document isnan, copysign, frexp and
ldexp.  Move float-e and float-pi to Math Functions node.
This commit is contained in:
Chong Yidong 2012-01-22 00:04:55 +08:00
parent cc6d5805ba
commit fead402ddd
5 changed files with 198 additions and 166 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
doc/lispref/ChangeLog
View file

@ -1,3 +1,18 @@
2012-01-21 Chong Yidong <cyd@gnu.org>
* intro.texi (A Sample Function Description): Special notation
used for macros too.
* objects.texi (Ctl-Char Syntax, Other Char Bits): Copyedits.
(Symbol Type): Add xref for keyword symbols.
(Sequence Type): Clarify differences between sequence types.
(Cons Cell Type): Add "linked list" index entry.
(Non-ASCII in Strings): Copyedits.
(Equality Predicates): Symbols with same name need not be eq.
* numbers.texi (Float Basics): Document isnan, copysign, frexp and
ldexp. Move float-e and float-pi to Math Functions node.
2012-01-21 Glenn Morris <rgm@gnu.org>
* modes.texi (Auto Major Mode):

23
doc/lispref/intro.texi
View file

@ -162,7 +162,7 @@ being described, are formatted like this: @var{first-number}.
@cindex @code{nil}
@cindex false
In Lisp, the symbol @code{nil} has three separate meanings: it
In Emacs Lisp, the symbol @code{nil} has three separate meanings: it
is a symbol with the name @samp{nil}; it is the logical truth value
@var{false}; and it is the empty list---the list of zero elements.
When used as a variable, @code{nil} always has the value @code{nil}.
@ -396,13 +396,14 @@ Form', respectively. Commands are simply functions that may be called
interactively; macros process their arguments differently from functions
(the arguments are not evaluated), but are presented the same way.
Special form descriptions use a more complex notation to specify
optional and repeated arguments because they can break the argument
list down into separate arguments in more complicated ways.
@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
arguments. Parentheses are used when several arguments are grouped into
additional levels of list structure. Here is an example:
The descriptions of macros and special forms use a more complex
notation to specify optional and repeated arguments, because they can
break the argument list down into separate arguments in more
complicated ways. @samp{@r{[}@var{optional-arg}@r{]}} means that
@var{optional-arg} is optional and @samp{@var{repeated-args}@dots{}}
stands for zero or more arguments. Parentheses are used when several
arguments are grouped into additional levels of list structure. Here
is an example:
@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
This imaginary special form implements a loop that executes the
@ -485,9 +486,9 @@ giving a prefix argument makes @var{here} non-@code{nil}.
@end deffn
@defvar emacs-build-time
The value of this variable indicates the time at which Emacs was built
at the local site. It is a list of three integers, like the value
of @code{current-time} (@pxref{Time of Day}).
The value of this variable indicates the time at which Emacs was
built. It is a list of three integers, like the value of
@code{current-time} (@pxref{Time of Day}).
@example
@group

124
doc/lispref/numbers.texi
View file

@ -168,34 +168,37 @@ character codepoint.
@node Float Basics
@section Floating Point Basics
@cindex @acronym{IEEE} floating point
Floating point numbers are useful for representing numbers that are
not integral. The precise range of floating point numbers is
machine-specific; it is the same as the range of the C data type
@code{double} on the machine you are using.
@code{double} on the machine you are using. Emacs uses the
@acronym{IEEE} floating point standard where possible (the standard is
supported by most modern computers).
The read-syntax for floating point numbers requires either a decimal
The read syntax for floating point numbers requires either a decimal
point (with at least one digit following), an exponent, or both. For
example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
@samp{.15e4} are five ways of writing a floating point number whose
value is 1500. They are all equivalent. You can also use a minus sign
to write negative floating point numbers, as in @samp{-1.0}.
value is 1500. They are all equivalent. You can also use a minus
sign to write negative floating point numbers, as in @samp{-1.0}.
Emacs Lisp treats @code{-0.0} as equal to ordinary zero (with
respect to @code{equal} and @code{=}), even though the two are
distinguishable in the @acronym{IEEE} floating point standard.
@cindex @acronym{IEEE} floating point
@cindex positive infinity
@cindex negative infinity
@cindex infinity
@cindex NaN
Most modern computers support the @acronym{IEEE} floating point standard,
which provides for positive infinity and negative infinity as floating point
values. It also provides for a class of values called NaN or
``not-a-number''; numerical functions return such values in cases where
there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a
NaN. For practical purposes, there's no significant difference between
different NaN values in Emacs Lisp, and there's no rule for precisely
which NaN value should be used in a particular case, so Emacs Lisp
doesn't try to distinguish them (but it does report the sign, if you
print it). Here are the read syntaxes for these special floating
point values:
The @acronym{IEEE} floating point standard supports positive
infinity and negative infinity as floating point values. It also
provides for a class of values called NaN or ``not-a-number'';
numerical functions return such values in cases where there is no
correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN. (NaN
values can also carry a sign, but for practical purposes there's no
significant difference between different NaN values in Emacs Lisp.)
Here are the read syntaxes for these special floating point values:
@table @asis
@item positive infinity
@ -206,16 +209,37 @@ point values:
@samp{0.0e+NaN} or @samp{-0.0e+NaN}.
@end table
To test whether a floating point value is a NaN, compare it with
itself using @code{=}. That returns @code{nil} for a NaN, and
@code{t} for any other floating point value.
@defun isnan number
This predicate tests whether its argument is NaN, and returns @code{t}
if so, @code{nil} otherwise. The argument must be a number.
@end defun
The value @code{-0.0} is distinguishable from ordinary zero in
@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and
@code{=} consider them equal values.
The following functions are specialized for handling floating point
numbers:
You can use @code{logb} to extract the binary exponent of a floating
point number (or estimate the logarithm of an integer):
@defun frexp x
This function returns a cons cell @code{(@var{sig} . @var{exp})},
where @var{sig} and @var{exp} are respectively the significand and
exponent of the floating point number @var{x}:
@smallexample
@var{x} = @var{sig} * 2^@var{exp}
@end smallexample
@var{sig} is a floating point number between 0.5 (inclusive) and 1.0
(exclusive). If @var{x} is zero, the return value is @code{(0 . 0)}.
@end defun
@defun ldexp sig &optional exp
This function returns a floating point number corresponding to the
significand @var{sig} and exponent @var{exp}.
@end defun
@defun copysign x1 x2
This function copies the sign of @var{x2} to the value of @var{x1},
and returns the result. @var{x1} and @var{x2} must be floating point
numbers.
@end defun
@defun logb number
This function returns the binary exponent of @var{number}. More
@ -230,14 +254,6 @@ down to an integer.
@end example
@end defun
@defvar float-e
The mathematical constant @math{e} (2.71828@dots{}).
@end defvar
@defvar float-pi
The mathematical constant @math{pi} (3.14159@dots{}).
@end defvar
@node Predicates on Numbers
@section Type Predicates for Numbers
@cindex predicates for numbers
@ -1122,35 +1138,15 @@ angle in radians between the vector @code{[@var{x}, @var{y}]} and the
@end defun
@defun exp arg
This is the exponential function; it returns
@tex
@math{e}
@end tex
@ifnottex
@i{e}
@end ifnottex
to the power @var{arg}.
@tex
@math{e}
@end tex
@ifnottex
@i{e}
@end ifnottex
is a fundamental mathematical constant also called the base of natural
logarithms.
This is the exponential function; it returns @math{e} to the power
@var{arg}.
@end defun
@defun log arg &optional base
This function returns the logarithm of @var{arg}, with base @var{base}.
If you don't specify @var{base}, the base
@tex
@math{e}
@end tex
@ifnottex
@i{e}
@end ifnottex
is used. If @var{arg} is negative, it signals a @code{domain-error}
error.
This function returns the logarithm of @var{arg}, with base
@var{base}. If you don't specify @var{base}, the natural base
@math{e} is used. If @var{arg} is negative, it signals a
@code{domain-error} error.
@end defun
@ignore
@ -1185,6 +1181,17 @@ This returns the square root of @var{arg}. If @var{arg} is negative,
it signals a @code{domain-error} error.
@end defun
In addition, Emacs defines the following common mathematical
constants:
@defvar float-e
The mathematical constant @math{e} (2.71828@dots{}).
@end defvar
@defvar float-pi
The mathematical constant @math{pi} (3.14159@dots{}).
@end defvar
@node Random Numbers
@section Random Numbers
@cindex random numbers
@ -1218,7 +1225,6 @@ nonnegative and less than @var{limit}.
If @var{limit} is @code{t}, it means to choose a new seed based on the
current time of day and on Emacs's process @acronym{ID} number.
@c "Emacs'" is incorrect usage!
On some machines, any integer representable in Lisp may be the result
of @code{random}. On other machines, the result can never be larger

199
doc/lispref/objects.texi
View file

@ -427,10 +427,10 @@ codes for these non-@acronym{ASCII} control characters include the
@ifnottex
2**26
@end ifnottex
bit as well as the code for the corresponding non-control
character. Ordinary terminals have no way of generating non-@acronym{ASCII}
control characters, but you can generate them straightforwardly using X
and other window systems.
bit as well as the code for the corresponding non-control character.
Ordinary text terminals have no way of generating non-@acronym{ASCII}
control characters, but you can generate them straightforwardly using
X and other window systems.
For historical reasons, Emacs treats the @key{DEL} character as
the control equivalent of @kbd{?}:
@ -501,10 +501,10 @@ character is upper case or lower case. Emacs uses the
@end ifnottex
bit to indicate that the shift key was used in typing a control
character. This distinction is possible only when you use X terminals
or other special terminals; ordinary terminals do not report the
distinction to the computer in any way. The Lisp syntax for
the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
represents the shifted-control-o character.
or other special terminals; ordinary text terminals do not report the
distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus,
@samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o
character.
@cindex hyper characters
@cindex super characters
@ -541,9 +541,9 @@ intended. But you can use one symbol in all of these ways,
independently.
A symbol whose name starts with a colon (@samp{:}) is called a
@dfn{keyword symbol}. These symbols automatically act as constants, and
are normally used only by comparing an unknown symbol with a few
specific alternatives.
@dfn{keyword symbol}. These symbols automatically act as constants,
and are normally used only by comparing an unknown symbol with a few
specific alternatives. @xref{Constant Variables}.
@cindex @samp{\} in symbols
@cindex backslash in symbols
@ -617,26 +617,28 @@ all symbols; @pxref{Creating Symbols}.)
@subsection Sequence Types
A @dfn{sequence} is a Lisp object that represents an ordered set of
elements. There are two kinds of sequence in Emacs Lisp, lists and
arrays. Thus, an object of type list or of type array is also
considered a sequence.
elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists}
and @dfn{arrays}.
Arrays are further subdivided into strings, vectors, char-tables and
bool-vectors. Vectors can hold elements of any type, but string
elements must be characters, and bool-vector elements must be @code{t}
or @code{nil}. Char-tables are like vectors except that they are
indexed by any valid character code. The characters in a string can
have text properties like characters in a buffer (@pxref{Text
Properties}), but vectors do not support text properties, even when
their elements happen to be characters.
Lists are the most commonly-used sequences. A list can hold
elements of any type, and its length can be easily changed by adding
or removing elements. See the next subsection for more about lists.
Lists, strings and the other array types are different, but they have
important similarities. For example, all have a length @var{l}, and all
have elements which can be indexed from zero to @var{l} minus one.
Several functions, called sequence functions, accept any kind of
sequence. For example, the function @code{elt} can be used to extract
an element of a sequence, given its index. @xref{Sequences Arrays
Vectors}.
Arrays are fixed-length sequences. They are further subdivided into
strings, vectors, char-tables and bool-vectors. Vectors can hold
elements of any type, whereas string elements must be characters, and
bool-vector elements must be @code{t} or @code{nil}. Char-tables are
like vectors except that they are indexed by any valid character code.
The characters in a string can have text properties like characters in
a buffer (@pxref{Text Properties}), but vectors do not support text
properties, even when their elements happen to be characters.
Lists, strings and the other array types also share important
similarities. For example, all have a length @var{l}, and all have
elements which can be indexed from zero to @var{l} minus one. Several
functions, called sequence functions, accept any kind of sequence.
For example, the function @code{length} reports the length of any kind
of sequence. @xref{Sequences Arrays Vectors}.
It is generally impossible to read the same sequence twice, since
sequences are always created anew upon reading. If you read the read
@ -650,24 +652,27 @@ same object, @code{nil}.
@cindex decrement field of register
@cindex pointers
A @dfn{cons cell} is an object that consists of two slots, called the
@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
this cons cell is'' whatever object its @sc{car} slot currently holds,
and likewise for the @sc{cdr}.
@quotation
A note to C programmers: in Lisp, we do not distinguish between
``holding'' a value and ``pointing to'' the value, because pointers in
Lisp are implicit.
@end quotation
A @dfn{cons cell} is an object that consists of two slots, called
the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any
Lisp object. We also say that ``the @sc{car} of this cons cell is''
whatever object its @sc{car} slot currently holds, and likewise for
the @sc{cdr}.
@cindex list structure
A @dfn{list} is a series of cons cells, linked together so that the
@sc{cdr} slot of each cons cell holds either the next cons cell or the
empty list. The empty list is actually the symbol @code{nil}.
@xref{Lists}, for functions that work on lists. Because most cons
cells are used as part of lists, the phrase @dfn{list structure} has
come to refer to any structure made out of cons cells.
@xref{Lists}, for details. Because most cons cells are used as part
of lists, we refer to any structure made out of cons cells as a
@dfn{list structure}.
@cindex linked list
@quotation
A note to C programmers: a Lisp list thus works as a @dfn{linked list}
built up of cons cells. Because pointers in Lisp are implicit, we do
not distinguish between a cons cell slot ``holding'' a value versus
``pointing to'' the value.
@end quotation
@cindex atoms
Because cons cells are so central to Lisp, we also have a word for
@ -1025,40 +1030,40 @@ but the newline is ignored if escaped."
@node Non-ASCII in Strings
@subsubsection Non-@acronym{ASCII} Characters in Strings
You can include a non-@acronym{ASCII} international character in a string
constant by writing it literally. There are two text representations
for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
and multibyte. If the string constant is read from a multibyte source,
such as a multibyte buffer or string, or a file that would be visited as
multibyte, then the character is read as a multibyte character, and that
makes the string multibyte. If the string constant is read from a
unibyte source, then the character is read as unibyte and that makes the
string unibyte.
You can include a non-@acronym{ASCII} international character in a
string constant by writing it literally. There are two text
representations for non-@acronym{ASCII} characters in Emacs strings
(and in buffers): unibyte and multibyte (@pxref{Text
Representations}). If the string constant is read from a multibyte
source, such as a multibyte buffer or string, or a file that would be
visited as multibyte, then Emacs reads the non-@acronym{ASCII}
character as a multibyte character and automatically makes the string
a multibyte string. If the string constant is read from a unibyte
source, then Emacs reads the non-@acronym{ASCII} character as unibyte,
and makes the string unibyte.
You can also represent a multibyte non-@acronym{ASCII} character with its
character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all
greater than 256.) Any character which is not a valid hex digit
terminates this construct. If the next character in the string could be
interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
terminate the hex escape---for example, @w{@samp{\xe0\ }} represents
one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
constant is just like backslash-newline; it does not contribute any
character to the string, but it does terminate the preceding hex escape.
Instead of writing a non-@acronym{ASCII} character literally into a
multibyte string, you can write it as its character code using a hex
escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary.
(Multibyte non-@acronym{ASCII} character codes are all greater than
256.) You can also specify a character in a multibyte string using
the @samp{\u} or @samp{\U} Unicode escape syntax (@pxref{General
Escape Syntax}). In either case, any character which is not a valid
hex digit terminates the construct. If the next character in the
string could be interpreted as a hex digit, write @w{@samp{\ }}
(backslash and space) to terminate the hex escape---for example,
@w{@samp{\xe0\ }} represents one character, @samp{a} with grave
accent. @w{@samp{\ }} in a string constant is just like
backslash-newline; it does not contribute any character to the string,
but it does terminate the preceding hex escape. Using any hex escape
in a string (even for an @acronym{ASCII} character) automatically
forces the string to be multibyte.
You can represent a unibyte non-@acronym{ASCII} character with its
character code, which must be in the range from 128 (0200 octal) to
255 (0377 octal). If you write all such character codes in octal and
the string contains no other characters forcing it to be multibyte,
this produces a unibyte string. However, using any hex escape in a
string (even for an @acronym{ASCII} character) forces the string to be
multibyte.
You can also specify characters in a string by their numeric values
in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}).
@xref{Text Representations}, for more information about the two
text representations.
this produces a unibyte string.
@node Nonprinting Characters
@subsubsection Nonprinting Characters in Strings
@ -1922,23 +1927,24 @@ This function returns a symbol naming the primitive type of
@section Equality Predicates
@cindex equality
Here we describe functions that test for equality between any two
objects. Other functions test equality of contents between objects of specific
types, e.g., strings. For these predicates, see the appropriate chapter
describing the data type.
Here we describe functions that test for equality between two
objects. Other functions test equality of contents between objects of
specific types, e.g.@: strings. For these predicates, see the
appropriate chapter describing the data type.
@defun eq object1 object2
This function returns @code{t} if @var{object1} and @var{object2} are
the same object, @code{nil} otherwise.
the same object, and @code{nil} otherwise.
@code{eq} returns @code{t} if @var{object1} and @var{object2} are
integers with the same value. Also, since symbol names are normally
unique, if the arguments are symbols with the same name, they are
@code{eq}. For other types (e.g., lists, vectors, strings), two
arguments with the same contents or elements are not necessarily
@code{eq} to each other: they are @code{eq} only if they are the same
object, meaning that a change in the contents of one will be reflected
by the same change in the contents of the other.
If @var{object1} and @var{object2} are integers with the same value,
they are considered to be the same object (i.e.@: @code{eq} returns
@code{t}). If @var{object1} and @var{object2} are symbols with the
same name, they are normally the same object---but see @ref{Creating
Symbols} for exceptions. For other types (e.g.@: lists, vectors,
strings), two arguments with the same contents or elements are not
necessarily @code{eq} to each other: they are @code{eq} only if they
are the same object, meaning that a change in the contents of one will
be reflected by the same change in the contents of the other.
@example
@group
@ -1988,6 +1994,7 @@ by the same change in the contents of the other.
@end group
@end example
@noindent
The @code{make-symbol} function returns an uninterned symbol, distinct
from the symbol that is used if you write the name in a Lisp expression.
Distinct symbols with the same name are not @code{eq}. @xref{Creating
@ -2003,11 +2010,11 @@ Symbols}.
@defun equal object1 object2
This function returns @code{t} if @var{object1} and @var{object2} have
equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
arguments are the same object, @code{equal} looks inside nonidentical
arguments to see if their elements or contents are the same. So, if two
objects are @code{eq}, they are @code{equal}, but the converse is not
always true.
equal components, and @code{nil} otherwise. Whereas @code{eq} tests
if its arguments are the same object, @code{equal} looks inside
nonidentical arguments to see if their elements or contents are the
same. So, if two objects are @code{eq}, they are @code{equal}, but
the converse is not always true.
@example
@group
@ -2059,13 +2066,13 @@ always true.
@end example
Comparison of strings is case-sensitive, but does not take account of
text properties---it compares only the characters in the strings. Use
@code{equal-including-properties} to also compare text properties. For
technical reasons, a unibyte string and a multibyte string are
@code{equal} if and only if they contain the same sequence of
character codes and all these codes are either in the range 0 through
127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
(@pxref{Text Representations}).
text properties---it compares only the characters in the strings.
@xref{Text Properties}. Use @code{equal-including-properties} to also
compare text properties. For technical reasons, a unibyte string and
a multibyte string are @code{equal} if and only if they contain the
same sequence of character codes and all these codes are either in the
range 0 through 127 (@acronym{ASCII}) or 160 through 255
(@code{eight-bit-graphic}). (@pxref{Text Representations}).
@example
@group

3
etc/NEWS
View file

@ -1367,6 +1367,9 @@ This means that the empty symbol can now be read back. Also, #: by itself
(when not immediately followed by a possible symbol character) stands for
an empty uninterned symbol.
+++
** New math functions `isnan', `copysign', `frexp', `ldexp'.
** Obsolete functions and variables
*** buffer-substring-filters is obsolete.