[Emacs-diffs] /srv/bzr/emacs/trunk r107492: Checked lispref/internals.texi, somewhat

[Glenn Morris]

------------------------------------------------------------
revno: 107492
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2012-03-03 14:13:28 -0800
message:
  Checked lispref/internals.texi, somewhat
  
  * doc/lispref/internals.texi: (Writing Emacs Primitives):
  Update Fcoordinates_in_window_p and For example definitions.
  Give examples of things with non-nil interactive args.  Mention eval_sub.
  Remove old info about strings and GCPRO.  Mention cus-start.el.
  (Buffer Internals, Window Internals, Process Internals):
  Misc small updates and fixes for fields.
  
  * admin/FOR-RELEASE: Related markup.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/internals.texi

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-03-03 01:29:55 +0000
+++ b/admin/FOR-RELEASE 2012-03-03 22:13:28 +0000
@@ -203,7 +203,8 @@
 help.texi         cyd
 hooks.texi        rgm
 index.texi
-internals.texi    
+internals.texi    rgm  (I don't know much about this, so it would be
+    good if someone else could at least look at the FIXME? comments.)
 intro.texi        cyd
 keymaps.texi      cyd
 lists.texi        cyd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-03 04:18:09 +0000
+++ b/doc/lispref/ChangeLog     2012-03-03 22:13:28 +0000
@@ -5,6 +5,12 @@
        Replace deleted eval-at-startup with custom-initialize-delay.
        (Pure Storage): Small changes.
        (Memory Usage): Copyedit.
+       (Writing Emacs Primitives): Update Fcoordinates_in_window_p and For
+       example definitions. Give examples of things with non-nil
+       interactive args.  Mention eval_sub.  Remove old info about
+       strings and GCPRO.  Mention cus-start.el.
+       (Buffer Internals, Window Internals, Process Internals):
+       Misc small updates and fixes for fields.
 
        * tips.texi: Copyedits.
        (Coding Conventions): Mention autoloads.

