Merge: Document wide integers better.

diff --cc doc/emacs/ChangeLog
index 89a78263e94e69a4353d2e89a1f9e1139599bc85,3b61ca6ccba3afe0ce9ea89333d82f6e1c321789..6e69a96a2a84fb8cf4ecdf45e89c263f9d58b82e
--- 1/doc/emacs/ChangeLog
--- 2/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@@ -1,3 -1,9 +1,10 @@@
 -      * files.texi (Visiting): Default buffer maximum is now 2 EiB typically.
+ 2011-06-02  Paul Eggert  <eggert@cs.ucla.edu>
+ 
+       Document wide integers better.
+       * buffers.texi (Buffers):
++      * files.texi (Visiting): Document maxima for 64-bit machines,
++      and mention virtual memory limits.
+ 
  2011-05-28  Chong Yidong  <cyd@stupidchicken.com>
  
        * custom.texi (Hooks): Reorganize.  Mention Prog mode.

diff --cc doc/emacs/buffers.texi
index ae0d85f249bfda90e1e70dc42611c89ada16461f,ea48be48bf1a0747bf66a1e89862e6da712ad3f4..d4cc4f7bb6affd2e2ecfd5d4304e19add2799980
--- 1/doc/emacs/buffers.texi
--- 2/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@@ -43,8 -43,12 +43,11 @@@ can be different from the value in othe
    A buffer's size cannot be larger than some maximum, which is defined
  by the largest buffer position representable by the @dfn{Emacs
  integer} data type.  This is because Emacs tracks buffer positions
- using that data type.  For 32-bit machines, the largest buffer size is
- 512 megabytes.
 -using that data type.  For 64-bit machines, the maximum buffer size
++using that data type.  For typical 64-bit machines, the maximum buffer size
+ enforced by the data types is @math{2^61 - 2} bytes, or about 2 EiB.
 -For most 32-bit machines, the maximum is @math{2^31 - 1} bytes, or about 2 GiB.
 -For some older machines, the maximum is @math{2^29 - 2} bytes, or
++For typical 32-bit machines, the maximum is @math{2^29 - 2} bytes, or
+ about 512 MiB.  Buffer sizes are also limited by the size of Emacs's
+ virtual memory.
  
  @menu
  * Select Buffer::       Creating a new buffer or reselecting an old one.

diff --cc doc/lispref/ChangeLog
index 83cee10f8993d0ff6dd6ae5658a0faa84bb1c68c,a22b86cf36b6169fde68bdcf5e0520d4d814562c..54ad6abdb0794ea18216d1de38c4a72bcbc4cc90
--- 1/doc/lispref/ChangeLog
--- 2/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@@ -1,3 -1,14 +1,15 @@@
 -
+ 2011-06-03  Paul Eggert  <eggert@cs.ucla.edu>
+ 
+       Document wide integers better.
+       * files.texi (File Attributes): Document ino_t values better.
+       ino_t values no longer map to anything larger than a single cons.
 -      * objects.texi (Integer Type): Integers are typically 62 bits now.
+       * numbers.texi (Integer Basics, Integer Basics, Arithmetic Operations):
+       (Bitwise Operations):
++      * objects.texi (Integer Type): Use a binary notation that is a bit easier
++      to read, and that will port better if 62-bits becomes the default.
++      Fix or remove incorrect examples.
+       * os.texi (Time Conversion): Document time_t values better.
+ 
  2011-05-31  Lars Magne Ingebrigtsen  <larsi@gnus.org>
  
        * processes.texi (Process Information): Document

diff --cc doc/lispref/files.texi
index 72f39f681ae713463637ee53435b0d47b70bf33f,51c27ecc42f42ea3328908bdea04361141c31e8e..4d992bd2c515d7710329b6d4ad8e2aeb4ca2b392
--- 1/doc/lispref/files.texi
--- 2/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@@ -1236,13 -1236,10 +1236,14 @@@ deleted and recreated; @code{nil} other
  
  @item
  The file's inode number.  If possible, this is an integer.  If the
 -inode number @math{N} is too large to be represented as an integer in
 -Emacs Lisp, then the value has the form @code{(@var{high}
 -. @var{low})}, where @var{high} holds the high bits (i.e., all but the
 -low 16 bits) and @var{low} the low 16 bits.
 +inode number is too large to be represented as an integer in Emacs
- Lisp, but still fits into a 32-bit integer, then the value has the
++Lisp but dividing it by @math{2^16} yields a representable integer,
++then the value has the
 +form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
- bits.  If the inode is wider than 32 bits, the value is of the form
++bits.  If the inode number is too wide for even that, the value is of the form
 +@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
