[Emacs-diffs] /srv/bzr/emacs/trunk r106908: Emacs Lisp manual updates.

[Chong Yidong]

------------------------------------------------------------
revno: 106908
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-01-22 00:04:55 +0800
message:
  Emacs Lisp manual updates.
  
  * 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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/intro.texi
  doc/lispref/numbers.texi
  doc/lispref/objects.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-01-21 03:15:07 +0000
+++ b/doc/lispref/ChangeLog     2012-01-21 16:04:55 +0000
@@ -1,3 +1,18 @@
+2012-01-21  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * modes.texi (Auto Major Mode):

=== modified file 'doc/lispref/intro.texi'
--- a/doc/lispref/intro.texi    2012-01-19 07:21:25 +0000
+++ b/doc/lispref/intro.texi    2012-01-21 16:04:55 +0000
@@ -162,7 +162,7 @@
 
 @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 @@
 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.
address@hidden@address@hidden@r{]}} means that @var{optional-arg} is
-optional and @address@hidden@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.  @address@hidden@address@hidden means that
address@hidden is optional and @address@hidden@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} address@hidden @var{to} address@hidden) 
@address@hidden
 This imaginary special form implements a loop that executes the
@@ -485,9 +486,9 @@
 @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
address@hidden (@pxref{Time of Day}).
 
 @example
 @group

=== modified file 'doc/lispref/numbers.texi'
--- a/doc/lispref/numbers.texi  2012-01-19 07:21:25 +0000
+++ b/doc/lispref/numbers.texi  2012-01-21 16:04:55 +0000
@@ -168,34 +168,37 @@
 @node Float Basics
 @section Floating Point Basics
 
address@hidden @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
address@hidden on the machine you are using.
address@hidden on the machine you are using.  Emacs uses the
address@hidden 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}.
-
address@hidden @acronym{IEEE} floating point
+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 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 @@
 @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
address@hidden for any other floating point value.
-
-  The value @code{-0.0} is distinguishable from ordinary zero in
address@hidden floating point, but Emacs Lisp @code{equal} and
address@hidden consider them equal values.
-
-  You can use @code{logb} to extract the binary exponent of a floating
-point number (or estimate the logarithm of an integer):
address@hidden 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.
address@hidden defun
+
+  The following functions are specialized for handling floating point
+numbers:
+
address@hidden 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}:
+
address@hidden
address@hidden = @var{sig} * address@hidden
address@hidden smallexample
+
address@hidden 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)}.
address@hidden defun
+
address@hidden ldexp sig &optional exp
+This function returns a floating point number corresponding to the
+significand @var{sig} and exponent @var{exp}.
address@hidden defun
+
address@hidden 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.
address@hidden defun
 
 @defun logb number
 This function returns the binary exponent of @var{number}.  More
@@ -230,14 +254,6 @@
 @end example
 @end defun
 
address@hidden float-e
-The mathematical constant @math{e} (address@hidden).
address@hidden defvar
-
address@hidden float-pi
-The mathematical constant @math{pi} (address@hidden).
address@hidden defvar
-
 @node Predicates on Numbers
 @section Type Predicates for Numbers
 @cindex predicates for numbers
@@ -1122,35 +1138,15 @@
 @end defun
 
 @defun exp arg
-This is the exponential function; it returns
address@hidden
address@hidden
address@hidden tex
address@hidden
address@hidden
address@hidden ifnottex
-to the power @var{arg}.
address@hidden
address@hidden
address@hidden tex
address@hidden
address@hidden
address@hidden 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
address@hidden
 @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
address@hidden
address@hidden
address@hidden tex
address@hidden
address@hidden
address@hidden 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
address@hidden  If you don't specify @var{base}, the natural base
address@hidden is used.  If @var{arg} is negative, it signals a
address@hidden error.
 @end defun
 
 @ignore
@@ -1185,6 +1181,17 @@
 it signals a @code{domain-error} error.
 @end defun
 
