liberte@M.CS.UIUC.EDU (Daniel LaLiberte) (02/20/89)
Here are most of the noted questions in the manual. Some of them
will be simple to answer; but it takes time. Please post your
answers. Thanks for the help.
Dan LaLiberte
uiucdcs!liberte
liberte@cs.uiuc.edu
liberte%a.cs.uiuc.edu@uiucvmd.bitnet
==========
Backups
@defvar backup-by-copying
This global variable determines whether backup files will be made
by copying. If it is non-@code{nil}, then Emacs will always use copying
to create backup files. (How is this different from file-precious-flag??)
@end defvar
@defvar auto-save-visited-file-name
If this global variable is non-@code{nil}, then Emacs will auto-save buffers in
the files they are visiting (when practical???). Normally auto-save files
have other names (created by @code{make-auto-save-file-name}).
@end defvar
@defvar delete-auto-save-files
This global variable is used by the function
@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil}, then
auto-save files for the buffers will be deleted (when??).
@end defvar
Buffers
@node
@section Creating Buffers
The following two functions create buffers. @code{get-buffer-create}
may create a buffer if one by the given name doesn't exist.
@code{generate-new-buffer} always creates a new buffer, and gives it a
unique name.
Other functions that create buffers include @code{with-output-to-temp-buffer},
@code{create-file-buffer}, ...
Other functions that create buffers use these functions.
@xref{Finding and Visiting Files}.
(Which set the current buffer??)
@defun set-buffer buffer-or-name
This function makes @var{buffer-or-name} the current buffer. It does
not display the buffer in the currently selected window, however. This
means that as soon as Emacs returns to the command loop (or keyboard
input??), the buffer in the selected window will become current again.
@xref{Commands} to find out about the command loop.
Commands
@defun input-pending-p
This function determines whether command input is currently available.
It returns immediately and the result is @code{t} if so, @code{nil} otherwise.
Actually, the value is @code{nil} only if we can be sure that no input is
available. That is, there are times when the value is @code{t} even if
there may not be any command input available. (true??)
@end defun
@defun discard-input
This function discards the contents of the terminal input buffer and
flushs any keyboard macro that might be in the process of definition.
It returns @code{nil}.
In the example, the user may type a bunch of characters right after starting
the evaluation of the form. After the @code{sleep-for} finishes sleeping,
any characters that have been typed are discarded.
(anyone have a useful example??)
@example
(progn (sleep-for 2)
(discard-input))
@Arrow nil
@end example
@end defun
@node Aborting, Prefix Command Arguments, Command Keys, Commands
@section Aborting
Normally, @kbd{C-g} causes Emacs to @dfn{abort} whatever it is doing.
If aborted, Emacs returns to the currently active
command loop. If @kbd{C-g} is entered while waiting for command input,
the @code{keyboard-quit} command is executed instead.
Abort can only occur between atomic computations or while waiting for
input from the keyboard or a process. (but maybe not in read-char!!
true??) @kbd{C-g} does not cause an abort if input occurs while
evaluating a call to @code{read-key-sequence} or
@code{read-quoted-char}. (others??) @code{read-char} @emph{does} let
@kbd{C-g} quit.
Typing @kbd{C-g} sets @code{quit-flag} to a non-@code{nil} value.
Note that changing the keybinding of @kbd{C-g} would not prevent quitting.
Use @code{inhibit-quit} when, for various reasons, you do not want
@code{quit-flag} to abort the current computation. The incremental
search package, for example, binds @code{inhibit-quit} to @code{t} so
that it can intercept @kbd{C-g}.
@section Recursive Editing
It is possible to create a Emacs command loop from inside of a program,
allowing the user to perform arbitrary editing before returning to the
program that created the command loop. The functions and variables below
control the entry to and exit from command loops.
A command loop is created with @code{recursive-edit}.
@code{recursive-edit} sets up a tag (on the stack) named @code{exit},
which you may @code{throw} to (@pxref{throw}) in order to exit the
recursive edit. If you throw the value non-@code{t}, then
@code{recursive-edit} returns normally. Throwing a @code{t} value
causes @code{recursive-edit} to signal a @code{quit} error (with
@code{nil} data). (anything else??) You can also exit from
@code{recursive-edit} by calling @code{exit-recursive-edit},
@code{abort-recursive-edit}, or @code{top-level}.
Any @code{unwind-protect} unwind forms are
still evaluated no matter how @code{recursive-edit} is exited.
Byte Compiling
@defun byte-compile symbol
This function byte-compiles the function definition of @var{symbol},
replacing the previous definition with the compiled one. The function
cell of @var{symbol} must contain the actual code for the function;
i.e., the compiler will not follow indirection to another symbol.
@code{byte-compile} does not compile macros.
@code{byte-compile} is not autoloaded as are @code{byte-compile-file}
and @code{byte-recompile-directory}.
(which function calls are specially handled?? list in appendix)
@end defun
Debugging
Re: arg of debug function if non-nil
@item lambda
This is used to indicate that a function that is being debugged is
being entered.??
@item t
Is this used when?? It prints out @samp{Beginning evaluation
of function call form:} as the top line in the buffer.
@defcmd debug-on-entry function-name
This function requests @var{function-name} to invoke the debugger each time
it is called. It works by inserting the form @code{(debug 'debug)} into
the function definition as the first form.
Any function defined by Lisp code may be debugged, interpreted code or
compiled code. Even functions which are commands may be debugged. They
will enter the debugger when called inside of a function, or when called
interactively. Primitive functions (i.e., those written in C) may not be
debugged.
When called interactively, @var{function-name} is prompted for in the
minibuffer.
It returns @var{function-name}. If @code{debug-on-entry} is called
more than once on the same function, the second call does nothing
??A bug report has been sent, as presently it kills the function def
if called twice??
[Is this fixed??]
@defcmd cancel-debug-on-entry function-name
This function undoes the effect of @code{debug-on-entry} on
@var{function-name}.
It returns @var{function-name}. If @code{debug-on-entry} is called
more than once on the same function, the second call does nothing
??A bug report has been sent, as presently it kills the function def
if called twice??
[Is this fixed??]
When called interactively, @var{function-name} is prompted for in the
minibuffer.
@end defcmd
Displays
@defvar temp-buffer-show-hook
Non-@code{nil} means call as function to display a help buffer.
Used by @code{with-output-to-temp-buffer} (but could it be used elsewhere??).
@end defvar
Evaluation
@defvar values
The value of this variable is a list of values returned by all
expressions which were read, evaluated and printed. (how long can the
list be??) The order is reverse chronological.
(What is the use or purpose of values?? How does it relate to
the debugger??)
Some semantic questions:
What is the exact meaning of "special form"?? Is it a form such as
"(if a b c)" or is it the primitive "if"? Common Lisp, by
Steele gives both meanings. (special-form-p 'if) returns true.
Is the form "(func arg)" a function call? Or is the function call
what happens when the form is evaluated?
Files
@defcmd save-some-buffers &optional arg exiting
Save some modified file-visiting buffers. Asks user about each one.
With argument, saves all with no questions. (What about exiting??)
@end defcmd
@defcmd write-region start end filename &optional append visit
This function writes the region (of the current buffer) defined by
@var{start} and @var{end} into the file specified by @var{filename}.
If @var{append} is non-@code{nil}, then the region will be appended to the
existing file contents (if any).
If @var{visit} is @code{t}, then Emacs establishes an association between
the buffer and the file. It also sets the last file modification
time for the current buffer to filename's modtime, and marks the buffer as
not modified.
??If @var{visit} is neither @code{t} nor @code{nil}, then
Emacs will not print the message ``Wrote file''. I DON'T SEE THIS,
AND IT DOESN'T BEHAVE THIS WAY EITHER. ??
@end defcmd
@defun file-attributes pathname
This function returns a list of attributes of file @var{pathname}. If the
specified file cannot be opened, it returns @code{nil}.
...
@item 848920284
was last accessed on Aug 19 00:09. (how is this converted??)
@defun add-name-to-file oldname newname &optional ok-if-already-exists
...
Confirmation is requested if @var{ok-if-already-exists} is a number.
(Why??)
@defun delete-file filename
This function deletes the file @var{filename}. This function
is essentially the same as the Unix command @file{rm @var{filename}}.
It is an error (which??) if the file does not exist, or is not
deletable. (In Unix, a file is deletable if it is writable or its
directory is writable.)
@end defun
@defun file-name-as-directory pathname
This function returns a string representing @var{pathname} interpreted as a
directory. (interpreted?? explain!!) In Unix, this just appends a slash.
In VMS, it converts @file{[X]Y.DIR.1} to @file{[X.Y]}.
@defun make-temp-name string
This function generates a temporary name (string) starting with
@var{string}. The C fun mktemp == ?? Why is this a temp??
@defun expand-file-name filename &optional directory
...
Filenames containing @samp{.}, @samp{..}, or adjacent @samp{/}s as
components (??) are simplified. @samp{~} as a file is expanded into
the user's home directory.
@defun substitute-in-file-name filename
...
(What is the return value??)
@defun read-file-name prompt directory &optional default mustmatch
This function reads a file name in the minibuffer, prompting with
@var{prompt} and completing (??) in @var{directory}. If @var{default} is
non-@code{nil}, then it will be returned as the value if the user just
types @key{RET}. If not, the result is the string that (??)
Functions
@item Function
A @dfn{function} in general is anything that can be called in
Lisp code. In this manual, @dfn{function} will normally be used to
mean code written in Lisp. But the term is also sometimes used to refer to
primitives, special forms, and macros.
(should Function be used this way??
we need a consistent naming scheme!!)
Help
@defcmd Helper-describe-bindings
This function pops up a window displaying the help buffer containing a
listing of all of the key bindings from both the local and global keymaps.
(How is this different from @code{describe-bindings}??)
@end defcmd
@defcmd Helper-help
This function provides help for current mode. It prompts the user
in the minibuffer with a message: @code{Help (Type ? for further options)},
and then provides assistance for finding out what the key bindings are,
and what the mode is intended for. It returns @code{nil}.
(can it be customized??)
@end defcmd
@defvar help-char
The value of this variable is the character to recognize as meaning
Help. When it is read, do @code{(eval help-form)}, and display result
if it's a string. If @code{help-form}'s value is @code{nil}, this
character can be read normally. This variable is used in other contexts
than just the command loop. (where??)
@end defvar
Keymaps
@defconst meta-prefix-char
This global variable is the Meta-prefix character code. Normally it
will be @key{ESC}. It is used when translating a meta-character to
a two-character sequence so it can be looked up in a keymap. For
some keyboards, the @key{ESC} key may be so inconvenient that you
wish to change this variable to some other key.
(Can this be done in .emacs??)
@example
(setq meta-prefix-char "\C-?")
@end example
@end defconst
@defun global-unset-key key
This function removes the definition of @var{key} from the current
global map. One use of this function is to unset a key so that
a longer key may use the first key as a prefix---which would
not be allowed otherwise. (other consequences??)
(when does this function fail??)
Lists
@section Building Cons Cells and Lists
Many functions implicitly build lists, but they
ultimately build lists from cons cells with @code{cons} (true??).
@node
@section Alteration of List Structure
The car and cdr pointers of a cons cell are ultimately modified by
@code{setcar} and @code{setcdr}. (true?? should we list them all.)
@xref{delq} for another function that modifies cons cells.
Loading
@defopt load-path
...
The syntax of @code{EMACSLOADPATH} is the same as for @code{PATH};
each field is separated by @samp{:} (but "." is used for the current
working directory??). Here is an example of setting the variable
from a @file{.login} file.
Macros
There are several subtle bugs that should simply be avoided. (Where is
that fixed version of ` ??) The following forms do not work as one would
expect:
@example
(` (a . (, 1)))
@Arrow (a \, 1) ; Not (a . 1)
(` [a (, 1) c])
@arrow @i{ERROR:} Wrong type argument ; Not [a 1 c]
(` (, 2))
@Arrow (\, 2) ; Not 2
(` (a list of (, (list (+ 2 3))) elements xx))
@Arrow (a list of (5) elements xx)
@end example
@findex ,@@
It is also possible to have an evaluated list @dfn{spliced} into the
resulting list by using the special marker @code{,@@}. The elements of
the spliced list become elements at the same level as the other elements of the
resulting list. The equivalent code without using @code{`} is often
unreadable.
@example
(setq some-list '(2 3))
@Arrow (2 3)
(cons 1 (append some-list (list 4)))
@Arrow (1 2 3 4)
(` (1 (,@@ some-list) 4))
@Arrow (1 2 3 (4)) ???? bug ????
Minibuffers
@defvar cursor-in-echo-area
This global variable controls where the cursor will be placed when a
message is displayed in the echo area. If it is non-@code{nil}, then do
put the cursor there.
?? A bug here?? It gives bad results to me.
@end defvar
Modes
@defun hack-local-variables &optional force
Parse, and bind or evaluate as appropriate, any local variables for
current buffer. (What does @var{force} do??) @xref{Local Variables in
Files,,,,GNU Emacs Manual} for the syntax of the
@code{hack-local-variables} section of a file.
@end defun
(what is this for??: @code{(put some-mode 'mode-class 'special)})
Some minor modes are intended to change how text is inserted in a buffer.
In many cases, the biggest implementation problem for this kind of minor
mode is finding a way to insert the necessary hook into the running system.
The @code{auto-fill-hook} built into text insertion in C code is called
when @code{auto-fill-mode} is active and a space is inserted (typed??).
This hook is also used by @code{auto-justify-mode} because the two modes
are very similar.
Mode Line Format
@item %s
the process status (see @code{process-status}). (obsolete??)
OS interface
@defun dump-emacs filename symfile
This function dumps the current state of Emacs into an executable file
@var{filename}. It takes symbols from @var{symfile} (this is normally the file
@file{temacs}). (??)
You could use @code{dump-emacs} to create another Emacs executable...
@example
??
@end example
@xref{Snarf-documentation}
@end defun
@defun user-uid
This function returns the effective uid of the user. This will be
the real uid unless the user has (??).
@end defun
@defun set-input-mode interrupt flow
This function sets the mode for reading keyboard input. If
@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
@code{nil}, then it uses CBREAK mode.
If @var{flow} is non-@code{nil}, then Emacs uses xon/xoff (@kbd{C-q},
@kbd{C-s}) flow control for output to terminal. This has no effect except
in CBREAK mode.
The normal setting are system dependent. (table??)
@end defun
@defcmd open-dribble-file filename
After this function is called, Emacs copies all keyboard input characters
to @var{filename}. (What about inserted keyboard macros??) (How do you
turn it off??) It is normally only called interactively to debug Emacs output.
It returns @code{nil}.
Positions
@defspec save-restriction forms*
...
This function can be confused if, within the body, you widen
and then make changes outside the area of the saved restrictions.
Note that if you use both @code{save-restriction} and
@code{save-excursion}, @code{save-excursion} should come first. (why??)
Processes
@section Functions that Create Subprocesses
...
Each of these functions have a @var{buffer-name} argument. This buffer is
where the standard output from the program will go. @var{buffer-name} may
be either a buffer or the name of one, and it will be created if it does
not already exist. If @var{buffer-name} is @code{nil}, then the output
will be discarded by directing it to @file{/dev/null} unless an output
stream (how??) or filter function is specified to handle it.
(@xref{Process Filters} @pxref{Streams}.)
Normally, one does not want to have more than
one process outputting to one buffer because their outputs will be
intermixed randomly.
@defvar process-environment
This global variable is a list of strings to append to the environment of
processes that are started.
(does this apply to synchronous processes too??)
@defun process-list
This function returns a list of all processes (that are still alive??).
@example
(process-list)
@Arrow (#<process display-time> #<process shell>)
@end example
@end defun
@defun process-mark process
This function returns the marker which indicates the end of the last
output from @var{process} into its buffer. This marker actually controls
where output from the process will be inserted. Often it will be at the
end of the buffer. (can we change it predictably??) (show example!!)
@defun process-status process-name
This function returns the status of @var{process-name} as a symbol.
@var{process-name} must be either a process or a string. It need not name
an actual process.
(What is returned for net connections opened by @code{open-network-stream}??)
@subsection Sending Input to a Process
Limits on size of string??
@subsection Sending Signals to Processes
Several functions are provided to send signals to processes. The only
distinction between the functions is which signal they send. They each
take two optional arguments: @var{process-name} and @var{current-group}.
@var{process-name} must be either a process, the name of one, or
@code{nil}. If it is @code{nil}, the process defaults to the process
associated with the current buffer. It is an error if @var{process-name}
does not identify a process.
@var{current-group} is a flag. The action depends on the
@code{process-connection-type} of the process. If it is a pty and
@var{current-group} is non-@code{nil}, then the signal is sent to the
current process-group of the process's controlling terminal rather than to
the process's own process group. If the process is a shell, this means
interrupt current subjob rather than the shell itself. If the connection
type is a pipe, then the signal always goes to the process group of the
immediate inferior of Emacs.
Killing a buffer sends a @code{SIGHUP} signal to all its associated
(sub??)processes. Killing Emacs sends a @code{SIGHUP} signal to all remaining
processes.
@section Receiving Information from a Process
There are three ways to asynchronously receive information from a process;
two are for standard output and the third is for the process status.
It is important to note that the filter and sentinel functions are
only called when Emacs is waiting for something; they never run
while other Lisp code is running. Similarly, output is only inserted
in an associated buffer when Emacs is waiting.
You may explicitly cause Emacs to wait by calling @code{sit-for},
@code{sleep}, or @code{accept-process-output} (others??).
Emacs also waits in the command loop for the next key command.
@defun get-buffer-process buffer-name
Return the process associated with @var{buffer-name}. If there are
several processes associated with it, then one is chosen. (Presently,
the one chosen is the one most recently created. This should not
be relied upon??)
@defun setprv args??
Set or reset a VMS privilege. First arg is privilege name. Second
arg is @code{t} or @code{nil}, indicating whether the privilege is to
be set or reset. Default is @code{nil}. Returns @code{t} if success,
@code{nil} if not. If third arg is non-@code{nil}, does not change
privilege, but returns @code{t} or @code{nil}, depending upon whether
the privilege is already enabled.
@end defun
@defun skip-chars-forward chars &optional limit
...
If @var{limit} is supplied (it must be a number or a marker), it will be
the maximum position in the buffer that the point can be skipped to. The
point is guaranteed to stop at @var{limit} at most.
(return value??)
Sequences
@defun aset array integer object
This function sets the @var{integer'th} element of the array to be
@var{object}. It returns @var{object}. It is not an error if @var{array}
is a string and @var{object} is not a character -???but it should be!!
This is different behavior than the @code{fillarray} function below.
Streams
Normally, of course, input streams obtain their characters from the
keyboard, a buffer, or a file, while output streams either print their
characters in the minibuffer (echo area??) or insert them into a buffer.
Is output always to the echo area rather than the minibuffer??
@defun parse-partial-sexp start limit &optional target-depth stop-before state
...
@enumerate
@item
Depth in parens, starting at 0.
@item
Character position of the start of the innermost containing list;
@code{nil} if none.
@item
Character position of the start of the last complete sexp terminated;
@code{nil} if none (??).
@item
Non-@code{nil} if inside a string.
(it is the character that will terminate the string.)
@item
@code{t} if inside a comment.
@item
@code{t} if following a quote character.
@item
The minimum paren-depth encountered during this scan.
@end enumerate
@node Property Lists
@section Property Lists
A @dfn{property list} (@dfn{plist} for short) is a list of paired elements
stored in the property list cell of a symbol. Each of the pairs associate
a property name (usually a symbol) with some property or value. Property
lists are generally used to record information about a symbol, such as
which file it received a function definition in, or the grammatical class
the name of the symbol belongs to in a language understanding system.
(more appropriate examples??)
Syntax Tables
Paired @dfn{delimiter} characters serve a similar purpose to string quote
characters, but differ in that ???.
Only TeX mode uses paired delimiters presently.
Text
@defcmd indent-relative &optional unindented-ok
@comment !!SourceFile indent.el
Space out to under next indent point in previous nonblank line.
An indent point is a non-whitespace character following whitespace.
If the previous nonblank line has no indent points beyond
the column point starts at, @code{tab-to-tab-stop} is done instead.
@var{unindented-ok}??
@end defcmd
Variables
There are two varieties of buffer-local variables.
@code{make-local-variable} makes a variable local to just the current buffer
whereas @code{make-variable-buffer-local} makes a variable local to
@emph{every} buffer, even new buffers that are created afterwards. The
latter will be called @dfn{per-buffer-local} variables when it is
necessary to distinguish them from @dfn{buffer-local} variables.
(terminology!!) A per-buffer-local variable is buffer-local in every buffer.
When a variable that is buffer-local in the current buffer is changed
the value that other buffers see is not changed.
(What happens if both varieties are used for a single variable?? What
happens if the variable is locally bound before or after it becomes
buffer-local??)
Windows
@defopt window-min-width
The value of this variable determines how small a window may become (when
enlarging other windows) before it disappears. No window may be created
that is smaller than this. The absolute minimum width is 1; any value
below that is ignored.
@b{WARNING:} version 18.50 of emacs doesn't
always guard this value properly, and can core dump when the value is less
than 2 and actions force a window to a size smaller than that. Because of
the vertical borders between windows, 2 is the minimum reasonable value for
this option. (Is this fixed??)
@end defopt