Mercurial > emacs

--- a/doc/lispref/internals.texi	Mon May 04 04:07:11 2009 +0000
+++ b/doc/lispref/internals.texi	Mon May 04 04:07:28 2009 +0000
@@ -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.
-@xref{Buffer Gap}.
+@itemx 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.
-
-@item gpt_byte
-Contains the byte position of the gap.
-
-@item z_byte
-Holds the byte position of the end of the buffer text.
+@itemx 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.
-
-@item save_modiff
-Contains the previous value of @code{modiff}, as of the last time a
-buffer was visited or saved in a file.
-
-@item overlay_modiff
-Counts modifications to overlays analogous to @code{modiff}.
+@itemx save_modiff
+@itemx chars_modiff
+@itemx 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;
+@code{save_modiff} 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.
-
-@item 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.
+@itemx 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},
-@code{beg_unchanged} and @code{end_unchanged} contain no useful
-information.
-
-@item 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},
+@itemx overlay_unchanged_modified
+The values of @code{modiff} and @code{overlay_modiff}, respectively,
+after the last compelete redisplay.  If their current values match
+@code{modiff} 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.
-
-@item pt_byte
-Contains the byte position of point in a buffer.
+@itemx 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.
-
-@item begv_byte
-This field contains the byte position of the beginning of the
-accessible range of text in the buffer.
+@itemx 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.
-
-@item zv_byte
-This field contains the byte position of the end of the
-accessible range of text in the buffer.
+@itemx 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.

-@item 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
-@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in
-fields in the buffer structure itself.  (Some of these fields are
+@item local_flags
+This field contains flags indicating that certain variables are local
+in this buffer.  Such variables are declared in the C code using
+@code{DEFVAR_PER_BUFFER}, 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.
-
-@item 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.
+@xref{Narrowing}.

 @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.
+
+@item overlay_center
+This field holds the current overlay center position.  @xref{Managing
+Overlays}.

-@item undo_list
-This field points to the buffer's undo list.  @xref{Undo}.
+@item overlays_before
+@itemx 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}.
+@code{overlays_before} 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}.
-
-@item filename
-The name of the file visited in this buffer, or @code{nil}.
-
-@item directory
-The directory for expanding relative file names.
+A Lisp string that names the buffer.  It is guaranteed to be unique.
+@xref{Buffer Names}.

 @item 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
-@code{buffer_text} structure because indirect buffers are never saved.
+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.  This is the value of
+the buffer-local variable @code{default-directory} (@pxref{File Name Expansion}).
+
+@item 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}).

-@item auto_save_file_name
-File name used for auto-saving this buffer.  This is not in the
-@code{buffer_text} because it's not used in indirect buffers at all.
-
-@item read_only
-Non-@code{nil} means this buffer is read-only.
+@item undo_list
+@itemx backed_up
+@itemx auto_save_file_name
+@itemx read_only
+@itemx file_format
+@itemx file_truename
+@itemx invisibility_spec
+@itemx display_count
+@itemx 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"}.
-
-@item 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.
-
-@item 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}.
-
-@item abbrev_table
-This buffer's local abbrevs.
-
-@item syntax_table
-This field contains the syntax table for the buffer.  @xref{Syntax Tables}.
-
-@item category_table
-This field contains the category table for the buffer.
-
-@item case_fold_search
-The value of @code{case-fold-search} in this buffer.
-
-@item tab_width
-The value of @code{tab-width} in this buffer.
-
-@item fill_column
-The value of @code{fill-column} in this buffer.
-
-@item left_margin
-The value of @code{left-margin} in this buffer.
-
-@item auto_fill_function
-The value of @code{auto-fill-function} in this buffer.
+@itemx abbrev_table
+@itemx syntax_table
+@itemx category_table
+@itemx 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.
-@xref{Case Tables}.
-
-@item upcase_table
-This field contains the conversion table for converting text to upper case.
+@itemx upcase_table
+@itemx 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}.