- the high 24 bits, @var{middle} the next 24 bits, and @var{low} the low
++the high bits, @var{middle} the middle 24 bits, and @var{low} the low
 +16 bits.
  
  @item
  The filesystem number of the device that the file is on.  Depending on

diff --cc doc/lispref/numbers.texi
index 2c73a03a26c5f90c6d201ef88762bf369900fb0a,ff057c22254e150957621031b9670d162803c984..65921f444e0d94666f4d238b67baebd56fdfafbf
--- 1/doc/lispref/numbers.texi
--- 2/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@@ -45,13 -46,14 +45,14 @@@ minimum range is @minus{}536870912 to 5
  @end tex
  to
  @ifnottex
 -2**61 - 1)
 +2**29 - 1),
  @end ifnottex
  @tex
 -@math{2^{61}-1})
 +@math{2^{29}-1}),
  @end tex
- but some machines may provide a wider range.  Many examples in this
- chapter assume an integer has 30 bits.
 -but some older machines provide only 30 bits.  Many examples in this
 -chapter assume that an integer has 62 bits and that floating point
++but some machines provide a wider range.  Many examples in this
++chapter assume that an integer has 30 bits and that floating point
+ numbers are IEEE double precision.
  @cindex overflow
  
    The Lisp reader reads an integer as a sequence of digits with optional
@@@ -94,20 -97,16 +95,21 @@@ from 2 to 36.  For example
  bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
  view the numbers in their binary form.
  
 -  In 62-bit binary, the decimal integer 5 looks like this:
 +  In 30-bit binary, the decimal integer 5 looks like this:
  
  @example
- 00 0000  0000 0000  0000 0000  0000 0101
 -0000...000101 (62 bits total)
++0000...000101 (30 bits total)
  @end example
  
- (We have inserted spaces between groups of 4 bits, and two spaces
- between groups of 8 bits, to make the binary integer easier to read.)
 +@noindent
++(The @samp{...} stands for enough bits to fill out a 30-bit word; in
++this case, @samp{...} stands for twenty 0 bits.  Later examples also
++use the @samp{...} notation to make binary integers easier to read.)
 +
    The integer @minus{}1 looks like this:
  
  @example
- 11 1111  1111 1111  1111 1111  1111 1111
 -1111...111111 (62 bits total)
++1111...111111 (30 bits total)
  @end example
  
  @noindent
@@@ -120,24 -119,24 +122,24 @@@ complement} notation.
  @minus{}5 looks like this:
  
  @example
- 11 1111  1111 1111  1111 1111  1111 1011
 -1111...111011 (62 bits total)
++1111...111011 (30 bits total)
  @end example
  
 -  In this implementation, the largest 62-bit binary integer value is
 -2,305,843,009,213,693,951 in decimal.  In binary, it looks like this:
 +  In this implementation, the largest 30-bit binary integer value is
 +536,870,911 in decimal.  In binary, it looks like this:
  
  @example
- 01 1111  1111 1111  1111 1111  1111 1111
 -0111...111111 (62 bits total)
++0111...111111 (30 bits total)
  @end example
  
    Since the arithmetic functions do not check whether integers go
 -outside their range, when you add 1 to 2,305,843,009,213,693,951, the value is the
 -negative integer @minus{}2,305,843,009,213,693,952:
 +outside their range, when you add 1 to 536,870,911, the value is the
 +negative integer @minus{}536,870,912:
  
  @example
 -(+ 1 2305843009213693951)
 -     @result{} -2305843009213693952
 -     @result{} 1000...000000 (62 bits total)
 +(+ 1 536870911)
 +     @result{} -536870912
-      @result{} 10 0000  0000 0000  0000 0000  0000 0000
++     @result{} 1000...000000 (30 bits total)
  @end example
  
    Many of the functions described in this chapter accept markers for
@@@ -508,8 -507,8 +510,8 @@@ commonly used
  if any argument is floating.
  
    It is important to note that in Emacs Lisp, arithmetic functions
- do not check for overflow.  Thus @code{(1+ 268435455)} may evaluate to
- @minus{}268435456, depending on your hardware.
 -do not check for overflow.  Thus @code{(1+ 2305843009213693951)} may
 -evaluate to @minus{}2305843009213693952, depending on your hardware.
++do not check for overflow.  Thus @code{(1+ 536870911)} may evaluate to
++@minus{}536870912, depending on your hardware.
  
  @defun 1+ number-or-marker
  This function returns @var{number-or-marker} plus 1.
@@@ -829,19 -828,19 +831,19 @@@ value of a positive integer by two, rou
  The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
  not check for overflow, so shifting left can discard significant bits
  and change the sign of the number.  For example, left shifting
