diff options
Diffstat (limited to 'lispref')
| -rw-r--r-- | lispref/ChangeLog | 37 | ||||
| -rw-r--r-- | lispref/compile.texi | 13 | ||||
| -rw-r--r-- | lispref/display.texi | 27 | ||||
| -rw-r--r-- | lispref/elisp.texi | 2 | ||||
| -rw-r--r-- | lispref/markers.texi | 24 | ||||
| -rw-r--r-- | lispref/minibuf.texi | 11 | ||||
| -rw-r--r-- | lispref/modes.texi | 4 | ||||
| -rw-r--r-- | lispref/nonascii.texi | 7 | ||||
| -rw-r--r-- | lispref/os.texi | 10 | ||||
| -rw-r--r-- | lispref/sequences.texi | 8 | ||||
| -rw-r--r-- | lispref/strings.texi | 71 | ||||
| -rw-r--r-- | lispref/syntax.texi | 3 | ||||
| -rw-r--r-- | lispref/variables.texi | 19 |
13 files changed, 148 insertions, 88 deletions
diff --git a/lispref/ChangeLog b/lispref/ChangeLog index bfae908005..1510ec19e0 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,40 @@ +2007-03-19 Richard Stallman <[email protected]> + + * os.texi (Recording Input): recent-keys now gives 300 keys. + +2007-03-12 Glenn Morris <[email protected]> + + * os.texi: Replace "daylight savings" with "daylight saving" + throughout. + +2007-03-05 Richard Stallman <[email protected]> + + * variables.texi (File Local Variables): Update + enable-local-variables values. + +2007-03-04 Richard Stallman <[email protected]> + + * syntax.texi (Control Parsing): Minor clarification. + + * strings.texi (Formatting Strings): Clarify width, precision, flags. + + * sequences.texi (Sequence Functions): Move string-bytes away, + add xref. + + * nonascii.texi (Text Representations): Move string-bytes here. + + * modes.texi (Major Mode Conventions): Fundamental mode is exception. + + * minibuf.texi (Basic Completion): Minor clarification. + + * markers.texi (The Mark): Clarify existence vs activation of mark. + Other cleanup. + + * display.texi (Finding Overlays): Write better example. + + * compile.texi (Eval During Compile): Clarify putting macros + in eval-when-compile. + 2007-02-25 Vinicius Jose Latorre <[email protected]> * loading.texi (How Programs Do Loading): Fix anchor position at diff --git a/lispref/compile.texi b/lispref/compile.texi index 0d63887e1c..4ed0eb8c1b 100644 --- a/lispref/compile.texi +++ b/lispref/compile.texi @@ -454,11 +454,10 @@ used to load it for compiling, but not executing. For example, (require 'my-macro-package)) ;; only macros needed from this @end lisp -The same sort of thing goes for macros or @code{defalias}es defined -locally and only for use within the file. They can be defined while -compiling, but then not needed when executing. This is good for code -that's only a fallback for compatibility with other versions of Emacs. -For example. +The same sort of thing goes for macros and @code{defsubst} functions +defined locally and only for use within the file. They are needed for +compiling the file, but in most cases they are not needed for +execution of the compiled file. For example, @lisp (eval-when-compile @@ -467,6 +466,10 @@ For example. (compatibility code)))) @end lisp +@noindent +This is often good for code that's only a fallback for compatibility +with other versions of Emacs. + @strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp @samp{#.} reader macro (but not when interpreting) is closer diff --git a/lispref/display.texi b/lispref/display.texi index 02491c422d..f485829725 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -1527,26 +1527,25 @@ end of an overlay, before @var{pos}. If there is none, it returns @code{(point-min)}. @end defun - Here's a function which uses @code{next-overlay-change} to search -for the next character which gets a given property @code{prop} from -either its overlays or its text properties (@pxref{Property Search}): + As an example, here's a simplified (and inefficient) version of the +primitive function @code{next-single-char-property-change} +(@pxref{Property Search}). It searches forward from position +@var{pos} for the next position where the value of a given property +@code{prop}, as obtained from either overlays or text properties, +changes. @smallexample -(defun find-overlay-prop (prop) +(defun next-single-char-property-change (position prop) (save-excursion - (while (and (not (eobp)) - (not (get-char-property (point) prop))) - (goto-char (min (next-overlay-change (point)) - (next-single-property-change (point) prop)))) + (goto-char position) + (let ((propval (get-char-property (point) prop))) + (while (and (not (eobp)) + (eq (get-char-property (point) prop) propval)) + (goto-char (min (next-overlay-change (point)) + (next-single-property-change (point) prop))))) (point))) @end smallexample - Now you can search for a @code{happy} property like this: - -@smallexample -(find-overlay-prop 'happy) -@end smallexample - @node Width @section Width diff --git a/lispref/elisp.texi b/lispref/elisp.texi index 3b99e9eff8..fa9f93208e 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -7,7 +7,7 @@ @c Version of the manual and of Emacs. @c Please remember to update the edition number in README as well. @set VERSION 2.9 -@set EMACSVER 22.0.95 +@set EMACSVER 22.0.96 @dircategory Emacs @direntry diff --git a/lispref/markers.texi b/lispref/markers.texi index e8e0447975..b955538fe0 100644 --- a/lispref/markers.texi +++ b/lispref/markers.texi @@ -410,10 +410,10 @@ values of point and the mark as arguments to the command in an interactive call, but permits other Lisp programs to specify arguments explicitly. @xref{Interactive Codes}. - Each buffer has its own value of the mark that is independent of the -value of the mark in other buffers. When a buffer is created, the mark -exists but does not point anywhere. We consider this state as ``the -absence of a mark in that buffer.'' + Each buffer has a marker which represents the value of the mark in +that buffer, independent of any other buffer. When a buffer is newly +created, this marker exists but does not point anywhere. That means +the mark ``doesn't exist'' in that buffer as yet. Once the mark ``exists'' in a buffer, it normally never ceases to exist. However, it may become @dfn{inactive}, if Transient Mark mode is @@ -452,10 +452,10 @@ inactivity of the mark, and returns the mark position anyway (or @end defun @defun mark-marker -This function returns the current buffer's mark. This is the very marker -that records the mark location inside Emacs, not a copy. Therefore, -changing this marker's position will directly affect the position of the mark. -Don't do it unless that is the effect you want. +This function returns the marker that represents the current buffer's +mark. It is not a copy, it is the marker used internally. Therefore, +changing this marker's position will directly affect the buffer's +mark. Don't do that unless that is the effect you want. @example @group @@ -472,10 +472,10 @@ Don't do it unless that is the effect you want. @end group @end example -Like any marker, this marker can be set to point at any buffer you like. -We don't recommend that you make it point at any buffer other than the -one of which it is the mark. If you do, it will yield perfectly -consistent, but rather odd, results. +Like any marker, this marker can be set to point at any buffer you +like. If you make it point at any buffer other than the one of which +it is the mark, it will yield perfectly consistent, but rather odd, +results. We recommend that you not do it! @end defun @ignore diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi index de81e94e54..1abbb148b8 100644 --- a/lispref/minibuf.texi +++ b/lispref/minibuf.texi @@ -629,12 +629,11 @@ match. If @var{collection} is an alist (@pxref{Association Lists}), the permissible completions are the elements of the alist that are either strings, symbols, or conses whose @sc{car} is a string or symbol. -Symbols are converted to strings using @code{symbol-name}. -Other elements of the alist are ignored. (Remember that in Emacs Lisp, -the elements of alists do not @emph{have} to be conses.) As all -elements of the alist can be strings, this case actually includes -lists of strings or symbols, even though we usually do not think of -such lists as alists. +Symbols are converted to strings using @code{symbol-name}. Other +elements of the alist are ignored. (Remember that in Emacs Lisp, the +elements of alists do not @emph{have} to be conses.) In particular, a +list of strings or symbols is allowed, even though we usually do not +think of such lists as alists. @cindex obarray in completion If @var{collection} is an obarray (@pxref{Creating Symbols}), the names diff --git a/lispref/modes.texi b/lispref/modes.texi index cfa9e90d79..6eba02d5a0 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -256,7 +256,9 @@ Fundamental mode. Rmail mode is a complicated and specialized mode. The code for existing major modes follows various coding conventions, including conventions for local keymap and syntax table initialization, global names, and hooks. Please follow these conventions when you -define a new major mode. +define a new major mode. (Fundamental mode is an exception to many +of these conventions, because its definition is to present the global +state of Emacs.) This list of conventions is only partial, because each major mode should aim for consistency in general with other Emacs major modes. diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi index d733cc8086..3661079c56 100644 --- a/lispref/nonascii.texi +++ b/lispref/nonascii.texi @@ -111,6 +111,13 @@ out of range, the value is @code{nil}. Return @code{t} if @var{string} is a multibyte string. @end defun +@defun string-bytes string +@cindex string, number of bytes +This function returns the number of bytes in @var{string}. +If @var{string} is a multibyte string, this can be greater than +@code{(length @var{string})}. +@end defun + @node Converting Representations @section Converting Text Representations diff --git a/lispref/os.texi b/lispref/os.texi index 1ff0517891..9fde03b650 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -1042,7 +1042,7 @@ The value has the form @code{(@var{offset} @var{name})}. Here @var{offset} is an integer giving the number of seconds ahead of UTC (east of Greenwich). A negative value means west of Greenwich. The second element, @var{name}, is a string giving the name of the time -zone. Both elements change when daylight savings time begins or ends; +zone. Both elements change when daylight saving time begins or ends; if the user has specified a time zone that does not use a seasonal time adjustment, then the value is constant through time. @@ -1125,7 +1125,7 @@ The year, an integer typically greater than 1900. The day of week, as an integer between 0 and 6, where 0 stands for Sunday. @item dst -@code{t} if daylight savings time is effect, otherwise @code{nil}. +@code{t} if daylight saving time is effect, otherwise @code{nil}. @item zone An integer indicating the time zone, as the number of seconds east of Greenwich. @@ -1145,11 +1145,11 @@ to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. The optional argument @var{zone} defaults to the current time zone and -its daylight savings time rules. If specified, it can be either a list +its daylight saving time rules. If specified, it can be either a list (as you would get from @code{current-time-zone}), a string as in the @code{TZ} environment variable, @code{t} for Universal Time, or an integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight savings time. +zone is used without any further alteration for daylight saving time. If you pass more than seven arguments to @code{encode-time}, the first six are used as @var{seconds} through @var{year}, the last argument is @@ -1697,7 +1697,7 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}. @subsection Recording Input @defun recent-keys -This function returns a vector containing the last 100 input events from +This function returns a vector containing the last 300 input events from the keyboard or mouse. All input events are included, whether or not they were used as parts of key sequences. Thus, you always get the last 100 input events, not counting events generated by keyboard macros. diff --git a/lispref/sequences.texi b/lispref/sequences.texi index 8087b8051c..ac5a16e261 100644 --- a/lispref/sequences.texi +++ b/lispref/sequences.texi @@ -111,12 +111,8 @@ Emacs character code. @end example @end defun -@defun string-bytes string -@cindex string, number of bytes -This function returns the number of bytes in @var{string}. -If @var{string} is a multibyte string, this is greater than -@code{(length @var{string})}. -@end defun +@noindent +See also @code{string-bytes}, in @ref{Text Representations}. @defun elt sequence index @cindex elements of sequences diff --git a/lispref/strings.texi b/lispref/strings.texi index e1824518ab..23f679d5bb 100644 --- a/lispref/strings.texi +++ b/lispref/strings.texi @@ -821,18 +821,19 @@ operation} error. @cindex field width @cindex padding - All the specification characters allow an optional ``width,'' which -is a digit-string between the @samp{%} and the character. If the + A specification can have a @dfn{width}, which is a signed decimal +number between the @samp{%} and the specification character. If the printed representation of the object contains fewer characters than -this width, then it is padded. The padding is on the left if the -width is positive (or starts with zero) and on the right if the -width is negative. The padding character is normally a space, but if -the width starts with a zero, zeros are used for padding. Some of -these conventions are ignored for specification characters for which -they do not make sense. That is, @samp{%s}, @samp{%S} and @samp{%c} -accept a width starting with 0, but still pad with @emph{spaces} on -the left. Also, @samp{%%} accepts a width, but ignores it. Here are -some examples of padding: +this width, @code{format} extends it with padding. The padding goes +on the left if the width is positive (or starts with zero) and on the +right if the width is negative. The padding character is normally a +space, but it's @samp{0} if the width starts with a zero. + + Some of these conventions are ignored for specification characters +for which they do not make sense. That is, @samp{%s}, @samp{%S} and +@samp{%c} accept a width starting with 0, but still pad with +@emph{spaces} on the left. Also, @samp{%%} accepts a width, but +ignores it. Here are some examples of padding: @example (format "%06d is padded on the left with zeros" 123) @@ -842,15 +843,16 @@ some examples of padding: @result{} "123 is padded on the right" @end example +@noindent If the width is too small, @code{format} does not truncate the object's printed representation. Thus, you can use a width to specify a minimum spacing between columns with no risk of losing information. - In the following three examples, @samp{%7s} specifies a minimum width -of 7. In the first case, the string inserted in place of @samp{%7s} has -only 3 letters, so 4 blank spaces are inserted for padding. In the -second case, the string @code{"specification"} is 13 letters wide but is -not truncated. In the third case, the padding is on the right. + In the following three examples, @samp{%7s} specifies a minimum +width of 7. In the first case, the string inserted in place of +@samp{%7s} has only 3 letters, it needs 4 blank spaces as padding. In +the second case, the string @code{"specification"} is 13 letters wide +but is not truncated. In the third case, the padding is on the right. @smallexample @group @@ -873,32 +875,35 @@ not truncated. In the third case, the padding is on the right. @end smallexample @cindex precision in format specifications - All the specification characters allow an optional ``precision'' + All the specification characters allow an optional @dfn{precision} before the character (after the width, if present). The precision is a decimal-point @samp{.} followed by a digit-string. For the floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the precision specifies how many decimal places to show; if zero, the decimal-point itself is also omitted. For @samp{%s} and @samp{%S}, -the precision truncates the string to the given width, so -@samp{%.3s} shows only the first three characters of the -representation for @var{object}. Precision is ignored for other -specification characters. +the precision truncates the string to the given width, so @samp{%.3s} +shows only the first three characters of the representation for +@var{object}. Precision has no effect for other specification +characters. @cindex flags in format specifications -Immediately after the @samp{%} and before the optional width and + Immediately after the @samp{%} and before the optional width and precision, you can put certain ``flag'' characters. -A space character inserts a space for positive numbers, a plus character -inserts a plus sign (otherwise nothing is inserted for positive -numbers). These flags are ignored except for @samp{%d}, @samp{%e}, -@samp{%f}, @samp{%g}, and if both flags are present the space is -ignored. - -The flag @samp{#} indicates ``alternate form.'' For @samp{%o} it -ensures that the result begins with a 0. For @samp{%x} and @samp{%X} -the result is prefixed with @samp{0x} or @samp{0X}. For @samp{%e}, -@samp{%f}, and @samp{%g} a decimal point is always shown even if the -precision is zero. + @samp{+} as a flag inserts a plus sign before a positive number, so +that it always has a sign. A space character as flag inserts a space +before a positive number. (Otherwise, positive numbers start with the +first digit.) Either of these two flags ensures that positive numbers +and negative numbers use the same number of columns. These flags are +ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if +both flags are used, the @samp{+} takes precedence. + + The flag @samp{#} specifies an ``alternate form'' which depends on +the format in use. For @samp{%o} it ensures that the result begins +with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result +with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, +the @samp{#} flag means include a decimal point even if the precision +is zero. @node Case Conversion @comment node-name, next, previous, up diff --git a/lispref/syntax.texi b/lispref/syntax.texi index 85dcb83bd5..47f0994488 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -873,7 +873,8 @@ can still override the syntax.) @defopt parse-sexp-ignore-comments @cindex skipping comments If the value is non-@code{nil}, then comments are treated as -whitespace by the functions in this section and by @code{forward-sexp}. +whitespace by the functions in this section and by @code{forward-sexp}, +@code{scan-lists} and @code{scan-sexps}. @end defopt @vindex parse-sexp-lookup-properties diff --git a/lispref/variables.texi b/lispref/variables.texi index 8d3e0bb5c2..56732d22db 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -1654,10 +1654,21 @@ This section describes the functions and variables that affect processing of file local variables. @defopt enable-local-variables -This variable controls whether to process file local variables. A -value of @code{t} means to process them, querying the user if unsafe -variables are encountered; @code{nil} means ignore them; anything else -means to query the user for each file. The default value is @code{t}. +This variable controls whether to process file local variables. +The possible values are: + +@table @asis +@item @code{t} (the default) +Set the safe variables, and query (once) about any unsafe variables. +@item @code{:safe} +Set only the safe variables and do not query. +@item @code{:all} +Set all the variables and do not query. +@item @code{nil} +Don't set any variables. +@item anything else +Query (once) about all the variables. +@end table @end defopt @defun hack-local-variables &optional mode-only |