@section Compiler Errors
@cindex compiler errors
- Byte compilation writes errors and warnings into the buffer
+ Byte compilation outputs all errors and warnings into the buffer
@samp{*Compile-Log*}. The messages include file names and line
numbers that identify the location of the problem. The usual Emacs
commands for operating on compiler diagnostics work properly on
most general last. Here's an example of proper usage:
@example
-(choice (const :tag "Off" nil) symbol (sexp :tag "Other"))
+(choice (const :tag "Off" nil)
+ symbol (sexp :tag "Other"))
@end example
@noindent
buffer.
@item debug
-@code{debug} as first argument indicates a call to @code{debug}
-because of entry to a function that was set to debug on entry. The
-debugger displays @samp{Debugger entered--entering a function:}, just
-as in the @code{lambda} case. It also marks the stack frame for that
-function so that it will invoke the debugger when exited.
+@code{debug} as first argument means @code{debug} was called because
+of entry to a function that was set to debug on entry. The debugger
+displays the string @samp{Debugger entered--entering a function:},
+just as in the @code{lambda} case. It also marks the stack frame for
+that function so that it will invoke the debugger when exited.
@item t
When the first argument is @code{t}, this indicates a call to
-@code{debug} due to evaluation of a list form when
+@code{debug} due to evaluation of a function call form when
@code{debug-on-next-call} is non-@code{nil}. The debugger displays
@samp{Debugger entered--beginning evaluation of function call form:}
as the top line in the buffer.
reporting operation progress. Here is a working example that does
nothing useful:
-@example
+@smallexample
(let ((progress-reporter
- (make-progress-reporter "Collecting some mana for Emacs..."
+ (make-progress-reporter "Collecting mana for Emacs..."
0 500)))
(dotimes (k 500)
(sit-for 0.01)
(progress-reporter-update progress-reporter k))
(progress-reporter-done progress-reporter))
-@end example
+@end smallexample
@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
This function creates and returns a @dfn{progress reporter}---an
@code{(background-color . @var{color-name})}. These elements specify
just the foreground color or just the background color.
-@code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+@code{(foreground-color . @var{color-name})} has the same effect as
+@code{(:foreground @var{color-name})}; likewise for the background.
@end itemize
@item mouse-face
registry name is @samp{JISX0208.1983} for all characters belonging to
the charset @code{japanese-jisx0208}.
-@example
+@smallexample
(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
-@end example
-
+@end smallexample
@end defun
@defun char-displayable-p char
Lisp objects as their @code{display} properties are handled
separately. Here's a function that illustrates this point:
-@example
+@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(forward-char 1)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 1))))
-@end example
+@end smallexample
@noindent
It gives each of the first ten characters in the buffer string
characters appear as five A's. This function would have the same
results:
-@example
+@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(put-text-property (point) (2+ (point)) 'display string)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 2))))
-@end example
+@end smallexample
@noindent
This illustrates that what matters is the property value for
The following expressions are supported:
-@example
+@smallexample
@group
@var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
@var{num} ::= @var{integer} | @var{float} | @var{symbol}
@var{unit} ::= in | mm | cm | width | height
+@end group
+@group
@var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
| scroll-bar | text
@var{pos} ::= left | center | right
@var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
@var{op} ::= + | -
@end group
-@end example
+@end smallexample
The form @var{num} specifies a fraction of the default frame font
height or width. The form @code{(@var{num})} specifies an absolute
Display @var{string} instead of the text that has this property.
@item (image . @var{image-props})
-This display specification is an image descriptor (@pxref{Images}).
+This kind of display specification is an image descriptor (@pxref{Images}).
When used as a display specification, it means to display the image
instead of the text that has the display specification.
Proceed to the stop point near where point is (@code{edebug-goto-here}).
@item f
-Run the program forward over one expression
+Run the program for one expression
(@code{edebug-forward-sexp}).
@item o
@item x @var{condition} @key{RET}
Set a conditional breakpoint which stops the program only if
-@var{condition} evaluates to a non-@code{nil} value
-(@code{edebug-set-conditional-breakpoint}). With a prefix argument, the
-breakpoint is temporary.
+evaluating @var{condition} produces a non-@code{nil} value
+(@code{edebug-set-conditional-breakpoint}). With a prefix argument,
+the breakpoint is temporary.
@item B
Move point to the next breakpoint in the current definition
@table @kbd
@item v
-View the outside window configuration (@code{edebug-view-outside}).
-Type @kbd{C-x X w} to return to Edebug.
+Switch to viewing the outside window configuration
+(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug.
@item p
Temporarily display the outside current buffer with point at its
The current match data. @xref{Match Data}.
@item
-@code{last-command}, @code{this-command}, @code{last-command-char},
-@code{last-input-char}, @code{last-input-event},
-@code{last-command-event}, @code{last-event-frame},
-@code{last-nonmenu-event}, and @code{track-mouse}. Commands used within
-Edebug do not affect these variables outside of Edebug.
+The variables @code{last-command}, @code{this-command},
+@code{last-command-char}, @code{last-input-char},
+@code{last-input-event}, @code{last-command-event},
+@code{last-event-frame}, @code{last-nonmenu-event}, and
+@code{track-mouse}. Commands used within Edebug do not affect these
+variables outside of Edebug.
The key sequence returned by @code{this-command-keys} is changed by
executing commands within Edebug and there is no way to reset
definition. Here is a simple example that shows the specification for
the @code{for} example macro (@pxref{Argument Evaluation}).
-@example
+@smallexample
(defmacro for (var from init to final do &rest body)
"Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
(declare (debug (symbolp "from" form "to" form "do" &rest form)))
...)
-@end example
+@end smallexample
The Edebug specification says which parts of a call to the macro are
forms to be evaluated. For simple macros, the @var{specification}
@xref{Function Indirection}.
@item cyclic-variable-indirection
-@code{"Symbol's chain of variable indirections contains a loop"}@*
+@code{"Symbol's chain of variable indirections\@* contains a loop"}@*
@xref{Variable Aliases}.
@item end-of-buffer
Aside from some technical details, the body of the @code{find-file}
function is basically equivalent to:
-@example
+@smallexample
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
-@end example
+@end smallexample
@noindent
(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
If @var{filename} is indeed remote, the return value is a string that
identifies the remote system.
-This identifier string may include a host name, a user name, and
-characters designating the method used to access the remote system.
-For example, the remote identifier string for the filename
+This identifier string can include a host name and a user name, as
+well as characters designating the method used to access the remote
+system. For example, the remote identifier string for the filename
@code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
If @code{file-remote-p} returns the same identifier for two different
The @var{data-type} argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data. Meaningful values include @code{TEXT}, @code{STRING},
-@code{UTF8_STRING},
-@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
-@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
-@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
-@code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with
-upper-case names in accord with X conventions.) The default for
-@var{data-type} is @code{STRING}.
+@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE},
+@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME},
+@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS},
+@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and
+@code{INTEGER}. (These are symbols with upper-case names in accord
+with X conventions.) The default for @var{data-type} is
+@code{STRING}.
@end defun
@cindex cut buffer
@end example
@noindent
-in in your X resources file (usually named @file{~/.Xdefaults} or
-@file{~/.Xresources}). Then:
+in in your X resources file (whose name is usually @file{~/.Xdefaults}
+or @file{~/.Xresources}). Then:
@example
@group
@var{name}. It returns the value @var{name}, but usually we ignore this
value.
-As described previously (@pxref{Lambda Expressions}),
-@var{argument-list} is a list of argument names and may include the
-keywords @code{&optional} and @code{&rest}. Also, the first two of the
+As described previously, @var{argument-list} is a list of argument
+names and may include the keywords @code{&optional} and @code{&rest}
+(@pxref{Lambda Expressions}). Also, the first two of the
@var{body-forms} may be a documentation string and an interactive
declaration.
same time using the macro @code{define-obsolete-function-alias}.
@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
-This macro marks the function @var{obsolete-name} obsolete and also defines
-it as an alias for the function @var{current-name}. A typical call has the
-form:
+This macro marks the function @var{obsolete-name} obsolete and also
+defines it as an alias for the function @var{current-name}. It is
+equivalent to the following:
@example
-(define-obsolete-function-alias 'old-fun 'new-fun "22.1" "Doc.")
-@end example
-
-@noindent
-which is equivalent to the following two lines of code:
-
-@example
-(defalias 'old-fun 'new-fun "Doc.")
-(make-obsolete 'old-fun 'new-fun "22.1")
+(defalias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
@end example
@end defmac
property value isn't @code{nil}, isn't a string, and doesn't refer to
text in a file, then it is evaluated to obtain a string.
-Finally, @code{documentation-property} passes the string through
+The last thing this function does is pass the string through
@code{substitute-command-keys} to substitute actual key bindings,
unless @var{verbatim} is non-@code{nil}.
instead of @code{kill-line} and @code{kill-word}. It can establish
this by making these two command-remapping bindings in its keymap:
-@example
+@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap kill-word] 'my-kill-word)
-@end example
+@end smallexample
Whenever @code{my-mode-map} is an active keymap, if the user types
@kbd{C-k}, Emacs will find the standard global binding of
Remapping only works through a single level. In other words,
-@example
+@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
-@end example
+@end smallexample
@noindent
does not have the effect of remapping @code{kill-line} into
@item
The mode should specify how Imenu should find the definitions or
sections of a buffer, by setting up a buffer-local value for the
-variable @code{imenu-generic-expression}, for the pair of variables
+variable @code{imenu-generic-expression}, for the two variables
@code{imenu-prev-index-position-function} and
@code{imenu-extract-index-name-function}, or for the variable
@code{imenu-create-index-function} (@pxref{Imenu}).
It creates the submenu @var{menu-title} specified by @var{sub-alist}.
The default value of @code{imenu-create-index-function} is
-@code{imenu-default-create-index-function}. This function uses
-@code{imenu-prev-index-position-function} and
+@code{imenu-default-create-index-function}. This function calls the
+value of @code{imenu-prev-index-position-function} and the value of
@code{imenu-extract-index-name-function} to produce the index alist.
However, if either of these two variables is @code{nil}, the default
function uses @code{imenu-generic-expression} instead.
@end example
If you use @code{regexp-opt} to produce the regular expression
-@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp
+@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp
Functions}) to calculate the value for @var{subexp}.
@item (@var{matcher} . @var{facespec})
Some modes provide specialized support you can use in additional
highlighting patterns. See the variables
@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
-@code{objc-font-lock-extra-types} and
-@code{java-font-lock-extra-types}, for example.
+and @code{java-font-lock-extra-types}, for example.
@strong{Warning:} major mode functions must not call
@code{font-lock-add-keywords} under any circumstances, either directly
@var{encoding-system} is the coding system for encoding (in case
@var{operation} does encoding).
-The argument @var{operation} should be a symbol, one of
-@code{insert-file-contents}, @code{write-region}, @code{call-process},
-@code{call-process-region}, @code{start-process}, or
-@code{open-network-stream}. These are the names of the Emacs I/O primitives
-that can do coding system conversion.
+The argument @var{operation} should be a symbol, any one of
+@code{insert-file-contents}, @code{write-region},
+@code{start-process}, @code{call-process}, @code{call-process-region},
+or @code{open-network-stream}. These are the names of the Emacs I/O
+primitives that can do coding system conversion.
The remaining arguments should be the same arguments that might be given
to that I/O primitive. Depending on the primitive, one of those
target. For @code{open-network-stream}, the target is the service name
or port number.
-This function looks up the target in @code{file-coding-system-alist},
-@code{process-coding-system-alist}, or
-@code{network-coding-system-alist}, depending on @var{operation}.
+Depending on @var{operation}, this function looks up the target in
+@code{file-coding-system-alist}, @code{process-coding-system-alist},
+or @code{network-coding-system-alist}.
@end defun
@node Specifying Coding Systems
@cindex @file{site-start.el}
@item
-It loads your init file (usually @file{~/.emacs}), unless @samp{-q}
-(or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was specified
-on the command line. The @samp{-u} option can specify another user
-whose home directory should be used instead of @file{~}.
+It loads your init file (usually @file{~/.emacs}), unless the option
+@samp{-q} (or @samp{--no-init-file}), @samp{-Q}, or @samp{--batch} was
+specified on the command line. The @samp{-u} option can specify
+another user whose home directory should be used instead of @file{~}.
@item
It loads the library @file{default} (if any), unless
system, the user's @acronym{UID}, and so on.
@defvar system-configuration
-This variable holds the GNU configuration name for the hardware/software
-configuration of your system, as a string. The convenient way to test
-parts of this string is with @code{string-match}.
+This variable holds the standard GNU configuration name for the
+hardware/software configuration of your system, as a string. The
+convenient way to test parts of this string is with
+@code{string-match}.
@end defvar
@defvar system-type
(shell-quote-argument "foo > bar")
@result{} "foo\\ \\>\\ bar"
-;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
+;; @r{This example shows the behavior on MS-DOS and MS-Windows.}
(shell-quote-argument "foo > bar")
@result{} "\"foo > bar\""
@end example
(buffer-string))))
(sel (random (bindat-get-field info :count)))
(beg (cdar (bindat-get-field info :offset sel)))
- (end (or (cdar (bindat-get-field info :offset (1+ sel)))
+ (end (or (cdar (bindat-get-field info
+ :offset (1+ sel)))
(nth 7 (file-attributes cookies)))))
- (switch-to-buffer (get-buffer-create
- (format "*Fortune Cookie: %s*"
- (file-name-nondirectory cookies))))
+ (switch-to-buffer
+ (get-buffer-create
+ (format "*Fortune Cookie: %s*"
+ (file-name-nondirectory cookies))))
(erase-buffer)
- (insert-file-contents-literally cookies nil beg (- end 3))))
+ (insert-file-contents-literally
+ cookies nil beg (- end 3))))
(defun fcookie-create-index (cookies &optional index delim)
"Scan file COOKIES, and write out its index file.
offsets (cons (1- p) offsets))))
(with-temp-buffer
(set-buffer-multibyte nil)
- (insert (string-make-unibyte
- (bindat-pack
- fcookie-index-spec
- `((:version . 2)
- (:count . ,count)
- (:longest . ,max)
- (:shortest . ,min)
- (:flags . 0)
- (:delim . ,delim)
- (:offset . ,(mapcar (lambda (o)
- (list (cons :foo o)))
- (nreverse offsets)))))))
+ (insert
+ (string-make-unibyte
+ (bindat-pack
+ fcookie-index-spec
+ `((:version . 2)
+ (:count . ,count)
+ (:longest . ,max)
+ (:shortest . ,min)
+ (:flags . 0)
+ (:delim . ,delim)
+ (:offset . ,(mapcar (lambda (o)
+ (list (cons :foo o)))
+ (nreverse offsets)))))))
(let ((coding-system-for-write 'raw-text-unix))
(write-file (or index (concat cookies ".dat")))))))
@end lisp
The corresponding decoded structure:
@lisp
-(setq decoded-structure (bindat-unpack packet-spec binary-data))
+(setq decoded (bindat-unpack packet-spec binary-data))
@result{}
((header
(dest-ip . [192 168 1 100])
Fetching data from this structure:
@lisp
-(bindat-get-field decoded-structure 'item 1 'id)
+(bindat-get-field decoded 'item 1 'id)
@result{} "BCDEFG"
@end lisp
The next alternative is for @samp{a*} to match only two @samp{a}s. With
this choice, the rest of the regexp matches successfully.@refill
-Nested repetition operators can be extremely slow or loop infinitely
-if they use repetition operators inside repetition operators. For
-example, it could take hours for the regular expression
-@samp{\(x+y*\)*a} to try to match the sequence
-@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately
-fails. Emacs must try each way of grouping the 35 @samp{x}s before
-concluding that none of them can work. Even worse, @samp{\(x*\)*} can
-match the null string in infinitely many ways, so it causes an
-infinite loop. To avoid these problems, check nested repetitions
-carefully.
+Nested repetition operators take a long time, or even forever, if they
+lead to ambiguous matching. For example, trying to match the regular
+expression @samp{\(x+y*\)*a} against the string
+@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could take hours before it
+ultimately fails. Emacs must try each way of grouping the 35
+@samp{x}s before concluding that none of them can work. Even worse,
+@samp{\(x*\)*} can match the null string in infinitely many ways, so
+it causes an infinite loop. To avoid these problems, check nested
+repetitions carefully.
@item @samp{+}
@cindex @samp{+} in regexp
@item @samp{[^ @dots{} ]}
@cindex @samp{^} in regexp
-@samp{[^} begins a @dfn{complemented character alternative}, which matches any
-character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
-all characters @emph{except} letters and digits.
+@samp{[^} begins a @dfn{complemented character alternative}. This
+matches any character except the ones specified. Thus,
+@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
+digits.
@samp{^} is not special in a character alternative unless it is the first
character. The character following the @samp{^} is treated as if it
@var{separators}:
@example
-(split-string " two words " split-string-default-separators)
+(split-string " two words "
+ split-string-default-separators)
@result{} ("" "two" "words" "")
@end example
@end defun
@defvar split-string-default-separators
-The default value of @var{separators} for @code{split-string}, initially
-@w{@samp{"[ \f\t\n\r\v]+"}}.
+The default value of @var{separators} for @code{split-string}. Its
+usual value is @w{@samp{"[ \f\t\n\r\v]+"}}.
@end defvar
@node Modifying Strings
follow specified justification style (see @code{current-justification},
below). @code{nil} means to do full justification.
-If @var{eop} is non-@code{nil}, that means do left-justification if
-@code{current-justification} specifies full justification. This is used
-for the last line of a paragraph; even if the paragraph as a whole is
-fully justified, the last line should not be.
+If @var{eop} is non-@code{nil}, that means do only left-justification
+if @code{current-justification} specifies full justification. This is
+used for the last line of a paragraph; even if the paragraph as a
+whole is fully justified, the last line should not be.
If @var{nosqueeze} is non-@code{nil}, that means do not change interior
whitespace.
starting after the left margin whitespace (if any) on a line; the
characters it matches are that line's candidate for the fill prefix.
-The default value of this variable is
-@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}}. This
-matches a number enclosed in parentheses or followed by a period,
-or certain punctuation characters, or any sequence of these
-intermingled with whitespace. In particular, it matches a sequence of
-whitespace, possibly empty.
+@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
+default value. This matches a number enclosed in parentheses or
+followed by a period, or certain punctuation characters, or any
+sequence of these intermingled with whitespace. In particular, it
+matches a sequence of whitespace, possibly empty.
@end defopt
@defopt adaptive-fill-first-line-regexp
just the foreground color or just the background color.
@code{(foreground-color . @var{color-name})} is equivalent to
-@code{(:foreground @var{color-name})}, and likewise for the background.
+specifying @code{(:foreground @var{color-name})}, and likewise for the
+background.
@end itemize
You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically
For example, here is how Info mode handles @key{Mouse-1}:
-@example
+@smallexample
(define-key Info-mode-map [follow-link] 'mouse-face)
-@end example
+@end smallexample
@item a function
If the condition is a valid function, @var{func}, then a position
For example, here is how pcvs enables @key{Mouse-1} to follow links on
file names only:
-@example
+@smallexample
(define-key map [follow-link]
(lambda (pos)
- (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
-@end example
+ (eq (get-char-property pos 'face) 'cvs-filename-face)))
+@end smallexample
@item anything else
If the condition value is anything else, then the position is inside a
projects / emacs.git / commitdiff