[Emacs-diffs] emacs/doc/lispref internals.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/05/04 04:07:28

Modified files:
        doc/lispref    : internals.texi 

Log message:
        * internals.texi (Object Internals): Don't assume 32-bit machines
        are the norm.
        (Buffer Internals): Consolidate table entries for readability.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/internals.texi?cvsroot=emacs&r1=1.6&r2=1.7

Patches:
Index: internals.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/internals.texi,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- internals.texi      8 Jan 2009 05:28:59 -0000       1.6
+++ internals.texi      4 May 2009 04:07:28 -0000       1.7
@@ -815,11 +815,10 @@
 
   GNU Emacs Lisp manipulates many different types of data.  The actual
 data are stored in a heap and the only access that programs have to it
-is through pointers.  Pointers are thirty-two bits wide in most
-implementations.  Depending on the operating system and type of machine
-for which you compile Emacs, twenty-nine bits are used to address the
-object, and the remaining three bits are used for the tag that
-identifies the object's type.
+is through pointers.  Each pointer is 32 bits wide on 32-bit machines,
+and 64 bits wide on 64-bit machines; three of these bits are used for
+the tag that identifies the object's type, and the remainder are used
+to address the object.
 
   Because Lisp objects are represented as tagged pointers, it is always
 possible to determine the Lisp data type of any object.  The C data type
@@ -842,67 +841,53 @@
 @cindex internals, of buffer
 @cindex buffer internals
 
-  Buffers contain fields not directly accessible by the Lisp programmer.
-We describe them here, naming them by the names used in the C code.
-Many are accessible indirectly in Lisp programs via Lisp primitives.
-
-Two structures are used to represent buffers in C.  The
+  Two structures are used to represent buffers in C.  The
 @code{buffer_text} structure contains fields describing the text of a
 buffer; the @code{buffer} structure holds other fields.  In the case
 of indirect buffers, two or more @code{buffer} structures reference
 the same @code{buffer_text} structure.
 
-Here is a list of the @code{struct buffer_text} fields:
+Here are some of the fields in @code{struct buffer_text}:
 
 @table @code
 @item beg
-This field contains the actual address of the buffer contents.
+The address of the buffer contents.
 
 @item gpt
-This holds the character position of the gap in the buffer.
address@hidden Gap}.
address@hidden gpt_byte
+The character and byte positions of the buffer gap.  @xref{Buffer
+Gap}.
 
 @item z
-This field contains the character position of the end of the buffer
-text.
-
address@hidden gpt_byte
-Contains the byte position of the gap.
-
address@hidden z_byte
-Holds the byte position of the end of the buffer text.
address@hidden z_byte
+The character and byte positions of the end of the buffer text.
 
 @item gap_size
-Contains the size of buffer's gap.  @xref{Buffer Gap}.
+The size of buffer's gap.  @xref{Buffer Gap}.
 
 @item modiff
-This field counts buffer-modification events for this buffer.  It is
-incremented for each such event, and never otherwise changed.
-
address@hidden save_modiff
-Contains the previous value of @code{modiff}, as of the last time a
-buffer was visited or saved in a file.
-
address@hidden overlay_modiff
-Counts modifications to overlays analogous to @code{modiff}.
address@hidden save_modiff
address@hidden chars_modiff
address@hidden overlay_modiff
+These fields count the number of buffer-modification events performed
+in this buffer.  @code{modiff} is incremented after each
+buffer-modification event, and is never otherwise changed;
address@hidden contains the value of @code{modiff} the last time
+the buffer was visited or saved; @code{chars_modiff} counts only
+modifications to the characters in the buffer, ignoring all other
+kinds of changes; and @code{overlay_modiff} counts only modifications
+to the overlays.
 
 @item beg_unchanged
-Holds the number of characters at the start of the text that are known
-to be unchanged since the last redisplay that finished.
-
address@hidden end_unchanged
-Holds the number of characters at the end of the text that are known to
-be unchanged since the last redisplay that finished.
address@hidden end_unchanged
+The number of characters at the start and end of the text that are
+known to be unchanged since the last complete redisplay.
 
 @item unchanged_modified
-Contains the value of @code{modiff} at the time of the last redisplay
-that finished.  If this value matches @code{modiff},
address@hidden and @code{end_unchanged} contain no useful
-information.
-
address@hidden overlay_unchanged_modified
-Contains the value of @code{overlay_modiff} at the time of the last
-redisplay that finished.  If this value matches @code{overlay_modiff},
address@hidden overlay_unchanged_modified
+The values of @code{modiff} and @code{overlay_modiff}, respectively,
+after the last compelete redisplay.  If their current values match
address@hidden or @code{overlay_modiff}, that means
 @code{beg_unchanged} and @code{end_unchanged} contain no useful
 information.
 
@@ -912,286 +897,209 @@
 markers referring to this buffer text.
 
 @item intervals
