[Emacs-diffs] master 43b1bf3: Improve documentation of 'integer-width'

[Eli Zaretskii]

branch: master
commit 43b1bf355a8a3ec4c6175b0e76007b8bf3a32eca
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of 'integer-width'
    
    * etc/NEWS: Minor rewording of the recent addition.
    
    * doc/lispref/numbers.texi (Bitwise Operations): Use @dots{}
    for ellipsis.  Improve indexing.
---
 doc/lispref/numbers.texi | 113 ++++++++++++++++++++++++-----------------------
 etc/NEWS                 |  10 ++---
 2 files changed, 62 insertions(+), 61 deletions(-)

diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 9c16b1a..dd78bce 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -112,18 +112,18 @@ view the numbers in their binary form.
   In binary, the decimal integer 5 looks like this:
 
 @example
-...000101
address@hidden
 @end example
 
 @noindent
-(The @samp{...} stands for a conceptually infinite number of bits that
-match the leading bit; here, an infinite number of 0 bits.  Later
-examples also use this @samp{...} notation.)
+(The ellipsis @address@hidden stands for a conceptually infinite number
+of bits that match the leading bit; here, an infinite number of 0
+bits.  Later examples also use this @address@hidden notation.)
 
   The integer @minus{}1 looks like this:
 
 @example
-...111111
address@hidden
 @end example
 
 @noindent
@@ -136,7 +136,7 @@ In binary, the decimal integer 4 is 100.  Consequently,
 @minus{}5 looks like this:
 
 @example
-...111011
address@hidden
 @end example
 
   Many of the functions described in this chapter accept markers for
@@ -189,15 +189,16 @@ on 64-bit platforms.
 
 @cindex bignum range
 @cindex integer range
address@hidden number of bignum bits, limit on
 @defvar integer-width
 The value of this variable is a nonnegative integer that is an upper
 bound on the number of bits in a bignum.  Integers outside the fixnum
 range are limited to absolute values less than address@hidden@var{n}}, where
 @var{n} is this variable's value.  Attempts to create bignums outside
-this range result in integer overflow.  Setting this variable to zero
-disables creation of bignums; setting it to a large number can cause
-Emacs to consume large quantities of memory if a computation creates
-huge integers.
+this range result in an integer overflow error.  Setting this variable
+to zero disables creation of bignums; setting it to a large number can
+cause Emacs to consume large quantities of memory if a computation
+creates huge integers.
 @end defvar
 
   In Emacs Lisp, text characters are represented by integers.  Any
@@ -871,30 +872,30 @@ equivalent to dividing by two and then rounding toward 
minus infinity.
 @group
 (ash 7 1) @result{} 14
 ;; @r{Decimal 7 becomes decimal 14.}
-...000111
address@hidden
      @result{}
-...001110
address@hidden
 @end group
 
 @group
 (ash 7 -1) @result{} 3
-...000111
address@hidden
      @result{}
-...000011
address@hidden
 @end group
 
 @group
 (ash -7 1) @result{} -14
-...111001
address@hidden
      @result{}
-...110010
address@hidden
 @end group
 
 @group
 (ash -7 -1) @result{} -4
-...111001
address@hidden
      @result{}
-...111100
address@hidden
 @end group
 @end example
 
@@ -903,18 +904,18 @@ Here are examples of shifting left or right by two bits:
 @smallexample
 @group
                   ;  @r{       binary values}
-(ash 5 2)         ;   5  =  @r{...000101}
-     @result{} 20         ;      =  @r{...010100}
-(ash -5 2)        ;  -5  =  @r{...111011}
-     @result{} -20        ;      =  @r{...101100}
+(ash 5 2)         ;   5  =  @address@hidden
+     @result{} 20         ;      =  @address@hidden
+(ash -5 2)        ;  -5  =  @address@hidden
+     @result{} -20        ;      =  @address@hidden
 @end group
 @group
 (ash 5 -2)
-     @result{} 1          ;      =  @r{...000001}
+     @result{} 1          ;      =  @address@hidden
 @end group
 @group
 (ash -5 -2)
-     @result{} -2         ;      =  @r{...111110}
+     @result{} -2         ;      =  @address@hidden
 @end group
 @end smallexample
 @end defun
@@ -938,16 +939,16 @@ exceptional cases.  These examples assume 30-bit fixnums.
 @smallexample
 @group
                  ; @r{     binary values}
-(ash -7 -1)      ; -7 = @r{...111111111111111111111111111001}
-     @result{} -4        ;    = @r{...111111111111111111111111111100}
+(ash -7 -1)      ; -7 = @address@hidden
+     @result{} -4        ;    = @address@hidden
 (lsh -7 -1)
-     @result{} 536870908 ;    = @r{...011111111111111111111111111100}
+     @result{} 536870908 ;    = @address@hidden
 @end group
 @group
-(ash -5 -2)      ; -5 = @r{...111111111111111111111111111011}
-     @result{} -2        ;    = @r{...111111111111111111111111111110}
+(ash -5 -2)      ; -5 = @address@hidden
+     @result{} -2        ;    = @address@hidden
 (lsh -5 -2)