- 536,870,911 produces @minus{}2 on a 30-bit machine:
 -2,305,843,009,213,693,951 produces @minus{}2 on a typical machine:
++536,870,911 produces @minus{}2 in the 30-bit implementation:
  
  @example
 -(lsh 2305843009213693951 1)  ; @r{left shift}
 +(lsh 536870911 1)          ; @r{left shift}
       @result{} -2
  @end example
  
- In binary, in the 30-bit implementation, the argument looks like this:
 -In binary, in the 62-bit implementation, the argument looks like this:
++In binary, the argument looks like this:
  
  @example
  @group
 -;; @r{Decimal 2,305,843,009,213,693,951}
 -0111...111111 (62 bits total)
 +;; @r{Decimal 536,870,911}
- 01 1111  1111 1111  1111 1111  1111 1111
++0111...111111 (30 bits total)
  @end group
  @end example
  
@@@ -851,7 -850,7 +853,7 @@@ which becomes the following when left s
  @example
  @group
  ;; @r{Decimal @minus{}2}
- 11 1111  1111 1111  1111 1111  1111 1110
 -1111...111110 (62 bits total)
++1111...111110 (30 bits total)
  @end group
  @end example
  @end defun
@@@ -874,9 -873,9 +876,9 @@@ looks like this
  @group
  (ash -6 -1) @result{} -3
  ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
- 11 1111  1111 1111  1111 1111  1111 1010
 -1111...111010 (62 bits total)
++1111...111010 (30 bits total)
       @result{}
- 11 1111  1111 1111  1111 1111  1111 1101
 -1111...111101 (62 bits total)
++1111...111101 (30 bits total)
  @end group
  @end example
  
@@@ -885,11 -884,11 +887,11 @@@ In contrast, shifting the pattern of bi
  
  @example
  @group
 -(lsh -6 -1) @result{} 2305843009213693949
 -;; @r{Decimal @minus{}6 becomes decimal 2,305,843,009,213,693,949.}
 -1111...111010 (62 bits total)
 +(lsh -6 -1) @result{} 536870909
 +;; @r{Decimal @minus{}6 becomes decimal 536,870,909.}
- 11 1111  1111 1111  1111 1111  1111 1010
++1111...111010 (30 bits total)
       @result{}
- 01 1111  1111 1111  1111 1111  1111 1101
 -0111...111101 (62 bits total)
++0111...111101 (30 bits total)
  @end group
  @end example
  
@@@ -899,10 -898,10 +901,10 @@@ Here are other examples
  @c     with smallbook but not with regular book! --rjc 16mar92
  @smallexample
  @group
-                    ;  @r{             30-bit binary values}
 -                   ;  @r{       62-bit binary values}
++                   ;  @r{       30-bit binary values}
  
- (lsh 5 2)          ;   5  =  @r{00 0000  0000 0000  0000 0000  0000 0101}
-      @result{} 20         ;      =  @r{00 0000  0000 0000  0000 0000  0001 0100}
+ (lsh 5 2)          ;   5  =  @r{0000...000101}
+      @result{} 20         ;      =  @r{0000...010100}
  @end group
  @group
  (ash 5 2)
@@@ -921,12 -920,13 +923,13 @@@
       @result{} 1
  @end group
  @group
- (lsh -5 -2)        ;  -5  =  @r{11 1111  1111 1111  1111 1111  1111 1011}
-      @result{} 268435454  ;      =  @r{00 0111  1111 1111  1111 1111  1111 1110}
+ (lsh -5 -2)        ;  -5  =  @r{1111...111011}
 -     @result{} 1152921504606846974
++     @result{} 268435454
+                    ;      =  @r{0011...111110}
  @end group
  @group
- (ash -5 -2)        ;  -5  =  @r{11 1111  1111 1111  1111 1111  1111 1011}
-      @result{} -2         ;      =  @r{11 1111  1111 1111  1111 1111  1111 1110}
+ (ash -5 -2)        ;  -5  =  @r{1111...111011}
+      @result{} -2         ;      =  @r{1111...111110}
  @end group
  @end smallexample
  @end defun
@@@ -961,11 -961,11 +964,11 @@@ because its binary representation consi
  
  @smallexample
  @group
-                    ; @r{               30-bit binary values}
 -                   ; @r{       62-bit binary values}
++                   ; @r{       30-bit binary values}
  
- (logand 14 13)     ; 14  =  @r{00 0000  0000 0000  0000 0000  0000 1110}
-                    ; 13  =  @r{00 0000  0000 0000  0000 0000  0000 1101}
-      @result{} 12         ; 12  =  @r{00 0000  0000 0000  0000 0000  0000 1100}
+ (logand 14 13)     ; 14  =  @r{0000...001110}
+                    ; 13  =  @r{0000...001101}
+      @result{} 12         ; 12  =  @r{0000...001100}
  @end group
  
  @group