-Contains the interval tree which records the text properties of this
-buffer.
+The interval tree which records the text properties of this buffer.
 @end table
 
-The fields of @code{struct buffer} are:
+Some of the fields of @code{struct buffer} are:
 
 @table @code
 @item next
-Points to the next buffer, in the chain of all buffers including killed
-buffers.  This chain is used only for garbage collection, in order to
-collect killed buffers properly.  Note that vectors, and most kinds of
-objects allocated as vectors, are all on one chain, but buffers are on a
-separate chain of their own.
+Points to the next buffer, in the chain of all buffers (including
+killed buffers).  This chain is used only for garbage collection, in
+order to collect killed buffers properly.  Note that vectors, and most
+kinds of objects allocated as vectors, are all on one chain, but
+buffers are on a separate chain of their own.
 
 @item own_text
-This is a @code{struct buffer_text} structure.  In an ordinary buffer,
-it holds the buffer contents.  In indirect buffers, this field is not
-used.
+A @code{struct buffer_text} structure that ordinarily holds the buffer
+contents.  In indirect buffers, this field is not used.
 
 @item text
-This points to the @code{buffer_text} structure that is used for this
-buffer.  In an ordinary buffer, this is the @code{own_text} field above.
-In an indirect buffer, this is the @code{own_text} field of the base
-buffer.
+A pointer to the @code{buffer_text} structure for this buffer.  In an
+ordinary buffer, this is the @code{own_text} field above.  In an
+indirect buffer, this is the @code{own_text} field of the base buffer.
 
 @item pt
-Contains the character position of point in a buffer.
-
address@hidden pt_byte
-Contains the byte position of point in a buffer.
address@hidden pt_byte
+The character and byte positions of point in a buffer.
 
 @item begv
-This field contains the character position of the beginning of the
-accessible range of text in the buffer.
-
address@hidden begv_byte
-This field contains the byte position of the beginning of the
-accessible range of text in the buffer.
address@hidden begv_byte
+The character and byte positions of the beginning of the accessible
+range of text in the buffer.
 
 @item zv
-This field contains the character position of the end of the
-accessible range of text in the buffer.
-
address@hidden zv_byte
-This field contains the byte position of the end of the
-accessible range of text in the buffer.
address@hidden zv_byte
+The character and byte positions of the end of the accessible range of
+text in the buffer.
 
 @item base_buffer
 In an indirect buffer, this points to the base buffer.  In an ordinary
 buffer, it is null.
 
address@hidden local_var_flags
-This field contains flags indicating that certain variables are local in
-this buffer.  Such variables are declared in the C code using
address@hidden, and their buffer-local bindings are stored in
-fields in the buffer structure itself.  (Some of these fields are
address@hidden local_flags
+This field contains flags indicating that certain variables are local
+in this buffer.  Such variables are declared in the C code using
address@hidden, and their buffer-local bindings are stored
+in fields in the buffer structure itself.  (Some of these fields are
 described in this table.)
 
 @item modtime
-This field contains the modification time of the visited file.  It is
-set when the file is written or read.  Before writing the buffer into a
-file, this field is compared to the modification time of the file to see
-if the file has changed on disk.  @xref{Buffer Modification}.
+The modification time of the visited file.  It is set when the file is
+written or read.  Before writing the buffer into a file, this field is
+compared to the modification time of the file to see if the file has
+changed on disk.  @xref{Buffer Modification}.
 
 @item auto_save_modified
-This field contains the time when the buffer was last auto-saved.
-
address@hidden auto_save_failure_time
-The time at which we detected a failure to auto-save, or -1 if we didn't
-have a failure.
+The time when the buffer was last auto-saved.
 
 @item last_window_start
-This field contains the @code{window-start} position in the buffer as of
-the last time the buffer was displayed in a window.
+The @code{window-start} position in the buffer as of the last time the
+buffer was displayed in a window.
 
 @item clip_changed
-This flag is set when narrowing changes in a buffer.
+This flag indicates that narrowing has changed in the buffer.
address@hidden
 
 @item prevent_redisplay_optimizations_p
-this flag indicates that redisplay optimizations should not be used
-to display this buffer.
+This flag indicates that redisplay optimizations should not be used to
+display this buffer.
 
address@hidden undo_list
-This field points to the buffer's undo list.  @xref{Undo}.
address@hidden overlay_center
+This field holds the current overlay center position.  @xref{Managing
+Overlays}.
+
address@hidden overlays_before
address@hidden overlays_after
+These fields hold, respectively, a list of overlays that end at or
+before the current overlay center, and a list of overlays that end
+after the current overlay center.  @xref{Managing Overlays}.
address@hidden is sorted in order of decreasing end position,
+and @code{overlays_after} is sorted in order of increasing beginning
+position.
 
 @item name
-The buffer name is a string that names the buffer.  It is guaranteed to
-be unique.  @xref{Buffer Names}.
+A Lisp string that names the buffer.  It is guaranteed to be unique.
address@hidden Names}.
 