-     @result{} 268435454 ;    = @r{...001111111111111111111111111110}
+     @result{} 268435454 ;    = @address@hidden
 @end group
 @end smallexample
 @end defun
@@ -983,21 +984,21 @@ because its binary representation consists entirely of 
ones.  If
 @group
                    ; @r{       binary values}
 
-(logand 14 13)     ; 14  =  @r{...001110}
-                   ; 13  =  @r{...001101}
-     @result{} 12         ; 12  =  @r{...001100}
+(logand 14 13)     ; 14  =  @address@hidden
+                   ; 13  =  @address@hidden
+     @result{} 12         ; 12  =  @address@hidden
 @end group
 
 @group
-(logand 14 13 4)   ; 14  =  @r{...001110}
-                   ; 13  =  @r{...001101}
-                   ;  4  =  @r{...000100}
-     @result{} 4          ;  4  =  @r{...000100}
+(logand 14 13 4)   ; 14  =  @address@hidden
+                   ; 13  =  @address@hidden
+                   ;  4  =  @address@hidden
+     @result{} 4          ;  4  =  @address@hidden
 @end group
 
 @group
 (logand)
-     @result{} -1         ; -1  =  @r{...111111}
+     @result{} -1         ; -1  =  @address@hidden
 @end group
 @end smallexample
 @end defun
@@ -1013,16 +1014,16 @@ passed just one argument, it returns that argument.
 @group
                    ; @r{       binary values}
 
-(logior 12 5)      ; 12  =  @r{...001100}
-                   ;  5  =  @r{...000101}
-     @result{} 13         ; 13  =  @r{...001101}
+(logior 12 5)      ; 12  =  @address@hidden
+                   ;  5  =  @address@hidden
+     @result{} 13         ; 13  =  @address@hidden
 @end group
 
 @group
-(logior 12 5 7)    ; 12  =  @r{...001100}
-                   ;  5  =  @r{...000101}
-                   ;  7  =  @r{...000111}
-     @result{} 15         ; 15  =  @r{...001111}
+(logior 12 5 7)    ; 12  =  @address@hidden
+                   ;  5  =  @address@hidden
+                   ;  7  =  @address@hidden
+     @result{} 15         ; 15  =  @address@hidden
 @end group
 @end smallexample
 @end defun
@@ -1038,16 +1039,16 @@ result is 0, which is an identity element for this 
operation.  If
 @group
                    ; @r{       binary values}
 
-(logxor 12 5)      ; 12  =  @r{...001100}
-                   ;  5  =  @r{...000101}
-     @result{} 9          ;  9  =  @r{...001001}
+(logxor 12 5)      ; 12  =  @address@hidden
+                   ;  5  =  @address@hidden
+     @result{} 9          ;  9  =  @address@hidden
 @end group
 
 @group
-(logxor 12 5 7)    ; 12  =  @r{...001100}
-                   ;  5  =  @r{...000101}
-                   ;  7  =  @r{...000111}
-     @result{} 14         ; 14  =  @r{...001110}
+(logxor 12 5 7)    ; 12  =  @address@hidden
+                   ;  5  =  @address@hidden
+                   ;  7  =  @address@hidden
+     @result{} 14         ; 14  =  @address@hidden
 @end group
 @end smallexample
 @end defun
@@ -1060,9 +1061,9 @@ bit is one in the result if, and only if, the @var{n}th 
bit is zero in
 @example
 (lognot 5)
      @result{} -6
-;;  5  =  @r{...000101}
+;;  5  =  @address@hidden
 ;; @r{becomes}
-;; -6  =  @r{...111010}
+;; -6  =  @address@hidden
 @end example
 @end defun
 
@@ -1077,9 +1078,9 @@ its two's complement binary representation.  The result 
is always
 nonnegative.
 
 @example
-(logcount 43)     ;  43 = @r{...000101011}
+(logcount 43)     ;  43 = @address@hidden
      @result{} 4
-(logcount -43)    ; -43 = @r{...111010101}
+(logcount -43)    ; -43 = @address@hidden
      @result{} 3
 @end example
 @end defun
diff --git a/etc/NEWS b/etc/NEWS
index 9a74164..892797b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -871,11 +871,11 @@ bignums.  However, note that unlike fixnums, bignums will 
not compare
 equal with 'eq', you must use 'eql' instead.  (Numerical comparison
 with '=' works on both, of course.)
 
-+++
-** New variable 'integer-width'.
-It is a nonnegative integer specifying the maximum number of bits
-allowed in a bignum.  Integer overflow occurs if this limit is
-exceeded.
+Since large bignums consume a lot of memory, Emacs limits the size of
+the largest bignum a Lisp program is allowed to create.  The
+nonnegative value of the new variable 'integer-width' specifies the
+maximum number of bits allowed in a bignum.  Emacs signals an integer
+overflow error if this limit is exceeded.
 
 ** define-minor-mode automatically documents the meaning of ARG