+In addition, Emacs defines the following common mathematical
+constants:
+
address@hidden float-e
+The mathematical constant @math{e} (address@hidden).
address@hidden defvar
+
address@hidden float-pi
+The mathematical constant @math{pi} (address@hidden).
address@hidden defvar
+
 @node Random Numbers
 @section Random Numbers
 @cindex random numbers
@@ -1218,7 +1225,6 @@
 
 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.
address@hidden "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

=== modified file 'doc/lispref/objects.texi'
--- a/doc/lispref/objects.texi  2012-01-19 07:21:25 +0000
+++ b/doc/lispref/objects.texi  2012-01-21 16:04:55 +0000
@@ -427,10 +427,10 @@
 @ifnottex
 2**26
 @end ifnottex
-bit as well as the code for the corresponding non-control
-character.  Ordinary terminals have no way of generating address@hidden
-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 address@hidden
+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 @@
 @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,
address@hidden or @samp{?\C-\S-O} represents the shifted-control-o
+character.
 
 @cindex hyper characters
 @cindex super characters
@@ -541,9 +541,9 @@
 independently.
 
   A symbol whose name starts with a colon (@samp{:}) is called a
address@hidden symbol}.  These symbols automatically act as constants, and
-are normally used only by comparing an unknown symbol with a few
-specific alternatives.
address@hidden 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 @@
 @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.
-
-  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, 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}.
+elements.  There are two kinds of sequence in Emacs Lisp: @dfn{lists}
+and @dfn{arrays}.
+
+  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.
+
+  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 @@
 @cindex decrement field of register
 @cindex pointers
 
-  A @dfn{cons cell} is an object that consists of two slots, called the
address@hidden slot and the @sc{cdr} slot.  Each slot can @dfn{hold} or
address@hidden 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}.
-
address@hidden
-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.
address@hidden 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}.
+
address@hidden 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}.
address@hidden, 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.
address@hidden, for details.  Because most cons cells are used as part
+of lists, we refer to any structure made out of cons cells as a
address@hidden structure}.
+
address@hidden linked list
address@hidden
+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.
address@hidden quotation
 
 @cindex atoms
   Because cons cells are so central to Lisp, we also have a word for
@@ -1025,40 +1030,40 @@
 @node Non-ASCII in Strings
 @subsubsection address@hidden Characters in Strings
 
-  You can include a address@hidden international character in a string
-constant by writing it literally.  There are two text representations
-for address@hidden 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 address@hidden international character in a
+string constant by writing it literally.  There are two text
+representations for address@hidden 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 address@hidden
+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 address@hidden character as unibyte,
+and makes the string unibyte.
 
-  You can also represent a multibyte address@hidden character with its
-character code: use a hex escape, @address@hidden, with as many
-digits as necessary.  (Multibyte address@hidden 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 @address@hidden }} (backslash and space) to
-terminate the hex escape---for example, @address@hidden }} represents
-one character, @samp{a} with grave accent.  @address@hidden }} 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 address@hidden character literally into a
+multibyte string, you can write it as its character code using a hex
+escape, @address@hidden, with as many digits as necessary.
+(Multibyte address@hidden 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 @address@hidden }}
+(backslash and space) to terminate the hex escape---for example,
address@hidden@samp{\xe0\ }} represents one character, @samp{a} with grave
+accent.  @address@hidden }} 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 address@hidden 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 @@
 @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.
 
address@hidden 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
address@hidden  For other types (e.g., lists, vectors, strings), two
-arguments with the same contents or elements are not necessarily
address@hidden 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
address@hidden).  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 @@
 @end group
 @end example
 
address@hidden
 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 @@
 
 @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 @@
 @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
address@hidden to also compare text properties.  For
-technical reasons, a unibyte string and a multibyte string are
address@hidden 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.
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-01-21 14:58:38 +0000
+++ b/etc/NEWS  2012-01-21 16:04:55 +0000
@@ -1367,6 +1367,9 @@
 (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.