address@hidden filename
-The name of the file visited in this buffer, or @code{nil}.
address@hidden save_length
+The length of the file this buffer is visiting, when last read or
+saved.  This and other fields concerned with saving are not kept in
+the @code{buffer_text} structure because indirect buffers are never
+saved.
 
 @item directory
-The directory for expanding relative file names.
+The directory for expanding relative file names.  This is the value of
+the buffer-local variable @code{default-directory} (@pxref{File Name 
Expansion}).
 
address@hidden save_length
-Length of the file this buffer is visiting, when last read or saved.
-This and other fields concerned with saving are not kept in the
address@hidden structure because indirect buffers are never saved.
-
address@hidden auto_save_file_name
-File name used for auto-saving this buffer.  This is not in the
address@hidden because it's not used in indirect buffers at all.
address@hidden filename
+The name of the file visited in this buffer, or @code{nil}.  This is
+the value of the buffer-local variable @code{buffer-file-name}
+(@pxref{Buffer File Name}).
 
address@hidden read_only
address@hidden means this buffer is read-only.
address@hidden undo_list
address@hidden backed_up
address@hidden auto_save_file_name
address@hidden read_only
address@hidden file_format
address@hidden file_truename
address@hidden invisibility_spec
address@hidden display_count
address@hidden display_time
+These fields store the values of Lisp variables that are automatically
+buffer-local (@pxref{Buffer-Local Variables}), whose corresponding
+variable names have the additional prefix @code{buffer-} and have
+underscores replaced with dashes.  For instance, @code{undo_list}
+stores the value of @code{buffer-undo-list}.  @xref{Standard
+Buffer-Local Variables}.
 
 @item mark
-This field contains the mark for the buffer.  The mark is a marker,
-hence it is also included on the list @code{markers}.  @xref{The Mark}.
+The mark for the buffer.  The mark is a marker, hence it is also
+included on the list @code{markers}.  @xref{The Mark}.
 
 @item local_var_alist
-This field contains the association list describing the buffer-local
-variable bindings of this buffer, not including the built-in
-buffer-local bindings that have special slots in the buffer object.
-(Those slots are omitted from this table.)  @xref{Buffer-Local
-Variables}.
+The association list describing the buffer-local variable bindings of
+this buffer, not including the built-in buffer-local bindings that
+have special slots in the buffer object.  (Those slots are omitted
+from this table.)  @xref{Buffer-Local Variables}.
 
 @item major_mode
 Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}.
 
 @item mode_name
-Pretty name of major mode, e.g., @code{"Lisp"}.
-
address@hidden mode_line_format
-Mode line element that controls the format of the mode line.  If this
-is @code{nil}, no mode line will be displayed.
-
address@hidden header_line_format
-This field is analogous to @code{mode_line_format} for the mode
-line displayed at the top of windows.
+Pretty name of the major mode, e.g., @code{"Lisp"}.
 
 @item keymap
-This field holds the buffer's local keymap.  @xref{Keymaps}.
-
address@hidden abbrev_table
-This buffer's local abbrevs.
-
address@hidden syntax_table
-This field contains the syntax table for the buffer.  @xref{Syntax Tables}.
-
address@hidden category_table
-This field contains the category table for the buffer.
-
address@hidden case_fold_search
-The value of @code{case-fold-search} in this buffer.
-
address@hidden tab_width
-The value of @code{tab-width} in this buffer.
-
address@hidden fill_column
-The value of @code{fill-column} in this buffer.
-
address@hidden left_margin
-The value of @code{left-margin} in this buffer.
-
address@hidden auto_fill_function
-The value of @code{auto-fill-function} in this buffer.
address@hidden abbrev_table
address@hidden syntax_table
address@hidden category_table
address@hidden display_table
+These fields store the buffer's local keymap (@pxref{Keymaps}), abbrev
+table (@pxref{Abbrev Tables}), syntax table (@pxref{Syntax Tables}),
+category table (@pxref{Categories}), and display table (@pxref{Display
+Tables}).
 
 @item downcase_table
-This field contains the conversion table for converting text to lower case.
address@hidden Tables}.
-
address@hidden upcase_table
-This field contains the conversion table for converting text to upper case.
address@hidden upcase_table
address@hidden case_canon_table
+These fields store the conversion tables for converting text to lower
+case, upper case, and for canonicalizing text for case-fold search.
 @xref{Case Tables}.
 