-@item case_canon_table
-This field contains the conversion table for canonicalizing text for
-case-folding search.  @xref{Case Tables}.
-
-@item case_eqv_table
-This field contains the equivalence table for case-folding search.
-@xref{Case Tables}.
-
-@item truncate_lines
-The value of @code{truncate-lines} in this buffer.
-
-@item ctl_arrow
-The value of @code{ctl-arrow} in this buffer.
-
-@item selective_display
-The value of @code{selective-display} in this buffer.
-
-@item 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.

-@item overwrite_mode
-The value of @code{overwrite_mode} in this buffer.
-
-@item abbrev_mode
-The value of @code{abbrev-mode} in this buffer.
-
-@item display_table
-This field contains the buffer's display table, or @code{nil} if it doesn't
-have one.  @xref{Display Tables}.
-
-@item save_modified
-This field contains the time when the buffer was last saved, as an integer.
-@xref{Buffer Modification}.
-
-@item mark_active
-This field is non-@code{nil} if the buffer's mark is active.
-
-@item 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.
-
-@item 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.
-
-@item overlay_center
-This field holds the current overlay center position.  @xref{Overlays}.
-
-@item enable_multibyte_characters
-This field holds the buffer's local value of
-@code{enable-multibyte-characters}---either @code{t} or @code{nil}.
-
-@item buffer_file_coding_system
-The value of @code{buffer-file-coding-system} in this buffer.
-
-@item file_format
-The value of @code{buffer-file-format} in this buffer.
-
-@item 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.
-
-@item 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
+@itemx begv_marker
+@itemx 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
+@code{pt}, @code{begv}, and @code{zv} respectively, for this buffer
 when the buffer is not current.

-@item 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.
-
-@item file_truename
-The truename of the visited file, or @code{nil}.
-
-@item invisibility_spec
-The value of @code{buffer-invisibility-spec} in this buffer.
+@item mode_line_format
+@itemx header_line_format
+@itemx case_fold_search
+@itemx tab_width
+@itemx fill_column
+@itemx left_margin
+@itemx auto_fill_function
+@itemx buffer_file_type
+@itemx truncate_lines
+@itemx word_wrap
+@itemx ctl_arrow
+@itemx selective_display
+@itemx selective_display_ellipses
+@itemx overwrite_mode
+@itemx abbrev_mode
+@itemx display_table
+@itemx mark_active
+@itemx enable_multibyte_characters
+@itemx buffer_file_coding_system
+@itemx auto_save_file_format
+@itemx cache_long_line_scans
+@itemx point_before_scroll
+@itemx left_fringe_width
+@itemx right_fringe_width
+@itemx fringes_outside_margins
+@itemx scroll_bar_width
+@itemx indicate_empty_lines
+@itemx indicate_buffer_boundaries
+@itemx fringe_indicator_alist
+@itemx fringe_cursor_alist
+@itemx scroll_up_aggressively
+@itemx scroll_down_aggressively
+@itemx cursor_type
+@itemx 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,
+@code{mode_line_format} stores the value of @code{mode-line-format}.
+@xref{Standard 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.
-
-@item display_count
-This field is incremented each time the buffer is displayed in a window.
-
-@item left_margin_width
-The value of @code{left-margin-width} in this buffer.
-
-@item right_margin_width
-The value of @code{right-margin-width} in this buffer.
-
-@item indicate_empty_lines
-Non-@code{nil} means indicate empty lines (lines with no text) with a
-small bitmap in the fringe, when using a window system that can do it.
-
-@item display_time
-This holds a time stamp that is updated each time this buffer is
-displayed in a window.
-
-@item scroll_up_aggressively
-The value of @code{scroll-up-aggressively} in this buffer.
-
-@item scroll_down_aggressively
-The value of @code{scroll-down-aggressively} in this buffer.
 @end table

 @node Window Internals