procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Checked lispref/internals.texi, somewhat

Browse source 
* 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.
This commit is contained in:
Glenn Morris 2012-03-03 14:13:28 -08:00
parent fbae463706
commit 7d2d7cc065
3 changed files with 116 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
admin/FOR-RELEASE
View file

@ -203,7 +203,8 @@ hash.texi cyd
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

6
doc/lispref/ChangeLog
View file

@ -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.

185
doc/lispref/internals.texi
View file

@ -538,7 +538,7 @@ usage: (or CONDITIONS ...) */)
@group
while (CONSP (args))
@{
val = Feval (XCAR (args));
val = eval_sub (XCAR (args));
if (!NILP (val))
break;
args = XCDR (args);
@ -603,6 +603,8 @@ the argument of @code{interactive} in a Lisp function. In the case of
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
@code{narrow-to-region} in @file{editfns.c}.
@item doc
This is the documentation string. It uses C comment syntax rather
@ -641,19 +643,22 @@ have types @code{int} and @w{@code{Lisp_Object *}}.
``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
@code{Feval} or anything that can directly or indirectly call
@code{Feval}. At such a time, any Lisp object that this function may
refer to again must be protected somehow.
@code{eval_sub} (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}).
@ignore
@footnote{Formerly, strings were a special exception; in older Emacs
versions, every local variable that might point to a string needed a
@code{GCPRO}.}.
@end 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 @@ with initializers are allocated in an area of memory that becomes
read-only (on certain operating systems) as a result of dumping Emacs.
@xref{Pure Storage}.
@c 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 @@ store a suitable subr object in its function cell. The code looks like
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 @@ with a value that is either @code{t} or @code{nil}. Note that variables
defined with @code{DEFVAR_BOOL} are automatically added to the list
@code{byte-boolean-vars} used by the byte compiler.
@cindex 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
@file{cus-start.el}.
@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 @@ of macros and functions to manipulate Lisp objects.
@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;
Lisp_Object lx, ly;
@end group
@group
CHECK_LIVE_WINDOW (window, 0);
CHECK_CONS (coordinates, 1);
x = XINT (Fcar (coordinates));
y = XINT (Fcdr (coordinates));
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);
@end group
@group
switch (coordinates_in_window (XWINDOW (window), &x, &y))
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
@group
case 1: /* In text part of window. */
return Fcons (make_number (x), make_number (y));
@end 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 @@ number of arguments. They work by calling @code{Ffuncall}.
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 @@ knows about it.
@section Object Internals
@cindex object internals
@c 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 @@ explicitly using a suitable predicate (@pxref{Type Predicates}).
@cindex internals, of buffer
@cindex buffer internals
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.
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 @@ The interval tree which records the text properties of this buffer.
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
@item 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 @@ after the current overlay center. @xref{Managing Overlays}.
and @code{overlays_after} is sorted in order of increasing beginning
position.
@c 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 @@ the value of the buffer-local variable @code{buffer-file-name}
@item undo_list
@itemx backed_up
@itemx auto_save_file_name
@itemx auto_save_file_format
@itemx read_only
@itemx file_format
@itemx file_truename
@ -1075,15 +1095,15 @@ when the buffer is not current.
@itemx truncate_lines
@itemx word_wrap
@itemx ctl_arrow
@itemx bidi_display_reordering
@itemx bidi_paragraph_direction
@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
@ -1113,7 +1133,8 @@ if that window no longer displays this buffer.
@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
@code{struct window} in @file{window.h}) include:
@table @code
@item frame
@ -1137,7 +1158,8 @@ leaves of the tree, which actually display buffers.
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 non-@code{nil}.
@item next
@itemx prev
@ -1214,11 +1236,19 @@ window was last updated.
@item vertical_scroll_bar
This window's vertical scroll bar.
@item left_margin_width
@itemx right_margin_width
@item left_margin_cols
@itemx right_margin_cols
The widths of the left and right margins in this window. A value of
@code{nil} means to use the buffer's value of @code{left-margin-width}
or @code{right-margin-width}.
@code{nil} means no margin.
@item left_fringe_width
@itemx right_fringe_width
The widths of the left and right fringes in this window. A value of
@code{nil} or @code{t} means use the values of the frame.
@item fringes_outside_margins
A non-@code{nil} 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 @@ The window-relative vertical position of the line containing
@item window_end_valid
This field is set to a non-@code{nil} 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 @@ The value of @code{cursor} as of the last redisplay that finished.
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.
@c FIXME What is this?
@c itemx phys_cursor_ascent
@itemx phys_cursor_height
@itemx 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 @@ This is used for displaying the line number of point in the mode line.
@item base_line_pos
The position in the buffer for which the line number is known, or
@code{nil} meaning none is known.
@code{nil} 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 @@ The column number currently displayed in this window's mode line, or @code{nil}
if column numbers are not being displayed.
@item current_matrix
A glyph matrix describing the current display of this window.
@item desired_matrix
A glyph matrix describing the desired display of this window.
@itemx desired_matrix
Glyph matrices describing the current and desired display of this window.
@end table
@node Process Internals
@ -1308,7 +1343,8 @@ A glyph matrix describing the desired display of this window.
@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
@code{struct Lisp_Process} in @file{process.h}) include:
@table @code
@item name
@ -1320,21 +1356,24 @@ process. For a network or serial process, it is @code{nil} if the
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 non-@code{nil}, 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 non-@code{nil}, 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, non-@code{nil} 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
@code{make-network-process} 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 @@ of the buffer.
If this is non-zero, killing Emacs while this process is still running
does not ask for confirmation about killing the process.
@item raw_status_low
@itemx raw_status_high
These two fields record 16 bits each of the process status returned by
the @code{wait} system call.
@item 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 @@ The file descriptor for input from the process.
@item outfd
The file descriptor for output to the process.
@item 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
@code{nil}.)
@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 @@ Coding-system for encoding the output to this process.
@item encoding_buf
A working buffer for encoding.
@item 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},
@code{serial}
@code{serial}.
@end table
@c FIXME Mention src/globals.h somewhere in this file?