@@@ -991,11 -991,11 +994,11 @@@ passed just one argument, it returns th
  
  @smallexample
  @group
-                    ; @r{              30-bit binary values}
 -                   ; @r{       62-bit binary values}
++                   ; @r{       30-bit binary values}
  
- (logior 12 5)      ; 12  =  @r{00 0000  0000 0000  0000 0000  0000 1100}
-                    ;  5  =  @r{00 0000  0000 0000  0000 0000  0000 0101}
-      @result{} 13         ; 13  =  @r{00 0000  0000 0000  0000 0000  0000 1101}
+ (logior 12 5)      ; 12  =  @r{0000...001100}
+                    ;  5  =  @r{0000...000101}
+      @result{} 13         ; 13  =  @r{0000...001101}
  @end group
  
  @group
@@@ -1016,11 -1016,11 +1019,11 @@@ result is 0, which is an identity eleme
  
  @smallexample
  @group
-                    ; @r{              30-bit binary values}
 -                   ; @r{       62-bit binary values}
++                   ; @r{       30-bit binary values}
  
- (logxor 12 5)      ; 12  =  @r{00 0000  0000 0000  0000 0000  0000 1100}
-                    ;  5  =  @r{00 0000  0000 0000  0000 0000  0000 0101}
-      @result{} 9          ;  9  =  @r{00 0000  0000 0000  0000 0000  0000 1001}
+ (logxor 12 5)      ; 12  =  @r{0000...001100}
+                    ;  5  =  @r{0000...000101}
+      @result{} 9          ;  9  =  @r{0000...001001}
  @end group
  
  @group
@@@ -1040,9 -1040,9 +1043,9 @@@ bit is one in the result if, and only i
  @example
  (lognot 5)
       @result{} -6
- ;;  5  =  @r{00 0000  0000 0000  0000 0000  0000 0101}
 -;;  5  =  @r{0000...000101} (62 bits total)
++;;  5  =  @r{0000...000101} (30 bits total)
  ;; @r{becomes}
- ;; -6  =  @r{11 1111  1111 1111  1111 1111  1111 1010}
 -;; -6  =  @r{1111...111010} (62 bits total)
++;; -6  =  @r{1111...111010} (30 bits total)
  @end example
  @end defun
  

diff --cc doc/lispref/objects.texi
index c58d54f13fc8f74839dce7e4874de118a6bf9a37,d5aa51098e74e2bf532ad0fe9de35f8f24d5cbb2..27d9ba10aef3eeb3264dadf401565f879c00c867
--- 1/doc/lispref/objects.texi
--- 2/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@@ -174,15 -174,15 +174,14 @@@ latter are unique to Emacs Lisp
  @end tex
  to
  @ifnottex
 -2**61 - 1)
 +2**29 - 1)
  @end ifnottex
  @tex
 -@math{2^{61}-1})
 +@math{2^{29}-1})
  @end tex
- on most machines.  (Some machines may provide a wider range.)  It is
- important to note that the Emacs Lisp arithmetic functions do not check
- for overflow.  Thus @code{(1+ 536870911)} is @minus{}536870912 on most
- machines.
 -on most machines.  Some machines may provide a narrower or wider
 -range; all machines provide at least 30 bits.  Emacs Lisp arithmetic
 -functions do not check for overflow.  Thus @code{(1+
 -2305843009213693951)} is @minus{}2305843009213693952 on most machines.
++on typical 32-bit machines.  (Some machines provide a wider range.)
++Emacs Lisp arithmetic functions do not check for overflow.  Thus
++@code{(1+ 536870911)} is @minus{}536870912 if Emacs integers are 30 bits.
  
    The read syntax for integers is a sequence of (base ten) digits with an
  optional sign at the beginning and an optional period at the end.  The
@@@ -203,8 -202,8 +201,8 @@@ leading @samp{+} or a final @samp{.}
  As a special exception, if a sequence of digits specifies an integer
  too large or too small to be a valid integer object, the Lisp reader
  reads it as a floating-point number (@pxref{Floating Point Type}).
- For instance, on most machines @code{536870912} is read as the
- floating-point number @code{536870912.0}.
 -For instance, on most machines @code{2305843009213693952} is read as the
 -floating-point number @code{2.305843009213694e+18}.
++For instance, if Emacs integers are 30 bits, @code{536870912} is read
++as the floating-point number @code{536870912.0}.
  
    @xref{Numbers}, for more information.