address@hidden case_canon_table
-This field contains the conversion table for canonicalizing text for
-case-folding search.  @xref{Case Tables}.
-
address@hidden case_eqv_table
-This field contains the equivalence table for case-folding search.
address@hidden Tables}.
-
address@hidden truncate_lines
-The value of @code{truncate-lines} in this buffer.
-
address@hidden ctl_arrow
-The value of @code{ctl-arrow} in this buffer.
-
address@hidden selective_display
-The value of @code{selective-display} in this buffer.
-
address@hidden selective_display_ellipsis
-The value of @code{selective-display-ellipsis} in this buffer.
-
 @item minor_modes
 An alist of the minor modes of this buffer.
 
address@hidden overwrite_mode
-The value of @code{overwrite_mode} in this buffer.
-
address@hidden abbrev_mode
-The value of @code{abbrev-mode} in this buffer.
-
address@hidden display_table
-This field contains the buffer's display table, or @code{nil} if it doesn't
-have one.  @xref{Display Tables}.
-
address@hidden save_modified
-This field contains the time when the buffer was last saved, as an integer.
address@hidden Modification}.
-
address@hidden mark_active
-This field is address@hidden if the buffer's mark is active.
-
address@hidden overlays_before
-This field holds a list of the overlays in this buffer that end at or
-before the current overlay center position.  They are sorted in order of
-decreasing end position.
-
address@hidden overlays_after
-This field holds a list of the overlays in this buffer that end after
-the current overlay center position.  They are sorted in order of
-increasing beginning position.
-
address@hidden overlay_center
-This field holds the current overlay center position.  @xref{Overlays}.
-
address@hidden enable_multibyte_characters
-This field holds the buffer's local value of
address@hidden @code{t} or @code{nil}.
-
address@hidden buffer_file_coding_system
-The value of @code{buffer-file-coding-system} in this buffer.
-
address@hidden file_format
-The value of @code{buffer-file-format} in this buffer.
-
address@hidden auto_save_file_format
-The value of @code{buffer-auto-save-file-format} in this buffer.
-
 @item pt_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records point for this buffer when the
-buffer is not current.
-
address@hidden begv_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records @code{begv} for this buffer
address@hidden begv_marker
address@hidden zv_marker
+These fields are only used in an indirect buffer, or in a buffer that
+is the base of an indirect buffer.  Each holds a marker that records
address@hidden, @code{begv}, and @code{zv} respectively, for this buffer
 when the buffer is not current.
 
address@hidden zv_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records @code{zv} for this buffer when
-the buffer is not current.
-
address@hidden file_truename
-The truename of the visited file, or @code{nil}.
-
address@hidden invisibility_spec
-The value of @code{buffer-invisibility-spec} in this buffer.
address@hidden mode_line_format
address@hidden header_line_format
address@hidden case_fold_search
address@hidden tab_width
address@hidden fill_column
address@hidden left_margin
address@hidden auto_fill_function
address@hidden buffer_file_type
address@hidden truncate_lines
address@hidden word_wrap
address@hidden ctl_arrow
address@hidden selective_display
address@hidden selective_display_ellipses
address@hidden overwrite_mode
address@hidden abbrev_mode
address@hidden display_table
address@hidden mark_active
address@hidden enable_multibyte_characters
address@hidden buffer_file_coding_system
address@hidden auto_save_file_format
address@hidden cache_long_line_scans
address@hidden point_before_scroll
address@hidden left_fringe_width
address@hidden right_fringe_width
address@hidden fringes_outside_margins
address@hidden scroll_bar_width
address@hidden indicate_empty_lines
address@hidden indicate_buffer_boundaries
address@hidden fringe_indicator_alist
address@hidden fringe_cursor_alist
address@hidden scroll_up_aggressively
address@hidden scroll_down_aggressively
address@hidden cursor_type
address@hidden cursor_in_non_selected_windows
+These fields store the values of Lisp variables that are automatically
+buffer-local (@pxref{Buffer-Local Variables}), whose corresponding
+variable names have underscores replaced with dashes.  For instance,
address@hidden stores the value of @code{mode-line-format}.
address@hidden Buffer-Local Variables}.
 
 @item last_selected_window
 This is the last window that was selected with this buffer in it, or @code{nil}
 if that window no longer displays this buffer.
-
address@hidden display_count
-This field is incremented each time the buffer is displayed in a window.
-
address@hidden left_margin_width
-The value of @code{left-margin-width} in this buffer.
-
address@hidden right_margin_width
-The value of @code{right-margin-width} in this buffer.
-
address@hidden indicate_empty_lines
address@hidden means indicate empty lines (lines with no text) with a
-small bitmap in the fringe, when using a window system that can do it.
-
address@hidden display_time
-This holds a time stamp that is updated each time this buffer is
-displayed in a window.
-
address@hidden scroll_up_aggressively
-The value of @code{scroll-up-aggressively} in this buffer.
-
address@hidden scroll_down_aggressively
-The value of @code{scroll-down-aggressively} in this buffer.
 @end table
 
 @node Window Internals