=== modified file 'doc/lispref/internals.texi'
--- a/doc/lispref/internals.texi        2012-03-03 04:18:09 +0000
+++ b/doc/lispref/internals.texi        2012-03-03 22:13:28 +0000
@@ -538,7 +538,7 @@
 @group
   while (CONSP (args))
     @{
-      val = Feval (XCAR (args));
+      val = eval_sub (XCAR (args));
       if (!NILP (val))
         break;
       args = XCDR (args);
@@ -603,6 +603,8 @@
 called interactively.  A value of @code{""} indicates a function that
 should receive no arguments when called interactively.  If the value
 begins with a @samp{(}, the string is evaluated as a Lisp form.
+For examples of the last two forms, see @code{widen} and
address@hidden in @file{editfns.c}.
 
 @item doc
 This is the documentation string.  It uses C comment syntax rather
@@ -641,19 +643,22 @@
 ``protect'' a variable from garbage collection---to inform the garbage
 collector that it must look in that variable and regard its contents
 as an accessible object.  GC protection is necessary whenever you call
address@hidden or anything that can directly or indirectly call
address@hidden  At such a time, any Lisp object that this function may
-refer to again must be protected somehow.
address@hidden (or @code{Feval}) either directly or indirectly.
+At such a time, any Lisp object that this function may refer to again
+must be protected somehow.
 
   It suffices to ensure that at least one pointer to each object is
 GC-protected; that way, the object cannot be recycled, so all pointers
 to it remain valid.  Thus, a particular local variable can do without
 protection if it is certain that the object it points to will be
-preserved by some other pointer (such as another local variable which
-has a @code{GCPRO})@footnote{Formerly, strings were a special
-exception; in older Emacs versions, every local variable that might
-point to a string needed a @code{GCPRO}.}.  Otherwise, the local
-variable needs a @code{GCPRO}.
+preserved by some other pointer (such as another local variable that
+has a @code{GCPRO}).
address@hidden
address@hidden, strings were a special exception; in older Emacs
+versions, every local variable that might point to a string needed a
address@hidden
address@hidden ignore
+Otherwise, the local variable needs a @code{GCPRO}.
 
   The macro @code{GCPRO1} protects just one local variable.  If you
 want to protect two variables, use @code{GCPRO2} instead; repeating
@@ -682,6 +687,7 @@
 read-only (on certain operating systems) as a result of dumping Emacs.
 @xref{Pure Storage}.
 
address@hidden FIXME is this still true?  I don't think so...
   Do not use static variables within functions---place all static
 variables at top level in the file.  This is necessary because Emacs on
 some operating systems defines the keyword @code{static} as a null
@@ -696,12 +702,11 @@
 this:
 
 @example
-defsubr (&@var{subr-structure-name});
+defsubr (&@var{sname});
 @end example
 
 @noindent
-Here @var{subr-structure-name} is the name you used as the third
-argument to @code{DEFUN}.
+Here @var{sname} is the name you used as the third argument to @code{DEFUN}.
 
   If you add a new primitive to a file that already has Lisp primitives
 defined in it, find the function (near the end of the file) named
@@ -726,6 +731,11 @@
 defined with @code{DEFVAR_BOOL} are automatically added to the list
 @code{byte-boolean-vars} used by the byte compiler.
 
address@hidden defining customization variables in C
+  If you want to make a Lisp variables that is defined in C behave
+like one declared with @code{defcustom}, add an appropriate entry to
address@hidden
+
 @cindex @code{staticpro}, protection from GC
   If you define a file-scope C variable of type @code{Lisp_Object},
 you must protect it from garbage-collection by calling @code{staticpro}
@@ -742,48 +752,53 @@
 @smallexample
 @group
 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
-  Scoordinates_in_window_p, 2, 2,
-  "xSpecify coordinate pair: \nXExpression which evals to window: ",
-  "Return non-nil if COORDINATES is in WINDOW.\n\
-COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
-...
+  Scoordinates_in_window_p, 2, 2, 0,
+  doc: /* Return non-nil if COORDINATES are in WINDOW.
+  ...
 @end group
 @group
-If they are on the border between WINDOW and its right sibling,\n\
-   `vertical-line' is returned.")
-  (coordinates, window)
-     register Lisp_Object coordinates, window;
+  or `right-margin' is returned.  */)
+  (register Lisp_Object coordinates, Lisp_Object window)
 @{
+  struct window *w;
+  struct frame *f;
   int x, y;
address@hidden group
-
address@hidden
-  CHECK_LIVE_WINDOW (window, 0);
-  CHECK_CONS (coordinates, 1);
-  x = XINT (Fcar (coordinates));
-  y = XINT (Fcdr (coordinates));
address@hidden group
-
address@hidden
-  switch (coordinates_in_window (XWINDOW (window), &x, &y))
+  Lisp_Object lx, ly;
address@hidden group
+
address@hidden
+  CHECK_LIVE_WINDOW (window);
+  w = XWINDOW (window);
+  f = XFRAME (w->frame);
+  CHECK_CONS (coordinates);
+  lx = Fcar (coordinates);
+  ly = Fcdr (coordinates);
+  CHECK_NUMBER_OR_FLOAT (lx);
+  CHECK_NUMBER_OR_FLOAT (ly);
+  x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH(f);
+  y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH(f);
address@hidden group
+
address@hidden
+  switch (coordinates_in_window (w, x, y))
     @{
-    case 0:                     /* NOT in window at all. */
+    case ON_NOTHING:            /* NOT in window at all. */
       return Qnil;
 @end group
 
address@hidden
-    case 1:                     /* In text part of window. */
-      return Fcons (make_number (x), make_number (y));
address@hidden group
+    ...
 
 @group
-    case 2:                     /* In mode line of window. */
+    case ON_MODE_LINE:          /* In mode line of window. */
       return Qmode_line;
 @end group
 
+    ...
+
 @group
-    case 3:                     /* On right border of window.  */
-      return Qvertical_line;
+    case ON_SCROLL_BAR:         /* On scroll-bar of window.  */
+      /* Historically we are supposed to return nil in this case.  */
+      return Qnil;
 @end group
 
 @group
@@ -814,7 +829,7 @@
 functions.
 
   If you define a function which is side-effect free, update the code
-in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
+in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
 @code{side-effect-and-error-free-fns} so that the compiler optimizer
 knows about it.
 
@@ -822,6 +837,7 @@
 @section Object Internals
 @cindex object internals
 
address@hidden FIXME Is this still true?  Does --with-wide-int affect anything?
   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.  Each pointer is 32 bits wide on 32-bit machines,
@@ -850,11 +866,11 @@
 @cindex internals, of buffer
 @cindex buffer internals
 
-  Two structures are used to represent buffers in C.  The
address@hidden 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.
+  Two structures (see @file{buffer.h}) 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 are some of the fields in @code{struct buffer_text}:
 
@@ -912,8 +928,9 @@
 Some of the fields of @code{struct buffer} are:
 
 @table @code
address@hidden next
-Points to the next buffer, in the chain of all buffers (including
address@hidden header
+A @code{struct vectorlike_header} structure where @code{header.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
@@ -987,6 +1004,8 @@
 and @code{overlays_after} is sorted in order of increasing beginning
 position.
 
address@hidden FIXME? the following are now all Lisp_Object 
BUFFER_INTERNAL_FIELD (foo).
+
 @item name
 A Lisp string that names the buffer.  It is guaranteed to be unique.
 @xref{Buffer Names}.
@@ -1009,6 +1028,7 @@
 @item undo_list
 @itemx backed_up
 @itemx auto_save_file_name
address@hidden auto_save_file_format
 @itemx read_only
 @itemx file_format
 @itemx file_truename
@@ -1075,15 +1095,15 @@
 @itemx truncate_lines
 @itemx word_wrap
 @itemx ctl_arrow
address@hidden bidi_display_reordering
address@hidden bidi_paragraph_direction
 @itemx selective_display
 @itemx selective_display_ellipses
 @itemx overwrite_mode
 @itemx abbrev_mode
address@hidden display_table
 @itemx mark_active
 @itemx enable_multibyte_characters
 @itemx buffer_file_coding_system
address@hidden auto_save_file_format
 @itemx cache_long_line_scans
 @itemx point_before_scroll
 @itemx left_fringe_width
@@ -1113,7 +1133,8 @@
 @cindex internals, of window
 @cindex window internals
 
-  Windows have the following accessible fields:
+  The fields of a window (for a complete list, see the definition of
address@hidden window} in @file{window.h}) include:
 
 @table @code
 @item frame
@@ -1137,7 +1158,8 @@
 These fields contain the window's leftmost child and its topmost child
 respectively.  @code{hchild} is used if the window is subdivided
 horizontally by child windows, and @code{vchild} if it is subdivided
-vertically.
+vertically.  In a live window, only one of @code{hchild}, @code{vchild},
+and @code{buffer} (q.v.) is address@hidden
 
 @item next
 @itemx prev
@@ -1214,11 +1236,19 @@
 @item vertical_scroll_bar
 This window's vertical scroll bar.
 
address@hidden left_margin_width
address@hidden right_margin_width
address@hidden left_margin_cols
address@hidden right_margin_cols
 The widths of the left and right margins in this window.  A value of
address@hidden means to use the buffer's value of @code{left-margin-width}
-or @code{right-margin-width}.
address@hidden means no margin.
+
address@hidden left_fringe_width
address@hidden right_fringe_width
+The widths of the left and right fringes in this window.  A value of
address@hidden or @code{t} means use the values of the frame.
+
address@hidden fringes_outside_margins
+A address@hidden value means the fringes outside the display margins;
+othersize they are between the margin and the text.
 
 @item window_end_pos
 This is computed as @code{z} minus the buffer position of the last glyph
@@ -1234,7 +1264,7 @@
 
 @item window_end_valid
 This field is set to a address@hidden value if @code{window_end_pos} is truly
-valid.  This is @code{nil} if nontrivial redisplay is preempted since in that
+valid.  This is @code{nil} if nontrivial redisplay is pre-empted, since in that
 case the display that @code{window_end_pos} was computed for did not get
 onto the screen.
 
@@ -1248,13 +1278,19 @@
 A structure describing where the cursor of this window physically is.
 
 @item phys_cursor_type
-The type of cursor that was last displayed on this window.
address@hidden FIXME What is this?
address@hidden itemx phys_cursor_ascent
address@hidden phys_cursor_height
address@hidden phys_cursor_width
+The type, height, and width of the cursor that was last displayed on
+this window.
 
 @item phys_cursor_on_p
 This field is non-zero if the cursor is physically on.
 
 @item cursor_off_p
-Non-zero means the cursor in this window is logically on.
+Non-zero means the cursor in this window is logically off.  This is
+used for blinking the cursor.
 
 @item last_cursor_off_p
 This field contains the value of @code{cursor_off_p} as of the time of
@@ -1285,7 +1321,8 @@
 
 @item base_line_pos
 The position in the buffer for which the line number is known, or
address@hidden meaning none is known.
address@hidden meaning none is known.  If it is a buffer, don't display
+the line number as long as the window shows that buffer.
 
 @item region_showing
 If the region (or part of it) is highlighted in this window, this field
@@ -1297,10 +1334,8 @@
 if column numbers are not being displayed.
 
 @item current_matrix
-A glyph matrix describing the current display of this window.
-
address@hidden desired_matrix
-A glyph matrix describing the desired display of this window.
address@hidden desired_matrix
+Glyph matrices describing the current and desired display of this window.
 @end table
 
 @node Process Internals
@@ -1308,7 +1343,8 @@
 @cindex internals, of process
 @cindex process internals
 
-  The fields of a process are:
+  The fields of a process (for a complete list, see the definition of
address@hidden Lisp_Process} in @file{process.h}) include:
 
 @table @code
 @item name
@@ -1320,21 +1356,24 @@
 process is running or @code{t} if the process is stopped.
 
 @item filter
-A function used to accept output from the process instead of a buffer,
-or @code{nil}.
+If address@hidden, a function used to accept output from the process
+instead of a buffer.
 
 @item sentinel
-A function called whenever the process receives a signal, or @code{nil}.
+If address@hidden, a function called whenever the state of the process
+changes.
 
 @item buffer
 The associated buffer of the process.
 
 @item pid
 An integer, the operating system's process @acronym{ID}.
+Pseudo-processes such as network or serial connections use a value of 0.
 
 @item childp
-A flag, address@hidden if this is really a child process.
-It is @code{nil} for a network or serial connection.
+A flag, @code{t} if this is really a child process.  For a network or
+serial connection, it is a plist based on the arguments to
address@hidden or @code{make-serial-process}.
 
 @item mark
 A marker indicating the position of the end of the last output from this
@@ -1345,10 +1384,8 @@
 If this is non-zero, killing Emacs while this process is still running
 does not ask for confirmation about killing the process.
 
address@hidden raw_status_low
address@hidden raw_status_high
-These two fields record 16 bits each of the process status returned by
-the @code{wait} system call.
address@hidden raw_status
+The raw process status, as returned by the @code{wait} system call.
 
 @item status
 The process status, as @code{process-status} should return it.
@@ -1369,11 +1406,6 @@
 @item outfd
 The file descriptor for output to the process.
 
address@hidden subtty
-The file descriptor for the terminal that the subprocess is using.  (On
-some systems, there is no need to record this, so the value is
address@hidden)
-
 @item tty_name
 The name of the terminal that the subprocess is using,
 or @code{nil} if it is using pipes.
@@ -1393,15 +1425,14 @@
 @item encoding_buf
 A working buffer for encoding.
 
address@hidden encoding_carryover
-Size of carryover in encoding.
-
 @item inherit_coding_system_flag
 Flag to set @code{coding-system} of the process buffer from the
 coding system used to decode process output.
 
 @item type
 Symbol indicating the type of process: @code{real}, @code{network},
address@hidden
address@hidden
 
 @end table
+
address@hidden FIXME Mention src/globals.h somewhere in this file?