changeset 89910:548375b6b1f8

Update unicode branch

--- a/lispref/ChangeLog	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/ChangeLog	Mon Apr 19 07:01:43 2004 +0000
@@ -1,3 +1,935 @@
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* buffers.texi (Read Only Buffers): Mention optional ARG to
+	`toggle-read-only'.
+
[phone]  Nick Roberts  <[e-mail]>
+
+	* windows.texi (Selecting Windows): Note that get-lru-window
+	returns a full-width window if possible.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* buffers.texi: Various changes in addition to:
+	(Buffer File Name): Add `find-buffer-visiting'.
+	(Buffer Modification): Mention optional ARG to `not-modified'.
+	(Indirect Buffers): Mention optional CLONE argument to
+	`make-indirect-buffer'.
+
+	* files.texi: Various changes in addition to:
+	(Visiting Functions): `find-file-hook' is now a normal hook.
+	(File Name Expansion): Explain difference between the way that
+	`expand-file-name' and `file-truename' treat `..'.
+	(Contents of Directories): Mention optional ID-FORMAT argument to
+	`directory-files-and-attributes'.
+	(Format Conversion): Mention new optional CONFIRM argument to
+	`format-write-file'.
+
[phone]  Miles Bader  <[e-mail]>
+
+	* macros.texi (Expansion): Add description of `macroexpand-all'.
+
[phone]  Jesper Harder  <[e-mail]>
+
+	* variables.texi (Variable Aliases): Mention
+	cyclic-variable-indirection.
+
+	* errors.texi (Standard Errors): Ditto.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* backups.texi:  Various small changes in addition to:
+	(Making Backups): Mention return value of `backup-buffer'.
+	(Auto-Saving): Mention optional FORCE argument to
+	`delete-auto-save-file-if-necessary'.
+	(Reverting): Mention optional PRESERVE-MODES argument to
+	`revert-buffer'.  Correct description of `revert-buffer-function'.
+
[phone]  Juri Linkov  <[e-mail]>
+
+	* sequences.texi (Sequence Functions): Replace xref to `Vectors'
+	with `Vector Functions'.
+
+	* text.texi (Sorting): Add missing quote.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* intro.texi (Lisp History): Replace xref to `cl' manual with
+	inforef.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* intro.texi (Version Info): Add arg to emacs-version.
+	(Lisp History): Change xref to CL manual.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* minibuf.texi (Completion Commands): Add xref to Emacs manual
+	for Partial Completion mode.
+
[phone]  Thien-Thi Nguyen  <[e-mail]>
+
+	* customize.texi: Fix typo. Remove eol whitespace.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* processes.texi: Fix typos.
+
+	* lists.texi (Building Lists): Minor clarification.
+
+	* hash.texi (Creating Hash): Correct the meaning of t for WEAK
+	in make-hash-table.
+
[phone]  Juanma Barranquero  <[e-mail]>
+
+	* makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of
+	rm, and ignore exit code.
+
[phone]  Dan Nicolaescu  <[e-mail]>
+
+	* display.texi (Defining Faces): Add description for min-colors.
+	Update example.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* abbrevs.texi: Various corrections and clarifications in addition
+	to the following:
+	(Abbrev Tables): Delete add-abbrev (as suggested by RMS).
+
[phone]  Matthew Mundell  <[e-mail]>  (tiny change)
+
+	* calendar.texi (Holiday Customizing): Quote arg of holiday-sexp.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* text.texi: Various small changes in addition to the following:
+	(User-Level Deletion): Mention optional BACKWARD-ONLY argument
+	to delete-horizontal-space.
+	(Kill Functions, Yanking, Low-Level Kill Ring): clarify and correct
+	description of yank-handler text property at various places.
+
+	* frames.texi (Window System Selections): Add anchor.
+
+	* syntax.texi (Syntax Table Functions): Clarify and correct
+	descriptions of make-syntax-table and copy-syntax-table.
+	(Motion and Syntax): Clarify SYNTAXES argument to
+	skip-syntax-forward.
+	(Parsing Expressions): Mention that the return value of
+	parse-partial-sexp is currently a list of ten rather than nine
+	elements.
+	(Categories): Various corrections and clarifications.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* markers.texi (Marker Insertion Types): Minor change.
+
+	* locals.texi (Standard Buffer-Local Variables):
+	* commands.texi (Interactive Codes, Using Interactive):
+	* functions.texi (Related Topics): Fix xrefs.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* lists.texi (Sets And Lists): Update description of delete-dups.
+
[phone]  Jesper Harder  <[e-mail]>  (tiny change)
+
+	* keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button.
+
[phone]  Jan Dj,Ad(Brv  <[e-mail]>
+
+	* frames.texi (Parameter Access): frame-parameters arg is optional.
+	modify-frame-parameters handles nil for FRAME.
+	(Window Frame Parameters): menu-bar-lines and tool-bar-lines
+	are all-or-nothing for certain toolkits.
+	Mention parameter wait-for-wm.
+	(Frames and Windows): In frame-first-window and frame-selected-window
+	the arg is optional.
+	(Input Focus): In redirect-frame-focus the second arg is optional.
+	(Window System Selections): Mention selection type CLIPBOARD.
+	Mention data-type UTF8_STRING.
+	Mention numbering of cut buffers.
+	(Resources): Describe x-resource-name.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* windows.texi (Buffers and Windows): Delete false table
+	about all-frames.
+
+	* syntax.texi (Parsing Expressions): Delete old caveat
+	about parse-sexp-ignore-comments.
+
+	* streams.texi (Output Variables): Add print-quoted.
+
+	* lists.texi (Building Lists): Minor cleanup.
+
+	* hash.texi (Creating Hash): Correct and clarify doc of WEAK values.
+
+	* display.texi (Overlays): Explain overlays use markers.
+	(Managing Overlays): Explain front-advance and rear-advance
+	in more detail.
+
+	* loading.texi (Unloading): Document unload-feature-special-hooks.
+	Get rid of fns-NNN.el file.
+
[phone]  Matthew Mundell  <[e-mail]>  (tiny change)
+
+	* help.texi (Describing Characters): Fix text-char-description
+	example output.
+
+	* edebug.texi (Using Edebug): Fix example.
+
+	* debugging.texi (Internals of Debugger): Fix return value.
+
+	* files.texi (Changing Files): Fix argname.
+
+	* calendar.texi: Fix parens, and default values.
+
+	* display.texi, frames.texi, internals.texi, modes.texi: Minor fixes.
+	* nonascii.texi, objects.texi, os.texi: Minor fixes.
+	* searching.texi, text.texi, tips.texi, windows.text: Minor fixes.
+
+	* positions.texi (Text Lines): Don't add -1 in current-line.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* compile.texi (Compiler Errors): if-boundp feature applies to cond.
+
[phone]  Jesper Harder  <[e-mail]>  (tiny change)
+
+	* processes.texi (Low-Level Network): Fix a typo.
+
[phone]  Kim F. Storm  <[e-mail]>
+
+	* display.texi (Fringes): Use consistent wording.
+	Note that window-fringe's window arg is optional.
+	(Scroll Bars): Use consistent wording.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* tips.texi (Comment Tips): Document the new conventions for
+	commenting out code.
+
[phone]  Jan Dj,Ad(Brv  <[e-mail]>
+
+	* positions.texi (Text Lines): Added missing end defun.
+
[phone]  Kim F. Storm  <[e-mail]>
+
+	* positions.texi (Text Lines): Add line-number-at-pos.
+
[phone]  John Paul Wallington  <[e-mail]>
+
+	* display.texi (Button Properties, Button Buffer Commands):
+	mouse-2 invokes button, not down-mouse-1.
+
[phone]  Jason Rumney  <[e-mail]>
+
+	* makefile.w32-in: Sync with Makefile.in changes.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* minibuf.texi (Text from Minibuffer): Various corrections and
+	clarifications.
+	(Object from Minibuffer): Correct Lisp description of
+	read-minibuffer.
+	(Minibuffer History): Clarify description of cons values for
+	HISTORY arguments.
+	(Basic Completion): Various corrections and clarifications.  Add
+	completion-regexp-list.
+	(Minibuffer Completion): Correct and clarify description of
+	completing-read.
+	(Completion Commands): Mention Partial Completion mode.  Various
+	other minor changes.
+	(High-Level Completion): Various corrections and clarifications.
+	(Reading File Names): Ditto.
+	(Minibuffer Misc): Ditto.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* strings.texi (Text Comparison): assoc-string also matches
+	elements of alists that are strings instead of conses.
+	(Formatting Strings): Standardize Texinfo usage.  Update index
+	entries.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* lists.texi (Sets And Lists): Add delete-dups.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* edebug.texi (Instrumenting Macro Calls): `declare' is not a
+	special form.
+	* macros.texi (Defining Macros): Update description of `declare',
+	which now is a macro.
+	(Wrong Time): Fix typos.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* compile.texi (Compilation Functions): Expand descriptions of
+	`compile-defun', `byte-compile-file', `byte-recompile-directory'
+	and `batch-byte-compile'.  In particular, mention and describe
+	all optional arguments.
+	(Disassembly): Correct and clarify the description of `disassemble'.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* searching.texi: Various small changes in addition to the
+	following.
+	(Regexp Example): Adapt to new value of `sentence-end'.
+	(Regexp Functions): The PAREN argument to `regexp-opt' can be
+	`words'.
+	(Search and Replace): Add usage note for `perform-replace'.
+	(Entire Match Data): Mention INTEGERS and REUSE arguments to
+	`match-data'.
+	(Standard Regexps): Update for new values of `paragraph-start'
+	and `sentence-end'.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* files.texi (Saving Buffers): Clarify descriptions of
+	`write-contents-functions' and `before-save-hook'.
+	Make the defvar's for `before-save-hook' and `after-save-hook'
+	into defopt's.
+
[phone]  Kim F. Storm  <[e-mail]>
+
+	* commands.texi (Click Events): Describe new image and
+	width/height elements of click events.
+	(Accessing Events): Add posn-string, posn-image, and
+	posn-object-width-height.  Change posn-object to return either
+	image or string object.
+
[phone]  Simon Josefsson  <[e-mail]>
+
+	* hooks.texi (Standard Hooks): Add before-save-hook.
+	* files.texi (Saving Buffers): Likewise.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* frames.texi (Frames and Windows): Delete frame-root-window.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* eval.texi, hash.texi, help.texi, symbols.texi: Add anchors.
+
+	* functions.texi: Various small changes in addition to the
+	following.
+	(What Is a Function): `functionp' returns nil for macros.  Clarify
+	behavior of this and following functions for symbol arguments.
+	(Function Documentation): Add `\' in front of (fn @var{arglist})
+	and explain why.
+	(Defining Functions): Mention DOCSTRING argument to `defalias'.
+	Add anchor.
+	(Mapping Functions): Add anchor.  Unquote nil in mapcar* example.
+
[phone]  Miles Bader  <[e-mail]>
+
+	* display.texi (Buttons): New section.
+
[phone]  Andreas Schwab  <[e-mail]>
+
+	* numbers.texi (Math Functions): sqrt reports a domain-error
+	error.
+	(Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* tips.texi (Documentation Tips): Update item on hyperlinks in
+	documentation strings.
+
+	* errors.texi (Standard Errors): Various small corrections and
+	additions.
+
+	* control.texi: Various small changes in addition to the
+	following.
+	(Signaling Errors): Provide some more details on how `signal'
+	constructs the error message.  Add anchor to the definition of
+	`signal'.
+	(Error Symbols): Describe special treatment of `quit'.
+	(Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM
+	to emphasize that it has to be a single form.
+
+	* buffers.texi: Add anchor.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* windows.texi (Choosing Window): Add same-window-p, special-display-p.
+	(Window Configurations): Add window-configuration-frame.
+
+	* variables.texi (Creating Buffer-Local): Add local-variable-if-set-p.
+
+	* text.texi (Examining Properties): Add get-char-property-and-overlay.
+	Change arg name in get-char-property.
+	(Special Properties): Update handling of keymap property.
+
+	* strings.texi (Modifying Strings): Add clear-string.
+	(Text Comparison): Add assoc-string and remove
+	assoc-ignore-case, assoc-ignore-representation.
+
+	* os.texi (Time of Day): Add set-time-zone-rule.
+
+	* numbers.texi (Math Functions): asin, acos, log, log10
+	report domain-error errors.
+
+	* nonascii.texi (Converting Representations):
+	Add multibyte-char-to-unibyte and unibyte-char-to-multibyte.
+	(Encoding and I/O): Add file-name-coding-system.
+
+	* modes.texi (Search-based Fontification): Explain that
+	face specs are symbols with face names as values.
+
+	* minibuf.texi (Minibuffer Misc): Add set-minibuffer-window.
+
+	* lists.texi (Building Lists): remq moved elsewhere.
+	(Sets And Lists): remq moved here.
+	(Association Lists): Refer to assoc-string.
+
+	* internals.texi (Garbage Collection): Add memory-use-counts.
+
+	* frames.texi (Frames and Windows): Add set-frame-selected-window
+	and frame-root-window.
+
+	* files.texi (Contents of Directories):
+	Add directory-files-and-attributes.
+
+	* display.texi (Refresh Screen): Add force-window-update.
+	(Invisible Text): Explain about moving point out of invis text.
+	(Overlay Properties): Add overlay-properties.
+	(Managing Overlays): Add overlayp.
+	(GIF Images): Invalid image number displays a hollow box.
+
+	* buffers.texi (Buffer Modification): Add restore-buffer-modified-p.
+	(Killing Buffers): Add buffer-live-p.
+
[phone]  Markus Rost  <[e-mail]>
+
+	* display.texi (Fringes): Fix typo "set-buffer-window".
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* display.texi, eval.texi, help.texi, internals.texi, loading.texi:
+	* nonascii.texi, processes.texi, tips.texi, variables.texi:
+	Add or change various xrefs and anchors.
+
+	* commands.texi: Replace all occurrences of @acronym{CAR} with
+	@sc{car}, for consistency with the rest of the Elisp manual.
+	`car' and `cdr' are historically acronyms, but are no longer
+	widely thought of as such.
+
+	* internals.texi (Pure Storage): Mention that `purecopy' does not
+	copy text properties.
+	(Object Internals): Now 29 bits are used (in most implementations)
+	to address Lisp objects.
+
+	* variables.texi (Variables with Restricted Values): New node.
+
+	* objects.texi (Lisp Data Types): Mention that certain variables
+	can only take on a restricted set of values and add an xref to
+	the new node "Variables with Restricted Values".
+
+	* eval.texi (Function Indirection): Describe the errors that
+	`indirect-function' can signal.
+	(Eval): Clarify the descriptions of `eval-region' and `values'.
+	Describe `eval-buffer' instead of `eval-current-buffer' and
+	mention `eval-current-buffer' as an alias for `current-buffer'.
+	Correct the description and mention all optional arguments.
+
+	* nonascii.texi: Various small changes in addition to the
+	following.
+	(Converting Representations): Clarify behavior of
+	`string-make-multibyte' and `string-to-multibyte' for unibyte all
+	ASCII arguments.
+	(Character Sets): Document the variable `charset-list' and adapt
+	the definition of the function `charset-list' accordingly.
+	(Translation of Characters): Clarify use of generic characters in
+	`make-translation-table'.  Clarify and correct the description of
+	the use of translation tables in encoding and decoding.
+	(User-Chosen Coding Systems): Correct and clarify the description
+	of `select-safe-coding-system'.
+	(Default Coding Systems): Clarify description of
+	`file-coding-system-alist'.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* strings.texi (Text Comparison): Correctly describe when two
+	strings are `equal'.  Combine and clarify descriptions of
+	`assoc-ignore-case' and `assoc-ignore-representation'.
+
+	* objects.texi (Non-ASCII in Strings): Clarify description of
+	when a string is unibyte or multibyte.
+	(Bool-Vector Type): Update examples.
+	(Equality Predicates): Correctly describe when two strings are
+	`equal'.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* lists.texi (Building Lists): `append' no longer accepts integer
+	arguments.  Update the description of `number-sequence' to reflect
+	recent changes.
+	(Sets And Lists): Describe `member-ignore-case' after `member'.
+
[phone]  Kim F. Storm  <[e-mail]>
+
+	* commands.texi (Click Events): Click object may be an images.
+	Describe (dx . dy) element of click positions.
+	(Accessing Events): Remove duplicate posn-timestamp.
+	New functions posn-object and posn-object-x-y.
+
[phone]  Kim F. Storm  <[e-mail]>
+
+	* commands.texi (Click Events): Describe enhancements to event
+	position lists, including new text-pos and (col . row) items.
+	Mention left-fringe and right-fringe area events.
+	(Accessing Events): New functions posn-area and
+	posn-actual-col-row.  Mention posn-timestamp.  Mention that
+	posn-point in non-text area still returns buffer position.
+	Clarify posn-col-row.
+
[phone]  Lars Hansen  <[e-mail]>
+
+	* files.texi (File Attributes): Describe new parameter ID-FORMAT.
+	* anti.texi (File Attributes): Describe removed parameter
+	ID-FORMAT.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* positions.texi (Positions): Mention that, if a marker is used as
+	a position, its buffer is ignored.
+
+	* markers.texi (Overview of Markers): Mention it here too.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* numbers.texi (Numeric Conversions): Not just `floor', but also
+	`truncate', `ceiling' and `round' accept optional argument DIVISOR.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* markers.texi (Creating Markers): Specify insertion type of
+	created markers.  Add xref to `Marker Insertion Types'.
+	Second argument to `copy-marker' is optional.
+	(Marker Insertion Types): Mention that most markers are created
+	with insertion type nil.
+	(The Mark): Correctly describe when `mark' signals an error.
+	(The Region): Correctly describe when `region-beginning' and
+	`region-end' signal an error.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* hash.texi (Creating Hash): Clarify description of `eql'.
+	`makehash' is obsolete.
+	(Hash Access): Add Common Lisp notes for `remhash' and `clrhash'.
+
+	* positions.texi (Point): Change description of `buffer-end', so
+	that it is also correct for floating point arguments.
+	(List Motion): Correct argument lists of `beginning-of-defun' and
+	`end-of-defun'.
+	(Excursions): Add xref to `Marker Insertion Types'.
+	(Narrowing): Argument to `narrow-to-page' is optional.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* streams.texi (Output Streams): Clarify behavior of point for
+	marker output streams.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* variables.texi (Defining Variables): Second argument to
+	`defconst' is not optional.
+	(Setting Variables): Mention optional argument APPEND to
+	`add-to-list'.
+	(Creating Buffer-Local): Expand description of
+	`make-variable-buffer-local'.
+	(Frame-Local Variables): Expand description of
+	`make-variable-frame-local'.
+	(Variable Aliases): Correct description of optional argument
+	DOCSTRING to `defvaralias'.  Mention return value of
+	`defvaralias'.
+	(File Local Variables): Add xref to `File variables' in Emacs
+	Manual.  Correct description of `hack-local-variables'.  Mention
+	`safe-local-variable' property.  Mention optional second argument
+	to `risky-local-variable-p'.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* symbols.texi (Symbol Plists): Mention return value of `setplist'.
+
[phone]  Jesper Harder  <[e-mail]>  (tiny change)
+
+	* lispref/anti.texi, lispref/backups.texi, lispref/commands.texi
+	lispref/customize.texi, lispref/display.texi, lispref/files.texi,
+	lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi,
+	lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi,
+	lispref/objects.texi, lispref/os.texi, lispref/positions.texi,
+	lispref/processes.texi, lispref/searching.texi,
+	lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi,
+	lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with
+	@acronym{FOO}.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* strings.texi (Creating Strings): Argument START to `substring'
+	can not be `nil'.  Expand description of
+	`substring-no-properties'.  Correct description of `split-string',
+	especially with respect to empty matches.  Prevent very bad line
+	break in definition of `split-string-default-separators'.
+	(Text Comparison): `string=' and `string<' also accept symbols as
+	arguments.
+	(String Conversion): More completely describe argument BASE in
+	`string-to-number'.
+	(Formatting Strings): `%s' and `%S' in `format' do require
+	corresponding object.  Clarify behavior of numeric prefix after
+	`%' in `format'.
+	(Case Conversion): The argument to `upcase-initials' can be a
+	character.
+
[phone]  Kenichi Handa  <[e-mail]>
+
+	* display.texi (Fontsets): Fix texinfo usage.
+
[phone]  Kenichi Handa  <[e-mail]>
+
+	* display.texi (Fontsets): Add description of the function
+	set-fontset-font.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* display.texi (Temporary Displays): Add xref to `Documentation
+	Tips'.
+
+	* functions.texi (Function Safety): Use inforef instead of pxref
+	for SES.
+
[phone]  Andreas Schwab  <[e-mail]>
+
+	* Makefile.in (TEX, texinputdir): Don't define.
+	(TEXI2DVI): Define.
+	(srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm,
+	add $(srcdir)/index.texi.
+	($(infodir)/elisp): Remove index.texi dependency.
+	(elisp.dvi): Likewise.  Use $(TEXI2DVI).
+	(index.texi): Remove target.
+	(dist): Don't link $(srcdir)/permute-index.
+	(clean): Don't remove index.texi.
+
+	* permute-index, index.perm: Remove.
+	* index.texi: Rename from index.unperm.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* tips.texi (Documentation Tips): Document new behavior for face
+	and variable hyperlinks in Help mode.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* objects.texi (Integer Type): Update for extra bit of integer range.
+	(Character Type): Ditto.
+
[phone]  Eli Zaretskii  <[e-mail]>
+
+	* numbers.texi (Integer Basics): Add index entries for reading
+	numbers in hex, octal, and binary.
+
[phone]  Lute Kamstra  <[e-mail]>
+
+	* modes.texi (Mode Line Format): Mention force-mode-line-update's
+	argument.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* windows.texi (Choosing Window): Fix typo.
+	* edebug.texi (Edebug Execution Modes): Fix typo.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* windows.texi (Basic Windows): A window has fringe settings,
+	display margins and scroll-bar settings.
+	(Splitting Windows): Doc split-window return value.
+	Clean up one-window-p.
+	(Selecting Windows): Fix typo.
+	(Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window.
+	(Buffers and Windows): In set-window-buffer, explain effect
+	on fringe settings and scroll bar settings.
+	(Displaying Buffers): In pop-to-buffer, explain nil as buffer arg.
+	(Choosing Window): Use defopt for pop-up-frame-function.
+	For special-display-buffer-names, explain same-window and same-frame.
+	Clarify window-dedicated-p return value.
+	(Textual Scrolling): scroll-up and scroll-down can get an error.
+	(Horizontal Scrolling): Clarify auto-hscroll-mode.
+	Clarify set-window-hscroll.
+	(Size of Window): Don't mention tool bar in window-height.
+	(Coordinates and Windows): Explain what coordinates-in-window-p
+	returns for fringes and display margins.
+	(Window Configurations): Explain saving fringes, etc.
+
+	* tips.texi (Library Headers): Clean up Documentation.
+
+	* syntax.texi (Parsing Expressions): Clean up forward-comment
+	and parse-sexp-lookup-properties.
+
+	* sequences.texi (Sequence Functions): sequencep accepts bool-vectors.
+
+	* os.texi (System Environment): Clean up text for load-average errors.
+
+	* modes.texi (Hooks): Don't explain local hook details at front.
+	Clarify run-hooks and run-hook-with-args a little.
+	Clean up add-hook and remove-hook.
+
+	* edebug.texi (Edebug Execution Modes): Clarify t.
+	Document edebug-sit-for-seconds.
+	(Coverage Testing): Document C-x X = and =.
+	(Instrumenting Macro Calls): Fix typo.
+	(Specification List): Don't index the specification keywords.
+
[phone]  Kim F. Storm  <[e-mail]>
+
+	* processes.texi (Network): Introduce make-network-process.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* tips.texi (Library Headers): Fix typo.
+
[phone]  Juri Linkov  <[e-mail]>
+
+	* modes.texi (Imenu): Mention imenu-create-index-function's
+	default value.  Explain submenus better.
+
[phone]  Lute Kamstra  <[e-mail]>
+
+	* modes.texi (Faces for Font Lock): Fix typo.
+	(Hooks): Explain how buffer-local hook variables can refer to
+	global hook variables.
+	Various minor clarifications.
+
[phone]  Lute Kamstra  <[e-mail]>
+
+	* tips.texi (Coding Conventions): Mention naming conventions for
+	hooks.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* loading.texi (Library Search): Correct default value of
+	load-suffixes.
+	(Named Features): Fix typo.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* loading.texi (Named Features): In `provide',
+	say how to test for subfeatures.
+	(Unloading): In unload-feature, use new var name
+	unload-feature-special-hooks.
+
[phone]  Lute Kamstra  <[e-mail]>
+
+	* modes.texi (Major Mode Conventions): Mention third way to set up
+	Imenu.
+	(Imenu): A number of small fixes.
+	Delete documentation of internal variable imenu--index-alist.
+	Document the return value format of imenu-create-index-function
+	functions.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* processes.texi (Network): Say what stopped datagram connections do.
+
+	* lists.texi (Association Lists): Clarify `assq-delete-all'.
+
+	* display.texi (Overlay Properties): Clarify `evaporate' property.
+
[phone]  Lute Kamstra  <[e-mail]>
+
+	* modes.texi (Mode Line Data): Explain when symbols in mode-line
+	constructs should be marked as risky.
+	Change cons cell into proper list.
+	(Mode Line Variables): Change cons cell into proper list.
+
[phone]  Lute Kamstra  <[e-mail]>
+
+	* modes.texi (Mode Line Data): Document the :propertize construct.
+	(Mode Line Variables): Reorder the descriptions of the variables
+	to match their order in the default mode-line-format.
+	Describe the new variables mode-line-position and mode-line-modes.
+	Update the default values of mode-line-frame-identification,
+	minor-mode-alist, and default-mode-line-format.
+	(Properties in Mode): Mention the :propertize construct.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* buffers.texi, commands.texi, debugging.texi, eval.texi:
+	* loading.texi, minibuf.texi, text.texi, variables.texi:
+	Avoid @strong{Note:}.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* keymaps.texi (Remapping Commands): Fix typo.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* processes.texi (Low-Level Network): Fix typo.
+
[phone]  Kim F. Storm  <[e-mail]>
+
+	* processes.texi (Network, Network Servers): Fix typos.
+	(Low-Level Network): Add timeout value for :server keyword.
+	Add new option keywords to make-network-process.
+	Add set-network-process-options.
+	Explain how to test availability of network options.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* text.texi (Motion by Indent): Arg to
+	backward-to-indentation and forward-to-indentation is optional.
+
+	* strings.texi (Creating Strings): Add substring-no-properties.
+
+	* processes.texi
+	(Process Information): Add list-processes arg QUERY-ONLY.
+	Delete process-contact from here.
+	Add new status values for process-status.
+	Add process-get, process-put, process-plist, set-process-plist.
+	(Synchronous Processes): Add call-process-shell-command.
+	(Signals to Processes): signal-process allows process objects.
+	(Network): Complete rewrite.
+	(Network Servers, Datagrams, Low-Level Network): New nodes.
+
+	* positions.texi (Word Motion): forward-word, backward-word
+	arg is optional.  Reword.
+
+	* abbrevs.texi (Defining Abbrevs): Index no-self-insert.
+
+	* variables.texi (Creating Buffer-Local):
+	Delete duplicate definition of buffer-local-value.
+	(File Local Variables): Explain about discarding text props.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* minibuf.texi (Intro to Minibuffers): Explain that the minibuffer
+	changes variables that record input events.
+	(Minibuffer Misc): Add minibuffer-selected-window.
+
+	* lists.texi (Building Lists): Add copy-tree.
+
+	* display.texi (Fontsets): Add char-displayable-p.
+	(Scroll Bars): New node.
+
[phone]  Lute Kamstra  <[e-mail]>
+
+	* modes.texi (%-Constructs): Document new `%i' and `%I'
+	constructs.
+
[phone]  Peter Runestig  <[e-mail]>
+
+	* makefile.w32-in: New file.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* display.texi (Overlay Properties): Clarify how priorities
+	affect use of the properties.
+
[phone]  Luc Teirlinck  <[e-mail]>
+
+	* customize.texi (Type Keywords): Correct the description of
+	`:help-echo' in the case where `motion-doc' is a function.
+
[phone]  John Paul Wallington  <[e-mail]>
+
+	* modes.texi (Emulating Mode Line): Subsection, not section.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* elisp.texi (Top): Update subnode lists in menu.
+
+	* text.texi (Insertion): Add insert-buffer-substring-no-properties.
+	(Kill Functions): kill-region has new arg yank-handler.
+	(Yanking): New node.
+	(Yank Commands): Add yank-undo-function.
+	(Low-Level Kill Ring):
+	kill-new and kill-append have new arg yank-handler.
+	(Changing Properties): Add remove-list-of-text-properties.
+	(Atomic Changes): New node.
+
+	* symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put.
+
+	* streams.texi (Output Variables): Add eval-expression-print-length
+	and eval-expression-print-level.
+
+	* os.texi (Time Conversion): For encode-time, explain limits on year.
+
+	* objects.texi (Character Type): Define anchor "modifier bits".
+
+	* modes.texi (Emulating Mode Line): New node.
+	(Search-based Fontification): Font Lock uses font-lock-face property.
+	(Other Font Lock Variables): Likewise.
+
+	* keymaps.texi (Format of Keymaps): Keymaps contain char tables,
+	not vectors.
+	(Active Keymaps): Add emulation-mode-map-alists.
+	(Functions for Key Lookup): key-binding has new arg no-remap.
+	(Remapping Commands): New node.
+	(Scanning Keymaps): where-is-internal has new arg no-remap.
+	(Tool Bar): Add tool-bar-local-item-from-menu.
+	Clarify when to use tool-bar-add-item-from-menu.
+
+	* commands.texi (Interactive Call): commandp has new arg.
+	(Command Loop Info): Add this-original-command.
+
[phone]  John Paul Wallington  <[e-mail]>
+
+	* compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'.
+
+	* display.texi (Warning Basics): Fix typo.
+	(Fringes): Add closing curly bracket and fix typo.
+
+	* elisp.texi (Top): Fix typo.
+
[phone]  Richard M. Stallman  <[e-mail]>
+
+	* elisp.texi: Update lists of subnodes.
+
+	* windows.texi (Buffers and Windows): set-window-buffer has new arg.
+
+	* variables.texi (Local Variables): Use lc for example variable names.
+
+	* tips.texi (Library Headers): Explain where to put -*-.
+
+	* strings.texi (Creating Strings): Fix xref for vconcat.
+
+	* sequences.texi (Vector Functions):
+	vconcat no longer allows integer args.
+
+	* minibuf.texi (Reading File Names): read-file-name has new
+	arg PREDICATE.  New function read-directory-name.
+
+	* macros.texi (Defining Macros): Give definition of `declare'
+	(Indenting Macros): New node.
+
+	* frames.texi (Parameter Access): Add modify-all-frames-parameters.
+	(Window Frame Parameters): Make separate table of parameters
+	that are coupled with specific face attributes.
+	(Deleting Frames): delete-frame-hooks renamed to
+	delete-frame-functions.
+
+	* files.texi (Magic File Names): Add file-remote-p.
+	Clarify file-local-copy.
+
+	* edebug.texi (Instrumenting Macro Calls): Don't define `declare'
+	here; instead xref Defining Macros.
+
+	* display.texi (Warnings): New node, and subnodes.
+	(Fringes): New node.
+
+	* debugging.texi (Test Coverage): New node.
+
+	* compile.texi (Compiler Errors): Explain with-no-warnings
+	and other ways to suppress warnings.
+
+	* commands.texi (Interactive Call): Minor clarification.
+
+	* buffers.texi (Buffer File Name): set-visited-file-name
+	renames the buffer too.
+
+	* abbrevs.texi (Abbrev Tables): Add copy-abbrev-table.
+
 2003-07-24  Markus Rost  <[e-mail]>
 
 	* abbrevs.texi (Abbrev Expansion): Use \s syntax in example.
@@ -88,7 +1020,7 @@
 	(Hooks): Add run-mode-hooks and delay-mode-hooks.
 
 	* variables.texi (Creating Buffer-Local): Add buffer-local-value.
-	(Variable Aliases): Clarify defvralias.
+	(Variable Aliases): Clarify defvaralias.
 
 	* loading.texi (Library Search): Add load-suffixes.
 
@@ -738,9 +1670,11 @@
 	for the Project GNU development environment.
 
 ;; Local Variables:
-;; coding: iso-2022-7bit-unix
+;; coding: iso-2022-7bit
 ;; End:
 
     Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
   Copying and distribution of this file, with or without modification,
   are permitted provided the copyright notice and this notice are preserved.
+
+;;; arch-tag: 985ae0ce-df29-475b-b3f8-4bbcbf6f7fda

--- a/lispref/Makefile.in	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/Makefile.in	Mon Apr 19 07:01:43 2004 +0000
@@ -1,6 +1,6 @@
 # Makefile for the GNU Emacs Lisp Reference Manual.
 
-# Copyright (C) 1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
+# Copyright (C) 1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001,2003
 #  Free Software Foundation, Inc.
 
 # This file is part of GNU Emacs.
@@ -28,24 +28,15 @@
 
 infodir = $(srcdir)/../info
 
-# Redefine `TEX' if `tex' does not invoke plain TeX.  For example:
-# TEX=platex
-TEX=tex
-SHELL=/bin/sh
+TEXI2DVI = texi2dvi
+SHELL = /bin/sh
 INSTALL_INFO = install-info
-MAKEINFO=makeinfo
-
-# The environment variable and its value to add $(srcdir) to the path
-# searched for TeX input files.
-texinputdir = TEXINPUTS=$(srcdir):"$(TEXINPUTS)"
+MAKEINFO = makeinfo
 
 # The name of the manual:
 VERSION=2.9
 manual = elisp-manual-21-$(VERSION)
 
-# Uncomment this line for permuted index.
-# permuted_index = 1
-
 # List of all the texinfo files in the manual:
 
 srcs = \
@@ -99,8 +90,7 @@
   $(srcdir)/tips.texi \
   $(srcdir)/variables.texi \
   $(srcdir)/windows.texi \
-  $(srcdir)/index.unperm \
-  $(srcdir)/index.perm \
+  $(srcdir)/index.texi \
   $(srcdir)/gpl.texi \
   $(srcdir)/doclicense.texi
 
@@ -110,31 +100,11 @@
 # The info file is named `elisp'.
 info: $(infodir)/elisp
 
-$(infodir)/elisp: $(srcs) index.texi
+$(infodir)/elisp: $(srcs)
 	$(MAKEINFO) -I. -I$(srcdir) $(srcdir)/elisp.texi -o $(infodir)/elisp
 
-elisp.dvi: $(srcs) index.texi
-	# Avoid losing old contents of aux file entirely.
-	-mv elisp.aux elisp.oaux
-	# First shot to define xrefs.
-	$(texinputdir) $(TEX) $(srcdir)/elisp.texi
-	if [ a${permuted_index} != a ]; \
-	then \
-	  $(srcdir)/permute-index; \
-	  mv permuted.fns elisp.fns; \
-	  texindex elisp.tp; \
-	else \
-	  texindex elisp.??; \
-	fi
-	$(texinputdir) $(TEX) $(srcdir)/elisp.texi
-
-index.texi:
-	if [ a${permuted_index} != a ]; \
-	then \
-	  ln -s $(srcdir)/index.perm index.texi || ln $(srcdir)/index.perm index.texi || cp $(srcdir)/index.perm index.texi; \
-	else \
-	  ln -s $(srcdir)/index.unperm index.texi || ln $(srcdir)/index.unperm index.texi || cp $(srcdir)/index.unperm index.texi; \
-	fi
+elisp.dvi: $(srcs)
+	$(TEXI2DVI) -I $(srcdir) $(srcdir)/elisp.texi
 
 install: elisp
 	$(srcdir)/mkinstalldirs $(infodir)
@@ -145,7 +115,6 @@
 	rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
               *.vr *.vrs *.pg *.pgs *.ky *.kys
 	rm -f make.out core
-	rm -f index.texi
 
 distclean: clean
 
@@ -157,7 +126,7 @@
 	-mkdir temp
 	-mkdir temp/$(manual)
 	-ln $(srcdir)/README $(srcdir)/configure.in $(srcdir)/configure \
- $(srcdir)/Makefile.in $(srcdir)/permute-index $(srcs) \
+ $(srcdir)/Makefile.in $(srcs) \
  $(srcdir)/../man/texinfo.tex \
  elisp.dvi elisp.aux elisp.??s elisp elisp-[0-9] elisp-[0-9][0-9] \
  temp/$(manual)
@@ -166,3 +135,5 @@
 	(cd temp/$(manual); rm -f *~)
 	(cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz
 	-rm -rf temp
+
+# arch-tag: f5a1a94d-62e1-4460-a2d1-f02e538ab554

--- a/lispref/abbrevs.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/abbrevs.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -24,12 +24,17 @@
 is the expansion; its function definition is the hook function to do
 the expansion (@pxref{Defining Abbrevs}); its property list cell
 typically contains the use count, the number of times the abbreviation
-has been expanded.  (Alternatively, the use count is on the
+has been expanded.  Alternatively, the use count is on the
 @code{count} property and the system-abbrev flag is on the
-@code{system-type} property.)  Because these symbols are not interned
-in the usual obarray, they will never appear as the result of reading
-a Lisp expression; in fact, normally they are never used except by the
-code that handles abbrevs.  Therefore, it is safe to use them in an
+@code{system-type} property.  Abbrevs with a non-@code{nil}
+@code{system-type} property are called ``system'' abbrevs.  They are
+usually defined by modes or packages, instead of by the user, and are
+treated specially in certain respects.
+
+Because the symbols used for abbrevs are not interned in the usual
+obarray, they will never appear as the result of reading a Lisp
+expression; in fact, normally they are never used except by the code
+that handles abbrevs.  Therefore, it is safe to use them in an
 extremely nonstandard way.  @xref{Creating Symbols}.
 
   For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
@@ -80,13 +85,28 @@
 leaving it empty.  It always returns @code{nil}.
 @end defun
 
+@defun copy-abbrev-table table
+This function returns a copy of abbrev table @var{table}---a new
+abbrev table that contains the same abbrev definitions.  The only
+difference between @var{table} and the returned copy is that this
+function sets the property lists of all copied abbrevs to 0.
+@end defun
+
 @defun define-abbrev-table tabname definitions
 This function defines @var{tabname} (a symbol) as an abbrev table
 name, i.e., as a variable whose value is an abbrev table.  It defines
 abbrevs in the table according to @var{definitions}, a list of
 elements of the form @code{(@var{abbrevname} @var{expansion}
-@var{hook} @var{usecount} @r{[}@var{system-flag}@r{]})}.  The return
-value is always @code{nil}.
+@var{hook} @var{usecount} @var{system-flag})}.  If an element of
+@var{definitions} has length less than five, omitted elements default
+to @code{nil}.  A value of @code{nil} for @var{usecount} is equivalent
+to zero.  The return value is always @code{nil}.
+
+If this function is called more than once for the same @var{tabname},
+subsequent calls add the definitions in @var{definitions} to
+@var{tabname}, rather than overriding the entire original contents.
+(A subsequent call only overrides abbrevs explicitly redefined or
+undefined in @var{definitions}.)
 @end defun
 
 @defvar abbrev-table-name-list
@@ -100,38 +120,24 @@
 abbrev table.  The return value is always @code{nil}.
 
 If @var{human} is non-@code{nil}, the description is human-oriented.
-Otherwise the description is a Lisp expression---a call to
-@code{define-abbrev-table} that would define @var{name} exactly as it
-is currently defined.
+System abbrevs are listed and identified as such.  Otherwise the
+description is a Lisp expression---a call to @code{define-abbrev-table}
+that would define @var{name} as it is currently defined, but without
+the system abbrevs.  (The mode or package using @var{name} is supposed
+to add these to @var{name} separately.)
 @end defun
 
 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
 @comment  node-name,  next,  previous,  up
 @section Defining Abbrevs
-
-  These functions define an abbrev in a specified abbrev table.
-@code{define-abbrev} is the low-level basic function, while
-@code{add-abbrev} is used by commands that ask for information from
-the user.  When major modes predefine standard abbrevs, they should
-call @code{define-abbrev} and specify @code{t} for @var{system-flag}.
-
-@defun add-abbrev table type arg
-This function adds an abbreviation to abbrev table @var{table} based on
-information from the user.  The argument @var{type} is a string
-describing in English the kind of abbrev this will be (typically,
-@code{"global"} or @code{"mode-specific"}); this is used in prompting
-the user.  The argument @var{arg} is the number of words in the
-expansion.
-
-The return value is the symbol that internally represents the new
-abbrev, or @code{nil} if the user declines to confirm redefining an
-existing abbrev.
-@end defun
+  @code{define-abbrev} is the low-level basic function for defining an
+abbrev in a specified abbrev table.  When major modes predefine
+standard abbrevs, they should call @code{define-abbrev} and specify
+@code{t} for @var{system-flag}.
 
 @defun define-abbrev table name expansion &optional hook count system-flag
 This function defines an abbrev named @var{name}, in @var{table}, to
-expand to @var{expansion} and call @var{hook}.  The return value is a
-symbol that represents the abbrev inside Emacs; its name is
+expand to @var{expansion} and call @var{hook}.  The return value is
 @var{name}.
 
 The value of @var{count}, if specified, initializes the abbrev's
@@ -149,6 +155,7 @@
 replaced with @var{expansion}; point is located at the end of
 @var{expansion} when @var{hook} is called.
 
+@cindex @code{no-self-insert} property
 If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}
 property is non-@code{nil}, @var{hook} can explicitly control whether
 to insert the self-inserting input character that triggered the
@@ -204,9 +211,10 @@
 @end defun
 
 @defopt save-abbrevs
-A non-@code{nil} value for @code{save-abbrev} means that Emacs should
-save abbrevs when files are saved.  @code{abbrev-file-name} specifies
-the file to save the abbrevs in.
+A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
+offer the user to save abbrevs when files are saved.  If the value is
+@code{silently}, Emacs saves the abbrevs without asking the user.
+@code{abbrev-file-name} specifies the file to save the abbrevs in.
 @end defopt
 
 @defvar abbrevs-changed
@@ -216,11 +224,11 @@
 @end defvar
 
 @deffn Command write-abbrev-file &optional filename
-Save all abbrev definitions (except ``system'' abbrevs), in all abbrev
-tables, in the file @var{filename}, in the form of a Lisp program that
-when loaded will define the same abbrevs.  If @var{filename} is
-@code{nil} or omitted, @code{abbrev-file-name} is used.  This function
-returns @code{nil}.
+Save all abbrev definitions (except ``system'' abbrevs), for all abbrev
+tables listed in @code{abbrev-table-name-list}, in the file
+@var{filename}, in the form of a Lisp program that when loaded will
+define the same abbrevs.  If @var{filename} is @code{nil} or omitted,
+@code{abbrev-file-name} is used.  This function returns @code{nil}.
 @end deffn
 
 @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
@@ -243,9 +251,10 @@
 
 @defun abbrev-expansion abbrev &optional table
 This function returns the string that @var{abbrev} would expand into (as
-defined by the abbrev tables used for the current buffer).  The optional
-argument @var{table} specifies the abbrev table to use, as in
-@code{abbrev-symbol}.
+defined by the abbrev tables used for the current buffer).  If
+@var{abbrev} is not a valid abbrev, the function returns @code{nil}.
+The optional argument @var{table} specifies the abbrev table to use,
+as in @code{abbrev-symbol}.
 @end defun
 
 @deffn Command expand-abbrev
@@ -260,10 +269,15 @@
 @end deffn
 
 @deffn Command abbrev-prefix-mark &optional arg
-Mark current point as the beginning of an abbrev.  The next call to
-@code{expand-abbrev} will use the text from here to point (where it is
-then) as the abbrev to expand, rather than using the previous word as
-usual.
+This command marks current point as the beginning of an abbrev.  The
+next call to @code{expand-abbrev} will use the text from here to point
+(where it is then) as the abbrev to expand, rather than using the
+previous word as usual.
+
+First, this command expands any abbrev before point, unless @var{arg}
+is non-@code{nil}.  (Interactively, @var{arg} is the prefix argument.)
+Then it inserts a hyphen before point, to indicate the start of the
+next abbrev to be expanded.  The actual expansion removes the hyphen.
 @end deffn
 
 @defopt abbrev-all-caps
@@ -274,9 +288,10 @@
 @end defopt
 
 @defvar abbrev-start-location
-This is the buffer position for @code{expand-abbrev} to use as the start
-of the next abbrev to be expanded.  (@code{nil} means use the word
-before point instead.)  @code{abbrev-start-location} is set to
+The value of this variable is a marker pointing to the buffer position
+for @code{expand-abbrev} to use as the start of the next abbrev to be
+expanded.  The value can also be @code{nil}, which means to use the
+word before point instead.  @code{abbrev-start-location} is set to
 @code{nil} each time @code{expand-abbrev} is called.  This variable is
 also set by @code{abbrev-prefix-mark}.
 @end defvar
@@ -377,3 +392,6 @@
 This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
 @end defvar
 
+@ignore
+   arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
+@end ignore

--- a/lispref/advice.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/advice.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -751,3 +751,7 @@
 executed even if some previous piece of advice had an error or a
 non-local exit.  If any around-advice is protected, then the whole
 around-advice onion is protected as a result.
+
+@ignore
+   arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f
+@end ignore

--- a/lispref/anti.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/anti.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -100,7 +100,7 @@
 the scroll bars.
 
 @item
-For simplicity, all @sc{ascii} characters now have the same height and width.
+For simplicity, all @acronym{ASCII} characters now have the same height and width.
 (Certain characters, such as Chinese characters, always have twice
 the standard width.)  All characters are created equal.
 
@@ -292,4 +292,9 @@
 @item
 @code{file-attributes} returns the file size and the file inode number
 only as a simple integer.
+Also @acronym{UID} and @acronym{GID} are always returned as integers.
 @end itemize
+
+@ignore
+   arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6
+@end ignore

--- a/lispref/back.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/back.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -31,3 +31,7 @@
 
 @hfil
 @bye
+
+@ignore
+   arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1
+@end ignore

--- a/lispref/backups.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/backups.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -55,6 +55,14 @@
   This function makes a backup of the file visited by the current
 buffer, if appropriate.  It is called by @code{save-buffer} before
 saving the buffer the first time.
+
+If a backup was made by renaming, the return value is a cons cell of
+the form (@var{modes} . @var{backupname}), where @var{modes} are the
+mode bits of the original file, as returned by @code{file-modes}
+(@pxref{File Attributes,, Other Information about Files}), and
+@var{backupname} is the name of the backup.  In all other cases, that
+is, if a backup was made by copying or if no backup was made, this
+function returns @code{nil}.
 @end defun
 
 @defvar buffer-backed-up
@@ -90,7 +98,7 @@
 @defvar backup-enable-predicate
 This variable's value is a function to be called on certain occasions to
 decide whether a file should have backup files.  The function receives
-one argument, a file name to consider.  If the function returns
+one argument, an absolute file name to consider.  If the function returns
 @code{nil}, backups are disabled for that file.  Otherwise, the other
 variables in this section say whether and how to make backups.
 
@@ -146,6 +154,7 @@
 This variable's value is a function to use for making backups instead
 of the default @code{make-backup-file-name}.  A value of @code{nil}
 gives the default @code{make-backup-file-name} behaviour.
+@xref{Backup Names,, Naming Backup Files}.
 
 This could be buffer-local to do something special for specific
 files.  If you define it, you may need to change
@@ -184,25 +193,25 @@
 if non-@code{nil}, also has this effect (as a sideline of its main
 significance).  @xref{Saving Buffers}.
 
-@defvar backup-by-copying
+@defopt backup-by-copying
 If this variable is non-@code{nil}, Emacs always makes backup files by
 copying.
-@end defvar
+@end defopt
 
   The following two variables, when non-@code{nil}, cause the second
 method to be used in certain special cases.  They have no effect on the
 treatment of files that don't fall into the special cases.
 
-@defvar backup-by-copying-when-linked
+@defopt backup-by-copying-when-linked
 If this variable is non-@code{nil}, Emacs makes backups by copying for
 files with multiple names (hard links).
 
 This variable is significant only if @code{backup-by-copying} is
 @code{nil}, since copying is always used when that variable is
 non-@code{nil}.
-@end defvar
+@end defopt
 
-@defvar backup-by-copying-when-mismatch
+@defopt backup-by-copying-when-mismatch
 If this variable is non-@code{nil}, Emacs makes backups by copying in cases
 where renaming would change either the owner or the group of the file.
 
@@ -214,9 +223,9 @@
 This variable is significant only if @code{backup-by-copying} is
 @code{nil}, since copying is always used when that variable is
 non-@code{nil}.
-@end defvar
+@end defopt
 
-@defvar backup-by-copying-when-privileged-mismatch
+@defopt backup-by-copying-when-privileged-mismatch
 This variable, if non-@code{nil}, specifies the same behavior as
 @code{backup-by-copying-when-mismatch}, but only for certain user-id
 values: namely, those less than or equal to a certain number.  You set
@@ -227,7 +236,7 @@
 when necessary to prevent a change in the owner of the file.
 
 The default is 200.
-@end defvar
+@end defopt
 
 @node Numbered Backups
 @subsection Making and Deleting Numbered Backup Files
@@ -379,7 +388,8 @@
 @var{filename}.  It may also propose certain existing backup files for
 deletion.  @code{find-backup-file-name} returns a list whose @sc{car} is
 the name for the new backup file and whose @sc{cdr} is a list of backup
-files whose deletion is proposed.
+files whose deletion is proposed.  The value can also be @code{nil},
+which means not to make a backup.
 
 Two variables, @code{kept-old-versions} and @code{kept-new-versions},
 determine which backup versions should be kept.  This function keeps
@@ -518,7 +528,7 @@
 change @code{auto-save-file-name-p} in a corresponding way.
 @end defun
 
-@defvar auto-save-visited-file-name
+@defopt auto-save-visited-file-name
 If this variable is non-@code{nil}, Emacs auto-saves buffers in
 the files they are visiting.  That is, the auto-save is done in the same
 file that you are editing.  Normally, this variable is @code{nil}, so
@@ -530,7 +540,7 @@
 reenabled in it.  If auto-save mode is already enabled, auto-saves
 continue to go in the same file name until @code{auto-save-mode} is
 called again.
-@end defvar
+@end defopt
 
 @defun recent-auto-save-p
 This function returns @code{t} if the current buffer has been
@@ -547,7 +557,8 @@
 The value of this variable specifies how often to do auto-saving, in
 terms of number of input events.  Each time this many additional input
 events are read, Emacs does auto-saving for all buffers in which that is
-enabled.
+enabled.  Setting this to zero disables autosaving based on the
+number of characters typed.
 @end defopt
 
 @defopt auto-save-timeout
@@ -586,24 +597,28 @@
 is auto-saved.
 @end deffn
 
-@defun delete-auto-save-file-if-necessary
+@defun delete-auto-save-file-if-necessary &optional force
 This function deletes the current buffer's auto-save file if
 @code{delete-auto-save-files} is non-@code{nil}.  It is called every
 time a buffer is saved.
+
+Unless @var{force} is non-@code{nil}, this function only deletes the
+file if it was written by the current Emacs session since the last
+true save.
 @end defun
 
-@defvar delete-auto-save-files
+@defopt delete-auto-save-files
 This variable is used by the function
 @code{delete-auto-save-file-if-necessary}.  If it is non-@code{nil},
 Emacs deletes auto-save files when a true save is done (in the visited
 file).  This saves disk space and unclutters your directory.
-@end defvar
+@end defopt
 
 @defun rename-auto-save-file
 This function adjusts the current buffer's auto-save file name if the
 visited file name has changed.  It also renames an existing auto-save
-file.  If the visited file name has not changed, this function does
-nothing.
+file, if it was made in the current Emacs session.  If the visited
+file name has not changed, this function does nothing.
 @end defun
 
 @defvar buffer-saved-size
@@ -633,7 +648,7 @@
 this file to find them.
 
 The default name for this file specifies your home directory and starts
-with @samp{.saves-}.  It also contains the Emacs process @sc{id} and the
+with @samp{.saves-}.  It also contains the Emacs process @acronym{ID} and the
 host name.
 @end defvar
 
@@ -654,7 +669,7 @@
 of the file with the @code{revert-buffer} command.  @xref{Reverting, ,
 Reverting a Buffer, emacs, The GNU Emacs Manual}.
 
-@deffn Command revert-buffer &optional ignore-auto noconfirm
+@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes
 This command replaces the buffer text with the text of the visited
 file on disk.  This action undoes all changes since the file was visited
 or saved.
@@ -670,6 +685,10 @@
 the buffer; but if the argument @var{noconfirm} is non-@code{nil},
 @code{revert-buffer} does not ask for confirmation.
 
+Normally, this command reinitializes the file's major and minor modes
+using @code{normal-mode}.  But if @var{preserve-modes} is
+non-@code{nil}, the modes remain unchanged.
+
 Reverting tries to preserve marker positions in the buffer by using the
 replacement feature of @code{insert-file-contents}.  If the buffer
 contents and the file contents are identical before the revert
@@ -682,22 +701,24 @@
 You can customize how @code{revert-buffer} does its work by setting
 the variables described in the rest of this section.
 
-@defvar revert-without-query
+@defopt revert-without-query
 This variable holds a list of files that should be reverted without
 query.  The value is a list of regular expressions.  If the visited file
 name matches one of these regular expressions, and the file has changed
 on disk but the buffer is not modified, then @code{revert-buffer}
 reverts the file without asking the user for confirmation.
-@end defvar
+@end defopt
 
   Some major modes customize @code{revert-buffer} by making
 buffer-local bindings for these variables:
 
 @defvar revert-buffer-function
-The value of this variable is the function to use to revert this buffer.
-If non-@code{nil}, it is called as a function with no arguments to do
-the work of reverting.  If the value is @code{nil}, reverting works the
-usual way.
+The value of this variable is the function to use to revert this
+buffer.  If non-@code{nil}, it should be a function with two optional
+arguments to do the work of reverting.  The two optional arguments,
+@var{ignore-auto} and @var{noconfirm}, are the arguments that
+@code{revert-buffer} received.  If the value is @code{nil}, reverting
+works the usual way.
 
 Modes such as Dired mode, in which the text being edited does not
 consist of a file's contents but can be regenerated in some other
@@ -729,3 +750,7 @@
 the modified contents---but only if @code{revert-buffer-function} is
 @code{nil}.
 @end defvar
+
+@ignore
+   arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f
+@end ignore

--- a/lispref/book-spine.texinfo	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/book-spine.texinfo	Mon Apr 19 07:01:43 2004 +0000
@@ -23,3 +23,7 @@
 @sp 5
 @center Free Software Foundation
 @bye
+
+@ignore
+   arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87
+@end ignore

--- a/lispref/buffers.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/buffers.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -106,7 +106,7 @@
 switch visibly to a different buffer so that the user can edit it.  For
 that, you must use the functions described in @ref{Displaying Buffers}.
 
-  @strong{Note:} Lisp functions that change to a different current buffer
+  @strong{Warning:} Lisp functions that change to a different current buffer
 should not depend on the command loop to set it back afterwards.
 Editing commands written in Emacs Lisp can be called from other programs
 as well as from the command loop; it is convenient for the caller if
@@ -215,14 +215,19 @@
 remains current.
 @end defspec
 
-@defmac with-current-buffer buffer body...
+@defmac with-current-buffer buffer-or-name body...
 The @code{with-current-buffer} macro saves the identity of the current
-buffer, makes @var{buffer} current, evaluates the @var{body} forms, and
-finally restores the buffer.  The return value is the value of the last
-form in @var{body}.  The current buffer is restored even in case of an
-abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
+buffer, makes @var{buffer-or-name} current, evaluates the @var{body}
+forms, and finally restores the buffer.  The return value is the value
+of the last form in @var{body}.  The current buffer is restored even
+in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal
+Exits}).
+
+An error is signaled if @var{buffer-or-name} does not identify an
+existing buffer.
 @end defmac
 
+@anchor{Definition of with-temp-buffer}
 @defmac with-temp-buffer body...
 The @code{with-temp-buffer} macro evaluates the @var{body} forms
 with a temporary buffer as the current buffer.  It saves the identity of
@@ -236,10 +241,11 @@
 
 The current buffer is restored even in case of an abnormal exit via
 @code{throw} or error (@pxref{Nonlocal Exits}).
+
+See also @code{with-temp-file} in @ref{Definition of with-temp-file,,
+Writing to Files}.
 @end defmac
 
-See also @code{with-temp-file} in @ref{Writing to Files}.
-
 @node Buffer Names
 @section Buffer Names
 @cindex buffer names
@@ -292,8 +298,7 @@
 
 @deffn Command rename-buffer newname &optional unique
 This function renames the current buffer to @var{newname}.  An error
-is signaled if @var{newname} is not a string, or if there is already a
-buffer with that name.  The function returns @var{newname}.
+is signaled if @var{newname} is not a string.
 
 @c Emacs 19 feature
 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
@@ -301,6 +306,8 @@
 @var{newname} to make a name that is not in use.  Interactively, you can
 make @var{unique} non-@code{nil} with a numeric prefix argument.
 (This is how the command @code{rename-uniquely} is implemented.)
+
+This function returns the name actually given to the buffer.
 @end deffn
 
 @defun get-buffer buffer-or-name
@@ -329,11 +336,12 @@
 @end defun
 
 @c Emacs 19 feature
-@defun generate-new-buffer-name starting-name &rest ignore
+@defun generate-new-buffer-name starting-name &optional ignore
 This function returns a name that would be unique for a new buffer---but
 does not create the buffer.  It starts with @var{starting-name}, and
 produces a name not currently in use for any buffer by appending a
-number inside of @samp{<@dots{}>}.
+number inside of @samp{<@dots{}>}.  It starts at 2 and keeps
+incrementing the number until it is not the name of an existing buffer.
 
 If the optional second argument @var{ignore} is non-@code{nil}, it
 should be a string; it makes a difference if it is a name in the
@@ -403,9 +411,11 @@
 @end defvar
 
 @defvar buffer-file-truename
-This buffer-local variable holds the truename of the file visited in the
-current buffer, or @code{nil} if no file is visited.  It is a permanent
-local, unaffected by @code{kill-all-local-variables}.  @xref{Truenames}.
+This buffer-local variable holds the abbreviated truename of the file
+visited in the current buffer, or @code{nil} if no file is visited.
+It is a permanent local, unaffected by
+@code{kill-all-local-variables}.  @xref{Truenames}, and
+@ref{Definition of abbreviate-file-name}.
 @end defvar
 
 @defvar buffer-file-number
@@ -419,6 +429,9 @@
 all files accessible on the system.  See the function
 @code{file-attributes}, in @ref{File Attributes}, for more information
 about them.
+
+If @code{buffer-file-name} is the name of a symbolic link, then both
+numbers refer to the recursive target.
 @end defvar
 
 @defun get-file-buffer filename
@@ -426,7 +439,9 @@
 there is no such buffer, it returns @code{nil}.  The argument
 @var{filename}, which must be a string, is expanded (@pxref{File Name
 Expansion}), then compared against the visited file names of all live
-buffers.
+buffers.  Note that the buffer's @code{buffer-file-name} must match
+the expansion of @var{filename} exactly.  This function will not
+recognize other names for the same file.
 
 @example
 @group
@@ -440,25 +455,50 @@
 such buffer in the buffer list.
 @end defun
 
+@defun find-buffer-visiting filename &optional predicate
+This is like @code{get-file-buffer}, except that it can return any
+buffer visiting the file @emph{possibly under a different name}.  That
+is, the buffer's @code{buffer-file-name} does not need to match the
+expansion of @var{filename} exactly, it only needs to refer to the
+same file.  If @var{predicate} is non-@code{nil}, it should be a
+function of one argument, a buffer visiting @var{filename}.  The
+buffer is only considered a suitable return value if @var{predicate}
+returns non-@code{nil}.  If it can not find a suitable buffer to
+return, @code{find-buffer-visiting} returns @code{nil}.
+@end defun
+
 @deffn Command set-visited-file-name filename &optional no-query along-with-file
 If @var{filename} is a non-empty string, this function changes the
 name of the file visited in the current buffer to @var{filename}.  (If the
 buffer had no visited file, this gives it one.)  The @emph{next time}
-the buffer is saved it will go in the newly-specified file.  This
-command marks the buffer as modified, since it does not (as far as Emacs
-knows) match the contents of @var{filename}, even if it matched the
-former visited file.
+the buffer is saved it will go in the newly-specified file.
+
+This command marks the buffer as modified, since it does not (as far
+as Emacs knows) match the contents of @var{filename}, even if it
+matched the former visited file.  It also renames the buffer to
+correspond to the new file name, unless the new name is already in
+use.
 
 If @var{filename} is @code{nil} or the empty string, that stands for
 ``no visited file''.  In this case, @code{set-visited-file-name} marks
-the buffer as having no visited file.
+the buffer as having no visited file, without changing the buffer's
+modified flag.
 
-Normally, this function asks the user for confirmation if the specified
-file already exists.  If @var{no-query} is non-@code{nil}, that prevents
-asking this question.
+Normally, this function asks the user for confirmation if there
+already is a buffer visiting @var{filename}.  If @var{no-query} is
+non-@code{nil}, that prevents asking this question.  If there already
+is a buffer visiting @var{filename}, and the user confirms or
+@var{query} is non-@code{nil}, this function makes the new buffer name
+unique by appending a number inside of @samp{<@dots{}>} to @var{filename}.
 
-If @var{along-with-file} is non-@code{nil}, that means to assume that the
-former visited file has been renamed to @var{filename}.
+If @var{along-with-file} is non-@code{nil}, that means to assume that
+the former visited file has been renamed to @var{filename}.  In this
+case, the command does not change the buffer's modified flag, nor the
+buffer's recorded last file modification time as reported by
+@code{visited-file-modtime} (@pxref{Modification Time}).  If
+@var{along-with-file} is @code{nil}, this function clears the recorded
+last file modification time, after which @code{visited-file-modtime}
+returns zero.
 
 @c Wordy to avoid overfull hbox.  --rjc 16mar92
 When the function @code{set-visited-file-name} is called interactively, it
@@ -514,10 +554,16 @@
 @end example
 @end defun
 
-@deffn Command not-modified
-This command marks the current buffer as unmodified, and not needing to
-be saved.  With prefix arg, it marks the buffer as modified, so that it
-will be saved at the next suitable occasion.
+@defun restore-buffer-modified-p flag
+Like @code{set-buffer-modified-p}, but does not force redisplay
+of mode lines.
+@end defun
+
+@deffn Command not-modified &optional arg
+This command marks the current buffer as unmodified, and not needing
+to be saved.  If @var{arg} is non-@code{nil}, it marks the buffer as
+modified, so that it will be saved at the next suitable occasion.
+Interactively, @var{arg} is the prefix argument.
 
 Don't use this function in programs, since it prints a message in the
 echo area; use @code{set-buffer-modified-p} (above) instead.
@@ -528,6 +574,7 @@
 This function returns @var{buffer}'s modification-count.  This is a
 counter that increments every time the buffer is modified.  If
 @var{buffer} is @code{nil} (or omitted), the current buffer is used.
+The counter can wrap around occasionally.
 @end defun
 
 @node Modification Time
@@ -552,6 +599,16 @@
 
 The function returns @code{t} if the last actual modification time and
 Emacs's recorded modification time are the same, @code{nil} otherwise.
+It also returns @code{t} if the buffer has no recorded last
+modification time, that is if @code{visited-file-modtime} would return
+zero.
+
+It always returns @code{t} for buffers that are not visiting a file,
+even if @code{visited-file-modtime} returns a non-zero value.  For
+instance, it always returns @code{t} for dired buffers.  It returns
+@code{t} for buffers that are visiting a file that does not exist and
+never existed, but @code{nil} for file-visiting buffers whose file has
+been deleted.
 @end defun
 
 @defun clear-visited-file-modtime
@@ -567,10 +624,30 @@
 
 @c Emacs 19 feature
 @defun visited-file-modtime
-This function returns the buffer's recorded last file modification time,
-as a list of the form @code{(@var{high} . @var{low})}.  (This is the
-same format that @code{file-attributes} uses to return time values; see
-@ref{File Attributes}.)
+This function returns the current buffer's recorded last file
+modification time, as a list of the form @code{(@var{high} .
+@var{low})}.  (This is the same format that @code{file-attributes}
+uses to return time values; see @ref{File Attributes}.)
+
+The function returns zero if the buffer has no recorded last
+modification time, which can happen, for instance, if the record has
+been explicitly cleared by @code{clear-visited-file-modtime} or if the
+buffer is not visiting a file.  Note, however, that
+@code{visited-file-modtime} can return a non-zero value for some
+buffers that are not visiting files, but are nevertheless closely
+associated with a file.  This happens, for instance, with dired
+buffers listing a directory.  For such buffers,
+@code{visited-file-modtime} returns the last modification time of that
+directory, as recorded by dired.
+
+For a new buffer visiting a not yet existing file, @var{high} is
+@minus{}1 and @var{low} is 65535, that is,
+@ifnottex
+@w{2**16 - 1.}
+@end ifnottex
+@tex
+@math{2^{16}-1}.
+@end tex
 @end defun
 
 @c Emacs 19 feature
@@ -580,7 +657,7 @@
 is not @code{nil}, and otherwise to the last modification time of the
 visited file.
 
-If @var{time} is not @code{nil}, it should have the form
+If @var{time} is neither @code{nil} nor zero, it should have the form
 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
 either case containing two integers, each of which holds 16 bits of the
 time.
@@ -646,12 +723,13 @@
 @end defvar
 
 @defvar inhibit-read-only
-If this variable is non-@code{nil}, then read-only buffers and read-only
-characters may be modified.  Read-only characters in a buffer are those
-that have non-@code{nil} @code{read-only} properties (either text
-properties or overlay properties).  @xref{Special Properties}, for more
-information about text properties.  @xref{Overlays}, for more
-information about overlays and their properties.
+If this variable is non-@code{nil}, then read-only buffers and,
+depending on the actual value, some or all read-only characters may be
+modified.  Read-only characters in a buffer are those that have
+non-@code{nil} @code{read-only} properties (either text properties or
+overlay properties).  @xref{Special Properties}, for more information
+about text properties.  @xref{Overlays}, for more information about
+overlays and their properties.
 
 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
 properties have no effect.  If @code{inhibit-read-only} is a list, then
@@ -659,17 +737,22 @@
 of the list (comparison is done with @code{eq}).
 @end defvar
 
-@deffn Command toggle-read-only
-This command changes whether the current buffer is read-only.  It is
+@deffn Command toggle-read-only &optional arg
+This command toggles whether the current buffer is read-only.  It is
 intended for interactive use; do not use it in programs.  At any given
 point in a program, you should know whether you want the read-only flag
 on or off; so you can set @code{buffer-read-only} explicitly to the
 proper value, @code{t} or @code{nil}.
+
+If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
+@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
+the numeric value of that prefix argument is positive and to
+@code{nil} otherwise.  @xref{Prefix Command Arguments}.
 @end deffn
 
 @defun barf-if-buffer-read-only
 This function signals a @code{buffer-read-only} error if the current
-buffer is read-only.  @xref{Interactive Call}, for another way to
+buffer is read-only.  @xref{Using Interactive}, for another way to
 signal an error if the current buffer is read-only.
 @end defun
 
@@ -807,12 +890,14 @@
 subprocess can also create a buffer (@pxref{Processes}).
 
 @defun get-buffer-create name
-This function returns a buffer named @var{name}.  It returns an existing
+This function returns a buffer named @var{name}.  It returns a live
 buffer with that name, if one exists; otherwise, it creates a new
 buffer.  The buffer does not become the current buffer---this function
 does not change which buffer is current.
 
-An error is signaled if @var{name} is not a string.
+If @var{name} is a buffer instead of a string, it is returned, even if
+it is dead.  An error is signaled if @var{name} is neither a string
+nor a buffer.
 
 @example
 @group
@@ -821,8 +906,8 @@
 @end group
 @end example
 
-The major mode for the new buffer is set to Fundamental mode.  The
-variable @code{default-major-mode} is handled at a higher level.
+The major mode for a newly created buffer is set to Fundamental mode.
+The variable @code{default-major-mode} is handled at a higher level.
 @xref{Auto Major Mode}.
 @end defun
 
@@ -896,8 +981,8 @@
 
 @deffn Command kill-buffer buffer-or-name
 This function kills the buffer @var{buffer-or-name}, freeing all its
-memory for other uses or to be returned to the operating system.  It
-returns @code{nil}.
+memory for other uses or to be returned to the operating system.  If
+@var{buffer-or-name} is @code{nil}, it kills the current buffer.
 
 Any processes that have this buffer as the @code{process-buffer} are
 sent the @code{SIGHUP} signal, which normally causes them to terminate.
@@ -912,16 +997,20 @@
 
 Killing a buffer that is already dead has no effect.
 
+This function returns @code{t} if it actually killed the buffer.  It
+returns @code{nil} if the user refuses to confirm or if
+@var{buffer-or-name} was already dead.
+
 @smallexample
 (kill-buffer "foo.unchanged")
-     @result{} nil
+     @result{} t
 (kill-buffer "foo.changed")
 
 ---------- Buffer: Minibuffer ----------
 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
 ---------- Buffer: Minibuffer ----------
 
-     @result{} nil
+     @result{} t
 @end smallexample
 @end deffn
 
@@ -944,12 +1033,19 @@
 
 @defvar buffer-offer-save
 This variable, if non-@code{nil} in a particular buffer, tells
-@code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to
-save that buffer, just as they offer to save file-visiting buffers.  The
-variable @code{buffer-offer-save} automatically becomes buffer-local
-when set for any reason.  @xref{Buffer-Local Variables}.
+@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the
+second optional argument to that function is @code{t}) to offer to
+save that buffer, just as they offer to save file-visiting buffers.
+@xref{Definition of save-some-buffers}.  The variable
+@code{buffer-offer-save} automatically becomes buffer-local when set
+for any reason.  @xref{Buffer-Local Variables}.
 @end defvar
 
+@defun buffer-live-p object
+This function returns @code{t} if @var{object} is a buffer which has
+not been killed, @code{nil} otherwise.
+@end defun
+
 @node Indirect Buffers
 @section Indirect Buffers
 @cindex indirect buffers
@@ -980,19 +1076,29 @@
 the base buffer effectively kills the indirect buffer in that it cannot
 ever again be the current buffer.
 
-@deffn Command make-indirect-buffer base-buffer name
-This creates an indirect buffer named @var{name} whose base buffer
-is @var{base-buffer}.  The argument @var{base-buffer} may be a buffer
-or a string.
+@deffn Command make-indirect-buffer base-buffer name &optional clone
+This creates and returns an indirect buffer named @var{name} whose
+base buffer is @var{base-buffer}.  The argument @var{base-buffer} may
+be a live buffer or the name (a string) of an existing buffer.  If
+@var{name} is the name of an existing buffer, an error is signaled.
+
+If @var{clone} is non-@code{nil}, then the indirect buffer originally
+shares the ``state'' of @var{base-buffer} such as major mode, minor
+modes, buffer local variables and so on.  If @var{clone} is omitted
+or @code{nil} the indirect buffer's state is set to the default state
+for new buffers.
 
 If @var{base-buffer} is an indirect buffer, its base buffer is used as
-the base for the new buffer.
+the base for the new buffer.  If, in addition, @var{clone} is
+non-@code{nil}, the initial state is copied from the actual base
+buffer, not from @var{base-buffer}.
 @end deffn
 
-@defun buffer-base-buffer buffer
-This function returns the base buffer of @var{buffer}.  If @var{buffer}
-is not indirect, the value is @code{nil}.  Otherwise, the value is
-another buffer, which is never an indirect buffer.
+@defun buffer-base-buffer &optional buffer
+This function returns the base buffer of @var{buffer}, which defaults
+to the current buffer.  If @var{buffer} is not indirect, the value is
+@code{nil}.  Otherwise, the value is another buffer, which is never an
+indirect buffer.
 @end defun
 
 @node Buffer Gap
@@ -1018,3 +1124,7 @@
 @defun gap-size
 This function returns the current gap size of the current buffer.
 @end defun
+
+@ignore
+   arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
+@end ignore

--- a/lispref/calendar.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/calendar.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -255,12 +255,12 @@
 divisible by 4:
 
 @smallexample
-(holiday-sexp (if (= 0 (% year 4))
+(holiday-sexp '(if (= 0 (% year 4))
                    (calendar-gregorian-from-absolute
                     (1+ (calendar-dayname-on-or-before
                           1 (+ 6 (calendar-absolute-from-gregorian
-                                  (list 11 1 year))))))
-              "US Presidential Election"))
+                                  (list 11 1 year)))))))
+              "US Presidential Election")
 @end smallexample
 
 @noindent
@@ -967,7 +967,7 @@
 @table @code
 @item appt-message-warning-time
 The time in minutes before an appointment that the reminder begins.  The
-default is 10 minutes.
+default is 12 minutes.
 @item appt-audible
 If this is non-@code{nil}, Emacs rings the
 terminal bell for appointment reminders.  The default is @code{t}.
@@ -988,5 +988,9 @@
 message window, when its time is up.
 @item appt-display-duration
 The number of seconds to display an appointment message.  The default
-is 5 seconds.
+is 10 seconds.
 @end table
+
+@ignore
+   arch-tag: 8e50c766-4703-4888-a421-af15244cca7e
+@end ignore

--- a/lispref/commands.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/commands.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -239,9 +239,8 @@
 @var{function} is a command (@pxref{Interactive Call}), the value is a
 list of the form @code{(interactive @var{spec})}, where @var{spec} is
 the descriptor specification used by the command's @code{interactive}
-form to compute the function's arguments (@pxref{Using Interactive}).
-If @var{function} is not a command, @code{interactive-form} returns
-@code{nil}.
+form to compute the function's arguments.  If @var{function} is not a
+command, @code{interactive-form} returns @code{nil}.
 @end defun
 
 @node Interactive Codes
@@ -328,7 +327,7 @@
 
 @item D
 A directory name.  The default is the current default directory of the
-current buffer, @code{default-directory} (@pxref{System Environment}).
+current buffer, @code{default-directory} (@pxref{File Name Expansion}).
 Existing, Completion, Default, Prompt.
 
 @item e
@@ -340,7 +339,7 @@
 specification.  If the key sequence that invoked the command has
 @var{n} events that are lists, the @var{n}th @samp{e} provides the
 @var{n}th such event.  Events that are not lists, such as function keys
-and @sc{ascii} characters, do not count where @samp{e} is concerned.
+and @acronym{ASCII} characters, do not count where @samp{e} is concerned.
 
 @item f
 A file name of an existing file (@pxref{File Names}).  The default
@@ -503,7 +502,7 @@
 @code{call-interactively}, which reads the arguments and calls the
 command.  You can also call these functions yourself.
 
-@defun commandp object
+@defun commandp object &optional for-call-interactively
 Returns @code{t} if @var{object} is suitable for calling interactively;
 that is, if @var{object} is a command.  Otherwise, returns @code{nil}.
 
@@ -514,11 +513,13 @@
 (non-@code{nil} fourth argument to @code{autoload}), and some of the
 primitive functions.
 
-A symbol satisfies @code{commandp} if its function definition satisfies
-@code{commandp}.
-
-Keys and keymaps are not commands.  Rather, they are used to look up
-commands (@pxref{Keymaps}).
+A symbol satisfies @code{commandp} if its function definition
+satisfies @code{commandp}.  Keys and keymaps are not commands.
+Rather, they are used to look up commands (@pxref{Keymaps}).
+
+If @var{for-call-interactively} is non-@code{nil}, then
+@code{commandp} returns @code{t} only for objects that
+@code{call-interactively} could call---thus, not for keyboard macros.
 
 See @code{documentation} in @ref{Accessing Documentation}, for a
 realistic example of using @code{commandp}.
@@ -661,6 +662,10 @@
     (message "foo")))
 @end example
 
+@noindent
+Defined in this way, the function does display the message when
+called from a keyboard macro.
+
   The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
 
 @node Command Loop Info
@@ -727,6 +732,14 @@
 restore the old value in case of error---a feature of @code{let} which
 in this case does precisely what we want to avoid.
 
+@defvar this-original-command
+This has the same value as @code{this-command} except when command
+remapping occurs (@pxref{Remapping Commands}).  In that case,
+@code{this-command} gives the command actually run (the result of
+remapping), and @code{this-original-command} gives the command that
+was specified to run but remapped into another command.
+@end defvar
+
 @defun this-command-keys
 This function returns a string or vector containing the key sequence
 that invoked the present command, plus any previous commands that
@@ -783,7 +796,7 @@
 @end example
 
 @noindent
-The value is 5 because that is the @sc{ascii} code for @kbd{C-e}.
+The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}.
 
 The alias @code{last-command-char} exists for compatibility with
 Emacs version 18.
@@ -902,14 +915,14 @@
 @ifnottex
 2**26
 @end ifnottex
-bit in the character code indicates a non-@sc{ascii}
+bit in the character code indicates a non-@acronym{ASCII}
 control character.
 
 @sc{ascii} control characters such as @kbd{C-a} have special basic
 codes of their own, so Emacs needs no special bit to indicate them.
 Thus, the code for @kbd{C-a} is just 1.
 
-But if you type a control combination not in @sc{ascii}, such as
+But if you type a control combination not in @acronym{ASCII}, such as
 @kbd{%} with the control key, the numeric value you get is the code
 for @kbd{%} plus
 @tex
@@ -918,7 +931,7 @@
 @ifnottex
 2**26
 @end ifnottex
-(assuming the terminal supports non-@sc{ascii}
+(assuming the terminal supports non-@acronym{ASCII}
 control characters).
 
 @item shift
@@ -929,13 +942,13 @@
 @ifnottex
 2**25
 @end ifnottex
-bit in the character code indicates an @sc{ascii} control
+bit in the character code indicates an @acronym{ASCII} control
 character typed with the shift key held down.
 
 For letters, the basic code itself indicates upper versus lower case;
 for digits and punctuation, the shift key selects an entirely different
 character with a different basic code.  In order to keep within the
-@sc{ascii} character set whenever possible, Emacs avoids using the
+@acronym{ASCII} character set whenever possible, Emacs avoids using the
 @tex
 @math{2^{25}}
 @end tex
@@ -944,7 +957,7 @@
 @end ifnottex
 bit for those characters.
 
-However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
+However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
 @kbd{C-a}, so Emacs uses the
 @tex
 @math{2^{25}}
@@ -1018,10 +1031,10 @@
 
 @table @asis
 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
-These keys correspond to common @sc{ascii} control characters that have
+These keys correspond to common @acronym{ASCII} control characters that have
 special keys on most keyboards.
 
-In @sc{ascii}, @kbd{C-i} and @key{TAB} are the same character.  If the
+In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character.  If the
 terminal can distinguish between them, Emacs conveys the distinction to
 Lisp programs by representing the former as the integer 9, and the
 latter as the symbol @code{tab}.
@@ -1033,7 +1046,7 @@
 symbols in this group.  The function @code{read-char} likewise converts
 these events into characters.
 
-In @sc{ascii}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
+In @acronym{ASCII}, @key{BS} is really @kbd{C-h}.  But @code{backspace}
 converts into the character code 127 (@key{DEL}), not into code 8
 (@key{BS}).  This is what most users prefer.
 
@@ -1105,27 +1118,13 @@
 @cindex mouse click event
 
 When the user presses a mouse button and releases it at the same
-location, that generates a @dfn{click} event.  Mouse click events have
-this form:
+location, that generates a @dfn{click} event.  All mouse click event
+share the same format:
 
 @example
-(@var{event-type}
- (@var{window} @var{buffer-pos} (@var{x} . @var{y})
-  @var{timestamp})
- @var{click-count})
+(@var{event-type} @var{position} @var{click-count})
 @end example
 
-or, for clicks on strings in the mode line, header line or marginal
-areas:
-
-@example
-(@var{event-type}
- (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp} (@var{string} . @var{string-pos})
- @var{click-count})
-@end example
-
-Here is what the elements normally mean:
-
 @table @asis
 @item @var{event-type}
 This is a symbol that indicates which mouse button was used.  It is
@@ -1141,21 +1140,50 @@
 @code{mouse-1}, that binding would apply to all events whose
 @var{event-type} is @code{mouse-1}.
 
+@item @var{position}
+This is the position where the mouse click occurred.  The actual
+format of @var{position} depends on what part of a window was clicked
+on.  The various formats are described below.
+
+@item @var{click-count}
+This is the number of rapid repeated presses so far of the same mouse
+button.  @xref{Repeat Events}.
+@end table
+
+For mouse click events in the text area, mode line, header line, or in
+the marginal areas, @var{position} has this form:
+
+@example
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row}) 
+ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
+@end example
+
+@table @asis
 @item @var{window}
 This is the window in which the click occurred.
 
+@item @var{pos-or-area}
+This is the buffer position of the character clicked on in the text
+area, or if clicked outside the text area, it is the window area in
+which the click occurred.  It is one of the symbols @code{mode-line},
+@code{header-line}, @code{vertical-line}, @code{left-margin},
+@code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
+
 @item @var{x}, @var{y}
 These are the pixel-denominated coordinates of the click, relative to
 the top left corner of @var{window}, which is @code{(0 . 0)}.
-
-@item @var{buffer-pos}
-This is the buffer position of the character clicked on.
+For the mode or header line, @var{y} does not have meaningful data.
+For the vertical line, @var{x} does not have meaningful data.
 
 @item @var{timestamp}
-This is the time at which the event occurred, in milliseconds.  (Since
-this value wraps around the entire range of Emacs Lisp integers in about
-five hours, it is useful only for relating the times of nearby
-events.)
+This is the time at which the event occurred, in milliseconds.
+
+@item @var{object}
+This is the object on which the click occurred.  It is either
+@code{nil} if there is no string property, or it has the form
+(@var{string} . @var{string-pos}) when there is a string-type text
+property at the click position.
 
 @item @var{string}
 This is the string on which the click occurred, including any
@@ -1165,29 +1193,58 @@
 This is the position in the string on which the click occurred,
 relevant if properties at the click need to be looked up.
 
-@item @var{click-count}
-This is the number of rapid repeated presses so far of the same mouse
-button.  @xref{Repeat Events}.
+@item @var{text-pos}
+For clicks on a marginal area or on a fringe, this is the buffer
+position of the first visible character in the corresponding line in
+the window.  For other events, it is the current buffer position in
+the window.
+
+@item @var{col}, @var{row}
+These are the actual coordinates of the glyph under the @var{x},
+@var{y} position, possibly padded with default character width
+glyphs if @var{x} is beyond the last glyph on the line.
+
+@item @var{image}
+This is the image object on which the click occurred.  It is either
+@code{nil} if there is no image at the position clicked on, or it is
+an image object as returned by @code{find-image} if click was in an image.
+
+@item @var{dx}, @var{dy}
+These are the pixel-denominated coordinates of the click, relative to
+the top left corner of @var{object}, which is @code{(0 . 0)}.  If
+@var{object} is @code{nil}, the coordinates are relative to the top
+left corner of the character glyph clicked on.
 @end table
 
-The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
-different when the event location is in a special part of the screen,
-such as the mode line or a scroll bar.
-
-If the location is in a scroll bar, then @var{buffer-pos} is the symbol
-@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
-@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
-. @var{whole})}, where @var{portion} is the distance of the click from
-the top or left end of the scroll bar, and @var{whole} is the length of
-the entire scroll bar.
-
-If the position is on a mode line, the vertical line separating
-@var{window} from its neighbor to the right, or in a marginal area,
-then @var{buffer-pos} is the symbol @code{mode-line},
-@code{header-line}, @code{vertical-line}, @code{left-margin}, or
-@code{right-margin}.  For the mode line, @var{y} does not have
-meaningful data.  For the vertical line, @var{x} does not have
-meaningful data.
+For mouse clicks on a scroll-bar, @var{position} has this form:
+
+@example
+(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
+@end example
+
+@table @asis
+@item @var{window}
+This is the window whose scroll-bar was clicked on.
+
+@item @var{area}
+This is the scroll bar where the click occurred.  It is one of the
+symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
+
+@item @var{portion}
+This is the distance of the click from the top or left end of
+the scroll bar.
+
+@item @var{whole}
+This is the length of the entire scroll bar.
+
+@item @var{timestamp}
+This is the time at which the event occurred, in milliseconds.
+
+@item @var{part}
+This is the part of the scroll-bar which was clicked on.  It is one
+of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
+@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
+@end table
 
 In one special case, @var{buffer-pos} is a list containing a symbol (one
 of the symbols listed above) instead of just the symbol.  This happens
@@ -1615,7 +1672,9 @@
 mouse-button event, as a list of this form:
 
 @example
-(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
+(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
+ @var{object} @var{text-pos} (@var{col} . @var{row})
+ @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
 @end example
 
 @defun event-start event
@@ -1636,15 +1695,24 @@
 @end defun
 
 @cindex mouse position list, accessing
-  These five functions take a position list as described above, and
+  These seven functions take a position list as described above, and
 return various parts of it.
 
 @defun posn-window position
 Return the window that @var{position} is in.
 @end defun
 
+@defun posn-area position
+Return the window area recorded in @var{position}.  It returns @code{nil}
+when the event occurred in the text area of the window; otherwise, it
+is a symbol identifying the area in which the the event occurred.
+@end defun
+
 @defun posn-point position
-Return the buffer position in @var{position}.  This is an integer.
+Return the buffer position in @var{position}.  When the event occurred
+in the text area of the window, in a marginal area, or on a fringe,
+this is an integer specifying a buffer position.  Otherwise, the value
+is undefined.
 @end defun
 
 @defun posn-x-y position
@@ -1653,15 +1721,54 @@
 @end defun
 
 @defun posn-col-row position
-Return the row and column (in units of characters) of @var{position}, as
-a cons cell @code{(@var{col} . @var{row})}.  These are computed from the
-@var{x} and @var{y} values actually found in @var{position}.
+Return the row and column (in units of frame default characters) of
+@var{position}, as a cons cell @code{(@var{col} . @var{row})}.  These
+are computed from the @var{x} and @var{y} values actually found in
+@var{position}.
+@end defun
+
+@defun posn-actual-col-row position
+Return the actual row and column in @var{position}, as a cons cell
+@code{(@var{col} . @var{row})}.  The values are the actual row number
+in the window, and the actual character number in that row.  Return
+@code{nil} if @var{position} does not include the actual positions; in that
+case, @code{posn-col-row} can be used to get approximate values.
+@end defun
+
+@defun posn-string position
+Return the string object in @var{position}, either @code{nil}, or a
+cons cell @code{(@var{string} . @var{string-pos})}.
+@end defun
+
+@defun posn-image position
+Return the image object in @var{position}, either @code{nil}, or an
+image @code{(image ...)}.
+@end defun
+
+@defun posn-object position
+Return the image or string object in @var{position}, either
+@code{nil}, an image @code{(image ...)}, or a cons cell
+@code{(@var{string} . @var{string-pos})}.
+@end defun
+
+@defun posn-object-x-y position
+Return the pixel-based x and y coordinates relative to the upper left
+corner of the object in @var{position} as a cons cell @code{(@var{dx}
+. @var{dy})}.  If the @var{position} is a buffer position, return the
+relative position in the character at that position.
+@end defun
+
+@defun posn-object-width-height position
+Return the pixel width and height of the object in @var{position} as a
+cons cell @code{(@var{width} . @var{height})}.  If the @var{position}
+is a buffer position, return the size of the character at that position.
 @end defun
 
 @cindex mouse event, timestamp
 @cindex timestamp of a mouse event
-@defun posn-timestamp position
-Return the timestamp in @var{position}.
+@defun posn-timestamp
+Return the timestamp in @var{position}.  This is the time at which the
+event occurred, in milliseconds.
 @end defun
 
   These functions are useful for decoding scroll bar events.
@@ -1796,7 +1903,7 @@
 can include these codes.
 
 @item
-Non-@sc{ascii} characters above 256 can be included in a multibyte string.
+Non-@acronym{ASCII} characters above 256 can be included in a multibyte string.
 
 @item
 Other keyboard character events cannot fit in a string.  This includes
@@ -1965,7 +2072,7 @@
 
 If @var{inherit-input-method} is non-@code{nil}, then the current input
 method (if any) is employed to make it possible to enter a
-non-@sc{ascii} character.  Otherwise, input method handling is disabled
+non-@acronym{ASCII} character.  Otherwise, input method handling is disabled
 for reading this event.
 
 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
@@ -1995,7 +2102,7 @@
 function key event), @code{read-char} signals an error.  The arguments
 work as in @code{read-event}.
 
-In the first example, the user types the character @kbd{1} (@sc{ascii}
+In the first example, the user types the character @kbd{1} (@acronym{ASCII}
 code 49).  The second example shows a keyboard macro definition that
 calls @code{read-char} from the minibuffer using @code{eval-expression}.
 @code{read-char} reads the keyboard macro's very next character, which
@@ -2041,7 +2148,7 @@
 If this is non-@code{nil}, its value specifies the current input method
 function.
 
-@strong{Note:} Don't bind this variable with @code{let}.  It is often
+@strong{Warning:} don't bind this variable with @code{let}.  It is often
 buffer-local, and if you bind it around reading input (which is exactly
 when you @emph{would} bind it), switching buffers asynchronously while
 Emacs is waiting will cause the value to be restored in the wrong
@@ -2175,7 +2282,7 @@
 as part of a command or explicitly by a Lisp program.
 
 In the example below, the Lisp program reads the character @kbd{1},
-@sc{ascii} code 49.  It becomes the value of @code{last-input-event},
+@acronym{ASCII} code 49.  It becomes the value of @code{last-input-event},
 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
 this expression) remains the value of @code{last-command-event}.
 
@@ -2819,3 +2926,7 @@
 macro terminates, regardless of what caused it to terminate (reaching
 the macro end or an error which ended the macro prematurely).
 @end defvar
+
+@ignore
+   arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1
+@end ignore

--- a/lispref/compile.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/compile.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -173,14 +173,18 @@
 certain primitives that are coded as special instructions.
 @end defun
 
-@deffn Command compile-defun
+@deffn Command compile-defun &optional arg
 This command reads the defun containing point, compiles it, and
 evaluates the result.  If you use this on a defun that is actually a
 function definition, the effect is to install a compiled version of that
 function.
+
+@code{compile-defun} normally displays the result of evaluation in the
+echo area, but if @var{arg} is non-@code{nil}, it inserts the result
+in the current buffer after the form it compiled.
 @end deffn
 
-@deffn Command byte-compile-file filename
+@deffn Command byte-compile-file filename &optional load
 This function compiles a file of Lisp code named @var{filename} into a
 file of byte-code.  The output file's name is made by changing the
 @samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
@@ -193,8 +197,11 @@
 executed when the file is read.  All comments are discarded when the
 input file is read.
 
-This command returns @code{t}.  When called interactively, it prompts
-for the file name.
+This command returns @code{t} if there were no errors and @code{nil}
+otherwise.  When called interactively, it prompts for the file name.
+
+If @var{load} is non-@code{nil}, this command loads the compiled file
+after compiling it.  Interactively, @var{load} is the prefix argument.
 
 @example
 @group
@@ -215,20 +222,28 @@
 @end example
 @end deffn
 
-@deffn Command byte-recompile-directory directory flag
+@deffn Command byte-recompile-directory directory &optional flag force
 @cindex library compilation
-This function recompiles every @samp{.el} file in @var{directory} that
-needs recompilation.  A file needs recompilation if a @samp{.elc} file
-exists but is older than the @samp{.el} file.
+This command recompiles every @samp{.el} file in @var{directory} (or
+its subdirectories) that needs recompilation.  A file needs
+recompilation if a @samp{.elc} file exists but is older than the
+@samp{.el} file.
 
-When a @samp{.el} file has no corresponding @samp{.elc} file, @var{flag}
-says what to do.  If it is @code{nil}, these files are ignored.  If it
-is non-@code{nil}, the user is asked whether to compile each such file.
+When a @samp{.el} file has no corresponding @samp{.elc} file,
+@var{flag} says what to do.  If it is @code{nil}, this command ignores
+these files.  If @var{flag} is 0, it compiles them.  If it is neither
+@code{nil} nor 0, it asks the user whether to compile each such file.
 
-The returned value of this command is unpredictable.
+Interactively, @code{byte-recompile-directory} prompts for
+@var{directory} and @var{flag} is the prefix argument.
+
+If @var{force} is non-@code{nil}, this command recompiles every
+@samp{.el} file that has a @samp{.elc} file.
+
+The returned value is unpredictable.
 @end deffn
 
-@defun batch-byte-compile
+@defun batch-byte-compile &optional noforce
 This function runs @code{byte-compile-file} on files specified on the
 command line.  This function must be used only in a batch execution of
 Emacs, as it kills Emacs on completion.  An error in one file does not
@@ -236,6 +251,9 @@
 generated for it, and the Emacs process will terminate with a nonzero
 status code.
 
+If @var{noforce} is non-@code{nil}, this function does not recompile
+files that have an up-to-date @samp{.elc} file.
+
 @example
 % emacs -batch -f batch-byte-compile *.el
 @end example
@@ -420,7 +438,45 @@
 defined are always ``located'' at the end of the file, so these
 commands won't find the places they are really used.  To do that,
 you must search for the function names.
- 
+
+  You can suppress the compiler warning for calling an undefined
+function @var{func} by conditionalizing the function call on a
+@code{fboundp} test, like this:
+
+@example
+(if (fboundp '@var{func}) ...(@var{func} ...)...)
+@end example
+
+@noindent
+The call to @var{func} must be in the @var{then-form} of the
+@code{if}, and @var{func} must appear quoted in the call to
+@code{fboundp}.  (This feature operates for @code{cond} as well.)
+
+  Likewise, you can suppress a compiler warning for an unbound variable
+@var{variable} by conditionalizing its use on a @code{boundp} test,
+like this:
+
+@example
+(if (boundp '@var{variable}) ...@var{variable}...)
+@end example
+
+@noindent
+The reference to @var{variable} must be in the @var{then-form} of the
+@code{if}, and @var{variable} must appear quoted in the call to
+@code{boundp}.
+
+  You can suppress any compiler warnings using the construct
+@code{with-no-warnings}:
+
+@defmac with-no-warnings body...
+In execution, this is equivalent to @code{(progn @var{body}...)},
+but the compiler does not issue warnings for anything that occurs
+inside @var{body}.
+
+We recommend that you use this construct around the smallest
+possible piece of code.
+@end defmac
+
 @node Byte-Code Objects
 @section Byte-Code Function Objects
 @cindex compiled function
@@ -513,14 +569,16 @@
 ordinary Lisp variables, by transferring values between variables and
 the stack.
 
-@deffn Command disassemble object &optional stream
-This function prints the disassembled code for @var{object}.  If
-@var{stream} is supplied, then output goes there.  Otherwise, the
-disassembled code is printed to the stream @code{standard-output}.  The
-argument @var{object} can be a function name or a lambda expression.
+@deffn Command disassemble object &optional buffer-or-name
+This command displays the disassembled code for @var{object}.  In
+interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
+the output goes in a buffer named @samp{*Disassemble*}.  If
+@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
+name of an existing buffer.  Then the output goes there, at point, and
+point is left before the output.
 
-As a special exception, if this function is used interactively,
-it outputs to a buffer named @samp{*Disassemble*}.
+The argument @var{object} can be a function name, a lambda expression
+or a byte-code object.
 @end deffn
 
   Here are two examples of using the @code{disassemble} function.  We
@@ -766,3 +824,6 @@
 @end example
 
 
+@ignore
+   arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
+@end ignore

--- a/lispref/configure.in	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/configure.in	Mon Apr 19 07:01:43 2004 +0000
@@ -1,3 +1,7 @@
 dnl Process this file with autoconf to produce a configure script.
 AC_INIT(elisp.texi)
 AC_OUTPUT(Makefile)
+
+m4_if(dnl	Do not change this comment
+   arch-tag: 61db4227-0d2b-4c4d-ad54-ca9a1ee518ea
+)dnl

--- a/lispref/control.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/control.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -496,7 +496,7 @@
 (inclusive) to @var{count} (exclusive), using the variable @var{var} to
 hold the integer for the current iteration.  Then it returns the value
 of evaluating @var{result}, or @code{nil} if @var{result} is omitted.
-Here is an example of using @code{dotimes} do something 100 times:
+Here is an example of using @code{dotimes} to do something 100 times:
 
 @example
 (dotimes (i 100)
@@ -757,7 +757,7 @@
 
 @defun error format-string &rest args
 This function signals an error with an error message constructed by
-applying @code{format} (@pxref{String Conversion}) to
+applying @code{format} (@pxref{Formatting Strings}) to
 @var{format-string} and @var{args}.
 
 These examples show typical uses of @code{error}:
@@ -784,6 +784,7 @@
 undesirable results.  Instead, use @code{(error "%s" @var{string})}.
 @end defun
 
+@anchor{Definition of signal}
 @defun signal error-symbol data
 This function signals an error named by @var{error-symbol}.  The
 argument @var{data} is a list of additional Lisp objects relevant to the
@@ -792,19 +793,26 @@
 The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol
 bearing a property @code{error-conditions} whose value is a list of
 condition names.  This is how Emacs Lisp classifies different sorts of
-errors.
+errors. @xref{Error Symbols}, for a description of error symbols,
+error conditions and condition names.
+
+If the error is not handled, the two arguments are used in printing
+the error message.  Normally, this error message is provided by the
+@code{error-message} property of @var{error-symbol}.  If @var{data} is
+non-@code{nil}, this is followed by a colon and a comma separated list
+of the unevaluated elements of @var{data}.  For @code{error}, the
+error message is the @sc{car} of @var{data} (that must be a string).
+Subcategories of @code{file-error} are handled specially.
 
 The number and significance of the objects in @var{data} depends on
 @var{error-symbol}.  For example, with a @code{wrong-type-arg} error,
 there should be two objects in the list: a predicate that describes the type
 that was expected, and the object that failed to fit that type.
-@xref{Error Symbols}, for a description of error symbols.
 
 Both @var{error-symbol} and @var{data} are available to any error
 handlers that handle the error: @code{condition-case} binds a local
 variable to a list of the form @code{(@var{error-symbol} .@:
-@var{data})} (@pxref{Handling Errors}).  If the error is not handled,
-these two values are used in printing the error message.
+@var{data})} (@pxref{Handling Errors}).
 
 The function @code{signal} never returns (though in older Emacs versions
 it could sometimes return).
@@ -989,7 +997,7 @@
 @defun error-message-string error-description
 This function returns the error message string for a given error
 descriptor.  It is useful if you want to handle an error by printing the
-usual error message for that error.
+usual error message for that error.  @xref{Definition of signal}.
 @end defun
 
 @cindex @code{arith-error} example
@@ -1071,10 +1079,10 @@
 names}.  The narrowest such classes belong to the error symbols
 themselves: each error symbol is also a condition name.  There are also
 condition names for more extensive classes, up to the condition name
-@code{error} which takes in all kinds of errors.  Thus, each error has
-one or more condition names: @code{error}, the error symbol if that
-is distinct from @code{error}, and perhaps some intermediate
-classifications.
+@code{error} which takes in all kinds of errors (but not @code{quit}).
+Thus, each error has one or more condition names: @code{error}, the
+error symbol if that is distinct from @code{error}, and perhaps some
+intermediate classifications.
 
   In order for a symbol to be an error symbol, it must have an
 @code{error-conditions} property which gives a list of condition names.
@@ -1082,13 +1090,16 @@
 (The error symbol itself, and the symbol @code{error}, should always be
 members of this list.)  Thus, the hierarchy of condition names is
 defined by the @code{error-conditions} properties of the error symbols.
+Because quitting is not considered an error, the value of the
+@code{error-conditions} property of @code{quit} is just @code{(quit)}.
 
+@cindex peculiar error
   In addition to the @code{error-conditions} list, the error symbol
 should have an @code{error-message} property whose value is a string to
 be printed when that error is signaled but not handled.  If the
+error symbol has no @code{error-message} property or if the
 @code{error-message} property exists, but is not a string, the error
-message @samp{peculiar error} is used.
-@cindex peculiar error
+message @samp{peculiar error} is used.  @xref{Definition of signal}.
 
   Here is how we define a new error symbol, @code{new-error}:
 
@@ -1114,8 +1125,8 @@
 not end with a period.  This is for consistency with the rest of Emacs.
 
   Naturally, Emacs will never signal @code{new-error} on its own; only
-an explicit call to @code{signal} (@pxref{Signaling Errors}) in your
-code can do this:
+an explicit call to @code{signal} (@pxref{Definition of signal}) in
+your code can do this:
 
 @example
 @group
@@ -1158,32 +1169,34 @@
 temporarily put a data structure in an inconsistent state; it permits
 you to make the data consistent again in the event of an error or throw.
 
-@defspec unwind-protect body cleanup-forms@dots{}
+@defspec unwind-protect body-form cleanup-forms@dots{}
 @cindex cleanup forms
 @cindex protected forms
 @cindex error cleanup
 @cindex unwinding
-@code{unwind-protect} executes the @var{body} with a guarantee that the
-@var{cleanup-forms} will be evaluated if control leaves @var{body}, no
-matter how that happens.  The @var{body} may complete normally, or
-execute a @code{throw} out of the @code{unwind-protect}, or cause an
-error; in all cases, the @var{cleanup-forms} will be evaluated.
+@code{unwind-protect} executes @var{body-form} with a guarantee that
+the @var{cleanup-forms} will be evaluated if control leaves
+@var{body-form}, no matter how that happens.  @var{body-form} may
+complete normally, or execute a @code{throw} out of the
+@code{unwind-protect}, or cause an error; in all cases, the
+@var{cleanup-forms} will be evaluated.
 
-If the @var{body} forms finish normally, @code{unwind-protect} returns
-the value of the last @var{body} form, after it evaluates the
-@var{cleanup-forms}.  If the @var{body} forms do not finish,
-@code{unwind-protect} does not return any value in the normal sense.
+If @var{body-form} finishes normally, @code{unwind-protect} returns the
+value of @var{body-form}, after it evaluates the @var{cleanup-forms}.
+If @var{body-form} does not finish, @code{unwind-protect} does not
+return any value in the normal sense.
 
-Only the @var{body} is protected by the @code{unwind-protect}.  If any
+Only @var{body-form} is protected by the @code{unwind-protect}.  If any
 of the @var{cleanup-forms} themselves exits nonlocally (via a
 @code{throw} or an error), @code{unwind-protect} is @emph{not}
 guaranteed to evaluate the rest of them.  If the failure of one of the
-@var{cleanup-forms} has the potential to cause trouble, then protect it
-with another @code{unwind-protect} around that form.
+@var{cleanup-forms} has the potential to cause trouble, then protect
+it with another @code{unwind-protect} around that form.
 
 The number of currently active @code{unwind-protect} forms counts,
 together with the number of local variable bindings, against the limit
-@code{max-specpdl-size} (@pxref{Local Variables}).
+@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local
+Variables}).
 @end defspec
 
   For example, here we make an invisible buffer for temporary use, and
@@ -1195,7 +1208,7 @@
   (let ((buffer (get-buffer-create " *temp*")))
     (set-buffer buffer)
     (unwind-protect
-        @var{body}
+        @var{body-form}
       (kill-buffer buffer))))
 @end group
 @end smallexample
@@ -1203,15 +1216,16 @@
 @noindent
 You might think that we could just as well write @code{(kill-buffer
 (current-buffer))} and dispense with the variable @code{buffer}.
-However, the way shown above is safer, if @var{body} happens to get an
-error after switching to a different buffer!  (Alternatively, you could
-write another @code{save-excursion} around the body, to ensure that the
-temporary buffer becomes current again in time to kill it.)
+However, the way shown above is safer, if @var{body-form} happens to
+get an error after switching to a different buffer!  (Alternatively,
+you could write another @code{save-excursion} around @var{body-form},
+to ensure that the temporary buffer becomes current again in time to
+kill it.)
 
   Emacs includes a standard macro called @code{with-temp-buffer} which
-expands into more or less the code shown above (@pxref{Current Buffer}).
-Several of the macros defined in this manual use @code{unwind-protect}
-in this way.
+expands into more or less the code shown above (@pxref{Definition of
+with-temp-buffer,, Current Buffer}).  Several of the macros defined in
+this manual use @code{unwind-protect} in this way.
 
 @findex ftp-login
   Here is an actual example derived from an FTP package.  It creates a
@@ -1240,3 +1254,7 @@
 @code{ftp-setup-buffer} returns but before the variable @code{process} is
 set, the process will not be killed.  There is no easy way to fix this bug,
 but at least it is very unlikely.
+
+@ignore
+   arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d
+@end ignore

--- a/lispref/customize.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/customize.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/customize
 @node Customization, Loading, Macros, Top
@@ -62,7 +62,7 @@
 in the customization buffer with the Info node name.
 
 @item (url-link @var{url})
-Link to a web page; @var{url} is a string which specifies the @sc{url}.
+Link to a web page; @var{url} is a string which specifies the @acronym{URL}.
 The link appears in the customization buffer as @var{url}.
 
 @item (emacs-commentary-link @var{library})
@@ -373,6 +373,7 @@
 * Composite Types::
 * Splicing into Lists::
 * Type Keywords::
+* Defining New Types::
 @end menu
 
 All customization types are implemented as widgets; see @ref{Top, ,
@@ -584,7 +585,7 @@
 
 @item color
 The value must be a valid color name, and you can do completion with
-@kbd{M-@key{TAB}}.  A sample is provided,
+@kbd{M-@key{TAB}}.  A sample is provided.
 @end table
 
 @node Composite Types
@@ -975,7 +976,8 @@
 @code{widget-backward}, it will display the string @var{motion-doc} in
 the echo area.  In addition, @var{motion-doc} is used as the mouse
 @code{help-echo} string and may actually be a function or form evaluated
-to yield a help string as for @code{help-echo} text properties.
+to yield a help string.  If it is a function, it is called with one
+argument, the widget.
 @c @xref{Text help-echo}.
 
 @item :match @var{function}
@@ -1054,3 +1056,77 @@
 @code{checkbox} associated with this item.
 @end ignore
 @end table
+
+@node Defining New Types
+@subsection Defining New Types
+
+In the previous sections we have described how to construct elaborate
+type specifications for @code{defcustom}.  In some cases you may want to
+give such a type specification a name.  The obvious case is when you are
+using the same type for many user options, rather than repeat the
+specification for each option, you can give the type specification a
+name once, and use that name each @code{defcustom}.  The other case is
+when a user option accept a recursive datastructure.  To make it
+possible for a datatype to refer to itself, it needs to have a name.
+
+Since custom types are implemented as widgets, the way to define a new
+customize type is to define a new widget.  We are not going to describe
+the widget interface here in details, see @ref{Top, , Introduction,
+widget, The Emacs Widget Library}, for that.  Instead we are going to
+demonstrate the minimal functionality needed for defining new customize
+types by a simple example.
+
+@example
+(define-widget 'binary-tree-of-string 'lazy
+  "A binary tree made of cons-cells and strings."
+  :offset 4
+  :tag "Node"
+  :type '(choice (string :tag "Leaf" :value "")
+                 (cons :tag "Interior"
+                       :value ("" . "")
+                       binary-tree-of-string
+                       binary-tree-of-string)))
+
+(defcustom foo-bar ""
+  "Sample variable holding a binary tree of strings."
+  :type 'binary-tree-of-string)
+@end example
+
+The function to define a new widget is name @code{define-widget}.  The
+first argument is the symbol we want to make a new widget type.  The
+second argument is a symbol representing an existing widget, the new
+widget is going to be defined in terms of difference from the existing
+widget.  For the purpose of defining new customization types, the
+@code{lazy} widget is perfect, because it accept a @code{:type} keyword
+argument with the same syntax as the keyword argument to
+@code{defcustom} with the same name.  The third argument is a
+documentation string for the new widget.  You will be able to see that
+string with the @kbd{M-x widget-browse @key{ret} binary-tree-of-string
+@key{ret}} command.
+
+After these mandatory arguments follows the keyword arguments.  The most
+important is @code{:type}, which describes the datatype we want to match
+with this widget.  Here a @code{binary-tree-of-string} is described as
+being either a string, or a cons-cell whose car and cdr are themselves
+both @code{binary-tree-of-string}.  Note the reference to the widget
+type we are currently in the process of defining.  The @code{:tag}
+attribute is a string to name the widget in the user interface, and the
+@code{:offset} argument are there to ensure that child nodes are
+indented four spaces relatively to the parent node, making the tree
+structure apparent in the customization buffer.
+
+The @code{defcustom} shows how the new widget can be used as an ordinary
+customization type.
+
+If you wonder about the name @code{lazy}, know that the other composite
+widgets convert their inferior widgets to internal form when the widget
+is instantiated in a buffer.  This conversion is recursive, so the
+inferior widgets will convert @emph{their} inferior widgets.  If the
+datastructure is itself recursive, this conversion will go on forever,
+or at least until Emacs run out of stack space.  The @code{lazy} widget
+stop this recursion, it will only convert its @code{:type} argument when
+needed.
+
+@ignore
+   arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2
+@end ignore

--- a/lispref/debugging.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/debugging.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -30,6 +30,7 @@
 * Debugger::            How the Emacs Lisp debugger is implemented.
 * Edebug::		A source-level Emacs Lisp debugger.
 * Syntax Errors::       How to find syntax errors.
+* Test Coverage::       Ensuring you have tested all branches in your code.
 * Compilation Errors::  How to find errors that show up in byte compilation.
 @end menu
 
@@ -215,10 +216,10 @@
 up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
 @code{debug-on-entry} always returns @var{function-name}.
 
-@strong{Note:} if you redefine a function after using
-@code{debug-on-entry} on it, the code to enter the debugger is discarded
-by the redefinition.  In effect, redefining the function cancels
-the break-on-entry feature for that function.
+@strong{Warning:} if you redefine a function after using
+@code{debug-on-entry} on it, the code to enter the debugger is
+discarded by the redefinition.  In effect, redefining the function
+cancels the break-on-entry feature for that function.
 
 @example
 @group
@@ -550,7 +551,7 @@
                          (1+ var)
                          (list 'testing (backtrace))))))))
 
-     @result{} nil
+     @result{} (testing nil)
 @end group
 
 @group
@@ -738,6 +739,42 @@
 and you have put back those parentheses, @kbd{C-M-q} should not change
 anything.
 
+@node Test Coverage
+@section Test Coverage
+@cindex coverage testing
+
+@findex testcover-start
+@findex testcover-mark-all
+@findex testcover-next-mark
+  You can do coverage testing for a file of Lisp code by first using
+the command @kbd{M-x testcover-start @key{RET} @var{file} @key{RET}}
+to instrument it.  Then test your code by calling it one or more
+times.  Then use the command @kbd{M-x testcover-mark-all} to display
+``splotches'' on the code to show where coverage is insufficient.  The
+command @kbd{M-x testcover-next-mark} will move point forward to the
+next spot that has a splotch.
+
+  Normally, a red splotch indicates the form was never completely
+evaluated; a brown splotch means it always evaluated to the same value
+(meaning there has been little testing of what is done with the
+result).  However, the red splotch is skipped for forms that can't
+possibly complete their evaluation, such as @code{error}.  The brown
+splotch is skipped for forms that are expected to always evaluate to
+the same value, such as @code{(setq x 14)}.
+
+  For difficult cases, you can add do-nothing macros to your code to
+give advice to the test coverage tool.
+
+@defmac 1value form
+Evaluate @var{form} and return its value, but inform coverage testing
+that @var{form}'s value should always be the same.
+@end defmac
+
+@defmac noreturn form
+Evaluate @var{form}, informing coverage testing that @var{form} should
+never return.  If it ever does return, you get a run-time error.
+@end defmac
+
 @node Compilation Errors
 @section Debugging Problems in Compilation
 
@@ -762,3 +799,7 @@
 successfully, then point is located at the end of the form.  In this
 case, this technique can't localize the error precisely, but can still
 show you which function to check.
+
+@ignore
+   arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7
+@end ignore

--- a/lispref/display.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/display.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -15,20 +15,24 @@
 * Forcing Redisplay::   Forcing redisplay.
 * Truncation::          Folding or wrapping long text lines.
 * The Echo Area::       Where messages are displayed.
+* Warnings::            Displaying warning messages for the user.
 * Invisible Text::      Hiding part of the buffer text.
 * Selective Display::   Hiding part of the buffer text (the old way).
 * Overlay Arrow::       Display of an arrow to indicate position.
 * Temporary Displays::  Displays that go away automatically.
-* Overlays::		Use overlays to highlight parts of the buffer.
+* Overlays::            Use overlays to highlight parts of the buffer.
 * Width::               How wide a character or string is on the screen.
-* Faces::		A face defines a graphics style for text characters:
+* Faces::               A face defines a graphics style for text characters:
                           font, colors, etc.
+* Fringes::             Controlling window fringes.
+* Scroll Bars::         Controlling vertical scroll bars.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
+* Buttons::             Adding clickable buttons to Emacs buffers.
 * Blinking::            How Emacs shows the matching open parenthesis.
-* Inverse Video::	Specifying how the screen looks.
-* Usual Display::	The usual conventions for displaying nonprinting chars.
-* Display Tables::	How to specify other conventions.
+* Inverse Video::       Specifying how the screen looks.
+* Usual Display::       The usual conventions for displaying nonprinting chars.
+* Display Tables::      How to specify other conventions.
 * Beeping::             Audible signal to the user.
 * Window Systems::      Which window system is being used.
 @end menu
@@ -50,6 +54,17 @@
 This function clears and redisplays all visible frames.
 @end deffn
 
+  This function forces certain windows to be redisplayed
+but does not clear them.
+
+@defun force-window-update object
+This function forces redisplay of some or all windows.  If
+@var{object} is a window, it forces redisplay of that window.  If
+@var{object} is a buffer or buffer name, it forces redisplay of all
+windows displaying that buffer.  If @var{object} is @code{nil}, it
+forces redisplay of all windows.
+@end defun
+
   Processing user input takes absolute priority over redisplay.  If you
 call these functions when input is available, they do nothing
 immediately, but a full redisplay does happen eventually---after all the
@@ -111,10 +126,9 @@
 which is also called @dfn{continuing} the line.  (The display table can
 specify alternative indicators; see @ref{Display Tables}.)
 
-@cindex fringes, and line continuation/truncation indicators
   On a windowed display, the @samp{$} and @samp{\} indicators are
-replaced with graphics bitmaps displayed on the thin areas right near
-the window edges, called the @dfn{fringes}.
+replaced with graphics bitmaps displayed in the window fringes
+(@pxref{Fringes}).
 
   Note that continuation is different from filling; continuation happens
 on the screen only, not in the buffer contents, and it breaks a line
@@ -327,6 +341,195 @@
 If the value is zero, then command input is not echoed.
 @end defvar
 
+@node Warnings
+@section Reporting Warnings
+@cindex warnings
+
+  @dfn{Warnings} are a facility for a program to inform the user of a
+possible problem, but continue running.
+
+@menu
+* Warning Basics::      Warnings concepts and functions to report them.
+* Warning Variables::   Variables programs bind to customize their warnings.
+* Warning Options::     Variables users set to control display of warnings.
+@end menu
+
+@node Warning Basics
+@subsection Warning Basics
+@cindex severity level
+
+  Every warning has a textual message, which explains the problem for
+the user, and a @dfn{severity level} which is a symbol.  Here are the
+possible severity levels, in order of decreasing severity, and their
+meanings:
+
+@table @code
+@item :emergency
+A problem that will seriously impair Emacs operation soon
+if you do not attend to it promptly.
+@item :error
+A report of data or circumstances that are inherently wrong.
+@item :warning
+A report of data or circumstances that are not inherently wrong, but
+raise suspicion of a possible problem.
+@item :debug
+A report of information that may be useful if you are debugging.
+@end table
+
+  When your program encounters invalid input data, it can either
+signal a Lisp error by calling @code{error} or @code{signal} or report
+a warning with severity @code{:error}.  Signaling a Lisp error is the
+easiest thing to do, but it means the program cannot continue
+processing.  If you want to take the trouble to implement a way to
+continue processing despite the bad data, then reporting a warning of
+severity @code{:error} is the right way to inform the user of the
+problem.  For instance, the Emacs Lisp byte compiler can report an
+error that way and continue compiling other functions.  (If the
+program signals a Lisp error and then handles it with
+@code{condition-case}, the user won't see the error message; it could
+show the message to the user by reporting it as a warning.)
+
+@cindex warning type
+  Each warning has a @dfn{warning type} to classify it.  The type is a
+list of symbols.  The first symbol should be the custom group that you
+use for the program's user options.  For example, byte compiler
+warnings use the warning type @code{(bytecomp)}.  You can also
+subcategorize the warnings, if you wish, by using more symbols in the
+list.
+
+@defun display-warning type message &optional level buffer-name
+This function reports a warning, using @var{message} as the message
+and @var{type} as the warning type.  @var{level} should be the
+severity level, with @code{:warning} being the default.
+
+@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
+for logging the warning.  By default, it is @samp{*Warnings*}.
+@end defun
+
+@defun lwarn type level message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message.  In other respects it is
+equivalent to @code{display-warning}.
+@end defun
+
+@defun warn message &rest args
+This function reports a warning using the value of @code{(format
+@var{message} @var{args}...)} as the message, @code{(emacs)} as the
+type, and @code{:warning} as the severity level.  It exists for
+compatibility only; we recommend not using it, because you should
+specify a specific warning type.
+@end defun
+
+@node Warning Variables
+@subsection Warning Variables
+
+  Programs can customize how their warnings appear by binding
+the variables described in this section.
+
+@defvar warning-levels
+This list defines the meaning and severity order of the warning
+severity levels.  Each element defines one severity level,
+and they are arranged in order of decreasing severity.
+
+Each element has the form @code{(@var{level} @var{string}
+@var{function})}, where @var{level} is the severity level it defines.
+@var{string} specifies the textual description of this level.
+@var{string} should use @samp{%s} to specify where to put the warning
+type information, or it can omit the @samp{%s} so as not to include
+that information.
+
+The optional @var{function}, if non-@code{nil}, is a function to call
+with no arguments, to get the user's attention.
+
+Normally you should not change the value of this variable.
+@end defvar
+
+@defvar warning-prefix-function
+If non-@code{nil}, the value is a function to generate prefix text for
+warnings.  Programs can bind the variable to a suitable function.
+@code{display-warning} calls this function with the warnings buffer
+current, and the function can insert text in it.  That text becomes
+the beginning of the warning message.
+
+The function is called with two arguments, the severity level and its
+entry in @code{warning-levels}.  It should return a list to use as the
+entry (this value need not be an actual member of
+@code{warning-levels}).  By constructing this value, the function can
+change the severity of the warning, or specify different handling for
+a given severity level.
+
+If the variable's value is @code{nil} then there is no function
+to call.
+@end defvar
+
+@defvar warning-series
+Programs can bind this variable to @code{t} to say that the next
+warning should begin a series.  When several warnings form a series,
+that means to leave point on the first warning of the series, rather
+than keep moving it for each warning so that it appears on the last one.
+The series ends when the local binding is unbound and
+@code{warning-series} becomes @code{nil} again.
+
+The value can also be a symbol with a function definition.  That is
+equivalent to @code{t}, except that the next warning will also call
+the function with no arguments with the warnings buffer current.  The
+function can insert text which will serve as a header for the series
+of warnings.
+
+Once a series has begun, the value is a marker which points to the
+buffer position in the warnings buffer of the start of the series.
+
+The variable's normal value is @code{nil}, which means to handle
+each warning separately.
+@end defvar
+
+@defvar warning-fill-prefix
+When this variable is non-@code{nil}, it specifies a fill prefix to
+use for filling each warning's text.
+@end defvar
+
+@defvar warning-type-format
+This variable specifies the format for displaying the warning type
+in the warning message.  The result of formatting the type this way
+gets included in the message under the control of the string in the
+entry in @code{warning-levels}.  The default value is @code{" (%s)"}.
+If you bind it to @code{""} then the warning type won't appear at
+all.
+@end defvar
+
+@node Warning Options
+@subsection Warning Options
+
+  These variables are used by users to control what happens
+when a Lisp program reports a warning.
+
+@defopt warning-minimum-level
+This user option specifies the minimum severity level that should be
+shown immediately to the user.  The default is @code{:warning}, which
+means to immediately display all warnings except @code{:debug}
+warnings.
+@end defopt
+
+@defopt warning-minimum-log-level
+This user option specifies the minimum severity level that should be
+logged in the warnings buffer.  The default is @code{:warning}, which
+means to log all warnings except @code{:debug} warnings.
+@end defopt
+
+@defopt warning-suppress-types
+This list specifies which warning types should not be displayed
+immediately for the user.  Each element of the list should be a list
+of symbols.  If its elements match the first elements in a warning
+type, then that warning is not displayed immediately.
+@end defopt
+
+@defopt warning-suppress-log-types
+This list specifies which warning types should not be logged in the
+warnings buffer.  Each element of the list should be a list of
+symbols.  If it matches the first few elements in a warning type, then
+that warning is not logged.
+@end defopt
+
 @node Invisible Text
 @section Invisible Text
 
@@ -397,7 +600,7 @@
 @end defun
 
 @defun remove-from-invisibility-spec element
-This removeds the element @var{element} from
+This removes the element @var{element} from
 @code{buffer-invisibility-spec}.  This does nothing if @var{element}
 is not in the list.
 @end defun
@@ -423,12 +626,22 @@
 @end example
 
 @vindex line-move-ignore-invisible
-  Ordinarily, commands that operate on text or move point do not care
+  Ordinarily, functions that operate on text or move point do not care
 whether the text is invisible.  The user-level line motion commands
 explicitly ignore invisible newlines if
 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
 they are explicitly programmed to do so.
 
+  However, if a command ends with point inside or immediately after
+invisible text, the main editing loop moves point further forward or
+further backward (in the same direction that the command already moved
+it) until that condition is no longer true.  Thus, if the command
+moved point back into an invisible range, Emacs moves point back to
+the beginning of that range, following the previous visible character.
+If the command moved point forward into an invisible range, Emacs
+moves point forward past the first visible character that follows the
+invisible text.
+
   Incremental search can make invisible overlays visible temporarily
 and/or permanently when a match includes invisible text.  To enable
 this, the overlay should have a non-@code{nil}
@@ -572,7 +785,6 @@
 about to be executed.
 
 @defvar overlay-arrow-string
-@cindex fringe, and overlay arrow display
 This variable holds the string to display to call attention to a
 particular line, or @code{nil} if the arrow feature is not in use.
 On a graphical display the contents of the string are ignored; instead a
@@ -612,11 +824,13 @@
 created if necessary, and put into Help mode.  Finally, the buffer is
 displayed in some window, but not selected.
 
-If the @var{forms} do not change the major mode in the output buffer, so
-that it is still Help mode at the end of their execution, then
+If the @var{forms} do not change the major mode in the output buffer,
+so that it is still Help mode at the end of their execution, then
 @code{with-output-to-temp-buffer} makes this buffer read-only at the
-end, and also scans it for function and variable names to make them into
-clickable cross-references.
+end, and also scans it for function and variable names to make them
+into clickable cross-references.  @xref{Docstring hyperlinks, , Tips
+for Documentation Strings}, in particular the item on hyperlinks in
+documentation strings, for more details.
 
 The string @var{buffer-name} specifies the temporary buffer, which
 need not already exist.  The argument must be a string, not a buffer.
@@ -752,8 +966,14 @@
 beginning and end.  It also has properties that you can examine and set;
 these affect the display of the text within the overlay.
 
+An overlays uses markers to record its beginning and end; thus,
+editing the text of the buffer adjusts the beginning and end of each
+overlay so that it stays with the text.  When you create the overlay,
+you can specify whether text inserted at the beginning should be
+inside the overlay or outside, and likewise for the end of the overlay.
+
 @menu
-* Overlay Properties::	How to read and set properties.
+* Overlay Properties::  How to read and set properties.
 			What properties do to the screen display.
 * Managing Overlays::   Creating and moving overlays.
 * Finding Overlays::    Searching for overlays.
@@ -789,6 +1009,10 @@
 @var{overlay} to @var{value}.  It returns @var{value}.
 @end defun
 
+@defun overlay-properties overlay
+This returns a copy of the property list of @var{overlay}.
+@end defun
+
   See also the function @code{get-char-property} which checks both
 overlay properties and text properties for a given character.
 @xref{Examining Properties}.
@@ -799,12 +1023,14 @@
 @table @code
 @item priority
 @kindex priority @r{(overlay property)}
-This property's value (which should be a nonnegative number) determines
-the priority of the overlay.  The priority matters when two or more
-overlays cover the same character and both specify a face for display;
-the one whose @code{priority} value is larger takes priority over the
-other, and its face attributes override the face attributes of the lower
-priority overlay.
+This property's value (which should be a nonnegative integer number)
+determines the priority of the overlay.  The priority matters when two
+or more overlays cover the same character and both specify the same
+property; the one whose @code{priority} value is larger takes priority
+over the other.  For the @code{face} property, the higher priority
+value does not completely replace the other; instead, its face
+attributes override the face attributes of the lower priority
+@code{face} property.
 
 Currently, all overlays take priority over text properties.  Please
 avoid using negative priority values, as we have not yet decided just
@@ -938,7 +1164,9 @@
 @item evaporate
 @kindex evaporate @r{(overlay property)}
 If this property is non-@code{nil}, the overlay is deleted automatically
-if it ever becomes empty (i.e., if it spans no characters).
+if it becomes empty (i.e., if its length becomes zero).  However,
+if the overlay is @emph{already} empty, @code{evaporate} does not
+delete it.
 
 @item local-map
 @cindex keymap of character (and overlays)
@@ -960,6 +1188,10 @@
   This section describes the functions to create, delete and move
 overlays, and to examine their contents.
 
+@defun overlayp object
+This function returns @code{t} if @var{object} is an overlay.
+@end defun
+
 @defun make-overlay start end &optional buffer front-advance rear-advance
 This function creates and returns an overlay that belongs to
 @var{buffer} and ranges from @var{start} to @var{end}.  Both @var{start}
@@ -969,7 +1201,11 @@
 
 The arguments @var{front-advance} and @var{rear-advance} specify the
 insertion type for the start of the overlay and for the end of the
-overlay, respectively.  @xref{Marker Insertion Types}.
+overlay, respectively.  @xref{Marker Insertion Types}.  If
+@var{front-advance} is non-@code{nil}, text inserted at the beginning
+of the overlay is excluded from the overlay.  If @var{read-advance} is
+non-@code{nil}, text inserted at the beginning of the overlay is
+included in the overlay.
 @end defun
 
 @defun overlay-start overlay
@@ -1199,10 +1435,10 @@
 * Standard Faces::      The faces Emacs normally comes with.
 * Defining Faces::      How to define a face with @code{defface}.
 * Face Attributes::     What is in a face?
-* Attribute Functions:: Functions to examine and set face attributes.
-* Merging Faces::	How Emacs combines the faces specified for a character.
+* Attribute Functions::  Functions to examine and set face attributes.
+* Merging Faces::       How Emacs combines the faces specified for a character.
 * Font Selection::      Finding the best available font for a face.
-* Face Functions::	How to define and examine faces.
+* Face Functions::      How to define and examine faces.
 * Auto Faces::          Hook for automatic face assignment.
 * Font Lookup::         Looking up the names of available fonts
                           and information about them.
@@ -1387,6 +1623,10 @@
 @item background
 The kind of background---either @code{light} or @code{dark}.
 
+@item min-colors
+An integer that represents the minimum number of colors the frame should
+support, it is compared with the result of @code{display-color-cells}.
+
 @item supports
 Whether or not the frame can display the face attributes given in
 @var{value}@dots{} (@pxref{Face Attributes}).  See the documentation
@@ -1408,17 +1648,20 @@
 
 @example
 @group
-(defface region
-  `((((type tty) (class color))
-     (:background "blue" :foreground "white"))
+  '((((class color) (min-colors 88) (background dark))
+     :background "blue3")
 @end group
+    (((class color) (min-colors 88) (background light))
+     :background "lightgoldenrod2")
+    (((class color) (min-colors 16) (background dark))
+     :background "blue3")
+    (((class color) (min-colors 16) (background light))
+     :background "lightgoldenrod2")
+    (((class color) (min-colors 8))
+     :background "blue" :foreground "white")
     (((type tty) (class mono))
-     (:inverse-video t))
-    (((class color) (background dark))
-     (:background "blue"))
-    (((class color) (background light))
-     (:background "lightblue"))
-    (t (:background "gray")))
+     :inverse-video t)
+    (t :background "gray"))
 @group
   "Basic face for highlighting the region."
   :group 'basic-faces)
@@ -1697,7 +1940,7 @@
 
 @tindex face-attribute-relative-p
 @defun face-attribute-relative-p attribute value
-This function returns non-@code{nil} if @var{value}, when used as a
+This function returns non-@code{nil} if @var{value}, when used as
 the value of the face attribute @var{attribute}, is relative (that is,
 if it modifies an underlying or inherited value of @var{attribute}).
 @end defun
@@ -1779,8 +2022,8 @@
 These functions return the foreground color (or background color,
 respectively) of face @var{face}, as a string.
 
-If @var{inherit} is nil, only a color directly defined by the face is
-returned.  If @var{inherit} is non-nil, any faces specified by its
+If @var{inherit} is @code{nil}, only a color directly defined by the face is
+returned.  If @var{inherit} is non-@code{nil}, any faces specified by its
 @code{:inherit} attribute are considered as well, and if @var{inherit}
 is a face or a list of faces, then they are also considered, until a
 specified color is found.  To ensure that the return value is always
@@ -1883,28 +2126,6 @@
 font choice, but not all.  Part of the choice depends on what character
 it is.
 
-  For multibyte characters, typically each font covers only one
-character set.  So each character set (@pxref{Character Sets}) specifies
-a registry and encoding to use, with the character set's
-@code{x-charset-registry} property.  Its value is a string containing
-the registry and the encoding, with a dash between them:
-
-@example
-(plist-get (charset-plist 'latin-iso8859-1)
-           'x-charset-registry)
-     @result{} "ISO8859-1"
-@end example
-
-  Unibyte text does not have character sets, so displaying a unibyte
-character takes the registry and encoding from the variable
-@code{face-default-registry}.
-
-@defvar face-default-registry
-This variable specifies which registry and encoding to use in choosing
-fonts for unibyte characters.  The value is initialized at Emacs startup
-time from the font the user specified for Emacs.
-@end defvar
-
   If the face specifies a fontset name, that fontset determines a
 pattern for fonts of the given charset.  If the face specifies a font
 family, a font pattern is constructed.
@@ -2242,7 +2463,7 @@
   For the remaining character sets, those that you don't specify
 explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
 @samp{fontset-@var{alias}} with a value that names one character set.
-For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced
+For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
 with @samp{ISO8859-1}.
 
   In addition, when several consecutive fields are wildcards, Emacs
@@ -2258,7 +2479,7 @@
 @end example
 
 @noindent
-the font specification for @sc{ascii} characters would be this:
+the font specification for @acronym{ASCII} characters would be this:
 
 @example
 -*-fixed-medium-r-normal-*-24-*-ISO8859-1
@@ -2287,6 +2508,143 @@
 Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
 field.
 
+@defun set-fontset-font name character fontname &optional frame
+This function modifies the existing fontset @var{name} to
+use the font name @var{fontname} for the character @var{character}.
+
+If @var{name} is @code{nil}, this function modifies the default
+fontset, whose short name is @samp{fontset-default}.
+
+@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
+@var{from} and @var{to} are non-generic characters.  In that case, use
+@var{fontname} for all characters in the range @var{from} and @var{to}
+(inclusive).
+
+@var{character} may be a charset.  In that case, use
+@var{fontname} for all character in the charsets.
+
+@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+where @var{family} is a family name of a font (possibly including a
+foundry name at the head), @var{registry} is a registry name of a font
+(possibly including an encoding name at the tail).
+
+For instance, this changes the default fontset to use a font of which
+registry name is @samp{JISX0208.1983} for all characters belonging to
+the charset @code{japanese-jisx0208}.
+
+@example
+(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
+@end example
+
+@end defun
+
+@defun char-displayable-p char
+This function returns @code{t} if Emacs ought to be able to display
+@var{char}.  More precisely, if the selected frame's fontset has a
+font to display the character set that @var{char} belongs to.
+
+Fontsets can specify a font on a per-character basis; when the fontset
+does that, this function's value may not be accurate.
+@end defun
+
+@node Fringes
+@section Fringes
+@cindex Fringes
+
+  The @dfn{fringes} of a window are thin vertical strips down the
+sides that are used for displaying bitmaps that indicate truncation,
+continuation, horizontal scrolling, and the overlay arrow.  The
+fringes normally appear between the display margins and the window
+text, but you can put them outside the display margins for a specific
+buffer by setting @code{fringes-outside-margins} buffer-locally to a
+non-@code{nil} value.
+
+@defvar fringes-outside-margins
+If the value is non-@code{nil}, the frames appear outside
+the display margins. 
+@end defvar
+
+@defvar left-fringe-width
+This variable, if non-@code{nil}, specifies the width of the left
+fringe in pixels.
+@end defvar
+
+@defvar right-fringe-width
+This variable, if non-@code{nil}, specifies the width of the right
+fringe in pixels.
+@end defvar
+
+  The values of these variables take effect when you display the
+buffer in a window.  If you change them while the buffer is visible,
+you can call @code{set-window-buffer} to display it once again in the
+same window, to make the changes take effect.
+
+@defun set-window-fringes window left &optional right outside-margins
+This function sets the fringe widths of window @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
+
+The argument @var{left} specifies the width in pixels of the left
+fringe, and likewise @var{right} for the right fringe.  A value of
+@code{nil} for either one stands for the default width.  If
+@var{outside-margins} is non-@code{nil}, that specifies that fringes
+should appear outside of the display margins.
+@end defun
+
+@defun window-fringes &optional window
+This function returns information about the fringes of a window
+@var{window}.  If @var{window} is omitted or @code{nil}, the selected
+window is used.  The value has the form @code{(@var{left-width}
+@var{right-width} @var{frames-outside-margins})}.
+@end defun
+
+@node Scroll Bars
+@section Scroll Bars
+
+Normally the frame parameter @code{vertical-scroll-bars} controls
+whether the windows in the frame have vertical scroll bars.  A
+non-@code{nil} parameter value means they do.  The frame parameter
+@code{scroll-bar-width} specifies how wide they are (@code{nil}
+meaning the default).  @xref{Window Frame Parameters}.
+
+You can also control this for individual windows.  Call the function
+@code{set-window-scroll-bars} to specify what to do for a specific window:
+
+@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
+Set width and type of scroll bars of window @var{window}.  
+If @var{window} is @code{nil}, the selected window is used.
+@var{width} specifies the scroll bar width in pixels (@code{nil} means
+use whatever is specified for width for the frame).
+@var{vertical-type} specifies whether to have a vertical scroll bar
+and, if so, where.  The possible values are @code{left}, @code{right}
+and @code{nil}, just like the values of the
+@code{vertical-scroll-bars} frame parameter.
+
+The argument @var{horizontal-type} is meant to specify whether and
+where to have horizontal scroll bars, but since they are not
+implemented, it has no effect.
+@end defun
+
+@defun window-scroll-bars &optional window
+Report the width and type of scroll bars specified for @var{window}.
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a list of the form @code{(@var{width}
+@var{cols} @var{vertical-type} @var{horizontal-type})}.  The value
+@var{width} is the value that was specified for the width (which may
+be @code{nil}); @var{cols} is the number of columns that the scroll
+bar actually occupies.
+
+@var{horizontal-type} is not actually meaningful.
+@end defun
+
+If you don't specify these values for a window with
+@code{set-window-scroll-bars}, the buffer-local variables
+@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
+displayed control the window's vertical scroll bars.  The function
+@code{set-window-buffer} examines these variables.  If you change them
+in a buffer that is already visible in a window, you can make the
+window take note of the new values by calling @code{set-window-buffer}
+specifying the same buffer that is already displayed.
+
 @node Display Property
 @section The @code{display} Property
 @cindex display specification
@@ -2301,12 +2659,12 @@
 they mean.
 
 @menu
-* Specified Space::     Displaying one space with a specified width.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
+* Specified Space::      Displaying one space with a specified width.
+* Other Display Specs::  Displaying an image; magnifying text; moving it
                           up or down on the page; adjusting the width
                           of spaces within text.
 * Display Margins::     Displaying text or images to the side of the main text.
-* Conditional Display:: Making any of the above features conditional
+* Conditional Display::  Making any of the above features conditional
                           depending on some Lisp expression.
 @end menu
 
@@ -2806,8 +3164,8 @@
 @item :index @var{index}
 You can use @code{:index} to specify one image from a GIF file that
 contains more than one image.  This property specifies use of image
-number @var{index} from the file.  An error is signaled if the GIF file
-doesn't contain an image with index @var{index}.
+number @var{index} from the file.  If the GIF file doesn't contain an
+image with index @var{index}, the image displays as a hollow box.
 @end table
 
 @ignore
@@ -3063,6 +3421,348 @@
 are cleared.
 @end defun
 
+@node Buttons
+@section Buttons
+@cindex buttons
+@cindex buttons in buffers
+@cindex clickable buttons in buffers
+
+  The @emph{button} package defines functions for inserting and
+manipulating clickable (with the mouse, or via keyboard commands)
+buttons in Emacs buffers, such as might be used for help hyper-links,
+etc.  Emacs uses buttons for the hyper-links in help text and the like.
+
+A button is essentially a set of properties attached (via text
+properties or overlays) to a region of text in an emacs buffer, which
+are called its button properties.  @xref{Button Properties}.
+
+One of the these properties (@code{action}) is a function, which will
+be called when the user invokes it using the keyboard or the mouse.
+The invoked function may then examine the button and use its other
+properties as desired.
+
+In some ways the emacs button package duplicates functionality offered
+by the widget package (@pxref{Top, , Introduction, widget, The Emacs
+Widget Library}), but the button package has the advantage that it is
+much faster, much smaller, and much simpler to use (for elisp
+programmers---for users, the result is about the same).  The extra
+speed and space savings are useful mainly if you need to create many
+buttons in a buffer (for instance an @code{*Apropos*} buffer uses
+buttons to make entries clickable, and may contain many thousands of
+entries).
+
+@menu
+* Button Properties::      Button properties with special meanings.
+* Button Types::           Defining common properties for classes of buttons.
+* Making Buttons::         Adding buttons to emacs buffers.
+* Manipulating Buttons::   Getting and setting properties of buttons.
+* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
+* Manipulating Button Types:: 
+@end menu
+
+@node Button Properties
+@subsection Button Properties
+@cindex button properties
+
+  Buttons have an associated list of properties defining their
+appearance and behavior, and other arbitrary properties may be used
+for application specific purposes.
+
+Some properties that have special meaning to the button package
+include:
+
+@table @code
+
+@item action
+@kindex action @r{(button property)}
+The function to call when the user invokes the button, which is passed
+the single argument @var{button}.  By default this is @code{ignore},
+which does nothing.
+
+@item mouse-action
+@kindex mouse-action @r{(button property)}
+This is similar to @code{action}, and when present, will be used
+instead of @code{action} for button invocations resulting from
+mouse-clicks (instead of the user hitting @key{RET}).  If not
+present, mouse-clicks use @code{action} instead.
+
+@item face
+@kindex face @r{(button property)}
+This is an emacs face controlling how buttons of this type are
+displayed; by default this is the @code{button} face.
+
+@item mouse-face
+@kindex mouse-face @r{(button property)}
+This is an additional face which controls appearance during
+mouse-overs (merged with the usual button face); by default this is
+the usual emacs @code{highlight} face.
+
+@item keymap
+@kindex keymap @r{(button property)}
+The button's keymap, defining bindings active within the button
+region.  By default this is the usual button region keymap, stored
+in the variable @code{button-map}, which defines @key{RET} and
+@key{mouse-2} to invoke the button.
+
+@item type
+@kindex type @r{(button property)}
+The button-type of the button.  When creating a button, this is
+usually specified using the @code{:type} keyword argument.
+@xref{Button Types}.
+
+@item help-echo
+@kindex help-index @r{(button property)}
+A string displayed by the emacs tool-tip help system; by default,
+@code{"mouse-2, RET: Push this button"}.
+
+@item button
+@kindex button @r{(button property)}
+All buttons have a non-@code{nil} @code{button} property, which may be useful
+in finding regions of text that comprise buttons (which is what the
+standard button functions do).
+@end table
+
+There are other properties defined for the regions of text in a
+button, but these are not generally interesting for typical uses.
+
+@node Button Types
+@subsection Button Types
+@cindex button types
+
+  Every button has a button @emph{type}, which defines default values
+for the button's properties.  Button types are arranged in a
+hierarchy, with specialized types inheriting from more general types,
+so that it's easy to define special-purpose types of buttons for
+specific tasks.
+
+@defun define-button-type name &rest properties
+@tindex define-button-type
+Define a `button type' called @var{name}.  The remaining arguments
+form a sequence of @var{property value} pairs, specifying default
+property values for buttons with this type (a button's type may be set
+by giving it a @code{type} property when creating the button, using
+the @code{:type} keyword argument).
+
+In addition, the keyword argument @code{:supertype} may be used to
+specify a button-type from which @var{name} inherits its default
+property values.  Note that this inheritance happens only when
+@var{name} is defined; subsequent changes to a supertype are not
+reflected in its subtypes.
+@end defun
+
+Using @code{define-button-type} to define default properties for
+buttons is not necessary---buttons without any specified type use the
+built-in button-type @code{button}---but it is is encouraged, since
+doing so usually makes the resulting code clearer and more efficient.
+
+@node Making Buttons
+@subsection Making Buttons
+@cindex making buttons
+
+  Buttons are associated with a region of text, using an overlay or
+text-properties to hold button-specific information, all of which are
+initialized from the button's type (which defaults to the built-in
+button type @code{button}).  Like all emacs text, the appearance of
+the button is governed by the @code{face} property; by default (via
+the @code{face} property inherited from the @code{button} button-type)
+this is a simple underline, like a typical web-page link.
+
+For convenience, there are two sorts of button-creation functions,
+those that add button properties to an existing region of a buffer,
+called @code{make-...button}, and those also insert the button text,
+called @code{insert-...button}.
+
+The button-creation functions all take the @code{&rest} argument
+@var{properties}, which should be a sequence of @var{property value}
+pairs, specifying properties to add to the button; see @ref{Button
+Properties}.  In addition, the keyword argument @code{:type} may be
+used to specify a button-type from which to inherit other properties;
+see @ref{Button Types}.  Any properties not explicitly specified
+during creation will be inherited from the button's type (if the type
+defines such a property).
+
+The following functions add a button using an overlay
+(@pxref{Overlays}) to hold the button properties:
+
+@defun make-button beg end &rest properties
+@tindex make-button
+Make a button from @var{beg} to @var{end} in the current buffer.
+@end defun
+
+@defun insert-button label &rest properties
+@tindex insert-button
+Insert a button with the label @var{label}.
+@end defun
+
+The following functions are similar, but use emacs text-properties
+(@pxref{Text Properties}) to hold the button properties, making the
+button actually part of the text instead of being a property of the
+buffer (using text-properties is usually faster than using overlays,
+so this may be preferable when creating large numbers of buttons):
+
+@defun make-text-button beg end &rest properties
+@tindex make-text-button
+Make a button from @var{beg} to @var{end} in the current buffer, using
+text-properties.
+@end defun
+
+@defun insert-text-button label &rest properties
+@tindex insert-text-button
+Insert a button with the label @var{label}, using text-properties.
+@end defun
+
+Buttons using text-properties retain no markers into the buffer are
+retained, which is important for speed in cases where there are
+extremely large numbers of buttons.
+
+@node Manipulating Buttons
+@subsection Manipulating Buttons
+@cindex manipulating buttons
+
+These are functions for getting and setting properties of buttons.
+Often these are used by a button's invocation function to determine
+what to do.
+
+Where a @var{button} parameter is specified, it means an object
+referring to a specific button, either an overlay (for overlay
+buttons), or a buffer-position or marker (for text property buttons).
+Such an object is passed as the first argument to a button's
+invocation function when it is invoked.
+
+@defun button-start button
+@tindex button-start
+Return the position at which @var{button} starts.
+@end defun
+
+@defun button-end button
+@tindex button-end
+Return the position at which @var{button} ends.
+@end defun
+
+@defun button-get button prop
+@tindex button-get
+Get the property of button @var{button} named @var{prop}.
+@end defun
+
+@defun button-put button prop val
+@tindex button-put
+Set @var{button}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-activate button &optional use-mouse-action
+@tindex button-activate
+Call @var{button}'s @code{action} property (i.e., invoke it).  If
+@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@end defun
+
+@defun button-label button
+@tindex button-label
+Return @var{button}'s text label.
+@end defun
+
+@defun button-type button
+@tindex button-type
+Return @var{button}'s button-type.
+@end defun
+
+@defun button-has-type-p button type
+@tindex button-has-type-p
+Return @code{t} if @var{button} has button-type @var{type}, or one of
+@var{type}'s subtypes.
+@end defun
+
+@defun button-at pos
+@tindex button-at
+Return the button at position @var{pos} in the current buffer, or @code{nil}.
+@end defun
+
+@node Button Buffer Commands
+@subsection Button Buffer Commands
+@cindex button buffer commands
+
+These are commands and functions for locating and operating on
+buttons in an emacs buffer.
+
+@code{push-button} is the command that a user uses to actually `push'
+a button, and is bound by default in the button itself to @key{RET}
+and to @key{mouse-2} using a region-specific keymap.  Commands
+that are useful outside the buttons itself, such as
+@code{forward-button} and @code{backward-button} are additionally
+available in the keymap stored in @code{button-buffer-map}; a mode
+which uses buttons may want to use @code{button-buffer-map} as a
+parent keymap for its keymap.
+
+@deffn Command push-button &optional pos use-mouse-action
+@tindex push-button
+Perform the action specified by a button at location @var{pos}.
+@var{pos} may be either a buffer position or a mouse-event.  If
+@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
+mouse-event (@pxref{Mouse Events}), try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@var{pos} defaults to point, except when @code{push-button} is invoked
+interactively as the result of a mouse-event, in which case, the mouse
+event's position is used.  If there's no button at @var{pos}, do
+nothing and return @code{nil}, otherwise return @code{t}.
+@end deffn
+
+@deffn Command forward-button n &optional wrap display-message
+@tindex forward-button
+Move to the @var{n}th next button, or @var{n}th previous button if
+@var{n} is negative.  If @var{n} is zero, move to the start of any
+button at point.  If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} @code{skip} property
+is skipped over.  Returns the button found.
+@end deffn
+
+@deffn Command backward-button n &optional wrap display-message
+@tindex backward-button
+Move to the @var{n}th previous button, or @var{n}th next button if
+@var{n} is negative.  If @var{n} is zero, move to the start of any
+button at point.  If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end.  If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed.  Any button with a non-@code{nil} @code{skip} property
+is skipped over.  Returns the button found.
+@end deffn
+
+@defun next-button pos &optional count-current
+@tindex next-button
+Return the next button after position @var{pos} in the current buffer.
+If @var{count-current} is non-@code{nil}, count any button at
+@var{pos} in the search, instead of starting at the next button.
+@end defun
+
+@defun previous-button pos &optional count-current
+@tindex previous-button
+Return the @var{n}th button before position @var{pos} in the current
+buffer.  If @var{count-current} is non-@code{nil}, count any button at
+@var{pos} in the search, instead of starting at the next button.
+@end defun
+
+@node Manipulating Button Types
+@subsection Manipulating Button Types
+@cindex manipulating button types
+
+@defun button-type-put type prop val
+@tindex button-type-put
+Set the button-type @var{type}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-type-get type prop
+@tindex button-type-get
+Get the property of button-type @var{type} named @var{prop}.
+@end defun
+
+@defun button-type-subtype-p type supertype
+@tindex button-type-subtype-p
+Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
+@end defun
+
 @node Blinking
 @section Blinking Parentheses
 @cindex parenthesis matching
@@ -3169,19 +3869,19 @@
 All other codes in the range 0 through 31, and code 127, display in one
 of two ways according to the value of @code{ctl-arrow}.  If it is
 non-@code{nil}, these codes map to sequences of two glyphs, where the
-first glyph is the @sc{ascii} code for @samp{^}.  (A display table can
+first glyph is the @acronym{ASCII} code for @samp{^}.  (A display table can
 specify a glyph to use instead of @samp{^}.)  Otherwise, these codes map
 just like the codes in the range 128 to 255.
 
 On MS-DOS terminals, Emacs arranges by default for the character code
 127 to be mapped to the glyph code 127, which normally displays as an
-empty polygon.  This glyph is used to display non-@sc{ascii} characters
+empty polygon.  This glyph is used to display non-@acronym{ASCII} characters
 that the MS-DOS terminal doesn't support.  @xref{MS-DOS and MULE,,,
 emacs, The GNU Emacs Manual}.
 
 @item
 Character codes 128 through 255 map to sequences of four glyphs, where
-the first glyph is the @sc{ascii} code for @samp{\}, and the others are
+the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
 digit characters representing the character code in octal.  (A display
 table can specify a glyph to use instead of @samp{\}.)
 
@@ -3225,9 +3925,9 @@
 @defopt indicate-empty-lines
 @tindex indicate-empty-lines
 @cindex fringes, and empty line indication
-When this is non-@code{nil}, Emacs displays a special glyph in
-each empty line at the end of the buffer, on terminals that
-support it (window systems).
+When this is non-@code{nil}, Emacs displays a special glyph in the
+fringe of each empty line at the end of the buffer, on terminals that
+support it (window systems).  @xref{Fringes}.
 @end defopt
 
 @defopt tab-width
@@ -3244,7 +3944,7 @@
 @cindex display table
 You can use the @dfn{display table} feature to control how all possible
 character codes display on the screen.  This is useful for displaying
-European languages that have letters not in the @sc{ascii} character
+European languages that have letters not in the @acronym{ASCII} character
 set.
 
 The display table maps each character code into a sequence of
@@ -3257,9 +3957,9 @@
 @code{force-mode-line-update} (@pxref{Mode Line Format}).
 
 @menu
-* Display Table Format::	What a display table consists of.
-* Active Display Table::	How Emacs selects a display table to use.
-* Glyphs::			How to define a glyph, and what glyphs mean.
+* Display Table Format::  What a display table consists of.
+* Active Display Table::  How Emacs selects a display table to use.
+* Glyphs::              How to define a glyph, and what glyphs mean.
 @end menu
 
 @node Display Table Format
@@ -3534,3 +4234,7 @@
 the window system, and creating the initial window.  Users should not
 interfere with it.
 @end defvar
+
+@ignore
+   arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6
+@end ignore

--- a/lispref/doclicense.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/doclicense.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -366,3 +366,7 @@
 recommend releasing these examples in parallel under your choice of
 free software license, such as the GNU General Public License,
 to permit their use in free software.
+
+@ignore
+   arch-tag: 9014cf6e-f3c4-401d-b8da-4fe52723984c
+@end ignore

--- a/lispref/edebug.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/edebug.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -124,7 +124,7 @@
 @example
 (defun fac (n)
   .(if .(< 0 n.).
-      .(* n. .(fac (1- n.).).).
+      .(* n. .(fac .(1- n.).).).
     1).)
 @end example
 
@@ -257,7 +257,8 @@
 @ref{Edebug Misc}.
 
 @item t
-Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).
+Trace: pause (normally one second) at each Edebug stop point
+(@code{edebug-trace-mode}).
 
 @item T
 Rapid trace: update the display at each stop point, but don't actually
@@ -307,6 +308,10 @@
 several times if, for example, an instrumented function is called
 several times from one command.
 
+@defopt edebug-sit-for-seconds
+This option specifies how many seconds to wait between execution steps
+in trace mode.  The default is 1 second.
+@end defopt
 
 @node Jumping
 @subsection Jumping
@@ -871,8 +876,12 @@
 execution mode is Go-nonstop, and regardless of whether coverage testing
 is enabled.
 
-  Use @kbd{M-x edebug-display-freq-count} to display both the
-coverage information and the frequency counts for a definition.
+@kindex C-x X =
+@findex edebug-temp-display-freq-count
+  Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
+the coverage information and the frequency counts for a definition.
+Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
+information temporarily, only until you type another key.
 
 @deffn Command edebug-display-freq-count
 This command displays the frequency count data for each line of the
@@ -1077,15 +1086,14 @@
   ...)
 @end example
 
-@defspec declare (edebug @var{specification})
-Specify which expressions of a call to the macro in which the
-declaration appears are forms to be evaluated.  For simple macros, the
-@var{specification} often looks very similar to the formal argument list
-of the macro definition, but specifications are much more general than
-macro arguments.
-@end defspec
+  The Edebug specification says which parts of a call to the macro are
+forms to be evaluated.  For simple macros, the @var{specification}
+often looks very similar to the formal argument list of the macro
+definition, but specifications are much more general than macro
+arguments.  @xref{Defining Macros}, for more explanation of
+the @code{declare} form.
 
-You can also define an edebug specification for a macro separately
+  You can also define an edebug specification for a macro separately
 from the macro definition with @code{def-edebug-spec}.  Adding
 @code{edebug} declarations is preferred, and more convenient, for
 macro definitions in Lisp, but @code{def-edebug-spec} makes it
@@ -1185,7 +1193,7 @@
 A lambda expression with no quoting.
 
 @item &optional
-@kindex &optional @r{(Edebug)}
+@c @kindex &optional @r{(Edebug)}
 All following elements in the specification list are optional; as soon
 as one does not match, Edebug stops matching at this level.
 
@@ -1195,7 +1203,7 @@
 [@var{specs}@dots{}]}.  See the @code{defun} example below.
 
 @item &rest
-@kindex &rest @r{(Edebug)}
+@c @kindex &rest @r{(Edebug)}
 All following elements in the specification list are repeated zero or
 more times.  In the last repetition, however, it is not a problem if the
 expression runs out before matching all of the elements of the
@@ -1206,7 +1214,7 @@
 @code{&rest [@var{specs}@dots{}]}.
 
 @item &or
-@kindex &or @r{(Edebug)}
+@c @kindex &or @r{(Edebug)}
 Each of the following elements in the specification list is an
 alternative.  One of the alternatives must match, or the @code{&or}
 specification fails.
@@ -1216,14 +1224,14 @@
 @code{[@dots{}]}.
 
 @item &not
-@kindex &not @r{(Edebug)}
+@c @kindex &not @r{(Edebug)}
 Each of the following elements is matched as alternatives as if by using
 @code{&or}, but if any of them match, the specification fails.  If none
 of them match, nothing is matched, but the @code{&not} specification
 succeeds.
 
 @item &define
-@kindex &define @r{(Edebug)}
+@c @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining
 form itself is not instrumented (that is, Edebug does not stop before and
 after the defining form), but forms inside it typically will be
@@ -1373,7 +1381,7 @@
 constraint by factoring the symbol out of the alternatives, e.g.,
 @code{["foo" &or [first case] [second case] ...]}.
 
-Most needs are satisfied by these two ways that bactracking is
+Most needs are satisfied by these two ways that backtracking is
 automatically disabled, but occasionally it is useful to explicitly
 disable backtracking by using the @code{gate} specification.  This is
 useful when you know that no higher alternatives could apply.  See the
@@ -1554,3 +1562,7 @@
 the result is non-@code{nil}, then break.  Errors are ignored.
 @xref{Global Break Condition}.
 @end defopt
+
+@ignore
+   arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd
+@end ignore

--- a/lispref/elisp-covers.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/elisp-covers.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -246,3 +246,7 @@
 
 @end titlepage
 @bye
+
+@ignore
+   arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98
+@end ignore

--- a/lispref/elisp.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/elisp.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -415,6 +415,7 @@
 * Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
+* Indenting Macros::        Specifying how to indent macro calls.
 
 Loading
 
@@ -534,6 +535,7 @@
 * Key Lookup::                  How extracting elements from keymaps works.
 * Functions for Key Lookup::    How to request key lookup.
 * Changing Key Bindings::       Redefining a key in a keymap.
+* Remapping Commands::          Bindings that translate one command to another.
 * Key Binding Commands::        Interactive interfaces for redefining keys.
 * Scanning Keymaps::            Looking through all keymaps, for printing help.
 
@@ -738,12 +740,16 @@
 * Transposition::           Swapping two portions of a buffer.
 * Registers::               How registers are implemented.  Accessing
                               the text or position stored in a register.
+* Atomic Changes::          Installing several buffer changes ``atomically''.
+* Base 64::                 Conversion to or from base 64 encoding.
+* MD5 Checksum::            Compute the MD5 ``message digest''/``checksum''.
 * Change Hooks::            Supplying functions to be run when text is changed.
 
 The Kill Ring
 
 * Kill Ring Concepts::      What text looks like in the kill ring.
 * Kill Functions::          Functions that kill text.
+* Yanking::                 How yanking is done.
 * Yank Commands::           Commands that access the kill ring.
 * Low-Level Kill Ring::	    Functions and variables for kill ring access.
 * Internals of Kill Ring::  Variables that hold kill-ring data.
@@ -852,6 +858,7 @@
 
 * Process Buffers::         If no filter, output is put in a buffer.
 * Filter Functions::        Filter functions accept output from the process.
+* Decoding Output::         Filters can get unibyte or multibyte strings.
 * Accepting Output::        How to wait until process output arrives.
 
 Operating System Interface
@@ -882,12 +889,21 @@
 * Refresh Screen::          Clearing the screen and redrawing everything on it.
 * Truncation::              Folding or wrapping long text lines.
 * The Echo Area::           Where messages are displayed.
+* Warnings::                Displaying warning messages for the user.
 * Selective Display::       Hiding part of the buffer text.
 * Overlay Arrow::           Display of an arrow to indicate position.
 * Temporary Displays::      Displays that go away automatically.
-* Waiting::                 Forcing display update and waiting for user.
+* Overlays::		    Use overlays to highlight parts of the buffer.
+* Width::                   How wide a character or string is on the screen.
+* Faces::		    A face defines a graphics style
+                              for text characters: font, colors, etc.
+* Fringes::                 Controlling window fringes.
+* Display Property::        Enabling special display features.
+* Images::                  Displaying images in Emacs buffers.
 * Blinking::                How Emacs shows the matching open parenthesis.
-* Usual Display::	    How control characters are displayed.
+* Inverse Video::	    Specifying how the screen looks.
+* Usual Display::	    The usual conventions for displaying nonprinting chars.
+* Display Tables::	    How to specify other conventions.
 * Beeping::                 Audible signal to the user.
 * Window Systems::          Which window system is being used.
 
@@ -988,3 +1004,7 @@
 
 
 These words prevent "local variables" above from confusing Emacs.
+
+@ignore
+   arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34
+@end ignore

--- a/lispref/errors.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/errors.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -62,6 +62,10 @@
 @code{"Symbol's chain of function indirections\@* contains a loop"}@*
 @xref{Function Indirection}.
 
+@item cyclic-variable-indirection
+@code{"Symbol's chain of variable indirections contains a loop"}@*
+@xref{Variable Aliases}.
+
 @item end-of-buffer
 @code{"End of buffer"}@*
 @xref{Motion}.
@@ -69,7 +73,7 @@
 @item end-of-file
 @code{"End of file during parsing"}@*
 Note that this is not a subcategory of @code{file-error},
-because it pertains to the Lisp reader, not to file I/O.
+because it pertains to the Lisp reader, not to file I/O.@*
 @xref{Input Functions}.
 
 @item file-already-exists
@@ -79,12 +83,16 @@
 @item file-date-error
 This is a subcategory of @code{file-error}.  It occurs when
 @code{copy-file} tries and fails to set the last-modification time of
-the output file.  @xref{Changing Files}.
+the output file.@*
+@xref{Changing Files}.
 
 @item file-error
-This error and its subcategories do not have error-strings, because the
-error message is constructed from the data items alone when the error
-condition @code{file-error} is present.@*
+We do not list the error-strings of this error and its subcategories,
+because the error message is normally constructed from the data items
+alone when the error condition @code{file-error} is present.  Thus,
+the error-strings are not very relevant.  However, these error symbols
+do have @code{error-message} properties, and if no data is provided,
+the @code{error-message} property @emph{is} used.@*
 @xref{Files}.
 
 @item file-locked
@@ -113,7 +121,7 @@
 @xref{Regular Expressions}.
 
 @item mark-inactive
-@code{"Mark inactive"}@*
+@code{"The mark is not active now"}@*
 @xref{The Mark}.
 
 @item no-catch
@@ -139,6 +147,7 @@
 
 @item text-read-only
 @code{"Text is read-only"}@*
+This is a subcategory of @code{buffer-read-only}.@*
 @xref{Special Properties}.
 
 @item undefined-color
@@ -173,6 +182,7 @@
 
 @item overflow-error
 @code{"Arithmetic overflow error"}@*
+This is a subcategory of @code{domain-error}.@*
 @xref{Math Functions}.
 
 @item range-error
@@ -181,9 +191,15 @@
 
 @item singularity-error
 @code{"Arithmetic singularity error"}@*
+This is a subcategory of @code{domain-error}.@*
 @xref{Math Functions}.
 
 @item underflow-error
 @code{"Arithmetic underflow error"}@*
+This is a subcategory of @code{domain-error}.@*
 @xref{Math Functions}.
 @end table
+
+@ignore
+   arch-tag: 717c6048-5d9d-4c7d-9a62-df57390b6f19
+@end ignore

--- a/lispref/eval.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/eval.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -313,12 +313,17 @@
 perform symbol function indirection explicitly.
 
 @c Emacs 19 feature
+@anchor{Definition of indirect-function}
 @defun indirect-function function
 This function returns the meaning of @var{function} as a function.  If
 @var{function} is a symbol, then it finds @var{function}'s function
 definition and starts over with that value.  If @var{function} is not a
 symbol, then it returns @var{function} itself.
 
+This function signals a @code{void-function} error if the final
+symbol is unbound and a @code{cyclic-function-indirection} error if
+there is a loop in the chain of symbols.
+
 Here is how you could define @code{indirect-function} in Lisp:
 
 @smallexample
@@ -588,11 +593,11 @@
 specify limits to the evaluation process, or record recently returned
 values.  Loading a file also does evaluation (@pxref{Loading}).
 
-  @strong{Note:} it is generally cleaner and more flexible to store a
-function in a data structure, and call it with @code{funcall} or
-@code{apply}, than to store an expression in the data structure and
-evaluate it.  Using functions provides the ability to pass information
-to them as arguments.
+  It is generally cleaner and more flexible to store a function in a
+data structure, and call it with @code{funcall} or @code{apply}, than
+to store an expression in the data structure and evaluate it.  Using
+functions provides the ability to pass information to them as
+arguments.
 
 @defun eval form
 This is the basic function evaluating an expression.  It evaluates
@@ -625,32 +630,51 @@
 @code{max-lisp-eval-depth} (see below).
 @end defun
 
+@anchor{Definition of eval-region}
 @deffn Command eval-region start end &optional stream read-function
 This function evaluates the forms in the current buffer in the region
 defined by the positions @var{start} and @var{end}.  It reads forms from
 the region and calls @code{eval} on them until the end of the region is
 reached, or until an error is signaled and not handled.
 
-If @var{stream} is non-@code{nil}, the values that result from
-evaluating the expressions in the region are printed using @var{stream}.
-@xref{Output Streams}.
+By default, @code{eval-region} does not produce any output.  However,
+if @var{stream} is non-@code{nil}, any output produced by output
+functions (@pxref{Output Functions}), as well as the values that
+result from evaluating the expressions in the region are printed using
+@var{stream}.  @xref{Output Streams}.
 
-If @var{read-function} is non-@code{nil}, it should be a function, which
-is used instead of @code{read} to read expressions one by one.  This
-function is called with one argument, the stream for reading input.  You
-can also use the variable @code{load-read-function} (@pxref{How Programs
-Do Loading}) to specify this function, but it is more robust to use the
+If @var{read-function} is non-@code{nil}, it should be a function,
+which is used instead of @code{read} to read expressions one by one.
+This function is called with one argument, the stream for reading
+input.  You can also use the variable @code{load-read-function}
+(@pxref{Definition of load-read-function,, How Programs Do Loading})
+to specify this function, but it is more robust to use the
 @var{read-function} argument.
 
-@code{eval-region} always returns @code{nil}.
+@code{eval-region} does not move point.  It always returns @code{nil}.
 @end deffn
 
 @cindex evaluation of buffer contents
-@deffn Command eval-current-buffer &optional stream
-This is like @code{eval-region} except that it operates on the whole
-buffer.
+@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
+This is similar to @code{eval-region}, but the arguments provide
+different optional features.  @code{eval-buffer} operates on the
+entire accessible portion of buffer @var{buffer-or-name}.
+@var{buffer-or-name} can be a buffer, a buffer name (a string), or
+@code{nil} (or omitted), which means to use the current buffer.
+@var{stream} is used as in @code{eval-region}, unless @var{stream} is
+@code{nil} and @var{print} non-@code{nil}.  In that case, values that
+result from evaluating the expressions are still discarded, but the
+output of the output functions is printed in the echo area.
+@var{filename} is the file name to use for @code{load-history}
+(@pxref{Unloading}), and defaults to @code{buffer-file-name}
+(@pxref{Buffer File Name}).  If @var{unibyte} is non-@code{nil},
+@code{read} converts strings to unibyte whenever possible.
+
+@findex eval-current-buffer
+@code{eval-current-buffer} is an alias for this command.
 @end deffn
 
+@anchor{Definition of max-lisp-eval-depth}
 @defvar max-lisp-eval-depth
 This variable defines the maximum depth allowed in calls to @code{eval},
 @code{apply}, and @code{funcall} before an error is signaled (with error
@@ -670,14 +694,17 @@
 left, to make sure the debugger itself has room to execute.
 
 @code{max-specpdl-size} provides another limit on nesting.
-@xref{Local Variables}.
+@xref{Definition of max-specpdl-size,, Local Variables}.
 @end defvar
 
 @defvar values
 The value of this variable is a list of the values returned by all the
 expressions that were read, evaluated, and printed from buffers
-(including the minibuffer) by the standard Emacs commands which do this.
-The elements are ordered most recent first.
+(including the minibuffer) by the standard Emacs commands which do
+this.  (Note that this does @emph{not} include evaluation in
+@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
+@code{lisp-interaction-mode}.)  The elements are ordered most recent
+first.
 
 @example
 @group
@@ -719,3 +746,7 @@
 @end group
 @end example
 @end defvar
+
+@ignore
+   arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
+@end ignore

--- a/lispref/files.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/files.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/files
@@ -95,11 +95,11 @@
 using an existing buffer if there is one, and otherwise creating a
 new buffer and reading the file into it.  It also returns that buffer.
 
-The body of the @code{find-file} function is very simple and looks
-like this:
+Aside from some technical details, the body of the @code{find-file}
+function is basically equivalent to:
 
 @example
-(switch-to-buffer (find-file-noselect filename))
+(switch-to-buffer (find-file-noselect filename nil nil wildcards))
 @end example
 
 @noindent
@@ -193,12 +193,14 @@
 @end deffn
 
 @tindex find-file-wildcards
-@defvar find-file-wildcards
+@defopt find-file-wildcards
 If this variable is non-@code{nil}, then the various @code{find-file}
 commands check for wildcard characters and visit all the files that
-match them.  If this is @code{nil}, then wildcard characters are
-not treated specially.
-@end defvar
+match them (when invoked interactively or when their @var{wildcards}
+argument is non-@code{nil}).  If this option is @code{nil}, then
+the @code{find-file} commands ignore their @var{wildcards} argument
+and never treat wildcard characters specially.
+@end defopt
 
 @defvar find-file-hook
 The value of this variable is a list of functions to be called after a
@@ -206,8 +208,7 @@
 have been processed before the hooks are run.  The buffer visiting the
 file is current when the hook functions are run.
 
-This variable works just like a normal hook, but we think that renaming
-it would not be advisable.  @xref{Hooks}.
+This variable is a normal hook.  @xref{Hooks}.
 @end defvar
 
 @defvar find-file-not-found-functions
@@ -322,16 +323,21 @@
 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
 @code{save-buffer} function unconditionally backs up the previous
 version of the file before saving it.
+
+@item
+With an argument of 0, unconditionally do @emph{not} make any backup file.
 @end itemize
 @end deffn
 
+@anchor{Definition of save-some-buffers}
 @deffn Command save-some-buffers &optional save-silently-p pred
 This command saves some modified file-visiting buffers.  Normally it
 asks the user about each buffer.  But if @var{save-silently-p} is
 non-@code{nil}, it saves all the file-visiting buffers without querying
 the user.
 
-The optional @var{pred} argument controls which buffers to ask about.
+The optional @var{pred} argument controls which buffers to ask about
+(or to save silently if @var{save-silently-p} is non-@code{nil}).
 If it is @code{nil}, that means to ask only about file-visiting buffers.
 If it is @code{t}, that means also offer to save certain other non-file
 buffers---those that have a non-@code{nil} buffer-local value of
@@ -346,6 +352,7 @@
 value in a certain buffer, that means do offer to save that buffer.
 @end deffn
 
+@anchor{Definition of write-file}
 @deffn Command write-file filename &optional confirm
 This function writes the current buffer into file @var{filename}, makes
 the buffer visit that file, and marks it not modified.  Then it renames
@@ -355,7 +362,13 @@
 @code{save-buffer}.
 
 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
-before overwriting an existing file.
+before overwriting an existing file.  Interactively, confirmation is
+required, unless the user supplies a prefix argument.
+
+If @var{filename} is an existing directory, or a symbolic link to one,
+@code{write-file} uses the name of the visited file, in directory
+@var{filename}.  If the buffer is not visiting a file, it uses the
+buffer name instead.
 @end deffn
 
   Saving a buffer runs several hooks.  It also performs format
@@ -378,8 +391,9 @@
 @end example
 
 You might wish to save the file modes value returned by
-@code{backup-buffer} and use that to set the mode bits of the file that
-you write.  This is what @code{save-buffer} normally does.
+@code{backup-buffer} and use that (if non-@code{nil}) to set the mode
+bits of the file that you write.  This is what @code{save-buffer}
+normally does. @xref{Making Backups,, Making Backup Files}.
 
 The hook functions in @code{write-file-functions} are also responsible for
 encoding the data (if desired): they must choose a suitable coding
@@ -404,20 +418,31 @@
 This works just like @code{write-file-functions}, but it is intended for
 hooks that pertain to the contents of the file, as opposed to hooks that
 pertain to where the file came from.  Such hooks are usually set up by
-major modes, as buffer-local bindings for this variable.
+major modes, as buffer-local bindings for this variable.  If any of the
+functions in this hook returns non-@code{nil}, @code{write-file-functions}
+is not run.
 
 This variable automatically becomes buffer-local whenever it is set;
-switching to a new major mode always resets this variable.
+switching to a new major mode always resets this variable, but
+calling @code{set-visited-file-name} does not.
 @end defvar
 
+@defopt before-save-hook
+This normal hook runs before a buffer is saved in its visited file,
+regardless of whether that is done normally or by one of the hooks
+described above.  For instance, the @file{copyright.el} program uses
+this hook to make sure the file you are saving has the current year in
+its copyright notice.
+@end defopt
+
 @c Emacs 19 feature
-@defvar after-save-hook
+@defopt after-save-hook
 This normal hook runs after a buffer has been saved in its visited file.
 One use of this hook is in Fast Lock mode; it uses this hook to save the
 highlighting information in a cache file.
-@end defvar
-
-@defvar file-precious-flag
+@end defopt
+
+@defopt file-precious-flag
 If this variable is non-@code{nil}, then @code{save-buffer} protects
 against I/O errors while saving by writing the new file to a temporary
 name instead of the name it is supposed to have, and then renaming it to
@@ -431,7 +456,7 @@
 
 Some modes give this variable a non-@code{nil} buffer-local value
 in particular buffers.
-@end defvar
+@end defopt
 
 @defopt require-final-newline
 This variable determines whether files may be written out that do
@@ -530,12 +555,22 @@
 
 An error is signaled if @var{filename} specifies a nonwritable file,
 or a nonexistent file in a directory where files cannot be created.
+
+When called from Lisp, this function is completely equivalent to:
+
+@example
+(write-region start end filename t)
+@end example
 @end deffn
 
 @deffn Command write-region start end filename &optional append visit lockname mustbenew
 This function writes the region delimited by @var{start} and @var{end}
 in the current buffer into the file specified by @var{filename}.
 
+If @var{start} is @code{nil}, then the command writes the entire buffer
+contents (@emph{not} just the accessible portion) to the file and
+ignores @var{end}.
+
 @c Emacs 19 feature
 If @var{start} is a string, then @code{write-region} writes or appends
 that string, rather than text from the buffer.  @var{end} is ignored in
@@ -590,6 +625,7 @@
 files that the user does not need to know about.
 @end deffn
 
+@anchor{Definition of with-temp-file}
 @defmac with-temp-file file body...
 The @code{with-temp-file} macro evaluates the @var{body} forms with a
 temporary buffer as the current buffer; then, at the end, it writes the
@@ -601,7 +637,8 @@
 The current buffer is restored even in case of an abnormal exit via
 @code{throw} or error (@pxref{Nonlocal Exits}).
 
-See also @code{with-temp-buffer} in @ref{Current Buffer}.
+See also @code{with-temp-buffer} in @ref{Definition of
+with-temp-buffer,, The Current Buffer}.
 @end defmac
 
 @node File Locks
@@ -714,7 +751,10 @@
 @cindex accessibility of a file
 @cindex file accessibility
 
-  These functions test for permission to access a file in specific ways.
+  These functions test for permission to access a file in specific
+ways.  Unless explicitly stated otherwise, they recursively follow
+symbolic links for their file name arguments, at all levels (at the
+level of the file itself and at all levels of parent directories).
 
 @defun file-exists-p filename
 This function returns @code{t} if a file named @var{filename} appears
@@ -818,7 +858,13 @@
 
 @defun file-ownership-preserved-p filename
 This function returns @code{t} if deleting the file @var{filename} and
-then creating it anew would keep the file's owner unchanged.
+then creating it anew would keep the file's owner unchanged.  It also
+returns @code{t} for nonexistent files.
+
+If @var{filename} is a symbolic link, then, unlike the other functions
+discussed here, @code{file-ownership-preserved-p} does @emph{not}
+replace @var{filename} with its target.  However, it does recursively
+follow symbolic links at all levels of parent directories.
 @end defun
 
 @defun file-newer-than-file-p filename1 filename2
@@ -826,8 +872,8 @@
 @cindex file modification time
 This function returns @code{t} if the file @var{filename1} is
 newer than file @var{filename2}.  If @var{filename1} does not
-exist, it returns @code{nil}.  If @var{filename2} does not exist,
-it returns @code{t}.
+exist, it returns @code{nil}.  If @var{filename1} does exist, but
+@var{filename2} does not, it returns @code{t}.
 
 In the following example, assume that the file @file{aug-19} was written
 on the 19th, @file{aug-20} was written on the 20th, and the file
@@ -866,9 +912,10 @@
 @defun file-symlink-p filename
 @cindex file symbolic links
 If the file @var{filename} is a symbolic link, the
-@code{file-symlink-p} function returns the link target as a string.
-(Determining the file name that the link points to from the target is
-nontrivial.)
+@code{file-symlink-p} function returns the (non-recursive) link target
+as a string.  (Determining the file name that the link points to from
+the target is nontrivial.)  First, this function recursively follows
+symbolic links at all levels of parent directories.
 
 If the file @var{filename} is not a symbolic link (or there is no such file),
 @code{file-symlink-p} returns @code{nil}.
@@ -895,6 +942,9 @@
 @c !!! file-symlink-p: should show output of ls -l for comparison
 @end defun
 
+The next two functions recursively follow symbolic links at
+all levels for @var{filename}.
+
 @defun file-directory-p filename
 This function returns @code{t} if @var{filename} is the name of an
 existing directory, @code{nil} otherwise.
@@ -946,14 +996,31 @@
 @defun file-truename filename
 The function @code{file-truename} returns the truename of the file
 @var{filename}.  The argument must be an absolute file name.
+
+This function does not expand environment variables.  Only
+@code{substitute-in-file-name} does that.  @xref{Definition of
+substitute-in-file-name}.
+
+If you may need to follow symbolic links preceding @samp{..}@:
+appearing as a name component, you should make sure to call
+@code{file-truename} without prior direct or indirect calls to
+@code{expand-file-name}, as otherwise the file name component
+immediately preceding @samp{..} will be ``simplified away'' before
+@code{file-truename} is called.  To eliminate the need for a call to
+@code{expand-file-name}, @code{file-truename} handles @samp{~} in the
+same way that @code{expand-file-name} does.  @xref{File Name
+Expansion,, Functions that Expand Filenames}.
 @end defun
 
 @defun file-chase-links filename &optional limit
 This function follows symbolic links, starting with @var{filename},
 until it finds a file name which is not the name of a symbolic link.
-Then it returns that file name.  If you specify a number for
-@var{limit}, then after chasing through that many links, the function
-just returns what it as even if that is still a symbolic link.
+Then it returns that file name.  This function does @emph{not} follow
+symbolic links at the level of parent directories.
+
+If you specify a number for @var{limit}, then after chasing through
+that many links, the function just returns what it has even if that is
+still a symbolic link.
 @end defun
 
   To illustrate the difference between @code{file-chase-links} and
@@ -993,9 +1060,13 @@
 is 1, then the file is writable by all users, etc.
 
 The highest value returnable is 4095 (7777 octal), meaning that
-everyone has read, write, and execute permission, that the @sc{suid} bit
+everyone has read, write, and execute permission, that the @acronym{SUID} bit
 is set for both others and group, and that the sticky bit is set.
 
+If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
+
+This function recursively follows symbolic links at all levels.
+
 @example
 @group
 (file-modes "~/junk/diffs")
@@ -1023,6 +1094,11 @@
 @end example
 @end defun
 
+If the @var{filename} argument to the next two functions is a symbolic
+link, then these function do @emph{not} replace it with its target.
+However, they both recursively follow symbolic links at all levels of
+parent directories.
+
 @defun file-nlinks filename
 This functions returns the number of names (i.e., hard links) that
 file @var{filename} has.  If the file does not exist, then this function
@@ -1048,9 +1124,16 @@
 @end example
 @end defun
 
-@defun file-attributes filename
+@anchor{Definition of file-attributes}
+@defun file-attributes filename &optional id-format
 This function returns a list of attributes of file @var{filename}.  If
 the specified file cannot be opened, it returns @code{nil}.
+The optional parameter @var{id-format} specifies the preferred format
+of attributes @acronym{UID} and @acronym{GID} (see below)---the
+valid values are @code{'string} and @code{'integer}.  The latter is
+the default, but we plan to change that, so you should specify a
+non-@code{nil} value for @var{id-format} if you use the returned
+@acronym{UID} or @acronym{GID}.
 
 The elements of the list, in order, are:
 
@@ -1066,10 +1149,11 @@
 (@pxref{Changing Files}).
 
 @item
-The file's @sc{uid}.
+The file's @acronym{UID} as a string or an integer.  If a string
+value cannot be looked up, the integer value is returned.
 
 @item
-The file's @sc{gid}.
+The file's @acronym{GID} likewise.
 
 @item
 The time of last access, as a list of two integers.
@@ -1092,7 +1176,7 @@
 as in @samp{ls -l}.
 
 @item
-@code{t} if the file's @sc{gid} would change if file were
+@code{t} if the file's @acronym{GID} would change if file were
 deleted and recreated; @code{nil} otherwise.
 
 @item
@@ -1114,8 +1198,8 @@
 
 @example
 @group
-(file-attributes "files.texi")
-     @result{}  (nil 1 2235 75
+(file-attributes "files.texi" 'string)
+     @result{}  (nil 1 "lh" "users"
           (8489 20284)
           (8489 20284)
           (8489 20285)
@@ -1135,11 +1219,11 @@
 has only one name (the name @file{files.texi} in the current default
 directory).
 
-@item 2235
-is owned by the user with @sc{uid} 2235.
-
-@item 75
-is in the group with @sc{gid} 75.
+@item "lh"
+is owned by the user with name "lh".
+
+@item "users"
+is in the group with name "users".
 
 @item (8489 20284)
 was last accessed on Aug 19 00:09.
@@ -1158,7 +1242,7 @@
 has a mode of read and write access for the owner, group, and world.
 
 @item nil
-would retain the same @sc{gid} if it were recreated.
+would retain the same @acronym{GID} if it were recreated.
 
 @item 129500
 has an inode number of 129500.
@@ -1195,7 +1279,12 @@
 is any other value.
 @end itemize
 
-@defun add-name-to-file oldname newname &optional ok-if-already-exists
+The next four commands all recursively follow symbolic links at all
+levels of parent directories for their first argument, but, if that
+argument is itself a symbolic link, then only @code{copy-file}
+replaces it with its (recursive) target.
+
+@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
 @cindex file with multiple names
 @cindex file hard link
 This function gives the file named @var{oldname} the additional name
@@ -1261,7 +1350,7 @@
 by copying the file instead.
 
 See also @code{file-nlinks} in @ref{File Attributes}.
-@end defun
+@end deffn
 
 @deffn Command rename-file filename newname &optional ok-if-already-exists
 This command renames the file @var{filename} as @var{newname}.
@@ -1270,10 +1359,6 @@
 continues to have those names.  In fact, adding the name @var{newname}
 with @code{add-name-to-file} and then deleting @var{filename} has the
 same effect as renaming, aside from momentary intermediate states.
-
-In an interactive call, this function prompts for @var{filename} and
-@var{newname} in the minibuffer; also, it requests confirmation if
-@var{newname} already exists.
 @end deffn
 
 @deffn Command copy-file oldname newname &optional ok-if-exists time
@@ -1289,9 +1374,19 @@
 
 This function copies the file modes, too.
 
-In an interactive call, this function prompts for @var{filename} and
-@var{newname} in the minibuffer; also, it requests confirmation if
-@var{newname} already exists.
+In an interactive call, a prefix argument specifies a non-@code{nil}
+value for @var{time}.
+@end deffn
+
+@deffn Command make-symbolic-link filename newname  &optional ok-if-exists
+@pindex ln
+@kindex file-already-exists
+This command makes a symbolic link to @var{filename}, named
+@var{newname}.  This is like the shell command @samp{ln -s
+@var{filename} @var{newname}}.
+
+This function is not available on systems that don't support symbolic
+links.
 @end deffn
 
 @deffn Command delete-file filename
@@ -1304,32 +1399,23 @@
 not exist, or is not deletable.  (On Unix and GNU/Linux, a file is
 deletable if its directory is writable.)
 
+If @var{filename} is a symbolic link, @code{delete-file} does not
+replace it with its target, but it does follow symbolic links at all
+levels of parent directories.
+
 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
 @end deffn
 
-@deffn Command make-symbolic-link filename newname  &optional ok-if-exists
-@pindex ln
-@kindex file-already-exists
-This command makes a symbolic link to @var{filename}, named
-@var{newname}.  This is like the shell command @samp{ln -s
-@var{filename} @var{newname}}.
-
-In an interactive call, this function prompts for @var{filename} and
-@var{newname} in the minibuffer; also, it requests confirmation if
-@var{newname} already exists.
-
-This function is not available on systems that don't support symbolic
-links.
-@end deffn
-
 @defun define-logical-name varname string
-This function defines the logical name @var{name} to have the value
+This function defines the logical name @var{varname} to have the value
 @var{string}.  It is available only on VMS.
 @end defun
 
 @defun set-file-modes filename mode
-This function sets mode bits of @var{filename} to @var{mode} (which must
-be an integer).  Only the low 12 bits of @var{mode} are used.
+This function sets mode bits of @var{filename} to @var{mode} (which
+must be an integer).  Only the low 12 bits of @var{mode} are used.
+This function recursively follows symbolic links at all levels for
+@var{filename}.
 @end defun
 
 @c Emacs 19 feature
@@ -1482,18 +1568,6 @@
 @end example
 @end defun
 
-@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension,'' if any,
-after applying @code{file-name-sans-versions} to remove any
-version/backup part.  It returns @code{nil} for extensionless file
-names such as @file{foo}.  If @var{period} is non-@code{nil}, then the
-returned value includes the period that delimits the extension, and if
-@var{filename} has no extension, the value is @code{""}.  If the last
-component of a file name begins with a @samp{.}, that @samp{.} doesn't
-count as the beginning of an extension, so, for example,
-@file{.emacs}'s ``extension'' is @code{nil}, not @samp{.emacs}.
-@end defun
-
 @defun file-name-sans-versions filename &optional keep-backup-version
 This function returns @var{filename} with any file version numbers,
 backup version numbers, or trailing tildes discarded.
@@ -1523,11 +1597,29 @@
 @end example
 @end defun
 
+@defun file-name-extension filename &optional period
+This function returns @var{filename}'s final ``extension'', if any,
+after applying @code{file-name-sans-versions} to remove any
+version/backup part.  The extension, in a file name, is the part that
+starts with the last @samp{.} in the last name component (minus
+any version/backup part).
+
+This function returns @code{nil} for extensionless file names such as
+@file{foo}.  It returns @code{""} for null extensions, as in
+@file{foo.}.  If the last component of a file name begins with a
+@samp{.}, that @samp{.}  doesn't count as the beginning of an
+extension.  Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
+@samp{.emacs}.
+
+If @var{period} is non-@code{nil}, then the returned value includes
+the period that delimits the extension, and if @var{filename} has no
+extension, the value is @code{""}.
+@end defun
+
 @defun file-name-sans-extension filename
-This function returns @var{filename} minus its ``extension,'' if any.
-The extension, in a file name, is the part that starts with the last
-@samp{.} in the last name component, except if that @samp{.} is the
-first character of the file name's last component.  For example,
+This function returns @var{filename} minus its extension, if any.  The
+version/backup part, if present, is only removed if the file has an
+extension.  For example,
 
 @example
 (file-name-sans-extension "foo.lose.c")
@@ -1538,7 +1630,14 @@
      @result{} "/my/home/.emacs"
 (file-name-sans-extension "/my/home/.emacs.el")
      @result{} "/my/home/.emacs"
+(file-name-sans-extension "~/foo.el.~3~")
+     @result{} "~/foo"
+(file-name-sans-extension "~/foo.~3~")
+     @result{} "~/foo.~3~"
 @end example
+
+Note that the @samp{.~3~} in the two last examples is the backup part,
+not an extension.
 @end defun
 
 @ignore
@@ -1605,9 +1704,9 @@
 the directory name but not identical to it.  (This is not quite the
 same as the usual Unix terminology.)  These two different names for
 the same entity are related by a syntactic transformation.  On GNU and
-Unix systems, this is simple: a directory name ends in a slash (or
-backslash), whereas the directory's name as a file lacks that slash.
-On MSDOS and VMS, the relationship is more complicated.
+Unix systems, this is simple: a directory name ends in a slash,
+whereas the directory's name as a file lacks that slash.  On MSDOS and
+VMS, the relationship is more complicated.
 
   The difference between a directory name and its name as a file is
 subtle but crucial.  When an Emacs variable or function argument is
@@ -1617,7 +1716,7 @@
 
   The following two functions convert between directory names and file
 names.  They do nothing special with environment variable substitutions
-such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
+such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
 
 @defun file-name-as-directory filename
 This function returns a string representing @var{filename} in a form
@@ -1695,7 +1794,9 @@
 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
 @var{to} when it appears in a directory name.  The @var{from} string is
 actually a regular expression; it should always start with @samp{^}.
-The function @code{abbreviate-file-name} performs these substitutions.
+The @var{to} string should be an ordinary absolute directory name.  Do
+not use @samp{~} to stand for a home directory in that string.  The
+function @code{abbreviate-file-name} performs these substitutions.
 
 You can set this variable in @file{site-init.el} to describe the
 abbreviations appropriate for your site.
@@ -1714,6 +1815,7 @@
   To convert a directory name to its abbreviation, use this
 function:
 
+@anchor{Definition of abbreviate-file-name}
 @defun abbreviate-file-name filename
 This function applies abbreviations from @code{directory-abbrev-alist}
 to its argument, and substitutes @samp{~} for the user's home
@@ -1731,6 +1833,9 @@
 be expanded.  Expansion also simplifies file names by eliminating
 redundancies such as @file{./} and @file{@var{name}/../}.
 
+In the next two functions, the @var{directory} argument can be either
+a directory name or a directory file name.  @xref{Directory Names}.
+
 @defun expand-file-name filename &optional directory
 This function converts @var{filename} to an absolute file name.  If
 @var{directory} is supplied, it is the default directory to start with
@@ -1758,6 +1863,12 @@
 @end group
 @end example
 
+If the part of the combined file name before the first slash is
+@samp{~}, it expands to the value of the @env{HOME} environment
+variable (usually your home directory).  If the part before the first
+slash is @samp{~@var{user}} and if @var{user} is a valid login name,
+it expands to @var{user}'s home directory.
+
 Filenames containing @samp{.} or @samp{..} are simplified to their
 canonical form:
 
@@ -1770,6 +1881,27 @@
 
 Note that @code{expand-file-name} does @emph{not} expand environment
 variables; only @code{substitute-in-file-name} does that.
+
+Note also that @code{expand-file-name} does not follow symbolic links
+at any level.  This results in a difference between the way
+@code{file-truename} and @code{expand-file-name} treat @samp{..}.
+Assuming that @samp{/tmp/bar} is a symbolic link to the directory
+@samp{/tmp/foo/bar} we get:
+
+@example
+@group
+(file-truename "/tmp/bar/../myfile")
+     @result{} "/tmp/foo/myfile"
+@end group
+@group
+(expand-file-name "/tmp/bar/../myfile")
+     @result{} "/tmp/myfile"
+@end group
+@end example
+
+If you may need to follow symbolic links preceding @samp{..}, you
+should make sure to call @code{file-truename} without prior direct or
+indirect calls to @code{expand-file-name}.  @xref{Truenames}.
 @end defun
 
 @c Emacs 19 feature
@@ -1811,8 +1943,9 @@
 @end example
 @end defvar
 
+@anchor{Definition of substitute-in-file-name}
 @defun substitute-in-file-name filename
-This function replaces environment variables references in
+This function replaces environment variable references in
 @var{filename} with the environment variable values.  Following
 standard Unix shell syntax, @samp{$} is the prefix to substitute an
 environment variable value.  If the input contains @samp{$$}, that is
@@ -1844,8 +1977,9 @@
 @end group
 @end example
 
-After substitution, if a @samp{~} or a @samp{/} appears following a
-@samp{/}, everything before the following @samp{/} is discarded:
+After substitution, if a @samp{~} or a @samp{/} appears immediately
+after another @samp{/}, the function discards everything before it (up
+through the immediately preceding @samp{/}).
 
 @example
 @group
@@ -1877,7 +2011,7 @@
 The job of @code{make-temp-file} is to prevent two different users or
 two different jobs from trying to use the exact same file name.
 
-@defun make-temp-file prefix &optional dir-flag
+@defun make-temp-file prefix &optional dir-flag suffix
 @tindex make-temp-file
 This function creates a temporary file and returns its name.
 The name starts with @var{prefix}; it also contains a number that is
@@ -1895,8 +2029,12 @@
 empty.  At that point, you should write the intended contents into the
 file.
 
-If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates
-an empty directory instead of an empty file.
+If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
+empty directory instead of an empty file.  It returns the file name,
+not the directory name, of that directory.  @xref{Directory Names}.
+
+If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
+the end of the file name.
 
 To prevent conflicts among different libraries running in the same
 Emacs, each Lisp program that uses @code{make-temp-file} should have its
@@ -1926,9 +2064,10 @@
 This function generates a string that can be used as a unique file name.
 The name starts with @var{string}, and contains a number that is
 different in each Emacs job.  It is like @code{make-temp-file} except
-that it just constructs a name, and does not create a file.  On MS-DOS,
-the @var{string} prefix can be truncated to fit into the 8+3 file-name
-limits.
+that it just constructs a name, and does not create a file.  Another
+difference is that @var{string} should be an absolute file name.  On
+MS-DOS, this function can truncate the @var{string} prefix to fit into
+the 8+3 file-name limits.
 @end defun
 
 @defvar temporary-file-directory
@@ -1946,11 +2085,11 @@
 environment variables, with a fall-back to a system-dependent name if
 none of these variables is defined.
 
-Even if you do not use @code{make-temp-name} to choose the temporary
-file's name, you should still use this variable to decide which
-directory to put the file in.  However, if you expect the file to be
-small, you should use @code{small-temporary-file-directory} first if
-that is non-@code{nil}.
+Even if you do not use @code{make-temp-file} to create the temporary
+file, you should still use this variable to decide which directory to
+put the file in.  However, if you expect the file to be small, you
+should use @code{small-temporary-file-directory} first if that is
+non-@code{nil}.
 @end defvar
 
 @tindex small-temporary-file-directory
@@ -2048,8 +2187,8 @@
 @defopt completion-ignored-extensions
 @code{file-name-completion} usually ignores file names that end in any
 string in this list.  It does not ignore them when all the possible
-completions end in one of these suffixes or when a buffer showing all
-possible completions is displayed.@refill
+completions end in one of these suffixes.  This variable has no effect
+on @code{file-name-all-completions}.@refill
 
 A typical value might look like this:
 
@@ -2158,9 +2297,20 @@
 that can be read.
 @end defun
 
+@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
+This is similar to @code{directory-files} in deciding which files
+to report on and how to report their names.  However, instead
+of returning a list of file names, it returns for each file a
+list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
+is what @code{file-attributes} would return for that file.
+The optional argument @var{id-format} has the same meaning as the
+corresponding argument to @code{file-attributes} (@pxref{Definition
+of file-attributes}).
+@end defun
+
 @defun file-name-all-versions file dirname
 This function returns a list of all versions of the file named
-@var{file} in directory @var{dirname}.
+@var{file} in directory @var{dirname}.  It is only available on VMS.
 @end defun
 
 @tindex file-expand-wildcards
@@ -2181,6 +2331,8 @@
 This function inserts (in the current buffer) a directory listing for
 directory @var{file}, formatted with @code{ls} according to
 @var{switches}.  It leaves point after the inserted text.
+@var{switches} may be a string of options, or a list of strings
+representing individual options.
 
 The argument @var{file} may be either a directory name or a file
 specification including wildcard characters.  If @var{wildcard} is
@@ -2202,6 +2354,12 @@
 MS-DOS and MS-Windows systems usually lack the standard Unix program
 @code{ls}, so this function emulates the standard Unix program @code{ls}
 with Lisp code.
+
+As a technical detail, when @var{switches} contains the long
+@samp{--dired} option, @code{insert-directory} treats it specially,
+for the sake of dired.  However, the normally equivalent short
+@samp{-D} option is just passed on to @code{insert-directory-program},
+as any other option.
 @end defun
 
 @defvar insert-directory-program
@@ -2221,8 +2379,9 @@
 
 @defun make-directory dirname &optional parents
 This function creates a directory named @var{dirname}.
-If @var{parents} is non-@code{nil}, that means to create
-the parent directories first, if they don't already exist.
+If @var{parents} is non-@code{nil}, as is always the case in an
+interactive call, that means to create the parent directories first,
+if they don't already exist.
 @end defun
 
 @defun delete-directory dirname
@@ -2230,6 +2389,9 @@
 @code{delete-file} does not work for files that are directories; you
 must use @code{delete-directory} for them.  If the directory contains
 any files, @code{delete-directory} signals an error.
+
+This function only follows symbolic links at the level of parent
+directories.
 @end defun
 
 @node Magic File Names
@@ -2261,10 +2423,10 @@
 the file name matches @var{regexp}, the primitives handle that file by
 calling @var{handler}.
 
-The first argument given to @var{handler} is the name of the primitive;
-the remaining arguments are the arguments that were passed to that
-primitive.  (The first of these arguments is most often the file name
-itself.)  For example, if you do this:
+The first argument given to @var{handler} is the name of the
+primitive, as a symbol; the remaining arguments are the arguments that
+were passed to that primitive.  (The first of these arguments is most
+often the file name itself.)  For example, if you do this:
 
 @example
 (file-exists-p @var{filename})
@@ -2434,7 +2596,7 @@
 each have handlers.
 
 @kindex safe-magic (@r{property})
-Handlers that don't really do anything specal for actual access to the
+Handlers that don't really do anything special for actual access to the
 file---such as the ones that implement completion of host names for
 remote file names---should have a non-@code{nil} @code{safe-magic}
 property.  For instance, Emacs normally ``protects'' directory names
@@ -2461,15 +2623,22 @@
 @end defun
 
 @defun file-local-copy filename
-This function copies file @var{filename} to an ordinary non-magic file,
-if it isn't one already.
-
-If @var{filename} specifies a magic file name, which programs
-outside Emacs cannot directly read or write, this copies the contents to
-an ordinary file and returns that file's name.
-
-If @var{filename} is an ordinary file name, not magic, then this function
-does nothing and returns @code{nil}.
+This function copies file @var{filename} to an ordinary non-magic file
+on the local machine, if it isn't on the local machine already.  Magic
+file names should handle the @code{file-local-copy} operation if they
+refer to files on other machines.  A magic file name that is used for
+other purposes than remote file access should not handle
+@code{file-local-copy}; then this function will treat the file as
+local.
+
+If @var{filename} is local, whether magic or not, this function does
+nothing and returns @code{nil}.  Otherwise it returns the file name
+of the local copy file.
+@end defun
+
+@defun file-remote-p filename
+This function returns @code{t} if @var{filename} is a remote file---that is,
+a magic file name that handles @code{file-local-copy}.
 @end defun
 
 @defun unhandled-file-name-directory filename
@@ -2598,11 +2767,14 @@
 encoding functions for the formats listed in @code{buffer-file-format},
 in the order of appearance in the list.
 
-@deffn Command format-write-file file format
-This command writes the current buffer contents into the file @var{file}
-in format @var{format}, and makes that format the default for future
-saves of the buffer.  The argument @var{format} is a list of format
-names.
+@deffn Command format-write-file file format &optional confirm
+This command writes the current buffer contents into the file
+@var{file} in format @var{format}, and makes that format the default
+for future saves of the buffer.  The argument @var{format} is a list
+of format names.  Except for the @var{format} argument, this command
+is similar to @code{write-file}.  In particular, @var{confirm} has the
+same meaning and interactive treatment as the corresponding argument
+to @code{write-file}.  @xref{Definition of write-file}.
 @end deffn
 
 @deffn Command format-find-file file format
@@ -2634,6 +2806,12 @@
 This variable specifies the format to use for auto-saving.  Its value is
 a list of format names, just like the value of
 @code{buffer-file-format}; however, it is used instead of
-@code{buffer-file-format} for writing auto-save files.  This variable is
-always buffer-local in all buffers.
+@code{buffer-file-format} for writing auto-save files.  If the value
+is @code{t}, the default, auto-saving uses the same format as a
+regular save in the same buffer.  This variable is always buffer-local
+in all buffers.
 @end defvar
+
+@ignore
+   arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
+@end ignore

--- a/lispref/frames.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/frames.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -56,7 +56,7 @@
 * Input Focus::			Specifying the selected frame.
 * Visibility of Frames::	Frames may be visible or invisible, or icons.
 * Raising and Lowering::	Raising a frame makes it hide other windows;
-				  lowering it makes the others hide them.
+				  lowering it makes the others hide it.
 * Frame Configurations::	Saving the state of all frames.
 * Mouse Tracking::		Getting events that say when the mouse moves.
 * Mouse Position::		Asking where the mouse is, or moving it.
@@ -212,9 +212,10 @@
 selected  frame's parameter.
 @end defun
 
-@defun frame-parameters frame
+@defun frame-parameters &optional frame
 The function @code{frame-parameters} returns an alist listing all the
-parameters of @var{frame} and their values.
+parameters of @var{frame} and their values.  If @var{frame} is
+@code{nil} or omitted, this returns the selected frame's parameters
 @end defun
 
 @defun modify-frame-parameters frame alist
@@ -222,7 +223,15 @@
 elements of @var{alist}.  Each element of @var{alist} has the form
 @code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
 parameter.  If you don't mention a parameter in @var{alist}, its value
-doesn't change.
+doesn't change.  If @var{frame} is @code{nil}, it defaults to the selected
+frame.
+@end defun
+
+@defun modify-all-frames-parameters alist
+This function alters the frame parameters of all existing frames
+according to @var{alist}, then modifies @code{default-frame-alist}
+to apply the same parameter values to frames that will be created
+henceforth.
 @end defun
 
 @node Initial Parameters
@@ -423,13 +432,6 @@
 A list of buffers that have been selected in this frame,
 ordered most-recently-selected first.
 
-@item font
-The name of the font for displaying text in the frame.  This is a
-string, either a valid font name for your system or the name of an Emacs
-fontset (@pxref{Fontsets}).  Changing this frame parameter on a frame
-also changes the font-related attributes of the default face on that
-frame.
-
 @item auto-raise
 Whether selecting the frame raises it (non-@code{nil} means yes).
 
@@ -447,7 +449,8 @@
 implemented.)
 
 @item scroll-bar-width
-The width of the vertical scroll bar, in pixels.
+The width of the vertical scroll bar, in pixels,
+or @code{nil} meaning to use the default width.
 
 @item icon-type
 The type of icon to use for this frame when it is iconified.  If the
@@ -459,33 +462,10 @@
 The name to use in the icon for this frame, when and if the icon
 appears.  If this is @code{nil}, the frame's title is used.
 
-@item foreground-color
-The color to use for the image of a character.  This is a string; the
-window system defines the meaningful color names.  Changing this
-parameter is equivalent to changing the foreground color of the face
-@code{default} on the frame in question.
-
-@item background-color
-The color to use for the background of characters.  Changing this
-parameter is equivalent to changing the foreground color of the face
-@code{default} on the frame in question.
-
 @item background-mode
 This parameter is either @code{dark} or @code{light}, according
 to whether the background color is a light one or a dark one.
 
-@item mouse-color
-The color for the mouse pointer.  Changing this parameter is equivalent
-to changing the background color of face @code{mouse}.
-
-@item cursor-color
-The color for the cursor that shows point.  Changing this parameter is
-equivalent to changing the background color of face @code{cursor}.
-
-@item border-color
-The color for the border of the frame.  Changing this parameter is
-equivalent to changing the background color of face @code{border}.
-
 @item tty-color-mode
 @cindex standard colors for character terminals
 This parameter overrides the terminal's color support as given by the
@@ -500,16 +480,6 @@
 @code{tty-color-mode-alist}, and if found, the associated number is
 used as the color support mode.
 
-@item scroll-bar-foreground
-If non-@code{nil}, the color for the foreground of scroll bars.
-Changing this parameter is equivalent to setting the foreground color of
-face @code{scroll-bar}.
-
-@item scroll-bar-background
-If non-@code{nil}, the color for the background of scroll bars.
-Changing this parameter is equivalent to setting the background color of
-face @code{scroll-bar}.
-
 @item display-type
 This parameter describes the range of possible colors that can be used
 in this frame.  Its value is @code{color}, @code{grayscale} or
@@ -537,9 +507,8 @@
 
 @vindex cursor-type
 The buffer-local variable @code{cursor-type} overrides the value of
-the @code{cursor-type} frame parameter, and can in addition have
-values @code{t} (use the cursor specified for the frame) and
-@code{nil} (don't display a cursor).
+the @code{cursor-type} frame parameter, but if it is @code{t}, that
+means to use the cursor specified for the frame.
 
 @item border-width
 The width in pixels of the window border.
@@ -547,6 +516,22 @@
 @item internal-border-width
 The distance in pixels between text and border.
 
+@item left-fringe
+@itemx right-fringe
+The default width of the left and right fringes of windows in this
+frame (@pxref{Fringes}).  If either of these is zero, that effectively
+removes the corresponding fringe.  A value of @code{nil} stands for
+the standard fringe width, which is the width needed to display the
+fringe bitmaps.
+
+The combined fringe widths must add up to an integral number of
+columns, so the actual default fringe widths for the frame may be
+larger than the specified values.  The extra width needed to reach an
+acceptable total is distributed evenly between the left and right
+fringe.  However, you can force one frame or the other to a precise
+width by specifying that width a negative integer.  If both widths are
+negative, only the left fringe gets the specified width.
+
 @item unsplittable
 If non-@code{nil}, this frame's window is never split automatically.
 
@@ -558,7 +543,7 @@
 @item menu-bar-lines
 The number of lines to allocate at the top of the frame for a menu bar.
 The default is 1.  @xref{Menu Bar}.  (In Emacs versions that use the X
-toolkit, there is only one menu bar line; all that matters about the
+toolkit or GTK, there is only one menu bar line; all that matters about the
 number you specify is whether it is greater than zero.)
 
 @item screen-gamma
@@ -582,7 +567,9 @@
 
 @item tool-bar-lines
 The number of lines to use for the toolbar.  A value of @code{nil} means
-don't display a tool bar.
+don't display a tool bar.  (In Emacs versions that use GTK, there is
+only one tool bar line; all that matters about the number you specify
+is whether it is greater than zero.)
 
 @item line-spacing
 Additional space put below text lines in pixels (a positive integer).
@@ -611,6 +598,53 @@
 is examined only when you specify a cursor type for a frame.
 @end defvar
 
+These frame parameters are semi-obsolete in that they are automatically
+equivalent to particular face attributes of particular faces.
+
+@table @code
+@item font
+The name of the font for displaying text in the frame.  This is a
+string, either a valid font name for your system or the name of an Emacs
+fontset (@pxref{Fontsets}).  It is equivalent to the @code{font}
+attribute of the @code{default} face.
+
+@item foreground-color
+The color to use for the image of a character.  It is equivalent to
+the @code{:foreground} attribute of the @code{default} face.
+
+@item background-color
+The color to use for the background of characters.  It is equivalent to
+the @code{:background} attribute of the @code{default} face.
+
+@item mouse-color
+The color for the mouse pointer.  It is equivalent to the @code{:background}
+attribute of the @code{mouse} face.
+
+@item cursor-color
+The color for the cursor that shows point.  It is equivalent to the
+@code{:background} attribute of the @code{cursor} face.
+
+@item border-color
+The color for the border of the frame.  It is equivalent to the
+@code{:background} attribute of the @code{border} face.
+
+@item scroll-bar-foreground
+If non-@code{nil}, the color for the foreground of scroll bars.  It is
+equivalent to the @code{:foreground} attribute of the
+@code{scroll-bar} face.
+
+@item scroll-bar-background
+If non-@code{nil}, the color for the background of scroll bars.  It is
+equivalent to the @code{:background} attribute of the
+@code{scroll-bar} face.
+
+@item wait-for-wm
+If non-@code{nil}, tell Xt to wait for the window manager to confirm
+geometry changes.  Some window managers, including versions of Fvwm2
+and KDE, fail to confirm, so Xt hangs.  Set this to @code{nil} to
+prevent hanging with those window managers.
+@end table
+
 @node Size and Position
 @subsection Frame Size And Position
 @cindex size of frame
@@ -798,10 +832,10 @@
 way windows behave.
 
 @deffn Command delete-frame &optional frame force
-@vindex delete-frame-hook
+@vindex delete-frame-functions
 This function deletes the frame @var{frame} after running the hook
-@code{delete-frame-hook}.  By default, @var{frame} is the selected
-frame.
+@code{delete-frame-functions} (each function gets one argument,
+@var{frame}).  By default, @var{frame} is the selected frame.
 
 A frame cannot be deleted if its minibuffer is used by other frames.
 Normally, you cannot delete a frame if all other frames are invisible,
@@ -884,8 +918,9 @@
 the lower right corner (always the minibuffer window, if the frame has
 one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.
 
-@defun frame-first-window frame
+@defun frame-first-window &optional frame
 This returns the topmost, leftmost window of frame @var{frame}.
+If omitted or @code{nil}, @var{frame} defaults to the selected frame.
 @end defun
 
 At any time, exactly one window on any frame is @dfn{selected within the
@@ -893,9 +928,16 @@
 frame also selects this window.  You can get the frame's current
 selected window with @code{frame-selected-window}.
 
-@defun frame-selected-window frame
+@defun frame-selected-window  &optional frame
 This function returns the window on @var{frame} that is selected within
-@var{frame}.
+@var{frame}.  If omitted or @code{nil}, @var{frame} defaults to the selected frame.
+@end defun
+
+@defun set-frame-selected-window frame window
+This sets the selected window of frame @var{frame} to @var{window}.
+If @var{frame} is @code{nil}, it operates on the selected frame.  If
+@var{frame} is the selected frame, this makes @var{window} the
+selected window.
 @end defun
 
   Conversely, selecting a window for Emacs with @code{select-window} also
@@ -994,14 +1036,14 @@
 Don't call it for any other reason.
 @end deffn
 
-@defun redirect-frame-focus frame focus-frame
+@defun redirect-frame-focus frame &optional focus-frame
 This function redirects focus from @var{frame} to @var{focus-frame}.
 This means that @var{focus-frame} will receive subsequent keystrokes and
 events intended for @var{frame}.  After such an event, the value of
 @code{last-event-frame} will be @var{focus-frame}.  Also, switch-frame
 events specifying @var{frame} will instead select @var{focus-frame}.
 
-If @var{focus-frame} is @code{nil}, that cancels any existing
+If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
 redirection for @var{frame}, which therefore once again receives its own
 events.
 
@@ -1426,9 +1468,10 @@
 selection values.
 
 Each possible @var{type} has its own selection value, which changes
-independently.  The usual values of @var{type} are @code{PRIMARY} and
-@code{SECONDARY}; these are symbols with upper-case names, in accord
-with X Window System conventions.  The default is @code{PRIMARY}.
+independently.  The usual values of @var{type} are @code{PRIMARY},
+@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
+names, in accord with X Window System conventions.  The default is
+@code{PRIMARY}.
 @end defun
 
 @defun x-get-selection &optional type data-type
@@ -1440,6 +1483,7 @@
 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},
@@ -1449,15 +1493,17 @@
 @end defun
 
 @cindex cut buffer
-The X server also has a set of numbered @dfn{cut buffers} which can
+The X server also has a set of eight numbered @dfn{cut buffers} which can
 store text or other data being moved between applications.  Cut buffers
 are considered obsolete, but Emacs supports them for the sake of X
-clients that still use them.
+clients that still use them.  Cut buffers are numbered from 0 to 7.
 
-@defun x-get-cut-buffer n
+@defun x-get-cut-buffer &optional n
 This function returns the contents of cut buffer number @var{n}.
+If omitted @var{n} defaults to 0.
 @end defun
 
+@anchor{Definition of x-set-cut-buffer}
 @defun x-set-cut-buffer string &optional push
 This function stores @var{string} into the first cut buffer (cut buffer
 0).  If @var{push} is @code{nil}, only the first cut buffer is changed.
@@ -1661,7 +1707,7 @@
 
 @defun x-get-resource attribute class &optional component subclass
 The function @code{x-get-resource} retrieves a resource value from the X
-Windows defaults database.
+Window defaults database.
 
 Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
 This function searches using a key of the form
@@ -1683,6 +1729,12 @@
 variable to some other string, around a call to @code{x-get-resource}.
 @end defvar
 
+@defvar x-resource-name
+This variable specifies the instance name that @code{x-get-resource}
+should look up.  The default value is the name Emacs was invoked with,
+or the value specified with the @samp{-name} or @samp{-rn} switches.
+@end defvar
+
   @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
 
 @node Display Feature Testing
@@ -1872,3 +1924,7 @@
 The functions @code{x-pixel-width} and @code{x-pixel-height} return the
 width and height of an X Window frame, measured in pixels.
 @end ignore
+
+@ignore
+   arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
+@end ignore

--- a/lispref/front-cover-1.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/front-cover-1.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -50,3 +50,7 @@
 
 @end titlepage
 @bye
+
+@ignore
+   arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d
+@end ignore

--- a/lispref/functions.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/functions.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -113,10 +113,15 @@
 @end table
 
 @defun functionp object
-This function returns @code{t} if @var{object} is any kind of function,
-or a special form or macro.
+This function returns @code{t} if @var{object} is any kind of
+function, or a special form, or, recursively, a symbol whose function
+definition is a function or special form.  (This does not include
+macros.)
 @end defun
 
+Unlike @code{functionp}, the next three functions do @emph{not}
+treat a symbol as its function definition.
+
 @defun subrp object
 This function returns @code{t} if @var{object} is a built-in function
 (i.e., a Lisp primitive).
@@ -428,13 +433,14 @@
 text like this:
 
 @example
-(fn @var{arglist})
+\(fn @var{arglist})
 @end example
 
 @noindent
-following a blank line, with no newline following it inside the
-documentation string.  This feature is particularly useful for
-macro definitions.
+following a blank line, at the beginning of the line, with no newline
+following it inside the documentation string.  This feature is
+particularly useful for macro definitions.  The @samp{\} is used to
+avoid confusing the Emacs motion commands.
 
 @node Function Names
 @section Naming a Function
@@ -571,9 +577,15 @@
 deliberate redefinition from unintentional redefinition.
 @end defspec
 
-@defun defalias name definition
+@anchor{Definition of defalias}
+@defun defalias name definition &optional docstring
 This special form defines the symbol @var{name} as a function, with
 definition @var{definition} (which can be any valid Lisp function).
+It returns @var{definition}.
+
+If @var{docstring} is non-@code{nil}, it becomes the function
+documentation of @var{name}.  Otherwise, any documentation provided by
+@var{definition} is used.
 
 The proper place to use @code{defalias} is where a specific function
 name is being defined---especially where that name appears explicitly in
@@ -587,7 +599,7 @@
 @end defun
 
   You cannot create a new primitive function with @code{defun} or
-@code{defalias}, but you use them to change the function definition of
+@code{defalias}, but you can use them to change the function definition of
 any symbol, even one such as @code{car} or @code{x-popup-menu} whose
 normal definition is a primitive.  However, this is risky: for
 instance, it is next to impossible to redefine @code{car} without
@@ -700,8 +712,8 @@
 @end group
 @end example
 
-For an interesting example of using @code{apply}, see the description of
-@code{mapcar}, in @ref{Mapping Functions}.
+For an interesting example of using @code{apply}, see @ref{Definition
+of mapcar}.
 @end defun
 
 @cindex functionals
@@ -726,19 +738,21 @@
 @section Mapping Functions
 @cindex mapping functions
 
-  A @dfn{mapping function} applies a given function to each element of a
-list or other collection.  Emacs Lisp has several such functions;
-@code{mapcar} and @code{mapconcat}, which scan a list, are described
-here.  @xref{Creating Symbols}, for the function @code{mapatoms} which
-maps over the symbols in an obarray.  @xref{Hash Access}, for the
-function @code{maphash} which maps over key/value associations in a
-hash table.
+  A @dfn{mapping function} applies a given function (@emph{not} a
+special form or macro) to each element of a list or other collection.
+Emacs Lisp has several such functions; @code{mapcar} and
+@code{mapconcat}, which scan a list, are described here.
+@xref{Definition of mapatoms}, for the function @code{mapatoms} which
+maps over the symbols in an obarray.  @xref{Definition of maphash},
+for the function @code{maphash} which maps over key/value associations
+in a hash table.
 
   These mapping functions do not allow char-tables because a char-table
 is a sparse array whose nominal range of indices is very large.  To map
 over a char-table in a way that deals properly with its sparse nature,
 use the function @code{map-char-table} (@pxref{Char-Tables}).
 
+@anchor{Definition of mapcar}
 @defun mapcar function sequence
 @code{mapcar} applies @var{function} to each element of @var{sequence}
 in turn, and returns a list of the results.
@@ -770,7 +784,7 @@
   "Apply FUNCTION to successive cars of all ARGS.
 Return the list of results."
   ;; @r{If no list is exhausted,}
-  (if (not (memq 'nil args))
+  (if (not (memq nil args))
       ;; @r{apply function to @sc{car}s.}
       (cons (apply function (mapcar 'car args))
             (apply 'mapcar* function
@@ -961,8 +975,8 @@
 Contrast this with @code{quote}, in @ref{Quoting}.
 @end defspec
 
-  See @code{documentation} in @ref{Accessing Documentation}, for a
-realistic example using @code{function} and an anonymous function.
+  @xref{describe-symbols example}, for a realistic example using
+@code{function} and an anonymous function.
 
 @node Function Cells
 @section Accessing Function Cell Contents
@@ -971,8 +985,8 @@
 function cell of the symbol.  The functions described here access, test,
 and set the function cell of symbols.
 
-  See also the function @code{indirect-function} in @ref{Function
-Indirection}.
+  See also the function @code{indirect-function}.  @xref{Definition of
+indirect-function}.
 
 @defun symbol-function symbol
 @kindex void-function
@@ -1027,8 +1041,9 @@
 
 @defun fmakunbound symbol
 This function makes @var{symbol}'s function cell void, so that a
-subsequent attempt to access this cell will cause a @code{void-function}
-error.  (See also @code{makunbound}, in @ref{Void Variables}.)
+subsequent attempt to access this cell will cause a
+@code{void-function} error.  It returns @var{symbol}.  (See also
+@code{makunbound}, in @ref{Void Variables}.)
 
 @example
 @group
@@ -1064,7 +1079,7 @@
 Copying one symbol's function definition to another---in other words,
 making an alternate name for a function.  (If you think of this as the
 definition of the new name, you should use @code{defalias} instead of
-@code{fset}; see @ref{Defining Functions}.)
+@code{fset}; see @ref{Definition of defalias}.)
 
 @item
 Giving a symbol a function definition that is not a list and therefore
@@ -1187,15 +1202,15 @@
 @cindex function safety
 @cindex safety of functions
 
-Some major modes such as SES (@pxref{Top,,,ses}) call functions that
-are stored in user files.  User files sometimes have poor
-pedigrees---you can get a spreadsheet from someone you've just met, or
-you can get one through email from someone you've never met.  So it is
-risky to call a function whose source code is stored in a user file
-until you have determined that it is safe.
+Some major modes such as SES call functions that are stored in user
+files.  (@inforef{Top, ,ses}, for more information on SES.)  User
+files sometimes have poor pedigrees---you can get a spreadsheet from
+someone you've just met, or you can get one through email from someone
+you've never met.  So it is risky to call a function whose source code
+is stored in a user file until you have determined that it is safe.
 
 @defun unsafep form &optional unsafep-vars
-Returns @code{nil} if @var{form} is a @dfn{safe} lisp expression, or
+Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
 returns a list that describes why it might be unsafe.  The argument
 @var{unsafep-vars} is a list of symbols known to have temporary
 bindings at this point; it is mainly used for internal recursive
@@ -1326,6 +1341,9 @@
 See @ref{Mapping Functions}.
 
 @item undefined
-See @ref{Key Lookup}.
+See @ref{Functions for Key Lookup}.
 @end table
 
+@ignore
+   arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2
+@end ignore

--- a/lispref/gpl.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/gpl.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -398,3 +398,6 @@
 library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.
 
+@ignore
+   arch-tag: d00ac830-e120-41fb-bbc5-7ca3eeaa227f
+@end ignore

--- a/lispref/hash.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/hash.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -76,8 +76,10 @@
 
 @table @code
 @item eql
-Keys which are numbers are ``the same'' if they are equal in value;
-otherwise, two distinct objects are never ``the same''.
+Keys which are numbers are ``the same'' if they are @code{equal}, that
+is, if they are equal in value and either both are integers or both
+are floating point numbers; otherwise, two distinct objects are never
+``the same''.
 
 @item eq
 Any two distinct Lisp objects are ``different'' as keys.
@@ -96,7 +98,7 @@
 
 The value, @var{weak}, must be one of @code{nil}, @code{key},
 @code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}
-which is an alias for @code{key-or-value}.  If @var{weak} is @code{key}
+which is an alias for @code{key-and-value}.  If @var{weak} is @code{key}
 then the hash table does not prevent its keys from being collected as
 garbage (if they are not referenced anywhere else); if a particular key
 does get collected, the corresponding association is removed from the
@@ -107,19 +109,19 @@
 anywhere else); if a particular value does get collected, the
 corresponding association is removed from the hash table.
 
-If @var{weak} is @code{key-or-value} or @code{t}, the hash table does
-not protect either keys or values from garbage collection; if either
-one is collected as garbage, the association is removed.
+If @var{weak} is @code{key-and-value} or @code{t}, both the key and
+the value must be live in order to preserve the association.  Thus,
+the hash table does not protect either keys or values from garbage
+collection; if either one is collected as garbage, that removes the
+association.
 
-If @var{weak} is @code{key-and-value}, associations are removed from
-the hash table when both their key and value would be collected as
-garbage, again not considering references to the key and value from
-weak hash tables.
+If @var{weak} is @code{key-or-value}, either the key or
+the value can preserve the association.  Thus, associations are
+removed from the hash table when both their key and value would be
+collected as garbage (if not for references from weak hash tables).
 
 The default for @var{weak} is @code{nil}, so that all keys and values
-referenced in the hash table are preserved from garbage collection.  If
-@var{weak} is @code{t}, neither keys nor values are protected (that is,
-both are weak).
+referenced in the hash table are preserved from garbage collection.
 
 @item :size @var{size}
 This specifies a hint for how many associations you plan to store in the
@@ -158,8 +160,7 @@
 argument list.  The argument @var{test} specifies the method
 of key lookup.
 
-If you want to specify other parameters, you should use
-@code{make-hash-table}.
+This function is obsolete. Use @code{make-hash-table} instead.
 @end defun
 
 @node Hash Access
@@ -187,6 +188,10 @@
 This function removes the association for @var{key} from @var{table}, if
 there is one.  If @var{key} has no association, @code{remhash} does
 nothing.
+
+@b{Common Lisp note:} In Common Lisp, @code{remhash} returns
+non-@code{nil} if it actually removed an association and @code{nil}
+otherwise.  In Emacs Lisp, @code{remhash} always returns @code{nil}.
 @end defun
 
 @tindex clrhash
@@ -194,9 +199,13 @@
 This function removes all the associations from hash table @var{table},
 so that it becomes empty.  This is also called @dfn{clearing} the hash
 table.
+
+@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
+@var{table}.  In Emacs Lisp, it returns @code{nil}.
 @end defun
 
 @tindex maphash
+@anchor{Definition of maphash}
 @defun maphash function table
 This function calls @var{function} once for each of the associations in
 @var{table}.  The function @var{function} should accept two
@@ -255,8 +264,8 @@
 @var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
 
 If the two objects are not equal, the values returned by @code{sxhash}
-are usually different, but not always; but once in a rare while, by
-luck, you will encounter two distinct-looking objects that give the same
+are usually different, but not always; once in a rare while, by luck,
+you will encounter two distinct-looking objects that give the same
 result from @code{sxhash}.
 @end defun
 
@@ -334,3 +343,7 @@
 @defun hash-table-size table
 This returns the current nominal size of @var{table}.
 @end defun
+
+@ignore
+   arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e
+@end ignore

--- a/lispref/help.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/help.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -156,6 +156,7 @@
 @code{documentation-property}, to display the documentation strings for
 several symbols in a @samp{*Help*} buffer.
 
+@anchor{describe-symbols example}
 @smallexample
 @group
 (defun describe-symbols (pattern)
@@ -259,6 +260,7 @@
 user option; see the description of @code{defvar} in @ref{Defining
 Variables}.
 
+@anchor{Definition of Snarf-documentation}
 @defun Snarf-documentation filename
 This function is used only during Emacs initialization, just before
 the runnable Emacs is dumped.  It finds the file offsets of the
@@ -430,7 +432,8 @@
 standard Emacs notation for characters that appear in text---like
 @code{single-key-description}, except that control characters are
 represented with a leading caret (which is how control characters in
-Emacs buffers are usually displayed).
+Emacs buffers are usually displayed) and character codes 128
+and above are not treated as Meta characters.
 
 @smallexample
 @group
@@ -439,11 +442,11 @@
 @end group
 @group
 (text-char-description ?\M-m)
-     @result{} "M-m"
+     @result{} "\xed"
 @end group
 @group
 (text-char-description ?\C-\M-m)
-     @result{} "M-^M"
+     @result{} "\x8d"
 @end group
 @end smallexample
 @end defun
@@ -635,3 +638,7 @@
 echo area at first, and display the longer @var{help-text} strings only
 if the user types the help character again.
 @end defopt
+
+@ignore
+   arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
+@end ignore

--- a/lispref/hooks.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/hooks.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2004 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/hooks
 @node Standard Hooks, Index, Standard Keymaps, Top
@@ -47,6 +47,7 @@
 @item before-init-hook
 @item before-make-frame-hook
 @item before-revert-hook
+@item before-save-hook
 @item blink-paren-function
 @item buffer-access-fontify-functions
 @item c-mode-hook
@@ -136,3 +137,7 @@
 @item write-file-functions
 @item write-region-annotate-functions
 @end table
+
+@ignore
+   arch-tag: 55fd0296-d906-4551-b300-979d3846aa88
+@end ignore

--- a/lispref/internals.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/internals.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -13,7 +13,7 @@
 internal aspects of GNU Emacs that may be of interest to C programmers.
 
 @menu
-* Building Emacs::      How to the dumped Emacs is made.
+* Building Emacs::      How the dumped Emacs is made.
 * Pure Storage::        A kludge to make preloaded Lisp functions sharable.
 * Garbage Collection::  Reclaiming space for Lisp objects no longer used.
 * Memory Usage::        Info about total size of Lisp objects made so far.
@@ -81,8 +81,9 @@
 
   After @file{loadup.el} reads @file{site-load.el}, it finds the
 documentation strings for primitive and preloaded functions (and
-variables) in the file @file{etc/DOC} where they are stored, by calling
-@code{Snarf-documentation} (@pxref{Accessing Documentation}).
+variables) in the file @file{etc/DOC} where they are stored, by
+calling @code{Snarf-documentation} (@pxref{Definition of
+Snarf-documentation,, Accessing Documentation}).
 
 @cindex @file{site-init.el}
   You can specify other Lisp expressions to execute just before dumping
@@ -151,10 +152,10 @@
 @defun purecopy object
 This function makes a copy in pure storage of @var{object}, and returns
 it.  It copies a string by simply making a new string with the same
-characters in pure storage.  It recursively copies the contents of
-vectors and cons cells.  It does not make copies of other objects such
-as symbols, but just returns them unchanged.  It signals an error if
-asked to copy markers.
+characters, but without text properties, in pure storage.  It
+recursively copies the contents of vectors and cons cells.  It does
+not make copies of other objects such as symbols, but just returns
+them unchanged.  It signals an error if asked to copy markers.
 
 This function is a no-op except while Emacs is being built and dumped;
 it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
@@ -367,7 +368,7 @@
 @code{garbage-collect} will set the threshold back to 10,000.
 @end defopt
 
-  The value return by @code{garbage-collect} describes the amount of
+  The value returned by @code{garbage-collect} describes the amount of
 memory used by Lisp data, broken down by data type.  By contrast, the
 function @code{memory-limit} provides information on the total amount of
 memory Emacs is currently using.
@@ -382,6 +383,12 @@
 memory usage.
 @end defun
 
+@defun memory-use-counts
+This returns a list of numbers that count the number of objects
+created in this Emacs session.  Each of these counters increments for
+a certain kind of object.  See the documentation string for details.
+@end defun
+
 @defvar gcs-done
 This variable contains the total number of garbage collections
 done so far in this Emacs session.
@@ -563,6 +570,8 @@
 @samp{usage:}, the rest of the line is treated as the argument list
 for documentation purposes.  This way, you can use different argument
 names in the documentation string from the ones used in the C code.
+@samp{usage:} is required if the function has an unlimited number of
+arguments.
 
 All the usual rules for documentation strings in Lisp code
 (@pxref{Documentation Tips}) apply to C code documentation strings
@@ -593,9 +602,9 @@
 GC-protected; as long as the object is not recycled, all pointers to
 it remain valid.  So if you are sure that a local variable points to
 an object that will be preserved by some other pointer, that local
-variable does not need a GCPRO.  (Formerly, strings were an exception
-to this rule; in older Emacs versions, every pointer to a string
-needed to be marked by GC.)
+variable does not need a @code{GCPRO}.  (Formerly, strings were an
+exception to this rule; in older Emacs versions, every pointer to a
+string needed to be marked by GC.)
 
   The macro @code{GCPRO1} protects just one local variable.  If you
 want to protect two, use @code{GCPRO2} instead; repeating
@@ -610,7 +619,7 @@
 accept two arguments at the C level: the number of Lisp arguments, and
 a @code{Lisp_Object *} pointer to a C vector containing those Lisp
 arguments.  This C vector may be part of a Lisp vector, but it need
-not be.  The responsibility for using GCPRO to protecting the Lisp
+not be.  The responsibility for using @code{GCPRO} to protect the Lisp
 arguments from GC if necessary rests with the caller in this case,
 since the caller allocated or found the storage for them.
 
@@ -649,6 +658,7 @@
 of these functions are called, and add a call to
 @code{syms_of_@var{filename}} there.
 
+@anchor{Defining Lisp variables in C}
 @vindex byte-boolean-vars
   The function @code{syms_of_@var{filename}} is also the place to define
 any C variables that are to be visible as Lisp variables.
@@ -746,10 +756,10 @@
 @file{lisp.h} contains the definitions for some important macros and
 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
-@code{side-effect-and-error-free-fns} to include it.  This will help the
-optimizer.
+  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
+@code{side-effect-and-error-free-fns} so that the compiler optimizer
+knows about it.
 
 @node Object Internals
 @appendixsec Object Internals
@@ -759,9 +769,9 @@
 data are stored in a heap and the only access that programs have to it
 is through pointers.  Pointers are thirty-two bits wide in most
 implementations.  Depending on the operating system and type of machine
-for which you compile Emacs, twenty-eight bits are used to address the
-object, and the remaining four bits are used for a GC mark bit and the
-tag that identifies the object's type.
+for which you compile Emacs, twenty-nine bits are used to address the
+object, and the remaining three bits are used for the tag that
+identifies the object's type.
 
   Because Lisp objects are represented as tagged pointers, it is always
 possible to determine the Lisp data type of any object.  The C data type
@@ -1287,7 +1297,7 @@
 
 @item redisplay_end_trigger
 If redisplay in this window goes beyond this buffer position, it runs
-run the @code{redisplay-end-trigger-hook}.
+the @code{redisplay-end-trigger-hook}.
 
 @ignore
 @item orig_height
@@ -1386,7 +1396,7 @@
 The associated buffer of the process.
 
 @item pid
-An integer, the Unix process @sc{id}.
+An integer, the operating system's process @acronym{ID}.
 
 @item childp
 A flag, non-@code{nil} if this is really a child process.
@@ -1416,7 +1426,7 @@
 message in the process buffer.
 
 @item pty_flag
-Non-@code{nil} if communication with the subprocess uses a @sc{pty};
+Non-@code{nil} if communication with the subprocess uses a @acronym{PTY};
 @code{nil} if it uses a pipe.
 
 @item infd
@@ -1456,3 +1466,7 @@
 Flag to set @code{coding-system} of the process buffer from the
 coding system used to decode process output.
 @end table
+
+@ignore
+   arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
+@end ignore

--- a/lispref/intro.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/intro.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -132,8 +132,7 @@
 
 @pindex cl
   A certain amount of Common Lisp emulation is available via the
-@file{cl} library.  @xref{Top,, Common Lisp Extension, cl, Common Lisp
-Extensions}.
+@file{cl} library.  @inforef{Top, Overview, cl}.
 
   Emacs Lisp is not at all influenced by Scheme; but the GNU project has
 an implementation of Scheme, called Guile.  We use Guile in all new GNU
@@ -476,7 +475,7 @@
   These facilities provide information about which version of Emacs is
 in use.
 
-@deffn Command emacs-version
+@deffn Command emacs-version &optional here
 This function returns a string describing the version of Emacs that is
 running.  It is useful to include this string in bug reports.
 
@@ -488,8 +487,10 @@
 @end group
 @end smallexample
 
-Called interactively, the function prints the same information in the
-echo area.
+If @var{here} is non-@code{nil}, it inserts the text in the buffer
+before point, and returns @code{nil}.  Called interactively, the
+function prints the same information in the echo area, but giving a
+prefix argument makes @var{here} non-@code{nil}.
 @end deffn
 
 @defvar emacs-build-time
@@ -548,3 +549,7 @@
 Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp,
 Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty,
 Dale Worley, Rusty Wright, and David D. Zuhn.
+
+@ignore
+   arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa
+@end ignore

--- a/lispref/keymaps.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/keymaps.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -28,6 +28,7 @@
 * Key Lookup::                  How extracting elements from keymaps works.
 * Functions for Key Lookup::    How to request key lookup.
 * Changing Key Bindings::       Redefining a key in a keymap.
+* Remapping Commands::          Bindings that translate one command to another.
 * Key Binding Commands::        Interactive interfaces for redefining keys.
 * Scanning Keymaps::            Looking through all keymaps, for printing help.
 * Menu Keymaps::		Defining a menu as a keymap.
@@ -124,27 +125,24 @@
 to enumerate all of them.  A keymap that has a default binding
 completely masks any lower-precedence keymap.
 
-@item @var{vector}
-If an element of a keymap is a vector, the vector counts as bindings for
-all the @sc{ascii} characters, codes 0 through 127; vector element
-@var{n} is the binding for the character with code @var{n}.  This is a
-compact way to record lots of bindings.  A keymap with such a vector is
-called a @dfn{full keymap}.  Other keymaps are called @dfn{sparse
-keymaps}.
-
-A @code{nil} binding is used to mean that a key is explicitly not bound.
-Just like any other binding, it takes precedence over a default binding
-or a binding in the parent keymap, but on the other hand, it does not
-take precedence over keymaps of lower priority.
-
-When a keymap contains a vector, it always defines a binding for each
-@sc{ascii} character, even if the vector contains @code{nil} for that
-character.  Such a binding of @code{nil} overrides any default key
-binding in the keymap, for @sc{ascii} characters.  However, default
-bindings are still meaningful for events other than @sc{ascii}
-characters.  A binding of @code{nil} does @emph{not} override
-lower-precedence keymaps; thus, if the local map gives a binding of
-@code{nil}, Emacs uses the binding from the global map.
+@item @var{char-table}
+If an element of a keymap is a char-table, it counts as holding
+bindings for all character events with no modifier bits
+(@pxref{modifier bits}): element @var{n} is the binding for the
+character with code @var{n}.  This is a compact way to record lots of
+bindings.  A keymap with such a char-table is called a @dfn{full
+keymap}.  Other keymaps are called @dfn{sparse keymaps}.
+
+When a keymap contains a char-table vector, it always defines a
+binding for each character without modifiers.  However, if the binding
+is @code{nil}, it doesn't constitute a definition.  @code{nil} takes
+precedence over a default binding or a binding in the parent keymap.
+So in a full keymap, default bindings are not meaningful for
+characters without modifiers.  They can still apply to characters with
+modifier bits and to non-character events.  A binding of @code{nil}
+does @emph{not} override lower-precedence keymaps; thus, if the local
+map gives a binding of @code{nil}, Emacs uses the binding from the
+global map.
 
 @item @var{string}
 @cindex keymap prompt string
@@ -233,9 +231,9 @@
 @defun make-keymap &optional prompt
 This function creates and returns a new full keymap.  That keymap
 contains a char-table (@pxref{Char-Tables}) with 384 slots: the first
-128 slots are for defining all the @sc{ascii} characters, the next 128
+128 slots are for defining all the @acronym{ASCII} characters, the next 128
 slots are for 8-bit European characters, and each one of the final 128
-slots is for one character set of non-@sc{ascii} characters supported by
+slots is for one character set of non-@acronym{ASCII} characters supported by
 Emacs.  The new keymap initially binds all these characters to
 @code{nil}, and does not bind any other kind of event.
 
@@ -530,7 +528,8 @@
 
   The variable @code{overriding-local-map}, if non-@code{nil}, specifies
 another local keymap that overrides the buffer's local map and all the
-minor mode keymaps.
+minor mode keymaps.  Modes for emulation can specify additional
+active keymaps through the variable @code{emulation-mode-map-alists}.
 
   All the active keymaps are used together to determine what command to
 execute when a key is entered.  Emacs searches these maps one by one, in
@@ -594,7 +593,7 @@
 This function returns the current buffer's local keymap, or @code{nil}
 if it has none.  In the following example, the keymap for the
 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
-in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse
+in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
 keymap.
 
 @example
@@ -714,6 +713,16 @@
 event is run directly by @code{read-event}.  @xref{Special Events}.
 @end defvar
 
+@defvar emulation-mode-map-alists
+This variable holds a list of keymap alists to use for emulations
+modes.  It is intended for modes or packages using multiple minor-mode
+keymaps.  Each element is a keymap alist which has the same format and
+meaning as @code{minor-mode-map-alist}, or a symbol with a variable
+binding which is such an alist.  The ``active'' keymaps in each alist
+are used before @code{minor-mode-map-alist} and
+@code{minor-mode-overriding-map-alist}.
+@end defvar
+
 @node Key Lookup
 @section Key Lookup
 @cindex key lookup
@@ -918,7 +927,7 @@
 not cause an error.
 @end deffn
 
-@defun key-binding key &optional accept-defaults
+@defun key-binding key &optional accept-defaults no-remap
 This function returns the binding for @var{key} in the current
 keymaps, trying all the active keymaps.  The result is @code{nil} if
 @var{key} is undefined in the keymaps.
@@ -927,6 +936,12 @@
 The argument @var{accept-defaults} controls checking for default
 bindings, as in @code{lookup-key} (above).
 
+When commands are remapped (@pxref{Remapping Commands}),
+@code{key-binding} normally processes command remappings so as to
+returns the remapped command that will actually be executed.  However,
+if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
+remappings and returns the binding directly specified for @var{key}.
+
 An error is signaled if @var{key} is not a string or a vector.
 
 @example
@@ -984,7 +999,7 @@
 translating a meta character to a two-character sequence so it can be
 looked up in a keymap.  For useful results, the value should be a prefix
 event (@pxref{Prefix Keys}).  The default value is 27, which is the
-@sc{ascii} code for @key{ESC}.
+@acronym{ASCII} code for @key{ESC}.
 
 As long as the value of @code{meta-prefix-char} remains 27, key lookup
 translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
@@ -1150,6 +1165,12 @@
 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
 default global map.
 
+  The function @code{substitute-key-definition} scans a keymap for
+keys that have a certain binding and rebind them with a different
+binding.  Another feature you can use for similar effects, but which
+is often cleaner, is to add a binding that remaps a command
+(@pxref{Remapping Commands}).
+
 @defun substitute-key-definition olddef newdef keymap &optional oldmap
 @cindex replace bindings
 This function replaces @var{olddef} with @var{newdef} for any keys in
@@ -1184,13 +1205,6 @@
 puts the special deletion command in @code{my-map} for whichever keys
 are globally bound to the standard deletion command.
 
-@ignore
-@c Emacs 18 only
-Prefix keymaps that appear within @var{keymap} are not checked
-recursively for keys bound to @var{olddef}; they are not changed at all.
-Perhaps it would be better to check nested keymaps recursively.
-@end ignore
-
 Here is an example showing a keymap before and after substitution:
 
 @smallexample
@@ -1259,6 +1273,56 @@
 @end smallexample
 @end defun
 
+@node Remapping Commands
+@section Remapping Commands
+@cindex remapping commands
+
+  A special kind of key binding, using a special ``key sequence''
+which includes a command name, has the effect of @dfn{remapping} that
+command into another.  Here's how it works.  You make a key binding
+for a key sequence that starts with the dummy event @code{remap},
+followed by the command name you want to remap.  Specify the remapped
+definition as the definition in this binding.  The remapped definition
+is usually a command name, but it can be any valid definition for
+a key binding.
+
+  Here's an example.  Suppose that My mode uses special commands
+@code{my-kill-line} and @code{my-kill-word}, which should be invoked
+instead of @code{kill-line} and @code{kill-word}.  It can establish
+this by making these two command-remapping bindings in its keymap:
+
+@example
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap kill-word] 'my-kill-word)
+@end example
+
+Whenever @code{my-mode-map} is an active keymap, if the user types
+@kbd{C-k}, Emacs will find the standard global binding of
+@code{kill-line} (assuming nobody has changed it).  But
+@code{my-mode-map} remaps @code{kill-line} to @code{my-mode-map},
+so instead of running @code{kill-line}, Emacs runs
+@code{my-kill-line}.
+
+Remapping only works through a single level.  In other words,
+
+@example
+(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
+
+@noindent
+does not have the effect of remapping @code{kill-line} into
+@code{my-other-kill-line}.  If an ordinary key binding specifies 
+@code{kill-line}, this keymap will remap it to @code{my-kill-line};
+if an ordinary binding specifies @code{my-kill-line}, this keymap will
+remap it to @code{my-other-kill-line}.
+
+@defun command-remapping command
+This function returns the remapping for @var{command}, given the
+current active keymaps.  If @var{command} is not remapped (which is
+the usual situation), the function returns @code{nil}.
+@end defun
+
 @node Key Binding Commands
 @section Commands for Binding Keys
 
@@ -1297,8 +1361,8 @@
 redefines the first (leftmost) mouse button, typed with the Meta key, to
 set point where you click.
 
-@cindex non-@sc{ascii} text in keybindings
-  Be careful when using non-@sc{ascii} text characters in Lisp
+@cindex non-@acronym{ASCII} text in keybindings
+  Be careful when using non-@acronym{ASCII} text characters in Lisp
 specifications of keys to bind.  If these are read as multibyte text, as
 they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
 must type the keys as multibyte too.  For instance, if you use this:
@@ -1488,7 +1552,7 @@
 in a keymap.
 @end defun
 
-@defun where-is-internal command &optional keymap firstonly noindirect
+@defun where-is-internal command &optional keymap firstonly noindirect no-remap
 This function is a subroutine used by the @code{where-is} command
 (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list
 of key sequences (of any length) that are bound to @var{command} in a
@@ -1512,13 +1576,20 @@
 string representing the first key sequence found, rather than a list of
 all possible key sequences.  If @var{firstonly} is @code{t}, then the
 value is the first key sequence, except that key sequences consisting
-entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
+entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
 characters) are preferred to all other key sequences.
 
 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
 follow indirect keymap bindings.  This makes it possible to search for
 an indirect definition itself.
 
+When command remapping is in effect (@pxref{Remapping Commands}),
+@code{where-is-internal} figures out when a command will be run due to
+remapping and reports keys accordingly.  It also returns @code{nil} if
+@var{command} won't really be run because it has been remapped to some
+other command.  However, if @var{no-remap} is non-@code{nil}.
+@code{where-is-internal} ignores remappings.
+
 @smallexample
 @group
 (where-is-internal 'describe-function)
@@ -1538,13 +1609,13 @@
 The listing describes meta characters as @key{ESC} followed by the
 corresponding non-meta character.
 
-When several characters with consecutive @sc{ascii} codes have the
+When several characters with consecutive @acronym{ASCII} codes have the
 same definition, they are shown together, as
 @samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
-know the @sc{ascii} codes to understand which characters this means.
+know the @acronym{ASCII} codes to understand which characters this means.
 For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line.  @key{SPC} is @sc{ascii} 32,
-@kbd{~} is @sc{ascii} 126, and the characters between them include all
+..@: ~} are described by a single line.  @key{SPC} is @acronym{ASCII} 32,
+@kbd{~} is @acronym{ASCII} 126, and the characters between them include all
 the normal printing characters, (e.g., letters, digits, punctuation,
 etc.@:); all these characters are bound to @code{self-insert-command}.
 @end deffn
@@ -1623,7 +1694,12 @@
 @noindent
 The @sc{car}, @var{item-string}, is the string to be displayed in the
 menu.  It should be short---preferably one to three words.  It should
-describe the action of the command it corresponds to.
+describe the action of the command it corresponds to.  Note that it is
+not generally possible to display non-@acronym{ASCII} text in menus.  It will
+work for keyboard menus and will work to a large extent when Emacs is
+built with Gtk+ support.@footnote{In this case, the text is first
+encoded using the @code{utf-8} coding system and then rendered by the
+toolkit as it sees fit.}
 
 You can also supply a second string, called the help string, as follows:
 
@@ -2248,7 +2324,7 @@
 @tindex tool-bar-add-item
 This function adds an item to the tool bar by modifying
 @code{tool-bar-map}.  The image to use is defined by @var{icon}, which
-is the base name of an XPM, XBM or PBM image file to located by
+is the base name of an XPM, XBM or PBM image file to be located by
 @code{find-image}.  Given a value @samp{"exit"}, say, @file{exit.xpm},
 @file{exit.pbm} and @file{exit.xbm} would be searched for in that order
 on a color display.  On a monochrome display, the search order is
@@ -2257,7 +2333,7 @@
 prefix keymap.  The remaining arguments @var{props} are additional
 property list elements to add to the menu item specification.
 
-To define items in some local map, bind @code{`tool-bar-map} with
+To define items in some local map, bind @code{tool-bar-map} with
 @code{let} around calls of this function:
 @example
 (defvar foo-tool-bar-map
@@ -2270,15 +2346,26 @@
 
 @defun tool-bar-add-item-from-menu command icon &optional map &rest props
 @tindex tool-bar-add-item-from-menu
-This command is a convenience for defining tool bar items which are
+This function is a convenience for defining tool bar items which are
 consistent with existing menu bar bindings.  The binding of
 @var{command} is looked up in the menu bar in @var{map} (default
 @code{global-map}) and modified to add an image specification for
-@var{icon}, which is looked for in the same way as by
+@var{icon}, which is found in the same way as by
 @code{tool-bar-add-item}.  The resulting binding is then placed in
-@code{tool-bar-map}.  @var{map} must contain an appropriate keymap bound
-to @code{[menu-bar]}.  The remaining arguments @var{props} are
-additional property list elements to add to the menu item specification.
+@code{tool-bar-map}, so use this function only for global tool bar
+items.
+
+@var{map} must contain an appropriate keymap bound to
+@code{[menu-bar]}.  The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+@end defun
+
+@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
+This function is used for making non-global tool bar items.  Use it
+like @code{tool-bar-add-item-from-menu} except that @var{in-map}
+specifies the local map to make the definition in.  The argument
+@var{from-map} si like the @var{map} argument of
+@code{tool-bar-add-item-from-menu}.
 @end defun
 
 @tindex auto-resize-tool-bar
@@ -2288,22 +2375,22 @@
 frame's height.
 @end defvar
 
-@tindex auto-raise-tool-bar-items
-@defvar auto-raise-tool-bar-items
+@tindex auto-raise-tool-bar-buttons
+@defvar auto-raise-tool-bar-buttons
 If this variable is non-@code{nil}, tool bar items display
 in raised form when the mouse moves over them.
 @end defvar
 
-@tindex tool-bar-item-margin
-@defvar tool-bar-item-margin
+@tindex tool-bar-button-margin
+@defvar tool-bar-button-margin
 This variable specifies an extra margin to add around tool bar items.
-The value is an integer, a number of pixels.  The default is 1.
+The value is an integer, a number of pixels.  The default is 4.
 @end defvar
 
-@tindex tool-bar-item-relief
-@defvar tool-bar-item-relief
+@tindex tool-bar-button-relief
+@defvar tool-bar-button-relief
 This variable specifies the shadow width for tool bar items.
-The value is an integer, a number of pixels.  The default is 3.
+The value is an integer, a number of pixels.  The default is 1.
 @end defvar
 
   You can define a special meaning for clicking on a tool bar item with
@@ -2371,3 +2458,7 @@
   [work] '("Work" . work-command) 'break)
 @end example
 @end defun
+
+@ignore
+   arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
+@end ignore

--- a/lispref/lay-flat.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/lay-flat.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -37,3 +37,7 @@
 @end tex
 
 @bye
+
+@ignore
+   arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07
+@end ignore

--- a/lispref/lists.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/lists.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -448,11 +448,11 @@
 code for Emacs than @code{cons}.
 
 @defun cons object1 object2
-This function is the fundamental function used to build new list
+This function is the most basic function for building new list
 structure.  It creates a new cons cell, making @var{object1} the
-@sc{car}, and @var{object2} the @sc{cdr}.  It then returns the new cons
-cell.  The arguments @var{object1} and @var{object2} may be any Lisp
-objects, but most often @var{object2} is a list.
+@sc{car}, and @var{object2} the @sc{cdr}.  It then returns the new
+cons cell.  The arguments @var{object1} and @var{object2} may be any
+Lisp objects, but most often @var{object2} is a list.
 
 @example
 @group
@@ -568,14 +568,13 @@
 ``dotted list'' since its final @sc{cdr} is not @code{nil} as required
 in a true list.
 
-The @code{append} function also allows integers as arguments.  It
-converts them to strings of digits, making up the decimal print
-representation of the integer, and then uses the strings instead of the
-original integers.  @strong{Don't use this feature; we plan to eliminate
-it.  If you already use this feature, change your programs now!}  The
-proper way to convert an integer to a decimal number in this way is with
-@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
-(@pxref{String Conversion}).
+In Emacs 20 and before, the @code{append} function also allowed
+integers as (non last) arguments.  It converted them to strings of
+digits, making up the decimal print representation of the integer, and
+then used the strings instead of the original integers.  This obsolete
+usage no longer works.  The proper way to convert an integer to a
+decimal number in this way is with @code{format} (@pxref{Formatting
+Strings}) or @code{number-to-string} (@pxref{String Conversion}).
 @end defun
 
   Here is an example of using @code{append}:
@@ -708,40 +707,55 @@
 @end example
 @end defun
 
-@defun remq object list
-This function returns a copy of @var{list}, with all elements removed
-which are @code{eq} to @var{object}.  The letter @samp{q} in @code{remq}
-says that it uses @code{eq} to compare @var{object} against the elements
-of @code{list}.
+@defun copy-tree tree &optional vecp
+This function returns a copy the tree @code{tree}.  If @var{tree} is a
+cons cell, this makes a new cons cell with the same @sc{car} and
+@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the
+same way.
 
-@example
-@group
-(setq sample-list '(a b c a b c))
-     @result{} (a b c a b c)
-@end group
-@group
-(remq 'a sample-list)
-     @result{} (b c b c)
-@end group
-@group
-sample-list
-     @result{} (a b c a b c)
-@end group
-@end example
-@noindent
-The function @code{delq} offers a way to perform this operation
-destructively.  See @ref{Sets And Lists}.
+Normally, when @var{tree} is anything other than a cons cell,
+@code{copy-tree} simply returns @var{tree}.  However, if @var{vecp} is
+non-@code{nil}, it copies vectors too (and operates recursively on
+their elements).
 @end defun
 
-@defun number-sequence from to &optional separation
-This returns a list of numbers starting with @var{from}
-and incrementing by @var{separation} (or by 1 if @var{separation}
-is @code{nil} or omitted), and ending at or just before @var{to}.
-For example,
+@defun number-sequence from &optional to separation
+This returns a list of numbers starting with @var{from} and
+incrementing by @var{separation}, and ending at or just before
+@var{to}.  @var{separation} can be positive or negative and defaults
+to 1.  If @var{to} is @code{nil} or numerically equal to @var{from},
+the one element list @code{(from)} is returned.  If @var{separation}
+is 0 and @var{to} is neither @code{nil} nor numerically equal to
+@var{from}, an error is signaled.
+
+All arguments can be integers or floating point numbers.  However,
+floating point arguments can be tricky, because floating point
+arithmetic is inexact.  For instance, depending on the machine, it may
+quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns
+the one element list @code{(0.4)}, whereas 
+@code{(number-sequence 0.4 0.8 0.2)} returns a list with three
+elements.  The @var{n}th element of the list is computed by the exact
+formula @code{(+ @var{from} (* @var{n} @var{separation}))}.  Thus, if
+one wants to make sure that @var{to} is included in the list, one can
+pass an expression of this exact type for @var{to}.  Alternatively,
+one can replace @var{to} with a slightly larger value (or a slightly
+more negative value if @var{separation} is negative).
+
+Some examples:
 
 @example
 (number-sequence 4 9)
      @result{} (4 5 6 7 8 9)
+(number-sequence 9 4 -1)
+     @result{} (9 8 7 6 5 4)
+(number-sequence 9 4 -2)
+     @result{} (9 7 5)
+(number-sequence 8)
+     @result{} (8)
+(number-sequence 8 5)
+     @result{} nil
+(number-sequence 5 8 -1)
+     @result{} nil
 (number-sequence 1.5 6 2)
      @result{} (1.5 3.5 5.5)
 @end example
@@ -1209,7 +1223,8 @@
   A list can represent an unordered mathematical set---simply consider a
 value an element of a set if it appears in the list, and ignore the
 order of the list.  To form the union of two sets, use @code{append} (as
-long as you don't mind having duplicate elements).  Other useful
+long as you don't mind having duplicate elements).  You can remove
+@code{equal} duplicates using @code{delete-dups}.  Other useful
 functions for sets include @code{memq} and @code{delq}, and their
 @code{equal} versions, @code{member} and @code{delete}.
 
@@ -1241,13 +1256,6 @@
 @end example
 @end defun
 
-@defun member-ignore-case object list
-This function is like @code{member}, except that it ignores
-differences in letter-case and text representation: upper-case and
-lower-case letters are treated as equal, and unibyte strings are
-converted to multibyte prior to comparison.
-@end defun
-
 @defun delq object list
 @cindex deletion of elements
 This function destructively removes all elements @code{eq} to
@@ -1314,9 +1322,34 @@
 @end group
 @end example
 
-The following two functions are like @code{memq} and @code{delq} but use
-@code{equal} rather than @code{eq} to compare elements.  @xref{Equality
-Predicates}.
+@defun remq object list
+This function returns a copy of @var{list}, with all elements removed
+which are @code{eq} to @var{object}.  The letter @samp{q} in @code{remq}
+says that it uses @code{eq} to compare @var{object} against the elements
+of @code{list}.
+
+@example
+@group
+(setq sample-list '(a b c a b c))
+     @result{} (a b c a b c)
+@end group
+@group
+(remq 'a sample-list)
+     @result{} (b c b c)
+@end group
+@group
+sample-list
+     @result{} (a b c a b c)
+@end group
+@end example
+@noindent
+The function @code{delq} offers a way to perform this operation
+destructively.  See @ref{Sets And Lists}.
+@end defun
+
+The following three functions are like @code{memq}, @code{delq} and
+@code{remq}, but use @code{equal} rather than @code{eq} to compare
+elements.  @xref{Equality Predicates}.
 
 @defun member object list
 The function @code{member} tests to see whether @var{object} is a member
@@ -1393,6 +1426,21 @@
 elements.
 @end quotation
 
+@defun member-ignore-case object list
+This function is like @code{member}, except that @var{object} should
+be a string and that it ignores differences in letter-case and text
+representation: upper-case and lower-case letters are treated as
+equal, and unibyte strings are converted to multibyte prior to
+comparison.
+@end defun
+
+@defun delete-dups list
+This function destructively removes all @code{equal} duplicates from
+@var{list}, stores the result in @var{list} and returns it.  Of
+several @code{equal} occurrences of an element in @var{list},
+@code{delete-dups} keeps the first one.
+@end defun
+
   See also the function @code{add-to-list}, in @ref{Setting Variables},
 for another way to add an element to a list stored in a variable.
 
@@ -1501,9 +1549,9 @@
 @end smallexample
 @end defun
 
-  The functions @code{assoc-ignore-representation} and
-@code{assoc-ignore-case} are much like @code{assoc} except using
-@code{compare-strings} to do the comparison.  @xref{Text Comparison}.
+  The function @code{assoc-string} is much like @code{assoc} except
+that it ignores certain differences between strings.  @xref{Text
+Comparison}.
 
 @defun rassoc value alist
 This function returns the first association with value @var{value} in
@@ -1658,13 +1706,22 @@
 @defun assq-delete-all key alist
 @tindex assq-delete-all
 This function deletes from @var{alist} all the elements whose @sc{car}
-is @code{eq} to @var{key}.  It returns @var{alist}, modified
-in this way.  Note that it modifies the original list structure
-of @var{alist}.
+is @code{eq} to @var{key}, much as if you used @code{delq} to delete
+each such element one by one.  It returns the shortened alist, and
+often modifies the original list structure of @var{alist}.  For
+correct results, use the return value of @code{assq-delete-all} rather
+than looking at the saved value of @var{alist}.
 
 @example
-(assq-delete-all 'foo
-                 '((foo 1) (bar 2) (foo 3) (lose 4)))
+(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
+     @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
+(assq-delete-all 'foo alist)
      @result{} ((bar 2) (lose 4))
+alist
+     @result{} ((foo 1) (bar 2) (lose 4))
 @end example
 @end defun
+
+@ignore
+   arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4
+@end ignore

--- a/lispref/loading.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/loading.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -37,7 +37,7 @@
 @menu
 * How Programs Do Loading::     The @code{load} function and others.
 * Library Search::              Finding a library to load.
-* Loading Non-ASCII::           Non-@sc{ascii} characters in Emacs Lisp files.
+* Loading Non-ASCII::           Non-@acronym{ASCII} characters in Emacs Lisp files.
 * Autoload::                    Setting up a function to autoload.
 * Repeated Loading::            Precautions about loading a file twice.
 * Named Features::              Loading a library if it isn't already loaded.
@@ -140,6 +140,7 @@
 file, and it is @code{nil} otherwise.
 @end defvar
 
+@anchor{Definition of load-read-function}
 @defvar load-read-function
 This variable specifies an alternate expression-reading function for
 @code{load} and @code{eval-region} to use instead of @code{read}.
@@ -148,9 +149,9 @@
 Normally, the variable's value is @code{nil}, which means those
 functions should use @code{read}.
 
-@strong{Note:} Instead of using this variable, it is cleaner to use
-another, newer feature: to pass the function as the @var{read-function}
-argument to @code{eval-region}.  @xref{Eval}.
+Instead of using this variable, it is cleaner to use another, newer
+feature: to pass the function as the @var{read-function} argument to
+@code{eval-region}.  @xref{Definition of eval-region,, Eval}.
 @end defvar
 
   For information about how @code{load} is used in building Emacs, see
@@ -172,7 +173,7 @@
 
   The value of @code{load-path} is initialized from the environment
 variable @code{EMACSLOADPATH}, if that exists; otherwise its default
-value is specified in @file{emacs/src/paths.h} when Emacs is built.
+value is specified in @file{emacs/src/epaths.h} when Emacs is built.
 Then the list is expanded by adding subdirectories of the directories
 in the list.
 
@@ -289,13 +290,13 @@
 @defvar load-suffixes
 This variable is a list of suffixes (strings) that @code{load} should
 try adding to the specified file name.  The default value is
-@code{(".el" ".elc")}.  There is no need to include the null suffix.
+@code{(".elc" ".el")}.  There is no need to include the null suffix.
 @end defvar
 
 @node Loading Non-ASCII
-@section Loading Non-@sc{ascii} Characters
+@section Loading Non-@acronym{ASCII} Characters
 
-  When Emacs Lisp programs contain string constants with non-@sc{ascii}
+  When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
 characters, these can be represented within Emacs either as unibyte
 strings or as multibyte strings (@pxref{Text Representations}).  Which
 representation is used depends on how the file is read into Emacs.  If
@@ -309,7 +310,7 @@
   To make the results more predictable, Emacs always performs decoding
 into the multibyte representation when loading Lisp files, even if it
 was started with the @samp{--unibyte} option.  This means that string
-constants with non-@sc{ascii} characters translate into multibyte
+constants with non-@acronym{ASCII} characters translate into multibyte
 strings.  The only exception is when a particular file specifies no
 decoding.
 
@@ -321,7 +322,7 @@
 @code{default-enable-multibyte-characters}, and convert representations
 appropriately.
 
-  In most Emacs Lisp programs, the fact that non-@sc{ascii} strings are
+  In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
 multibyte strings should not be noticeable, since inserting them in
 unibyte buffers converts them to unibyte automatically.  However, if
 this does make a difference, you can force a particular Lisp file to be
@@ -329,7 +330,7 @@
 comment on the file's first line.  With that designator, the file will
 unconditionally be interpreted as unibyte, even in an ordinary
 multibyte Emacs session.  This can matter when making keybindings to
-non-@sc{ascii} characters written as @code{?v@var{literal}}.
+non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
 
 @node Autoload
 @section Autoload
@@ -656,6 +657,7 @@
 
 If provided, @var{subfeatures} should be a list of symbols indicating
 a set of specific subfeatures provided by this version of @var{feature}.
+You can test the presence of a subfeature using @code{featurep}.
 
 @smallexample
 features
@@ -668,7 +670,7 @@
 @end smallexample
 
 When a file is loaded to satisfy an autoload, and it stops due to an
-error in the evaluating its contents, any function definitions or
+error in the evaluation of its contents, any function definitions or
 @code{provide} calls that occurred during the load are undone.
 @xref{Autoload}.
 @end defun
@@ -723,12 +725,14 @@
 It then restores any autoloads formerly associated with those symbols.
 (Loading saves these in the @code{autoload} property of the symbol.)
 
+@vindex unload-feature-special-hooks
 Before restoring the previous definitions, @code{unload-feature} runs
 @code{remove-hook} to remove functions in the library from certain
-hooks.  These hooks include variables whose names end in @samp{hook} or
-@samp{-hooks}, plus those listed in @code{loadhist-special-hooks}.  This
-is to prevent Emacs from ceasing to function because important hooks
-refer to functions that are no longer defined.
+hooks.  These hooks include variables whose names end in @samp{hook}
+or @samp{-hooks}, plus those listed in
+@code{unload-feature-special-hooks}.  This is to prevent Emacs from
+ceasing to function because important hooks refer to functions that
+are no longer defined.
 
 @vindex @var{feature}-unload-hook
 If these measures are not sufficient to prevent malfunction, a library
@@ -786,18 +790,7 @@
 by adding the symbols defined to the element for the file being visited,
 rather than replacing that element.  @xref{Eval}.
 
-  Preloaded libraries don't contribute initially to @code{load-history}.
-Instead, preloading writes information about preloaded libraries into a
-file, which can be loaded later on to add information to
-@code{load-history} describing the preloaded files.  This file is
-installed in @code{exec-directory} and has a name of the form
-@file{fns-@var{emacsversion}.el}.
-
-@findex symbol-file
-  See the source for the function @code{symbol-file}, for an example of
-code that loads this file to find functions in preloaded libraries.
-
-@defvar loadhist-special-hooks
+@defvar unload-feature-special-hooks
 This variable holds a list of hooks to be scanned before unloading a
 library, to remove functions defined in the library.
 @end defvar
@@ -852,3 +845,7 @@
 @end defvar
 
 @c Emacs 19 feature
+
+@ignore
+   arch-tag: df731f89-0900-4389-a436-9105241b6f7a
+@end ignore

--- a/lispref/locals.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/locals.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -79,7 +79,7 @@
 @xref{Comments,,, emacs, The GNU Emacs Manual}.
 
 @item default-directory
-@xref{System Environment}.
+@xref{File Name Expansion}.
 
 @item defun-prompt-regexp
 @xref{List Motion}.
@@ -174,3 +174,7 @@
 @item vc-mode
 @xref{Mode Line Variables}.
 @end table
+
+@ignore
+   arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543
+@end ignore

--- a/lispref/macros.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/macros.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2004 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/macros
 @node Macros, Customization, Functions, Top
@@ -30,6 +30,7 @@
 * Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
+* Indenting Macros::        Specifying how to indent macro calls.
 @end menu
 
 @node Simple Macro
@@ -136,6 +137,28 @@
 @end smallexample
 @end defun
 
+
+@defun macroexpand-all form &optional environment
+@cindex macro expansion in entire form
+
+@code{macroexpand-all} expands macros like @code{macroexpand}, but
+will look for and expand all macros in @var{form}, not just at the
+top-level.
+
+In emacs-lisp, @code{macroexpand-all} guarantees that if no macros
+are expanded, the return value will be @code{eq} to @var{form}.
+
+Repeating the example used for @code{macroexpand} above with
+@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does}
+expand the embedded calls to @code{inc}:
+
+@smallexample
+(macroexpand-all '(inc2 r s))
+     @result{} (progn (setq r (1+ r)) (setq s (1+ s)))
+@end smallexample
+
+@end defun
+
 @node Compiling Macros
 @section Macros and Byte Compilation
 @cindex byte-compiling macros
@@ -205,6 +228,41 @@
 called interactively.
 @end defspec
 
+  The body of the macro definition can include a @code{declare} form,
+which can specify how @key{TAB} should indent macro calls, and how to
+step through them for Edebug.
+
+@anchor{Definition of declare}
+@defmac declare @var{specs}@dots{}
+A @code{declare} form is used in a macro definition to specify various
+additional information about it.  Two kinds of specification are
+currently supported:
+
+@table @code
+@item (edebug @var{edebug-form-spec})
+Specify how to step through macro calls for Edebug.
+@xref{Instrumenting Macro Calls}, for more details.
+
+@item (indent @var{indent-spec})
+Specify how to indent calls to this macro.  @xref{Indenting Macros},
+for more details.
+@end table
+
+A @code{declare} form only has its special effect in the body of a
+@code{defmacro} form if it immediately follows the documentation
+string, if present, or the argument list otherwise.  (Strictly
+speaking, @emph{several} @code{declare} forms can follow the
+documentation string or argument list, but since a @code{declare} form
+can have several @var{specs}, they can always be combined into a
+single form.)  When used at other places in a @code{defmacro} form, or
+outside a @code{defmacro} form, @code{declare} just returns @code{nil}
+without evaluating any @var{specs}.
+@end defmac
+
+  No macro absolutely needs a @code{declare} form, because that form
+has no effect on how the macro expands, on what the macro means in the
+program.  It only affects secondary features: indentation and Edebug.
+
 @node Backquote
 @section Backquote
 @cindex backquote (list substitution)
@@ -331,9 +389,9 @@
 @node Wrong Time
 @subsection Wrong Time
 
-  The most common problem in writing macros is doing too some of the
+  The most common problem in writing macros is doing some of the
 real work prematurely---while expanding the macro, rather than in the
-expansion itself.  For instance, one real package had this nmacro
+expansion itself.  For instance, one real package had this macro
 definition:
 
 @example
@@ -636,3 +694,62 @@
 allocation construct.  You wouldn't use @code{setcar} on a constant such
 as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)}
 either.
+
+@node Indenting Macros
+@section Indenting Macros
+
+  You can use the @code{declare} form in the macro definition to
+specify how to @key{TAB} should indent indent calls to the macro.  You
+write it like this:
+
+@example
+(declare (indent @var{indent-spec}))
+@end example
+
+@noindent
+Here are the possibilities for @var{indent-spec}:
+
+@table @asis
+@item @code{nil}
+This is the same as no property---use the standard indentation pattern.
+@item @code{defun}
+Handle this function like a @samp{def} construct: treat the second
+line as the start of a @dfn{body}.
+@item a number, @var{number}
+The first @var{number} arguments of the function are
+@dfn{distinguished} arguments; the rest are considered the body
+of the expression.  A line in the expression is indented according to
+whether the first argument on it is distinguished or not.  If the
+argument is part of the body, the line is indented @code{lisp-body-indent}
+more columns than the open-parenthesis starting the containing
+expression.  If the argument is distinguished and is either the first
+or second argument, it is indented @emph{twice} that many extra columns.
+If the argument is distinguished and not the first or second argument,
+the line uses the standard pattern.
+@item a symbol, @var{symbol}
+@var{symbol} should be a function name; that function is called to
+calculate the indentation of a line within this expression.  The
+function receives two arguments:
+@table @asis
+@item @var{state}
+The value returned by @code{parse-partial-sexp} (a Lisp primitive for
+indentation and nesting computation) when it parses up to the
+beginning of this line.
+@item @var{pos}
+The position at which the line being indented begins.
+@end table
+@noindent
+It should return either a number, which is the number of columns of
+indentation for that line, or a list whose car is such a number.  The
+difference between returning a number and returning a list is that a
+number says that all following lines at the same nesting level should
+be indented just like this one; a list says that following lines might
+call for different indentations.  This makes a difference when the
+indentation is being computed by @kbd{C-M-q}; if the value is a
+number, @kbd{C-M-q} need not recalculate indentation for the following
+lines until the end of the list.
+@end table
+
+@ignore
+   arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b
+@end ignore

--- a/lispref/maps.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/maps.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -187,3 +187,7 @@
 @vindex view-mode-map
 A full keymap used by View mode.
 @end table
+
+@ignore
+   arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9
+@end ignore

--- a/lispref/markers.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/markers.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -28,10 +28,13 @@
 @node Overview of Markers
 @section Overview of Markers
 
-  A marker specifies a buffer and a position in that buffer.  The marker
-can be used to represent a position in the functions that require one,
-just as an integer could be used.  @xref{Positions}, for a complete
-description of positions.
+  A marker specifies a buffer and a position in that buffer.  The
+marker can be used to represent a position in the functions that
+require one, just as an integer could be used.  In that case, the
+marker's buffer is normally ignored.  Of course, a marker used in this
+way usually points to a position in the buffer that the function
+operates on, but that is entirely the programmer's responsibility.
+@xref{Positions}, for a complete description of positions.
 
   A marker has two attributes: the marker position, and the marker
 buffer.  The marker position is an integer that is equivalent (at a
@@ -144,6 +147,9 @@
 accessible portion of the buffer, or to the same place as another given
 marker.
 
+The next four functions all return markers with insertion type
+@code{nil}.  @xref{Marker Insertion Types}.
+
 @defun make-marker
 This function returns a newly created marker that does not point
 anywhere.
@@ -201,7 +207,7 @@
 @end example
 @end defun
 
-@defun copy-marker marker-or-integer insertion-type
+@defun copy-marker marker-or-integer &optional insertion-type
 If passed a marker as its argument, @code{copy-marker} returns a
 new marker that points to the same place and the same buffer as does
 @var{marker-or-integer}.  If passed an integer as its argument,
@@ -331,6 +337,11 @@
 This function reports the current insertion type of @var{marker}.
 @end defun
 
+Most functions that create markers, without an argument allowing to
+specify the insertion type, create them with insertion type
+@code{nil}.  Also, the mark has, by default, insertion type
+@code{nil}.
+
 @node Moving Markers
 @section Moving Marker Positions
 
@@ -432,10 +443,11 @@
 @cindex current buffer mark
 This function returns the current buffer's mark position as an integer.
 
-If the mark is inactive, @code{mark} normally signals an error.
-However, if @var{force} is non-@code{nil}, then @code{mark} returns the
-mark position anyway---or @code{nil}, if the mark is not yet set for
-this buffer.
+If Transient Mark mode is enabled, @code{mark-even-if-inactive} is
+@code{nil} and and the mark is inactive, @code{mark} normally signals
+an error.  However, if @var{force} is non-@code{nil}, then @code{mark}
+returns the mark position anyway---or @code{nil}, if the mark is not
+yet set for this buffer.
 @end defun
 
 @defun mark-marker
@@ -617,20 +629,21 @@
 only those functions specifically related to the region itself are
 described here.
 
+The next two functions signal an error if the mark does not point
+anywhere.  If Transient Mark mode is enabled and
+@code{mark-even-if-inactive} is @code{nil}, they also signal an error
+if the mark is inactive.
+
 @defun region-beginning
 This function returns the position of the beginning of the region (as
 an integer).  This is the position of either point or the mark,
 whichever is smaller.
-
-If the mark does not point anywhere, an error is signaled.
 @end defun
 
 @defun region-end
 This function returns the position of the end of the region (as an
 integer).  This is the position of either point or the mark, whichever is
 larger.
-
-If the mark does not point anywhere, an error is signaled.
 @end defun
 
   Few programs need to use the @code{region-beginning} and
@@ -639,3 +652,7 @@
 to find the beginning and end of the region.  This lets other Lisp
 programs specify the bounds explicitly as arguments.  (@xref{Interactive
 Codes}.)
+
+@ignore
+   arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
+@end ignore

--- a/lispref/minibuf.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/minibuf.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -63,6 +63,11 @@
 just a minibuffer, you can change the minibuffer's size by changing the
 frame's size.
 
+  Use of the minibuffer reads input events, and that alters the values
+of variables such as @code{this-command} and @code{last-command}
+(@pxref{Command Loop Info}).  Your program should bind them around the
+code that uses the minibuffer, if you do not want that to change them.
+
   If a command uses a minibuffer while there is an active minibuffer,
 this is called a @dfn{recursive minibuffer}.  The first minibuffer is
 named @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
@@ -130,13 +135,17 @@
 (@xref{Input Functions}, for information about reading.)
 
 The argument @var{default} specifies a default value to make available
-through the history commands.  It should be a string, or @code{nil}.  If
-@var{read} is non-@code{nil}, then @var{default} is also used as the
-input to @code{read}, if the user enters empty input.  However, in the
-usual case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
-does not return @var{default} when the user enters empty input; it
-returns an empty string, @code{""}.  In this respect, it is different
-from all the other minibuffer input functions in this chapter.
+through the history commands.  It should be a string, or @code{nil}.
+If non-@code{nil}, the user can access it using
+@code{next-history-element}, usually bound in the minibuffer to
+@kbd{M-n}.  If @var{read} is non-@code{nil}, then @var{default} is
+also used as the input to @code{read}, if the user enters empty input.
+(If @var{read} is non-@code{nil} and @var{default} is @code{nil}, empty
+input results in an @code{end-of-file} error.)  However, in the usual
+case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
+ignores @var{default} when the user enters empty input and returns an
+empty string, @code{""}.  In this respect, it is different from all
+the other minibuffer input functions in this chapter.
 
 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
 use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
@@ -166,8 +175,9 @@
 
 Alternatively, @var{initial-contents} can be a cons cell of the form
 @code{(@var{string} . @var{position})}.  This means to insert
-@var{string} in the minibuffer but put point @var{position} characters
-from the beginning, rather than at the end.
+@var{string} in the minibuffer but put point at @emph{one-indexed}
+@var{position} in the minibuffer, rather than at the end.  Any integer
+value less or equal to one puts point at the beginning of the string.
 
 @strong{Usage note:} The @var{initial-contents} argument and the
 @var{default} argument are two alternative features for more or less the
@@ -175,21 +185,21 @@
 to @code{read-from-minibuffer}.  In general, we recommend using
 @var{default}, since this permits the user to insert the default value
 when it is wanted, but does not burden the user with deleting it from
-the minibuffer on other occasions.
+the minibuffer on other occasions.  For an exception to this rule,
+see @ref{Minibuffer History}.
 @end defun
 
 @defun read-string prompt &optional initial history default inherit-input-method
 This function reads a string from the minibuffer and returns it.  The
-arguments @var{prompt} and @var{initial} are used as in
-@code{read-from-minibuffer}.  The keymap used is
-@code{minibuffer-local-map}.
+arguments @var{prompt}, @var{initial}, @var{history} and
+@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
+The keymap used is @code{minibuffer-local-map}.
 
-The optional argument @var{history}, if non-@code{nil}, specifies a
-history list and optionally the initial position in the list.  The
-optional argument @var{default} specifies a default value to return if
-the user enters null input; it should be a string.  The optional
-argument @var{inherit-input-method} specifies whether to inherit the
-current buffer's input method.
+The optional argument @var{default} is used as in
+@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
+specifies a default value to return if the user enters null input.  As
+in @code{read-from-minibuffer} it should be a string, or @code{nil},
+which is equivalent to an empty string.
 
 This function is a simplified interface to the
 @code{read-from-minibuffer} function:
@@ -201,7 +211,7 @@
 (let ((value
        (read-from-minibuffer @var{prompt} @var{initial} nil nil
                              @var{history} @var{default} @var{inherit})))
-  (if (equal value "")
+  (if (and (equal value "") @var{default})
       @var{default}
     value))
 @end group
@@ -211,13 +221,15 @@
 @defvar minibuffer-allow-text-properties
 If this variable is @code{nil}, then @code{read-from-minibuffer} strips
 all text properties from the minibuffer input before returning it.
-Since all minibuffer input uses @code{read-from-minibuffer}, this
-variable applies to all minibuffer input.
-
-Note that the completion functions discard text properties unconditionally,
-regardless of the value of this variable.
+This variable also affects @code{read-string}.  However,
+@code{read-no-blanks-input} (see below), as well as
+@code{read-minibuffer} and related functions (@pxref{Object from
+Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
+functions that do minibuffer input with completion, discard text
+properties unconditionally, regardless of the value of this variable.
 @end defvar
 
+@anchor{Definition of minibuffer-local-map}
 @defvar minibuffer-local-map
 This is the default local keymap for reading from the minibuffer.  By
 default, it makes the following bindings:
@@ -238,10 +250,10 @@
 @item @kbd{M-p}
 @code{previous-history-element}
 
-@item @kbd{M-r}
+@item @kbd{M-s}
 @code{next-matching-history-element}
 
-@item @kbd{M-s}
+@item @kbd{M-r}
 @code{previous-matching-history-element}
 @end table
 @end defvar
@@ -260,11 +272,15 @@
 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
 possible to put a space into the string, by quoting it.
 
+This function discards text properties, regardless of the value of
+@code{minibuffer-allow-text-properties}.
+
 @smallexample
 @group
 (read-no-blanks-input @var{prompt} @var{initial})
 @equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
+(let (minibuffer-allow-text-properties)
+  (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
 @end group
 @end smallexample
 @end defun
@@ -307,7 +323,8 @@
 @group
 (read-minibuffer @var{prompt} @var{initial})
 @equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil t)
+(let (minibuffer-allow-text-properties)
+  (read-from-minibuffer @var{prompt} @var{initial} nil t))
 @end group
 @end smallexample
 
@@ -416,11 +433,16 @@
 
 @item (@var{variable} . @var{startpos})
 Use @var{variable} (a symbol) as the history list, and assume that the
-initial history position is @var{startpos} (an integer, counting from
-zero which specifies the most recent element of the history).
+initial history position is @var{startpos} (a nonnegative integer).
 
-If you specify @var{startpos}, then you should also specify that element
-of the history as the initial minibuffer contents, for consistency.
+Specifying 0 for @var{startpos} is equivalent to just specifying the
+symbol @var{variable}.  @code{previous-history-element} will display
+the most recent element of the history list in the minibuffer.  If you
+specify a positive @var{startpos}, the minibuffer history functions
+behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
+history element currently shown in the minibuffer.  For consistency,
+you should also specify that element of the history as the initial
+minibuffer contents.
 @end table
 
   If you don't specify @var{hist}, then the default history list
@@ -534,8 +556,9 @@
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
 completions of @var{string} in @var{collection}.  The value of
-@var{collection} must be a list of strings, an alist, an obarray, or a
-function that implements a virtual set of strings (see below).
+@var{collection} must be a list of strings, an alist, an obarray, a
+hash table, or a function that implements a virtual set of strings
+(see below).
 
 Completion compares @var{string} against each of the permissible
 completions specified by @var{collection}; if the beginning of the
@@ -547,7 +570,12 @@
 match.
 
 If @var{collection} is an alist (@pxref{Association Lists}), the
-@sc{car}s of the alist elements form the set of permissible completions.
+permissible completions are the elements of the alist that are either
+strings or conses whose @sc{car} is a string.  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, 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
@@ -559,6 +587,9 @@
 empty and then add symbols to it one by one using @code{intern}.
 Also, you cannot intern a given symbol in more than one obarray.
 
+If @var{collection} is a hash table, then the keys that are strings
+are the possible completions.  Other keys are ignored.
+
 You can also use a symbol that is a function as @var{collection}.  Then
 the function is solely responsible for performing completion;
 @code{try-completion} returns whatever this function returns.  The
@@ -568,11 +599,20 @@
 thing in either case.)  @xref{Programmed Completion}.
 
 If the argument @var{predicate} is non-@code{nil}, then it must be a
-function of one argument.  It is used to test each possible match, and
-the match is accepted only if @var{predicate} returns non-@code{nil}.
-The argument given to @var{predicate} is either a string from the
-list, a cons cell from the alist (the @sc{car} of which is a string)
-or a symbol (@emph{not} a symbol name) from the obarray.
+function of one argument, unless @var{collection} is a hash table, in
+which case it should be a function of two arguments.  It is used to
+test each possible match, and the match is accepted only if
+@var{predicate} returns non-@code{nil}.  The argument given to
+@var{predicate} is either a string or a cons cell (the @sc{car} of
+which is a string) from the alist, or a symbol (@emph{not} a symbol
+name) from the obarray.  If @var{collection} is a hash table,
+@var{predicate} is called with two arguments, the string key and the
+associated value.
+
+In addition, to be acceptable, a completion must also match all the
+regular expressions in @code{completion-regexp-list}.  (Unless
+@var{collection} is a function, in which case that function has to
+handle @code{completion-regexp-list} itself.)
 
 In the first of the following examples, the string @samp{foo} is
 matched by three of the alist @sc{car}s.  All of the matches begin with
@@ -628,10 +668,13 @@
 
 @defun all-completions string collection &optional predicate nospace
 This function returns a list of all possible completions of
-@var{string}.  The arguments to this function (aside from @var{nospace})
-are the same as those of @code{try-completion}.  If @var{nospace} is
-non-@code{nil}, completions that start with a space are ignored unless
-@var{string} also starts with a space.
+@var{string}.  The arguments to this function (aside from
+@var{nospace}) are the same as those of @code{try-completion}.  Also,
+this function uses @code{completion-regexp-list} in the same way that
+@code{try-completion} does.  The optional argument @var{nospace} only
+matters if @var{string} is the empty string.  In that case, if
+@var{nospace} is non-@code{nil}, completions that start with a space
+are ignored.
 
 If @var{collection} is a function, it is called with three arguments:
 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
@@ -657,13 +700,24 @@
 @end smallexample
 @end defun
 
+@anchor{Definition of test-completion}
 @defun test-completion string collection &optional predicate
 This function returns non-@code{nil} if @var{string} is a valid
 completion possibility specified by @var{collection} and
-@var{predicate}.  The other arguments are the same as in
-@code{try-completion}.  For instance, if @var{collection} is a list,
-this is true if @var{string} appears in the list and @var{predicate}
-is satisfied.
+@var{predicate}.  The arguments are the same as in
+@code{try-completion}.  For instance, if @var{collection} is a list of
+strings, this is true if @var{string} appears in the list and
+@var{predicate} is satisfied.
+
+@code{test-completion} uses @code{completion-regexp-list} in the same
+way that @code{try-completion} does.
+
+If @var{predicate} is non-@code{nil} and if @var{collection} contains
+several strings that are equal to each other, as determined by
+@code{compare-strings} according to @code{completion-ignore-case},
+then @var{predicate} should accept either all or none of them.
+Otherwise, the return value of @code{test-completion} is essentially
+unpredictable.
 
 If @var{collection} is a function, it is called with three arguments,
 the values @var{string}, @var{predicate} and @code{lambda}; whatever
@@ -675,6 +729,13 @@
 consider case significant in completion.
 @end defvar
 
+@defvar completion-regexp-list
+This is a list of regular expressions.  The completion functions only
+consider a completion acceptable if it matches all regular expressions
+in this list, with @code{case-fold-search} (@pxref{Searching and Case})
+bound to the value of @code{completion-ignore-case}.
+@end defvar
+
 @defmac lazy-completion-table var fun &rest args
 This macro provides a way to initialize the variable @var{var} as a
 collection for completion in a lazy way, not computing its actual
@@ -706,8 +767,12 @@
 @var{prompt}, which must be a string.
 
 The actual completion is done by passing @var{collection} and
-@var{predicate} to the function @code{try-completion}.  This happens in
-certain commands bound in the local keymaps used for completion.
+@var{predicate} to the function @code{try-completion}.  This happens
+in certain commands bound in the local keymaps used for completion.
+Some of these commands also call @code{test-completion}.  Thus, if
+@var{predicate} is non-@code{nil}, it should be compatible with
+@var{collection} and @code{completion-ignore-case}.  @xref{Definition
+of test-completion}.
 
 If @var{require-match} is @code{nil}, the exit commands work regardless
 of the input in the minibuffer.  If @var{require-match} is @code{t}, the
@@ -718,19 +783,13 @@
 
 However, empty input is always permitted, regardless of the value of
 @var{require-match}; in that case, @code{completing-read} returns
-@var{default}.  The value of @var{default} (if non-@code{nil}) is also
-available to the user through the history commands.
+@var{default}, or @code{""}, if @var{default} is @code{nil}.  The
+value of @var{default} (if non-@code{nil}) is also available to the
+user through the history commands.
 
-The user can exit with null input by typing @key{RET} with an empty
-minibuffer.  Then @code{completing-read} returns @code{""}.  This is how
-the user requests whatever default the command uses for the value being
-read.  The user can return using @key{RET} in this way regardless of the
-value of @var{require-match}, and regardless of whether the empty string
-is included in @var{collection}.
-
-The function @code{completing-read} works by calling
-@code{read-minibuffer}.  It uses @code{minibuffer-local-completion-map}
-as the keymap if @var{require-match} is @code{nil}, and uses
+The function @code{completing-read} uses
+@code{minibuffer-local-completion-map} as the keymap if
+@var{require-match} is @code{nil}, and uses
 @code{minibuffer-local-must-match-map} if @var{require-match} is
 non-@code{nil}.  @xref{Completion Commands}.
 
@@ -739,15 +798,21 @@
 @code{minibuffer-history}.  @xref{Minibuffer History}.
 
 If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
-into the minibuffer as part of the input.  Then it allows the user to
-edit the input, providing several commands to attempt completion.
-In most cases, we recommend using @var{default}, and not @var{initial}.
+into the minibuffer as part of the input, with point at the end.  Then
+it allows the user to edit the input, providing several commands to
+attempt completion.  @var{initial} can also be a cons cell of the form
+@code{(@var{string} .  @var{position})}.  In that case, point is put at
+@emph{zero-indexed} position @var{position} in @var{string}.  Note
+that this is different from @code{read-from-minibuffer} and related
+functions, which use a one-indexed position.  In most cases, we
+recommend using @var{default}, and not @var{initial}.
 
 @strong{We discourage use of a non-@code{nil} value for
 @var{initial}}, because it is an intrusive interface.  The history
 list feature (which did not exist when we introduced @var{initial})
 offers a far more convenient and general way for the user to get the
-default and edit it, and it is always available.
+default and edit it, and it is always available.  For an exception to
+this rule, see @ref{Minibuffer History}.
 
 If the argument @var{inherit-input-method} is non-@code{nil}, then the
 minibuffer inherits the current input method (@pxref{Input
@@ -794,8 +859,13 @@
 @node Completion Commands
 @subsection Minibuffer Commands that Do Completion
 
-  This section describes the keymaps, commands and user options used in
-the minibuffer to do completion.
+  This section describes the keymaps, commands and user options used
+in the minibuffer to do completion.  The description refers to the
+situation when Partial Completion mode is disabled (as it is by
+default).  When enabled, this minor mode uses its own alternatives to
+some of the commands described below.  @xref{Completion Options,,,
+emacs, The GNU Emacs Manual}, for a short description of Partial
+Completion mode.
 
 @defvar minibuffer-local-completion-map
 @code{completing-read} uses this value as the local keymap when an
@@ -815,7 +885,7 @@
 
 @noindent
 with other characters bound as in @code{minibuffer-local-map}
-(@pxref{Text from Minibuffer}).
+(@pxref{Definition of minibuffer-local-map}).
 @end defvar
 
 @defvar minibuffer-local-must-match-map
@@ -847,8 +917,8 @@
 @end defvar
 
 @defvar minibuffer-completion-table
-The value of this variable is the alist or obarray used for completion
-in the minibuffer.  This is the global variable that contains what
+The value of this variable is the collection used for completion in
+the minibuffer.  This is the global variable that contains what
 @code{completing-read} passes to @code{try-completion}.  It is used by
 minibuffer completion commands such as @code{minibuffer-complete-word}.
 @end defvar
@@ -902,8 +972,10 @@
 information about streams.)  The argument @var{completions} is normally
 a list of completions just returned by @code{all-completions}, but it
 does not have to be.  Each element may be a symbol or a string, either
-of which is simply printed, or a list of two strings, which is printed
-as if the strings were concatenated.
+of which is simply printed.  It can also be a list of two strings,
+which is printed as if the strings were concatenated.  The first of
+the two strings is the actual completion, the second string serves as
+annotation.
 
 This function is called by @code{minibuffer-completion-help}.  The
 most common way to use it is together with
@@ -943,9 +1015,10 @@
 If @var{existing} is non-@code{nil}, then the name specified must be
 that of an existing buffer.  The usual commands to exit the minibuffer
 do not exit if the text is not valid, and @key{RET} does completion to
-attempt to find a valid name.  (However, @var{default} is not checked
-for validity; it is returned, whatever it is, if the user exits with the
-minibuffer empty.)
+attempt to find a valid name.  If @var{existing} is neither @code{nil}
+nor @code{t}, confirmation is required after completion.  (However,
+@var{default} is not checked for validity; it is returned, whatever it
+is, if the user exits with the minibuffer empty.)
 
 In the following example, the user enters @samp{minibuffer.t}, and
 then types @key{RET}.  The argument @var{existing} is @code{t}, and the
@@ -991,7 +1064,8 @@
 null input.  It can be a symbol or a string; if it is a string,
 @code{read-command} interns it before returning it.  If @var{default} is
 @code{nil}, that means no default has been specified; then if the user
-enters null input, the return value is @code{nil}.
+enters null input, the return value is @code{(intern "")}, that is, a
+symbol whose name is an empty string.
 
 @example
 (read-command "Command name? ")
@@ -1036,7 +1110,7 @@
 null input.  It can be a symbol or a string; if it is a string,
 @code{read-variable} interns it before returning it.  If @var{default}
 is @code{nil}, that means no default has been specified; then if the
-user enters null input, the return value is @code{nil}.
+user enters null input, the return value is @code{(intern "")}.
 
 @example
 @group
@@ -1083,12 +1157,9 @@
 file name.  It provides special features including automatic insertion
 of the default directory.
 
-@defun read-file-name prompt &optional directory default existing initial
+@defun read-file-name prompt &optional directory default existing initial predicate
 This function reads a file name in the minibuffer, prompting with
-@var{prompt} and providing completion.  If @var{default} is
-non-@code{nil}, then the function returns @var{default} if the user just
-types @key{RET}.  @var{default} is not checked for validity; it is
-returned, whatever it is, if the user exits with the minibuffer empty.
+@var{prompt} and providing completion.
 
 If @var{existing} is non-@code{nil}, then the user must specify the name
 of an existing file; @key{RET} performs completion to make the name
@@ -1099,18 +1170,58 @@
 acceptable.
 
 The argument @var{directory} specifies the directory to use for
-completion of relative file names.  If @code{insert-default-directory}
-is non-@code{nil}, @var{directory} is also inserted in the minibuffer as
-initial input.  It defaults to the current buffer's value of
-@code{default-directory}.
+completion of relative file names.  It should be an absolute directory
+name.  If @code{insert-default-directory} is non-@code{nil},
+@var{directory} is also inserted in the minibuffer as initial input.
+It defaults to the current buffer's value of @code{default-directory}.
 
 @c Emacs 19 feature
-If you specify @var{initial}, that is an initial file name to insert in
-the buffer (after @var{directory}, if that is inserted).  In this
+If you specify @var{initial}, that is an initial file name to insert
+in the buffer (after @var{directory}, if that is inserted).  In this
 case, point goes at the beginning of @var{initial}.  The default for
 @var{initial} is @code{nil}---don't insert any file name.  To see what
-@var{initial} does, try the command @kbd{C-x C-v}.  @strong{Note:} we
-recommend using @var{default} rather than @var{initial} in most cases.
+@var{initial} does, try the command @kbd{C-x C-v}.  @strong{Please
+note:} we recommend using @var{default} rather than @var{initial} in
+most cases.
+
+If @var{default} is non-@code{nil}, then the function returns
+@var{default} if the user exits the minibuffer with the same non-empty
+contents that @code{read-file-name} inserted initially.  The initial
+minibuffer contents are always non-empty if
+@code{insert-default-directory} is non-@code{nil}, as it is by
+default.  @var{default} is not checked for validity, regardless of the
+value of @var{existing}.  However, if @var{existing} is
+non-@code{nil}, the initial minibuffer contents should be a valid file
+(or directory) name.  Otherwise @code{read-file-name} attempts
+completion if the user exits without any editing, and does not return
+@var{default}.  @var{default} is also available through the history
+commands.
+
+If @var{default} is @code{nil}, @code{read-file-name} tries to find a
+substitute default to use in its place, which it treats in exactly the
+same way as if it had been specified explicitly.  If @var{default} is
+@code{nil}, but @var{initial} is non-@code{nil}, then the default is
+the absolute file name obtained from @var{directory} and
+@var{initial}.  If both @var{default} and @var{initial} are @code{nil}
+and the buffer is visiting a file, @code{read-file-name} uses the
+absolute file name of that file as default.  If the buffer is not
+visiting a file, then there is no default.  In that case, if the user
+types @key{RET} without any editing, @code{read-file-name} simply
+returns the pre-inserted contents of the minibuffer.
+
+If the user types @key{RET} in an empty minibuffer, this function
+returns an empty string, regardless of the value of @var{existing}.
+This is, for instance, how the user can make the current buffer visit
+no file using @code{M-x set-visited-file-name}.
+
+If @var{predicate} is non-@code{nil}, it specifies a function of one
+argument that decides which file names are acceptable completion
+possibilities.  A file name is an acceptable value if @var{predicate}
+returns non-@code{nil} for it.
+
+@code{read-file-name} does not automatically expand file names.  You
+must call @code{expand-file-name} yourself if an absolute file name is
+required.
 
 Here is an example:
 
@@ -1146,15 +1257,38 @@
 as the string @code{"/gp/gnu/elisp/manual.texi"}.
 @end defun
 
+@defun read-directory-name prompt &optional directory default existing initial
+This function is like @code{read-file-name} but allows only directory
+names as completion possibilities.
+
+If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
+@code{read-directory-name} constructs a substitute default by
+combining @var{directory} (or the current buffer's default directory
+if @var{directory} is @code{nil}) and @var{initial}.  If both
+@var{default} and @var{initial} are @code{nil}, this function uses the
+current buffer's default directory as substitute default, ignoring
+@var{directory}.
+@end defun
+
 @defopt insert-default-directory
-This variable is used by @code{read-file-name}.  Its value controls
-whether @code{read-file-name} starts by placing the name of the default
-directory in the minibuffer, plus the initial file name if any.  If the
-value of this variable is @code{nil}, then @code{read-file-name} does
-not place any initial input in the minibuffer (unless you specify
-initial input with the @var{initial} argument).  In that case, the
-default directory is still used for completion of relative file names,
-but is not displayed.
+This variable is used by @code{read-file-name}, and thus, indirectly,
+by most commands reading file names.  (This includes all commands that
+use the code letters @samp{f} or @samp{F} in their interactive form.
+@xref{Interactive Codes,, Code Characters for interactive}.)  Its
+value controls whether @code{read-file-name} starts by placing the
+name of the default directory in the minibuffer, plus the initial file
+name if any.  If the value of this variable is @code{nil}, then
+@code{read-file-name} does not place any initial input in the
+minibuffer (unless you specify initial input with the @var{initial}
+argument).  In that case, the default directory is still used for
+completion of relative file names, but is not displayed.
+
+If this variable is @code{nil} and the initial minibuffer contents are
+empty, the user may have to explicitly fetch the next history element
+to access a default value.  If the variable is non-@code{nil}, the
+initial minibuffer contents are always non-empty and the user can
+always request a default value by immediately typing @key{RET} in an
+unedited minibuffer.  (See above.)
 
 For example:
 
@@ -1611,9 +1745,10 @@
 locally inside the minibuffer (@pxref{Help Functions}).
 @end defvar
 
-@defun minibufferp &optional buffer
-This function returns non-@code{nil} if @var{buffer} is a minibuffer.
-If @var{buffer} is omitted, it tests the current buffer.
+@defun minibufferp &optional buffer-or-name
+This function returns non-@code{nil} if @var{buffer-or-name} is a
+minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
+buffer.
 @end defun
 
 @defun active-minibuffer-window
@@ -1629,9 +1764,19 @@
 other frame's minibuffer window.
 @end defun
 
+@defun set-minibuffer-window window
+This function specifies @var{window} as the minibuffer window to use.
+This affects where the minibuffer is displayed if you put text in it
+without invoking the usual minibuffer commands.  It has no effect on
+the usual minibuffer input functions because they all start by
+choosing the minibuffer window according to the current frame.
+@end defun
+
 @c Emacs 19 feature
-@defun window-minibuffer-p window
-This function returns non-@code{nil} if @var{window} is a minibuffer window.
+@defun window-minibuffer-p &optional window
+This function returns non-@code{nil} if @var{window} is a minibuffer
+window.
+@var{window} defaults to the selected window.
 @end defun
 
 It is not correct to determine whether a given window is a minibuffer by
@@ -1650,6 +1795,12 @@
 minibuffer, it scrolls this window.
 @end defvar
 
+@defun minibuffer-selected-window
+This function returns the window which was selected when the
+minibuffer was entered.  If selected window is not a minibuffer
+window, it returns @code{nil}.
+@end defun
+
 Finally, some functions and variables deal with recursive minibuffers
 (@pxref{Recursive Editing}):
 
@@ -1674,12 +1825,18 @@
 @c Emacs 19 feature
 If a command name has a property @code{enable-recursive-minibuffers}
 that is non-@code{nil}, then the command can use the minibuffer to read
-arguments even if it is invoked from the minibuffer.  The minibuffer
-command @code{next-matching-history-element} (normally @kbd{M-s} in the
-minibuffer) uses this feature.
+arguments even if it is invoked from the minibuffer.  A command can
+also achieve this by binding @code{enable-recursive-minibuffers}
+to @code{t} in the interactive declaration (@pxref{Using Interactive}).
+The minibuffer command @code{next-matching-history-element} (normally
+@kbd{M-s} in the minibuffer) does the latter.
 
-@defun minibuffer-message string &optional timeout
+@defun minibuffer-message string
 This function displays @var{string} temporarily at the end of the
-minibuffer text, for @var{timeout} seconds.  (The default is 2
-seconds.)
+minibuffer text, for two seconds, or until the next input event
+arrives, whichever comes first.
 @end defun
+
+@ignore
+   arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
+@end ignore

--- a/lispref/mkinstalldirs	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/mkinstalldirs	Mon Apr 19 07:01:43 2004 +0000
@@ -4,8 +4,6 @@
 # Created: 1993-05-16
 # Public domain
 
-# $Id: mkinstalldirs,v 1.10 1996/05/03 07:37:52 friedman Exp $
-
 errstatus=0
 
 for file

--- a/lispref/modes.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/modes.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/modes
-@node Modes, Documentation,  Keymaps, Top
+@node Modes, Documentation, Keymaps, Top
 @chapter Major and Minor Modes
 @cindex mode
 
@@ -203,7 +203,7 @@
 @kbd{C-j}.  Please keep this distinction uniform for all major modes.
 
 @item
-Major modes should not alter options that are primary a matter of user
+Major modes should not alter options that are primarily a matter of user
 preference, such as whether Auto-Fill mode is enabled.  Leave this to
 each user to decide.  However, a major mode should customize other
 variables so that Auto-Fill mode will work usefully @emph{if} the user
@@ -236,7 +236,9 @@
 @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} or
+variable @code{imenu-generic-expression}, for the pair of 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}).
 
 @item
@@ -274,7 +276,7 @@
 but this is not required.  Such a mode should use
 @code{delay-mode-hooks} around its entire body, including the call to
 the parent mode command and the final call to @code{run-mode-hooks}.
-(Using @code{define-derived-mode} does this automatically.) 
+(Using @code{define-derived-mode} does this automatically.)
 
 @item
 If something special should be done if the user switches a buffer from
@@ -421,7 +423,7 @@
 @group
       ;; @r{Set syntax of chars up to 0 to class of chars that are}
       ;;   @r{part of symbol names but not words.}
-      ;;   @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
+      ;;   @r{(The number 0 is @code{48} in the @acronym{ASCII} character set.)}
       (while (< i ?0)
         (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
         (setq i (1+ i)))
@@ -1101,7 +1103,7 @@
 @end smallexample
 
 @node Mode Line Format
-@section Mode Line Format
+@section Mode-Line Format
 @cindex mode line
 
   Each Emacs window (aside from minibuffer windows) typically has a mode
@@ -1137,10 +1139,12 @@
 display it in the new way.
 
 @c Emacs 19 feature
-@defun force-mode-line-update
+@defun force-mode-line-update &optional all
 Force redisplay of the current buffer's mode line and header line.
 The next redisplay will update the mode line and header line based on
-the latest values of all relevant variables.
+the latest values of all relevant variables.  With optional
+non-@code{nil} @var{all}, force redisplay of all mode lines and header
+lines.
 
 This function also forces recomputation of the menu bar menus
 and the frame title.
@@ -1161,41 +1165,44 @@
 * %-Constructs::          Putting information into a mode line.
 * Properties in Mode::    Using text properties in the mode line.
 * Header Lines::          Like a mode line, but at the top.
+* Emulating Mode Line::   Formatting text as the mode line would.
 @end menu
 
 @node Mode Line Data
 @subsection The Data Structure of the Mode Line
-@cindex mode line construct
-
-  The mode line contents are controlled by a data structure of lists,
+@cindex mode-line construct
+
+  The mode-line contents are controlled by a data structure of lists,
 strings, symbols, and numbers kept in buffer-local variables.  The data
-structure is called a @dfn{mode line construct}, and it is built in
-recursive fashion out of simpler mode line constructs.  The same data
+structure is called a @dfn{mode-line construct}, and it is built in
+recursive fashion out of simpler mode-line constructs.  The same data
 structure is used for constructing frame titles (@pxref{Frame Titles})
 and header lines (@pxref{Header Lines}).
 
 @defvar mode-line-format
-The value of this variable is a mode line construct with overall
-responsibility for the mode line format.  The value of this variable
-controls which other variables are used to form the mode line text, and
+The value of this variable is a mode-line construct with overall
+responsibility for the mode-line format.  The value of this variable
+controls which other variables are used to form the mode-line text, and
 where they appear.
 
 If you set this variable to @code{nil} in a buffer, that buffer does not
 have a mode line.  (This feature was added in Emacs 21.)
 @end defvar
 
-  A mode line construct may be as simple as a fixed string of text, but
+  A mode-line construct may be as simple as a fixed string of text, but
 it usually specifies how to use other variables to construct the text.
-Many of these variables are themselves defined to have mode line
+Many of these variables are themselves defined to have mode-line
 constructs as their values.
 
   The default value of @code{mode-line-format} incorporates the values
-of variables such as @code{mode-name} and @code{minor-mode-alist}.
-Because of this, very few modes need to alter @code{mode-line-format}
-itself.  For most purposes, it is sufficient to alter some of the
-variables that @code{mode-line-format} refers to.
-
-  A mode line construct may be a list, a symbol, or a string.  If the
+of variables such as @code{mode-line-position} and
+@code{mode-line-modes} (which in turn incorporates the values of the
+variables @code{mode-name} and @code{minor-mode-alist}).  Because of
+this, very few modes need to alter @code{mode-line-format} itself.  For
+most purposes, it is sufficient to alter some of the variables that
+@code{mode-line-format} either directly or indirectly refers to.
+
+  A mode-line construct may be a list, a symbol, or a string.  If the
 value is a list, each element may be a list, a symbol, or a string.
 
   The mode line can display various faces, if the strings that control
@@ -1206,43 +1213,56 @@
 @table @code
 @cindex percent symbol in mode line
 @item @var{string}
-A string as a mode line construct is displayed verbatim in the mode line
+A string as a mode-line construct is displayed verbatim in the mode line
 except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}
 specify the field width for space filling on the right (i.e., the data
 is left justified).  @xref{%-Constructs}.
 
 @item @var{symbol}
-A symbol as a mode line construct stands for its value.  The value of
-@var{symbol} is used as a mode line construct, in place of @var{symbol}.
+A symbol as a mode-line construct stands for its value.  The value of
+@var{symbol} is used as a mode-line construct, in place of @var{symbol}.
 However, the symbols @code{t} and @code{nil} are ignored, as is any
 symbol whose value is void.
 
 There is one exception: if the value of @var{symbol} is a string, it is
 displayed verbatim: the @code{%}-constructs are not recognized.
 
+Unless @var{symbol} is marked as ``risky'' (i.e., it has a
+non-@code{nil} @code{risky-local-variable} property), all properties in
+any strings, as well as all @code{:eval} and @code{:propertize} forms in
+the value of that symbol will be ignored.
+
 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
 A list whose first element is a string or list means to process all the
 elements recursively and concatenate the results.  This is the most
-common form of mode line construct.
+common form of mode-line construct.
 
 @item (:eval @var{form})
 A list whose first element is the symbol @code{:eval} says to evaluate
 @var{form}, and use the result as a string to display.
 (This feature is new as of Emacs 21.)
 
+@item (:propertize @var{elt} @var{props}@dots{})
+A list whose first element is the symbol @code{:propertize} says to
+process the mode-line construct @var{elt} recursively and add the text
+properties specified by @var{props} to the result.  The argument
+@var{props} should consist of zero or more pairs @var{text-property}
+@var{value}.  (This feature is new as of Emacs 21.4.)
+@c FIXME: This might be Emacs 21.5.
+
 @item (@var{symbol} @var{then} @var{else})
 A list whose first element is a symbol that is not a keyword specifies a
 conditional.  Its meaning depends on the value of @var{symbol}.  If the
 value is non-@code{nil}, the second element, @var{then}, is processed
-recursively as a mode line element.  But if the value of @var{symbol} is
+recursively as a mode-line element.  But if the value of @var{symbol} is
 @code{nil}, the third element, @var{else}, is processed recursively.
-You may omit @var{else}; then the mode line element displays nothing if
+You may omit @var{else}; then the mode-line element displays nothing if
 the value of @var{symbol} is @code{nil}.
 
 @item (@var{width} @var{rest}@dots{})
 A list whose first element is an integer specifies truncation or
 padding of the results of @var{rest}.  The remaining elements
-@var{rest} are processed recursively as mode line constructs and
+@var{rest} are processed recursively as mode-line constructs and
 concatenated together.  Then the result is space filled (if
 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
 if @var{width} is negative) on the right.
@@ -1274,7 +1294,7 @@
 @end group
 @group
    ;; @r{Note that this is evaluated while making the list.}
-   ;; @r{It makes a mode line construct which is just a string.}
+   ;; @r{It makes a mode-line construct which is just a string.}
    (getenv "HOST")
 @end group
    ":"
@@ -1291,7 +1311,7 @@
    '(which-func-mode ("" which-func-format "--"))
    '(line-number-mode "L%l--")
    '(column-number-mode "C%c--")
-   '(-3 . "%p")
+   '(-3 "%p")
    "-%-"))
 @end group
 @end example
@@ -1331,8 +1351,8 @@
 
 @defvar mode-line-frame-identification
 This variable identifies the current frame.  The default value is
-@code{" "} if you are using a window system which can show multiple
-frames, or @code{"-%F "} on an ordinary terminal which shows only one
+@code{"  "} if you are using a window system which can show multiple
+frames, or @code{"-%F  "} on an ordinary terminal which shows only one
 frame at a time.
 @end defvar
 
@@ -1342,24 +1362,74 @@
 with spaces to at least 12 columns.
 @end defvar
 
-@defvar global-mode-string
-This variable holds a mode line spec that appears in the mode line by
-default, just after the buffer name.  The command @code{display-time}
-sets @code{global-mode-string} to refer to the variable
-@code{display-time-string}, which holds a string containing the time and
-load information.
-
-The @samp{%M} construct substitutes the value of
-@code{global-mode-string}, but that is obsolete, since the variable is
-included in the mode line from @code{mode-line-format}.
+@defvar mode-line-position
+This variable indicates the position in the buffer.  Here is a
+simplified version of its default value.  The actual default value
+also specifies addition of the @code{help-echo} text property.
+
+@example
+@group
+((-3 "%p")
+ (size-indication-mode (8 " of %I"))
+@end group
+@group
+ (line-number-mode
+  ((column-number-mode
+    (10 " (%l,%c)")
+    (6 " L%l")))
+  ((column-number-mode
+    (5 " C%c")))))
+@end group
+@end example
+
+This means that @code{mode-line-position} displays at least the buffer
+percentage and possibly the buffer size, the line number and the column
+number.
 @end defvar
 
+@defvar vc-mode
+The variable @code{vc-mode}, buffer-local in each buffer, records
+whether the buffer's visited file is maintained with version control,
+and, if so, which kind.  Its value is a string that appears in the mode
+line, or @code{nil} for no version control.
+@end defvar
+
+@defvar mode-line-modes
+This variable displays the buffer's major and minor modes.  Here is a
+simplified version of its default value.  The real default value also
+specifies addition of text properties.
+
+@example
+@group
+("%[(" mode-name
+ mode-line-process minor-mode-alist
+ "%n" ")%]--")
+@end group
+@end example
+
+So @code{mode-line-modes} normally also displays the recursive editing
+level, information on the process status and whether narrowing is in
+effect.
+@end defvar
+
+  The following three variables are used in @code{mode-line-modes}:
+
 @defvar mode-name
 This buffer-local variable holds the ``pretty'' name of the current
 buffer's major mode.  Each major mode should set this variable so that the
 mode name will appear in the mode line.
 @end defvar
 
+@defvar mode-line-process
+This buffer-local variable contains the mode-line information on process
+status in modes used for communicating with subprocesses.  It is
+displayed immediately following the major mode name, with no intervening
+space.  For example, its value in the @samp{*shell*} buffer is
+@code{(":%s")}, which allows the shell to display its status along
+with the major mode as: @samp{(Shell:run)}.  Normally this variable
+is @code{nil}.
+@end defvar
+
 @defvar minor-mode-alist
 This variable holds an association list whose elements specify how the
 mode line should indicate that a minor mode is active.  Each element of
@@ -1369,51 +1439,28 @@
 (@var{minor-mode-variable} @var{mode-line-string})
 @end example
 
-More generally, @var{mode-line-string} can be any mode line spec.  It
-appears in the mode line when the value of @var{minor-mode-variable} is
-non-@code{nil}, and not otherwise.  These strings should begin with
+More generally, @var{mode-line-string} can be any mode-line spec.  It
+appears in the mode line when the value of @var{minor-mode-variable}
+is non-@code{nil}, and not otherwise.  These strings should begin with
 spaces so that they don't run together.  Conventionally, the
-@var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
-value when that minor mode is activated.
-
-The default value of @code{minor-mode-alist} is:
-
-@example
-@group
-minor-mode-alist
-@result{} ((vc-mode vc-mode)
-    (abbrev-mode " Abbrev")
-    (overwrite-mode overwrite-mode)
-    (auto-fill-function " Fill")
-    (defining-kbd-macro " Def")
-    (isearch-mode isearch-mode))
-@end group
-@end example
+@var{minor-mode-variable} for a specific mode is set to a
+non-@code{nil} value when that minor mode is activated.
 
 @code{minor-mode-alist} itself is not buffer-local.  Each variable
 mentioned in the alist should be buffer-local if its minor mode can be
 enabled separately in each buffer.
 @end defvar
 
-@defvar mode-line-process
-This buffer-local variable contains the mode line information on process
-status in modes used for communicating with subprocesses.  It is
-displayed immediately following the major mode name, with no intervening
-space.  For example, its value in the @samp{*shell*} buffer is
-@code{(":%s")}, which allows the shell to display its status along
-with the major mode as: @samp{(Shell:run)}.  Normally this variable
-is @code{nil}.
-@end defvar
-
-  Some variables are used by @code{minor-mode-alist} to display
-a string for various minor modes when enabled.  This is a typical
-example:
-
-@defvar vc-mode
-The variable @code{vc-mode}, buffer-local in each buffer, records
-whether the buffer's visited file is maintained with version control,
-and, if so, which kind.  Its value is a string that appears in the mode
-line, or @code{nil} for no version control.
+@defvar global-mode-string
+This variable holds a mode-line spec that appears in the mode line by
+default, just after the buffer name.  The command @code{display-time}
+sets @code{global-mode-string} to refer to the variable
+@code{display-time-string}, which holds a string containing the time and
+load information.
+
+The @samp{%M} construct substitutes the value of
+@code{global-mode-string}, but that is obsolete, since the variable is
+included in the mode line from @code{mode-line-format}.
 @end defvar
 
   The variable @code{default-mode-line-format} is where
@@ -1424,7 +1471,9 @@
 that do not override it.  This is the same as @code{(default-value
 'mode-line-format)}.
 
-The default value of @code{default-mode-line-format} is this list:
+Here is a simplified version of the default value of
+@code{default-mode-line-format}.  The real default value also
+specifies addition of text properties.
 
 @example
 @group
@@ -1435,23 +1484,13 @@
  mode-line-buffer-identification
 @end group
  "   "
- global-mode-string
+ mode-line-position
+ (vc-mode vc-mode)
+ "   "
 @group
- "   %[("
- ;; @r{@code{mode-line-mode-name} is a function}
- ;; @r{that copies the mode name and adds text}
- ;; @r{properties to make it mouse-sensitive.}
- (:eval (mode-line-mode-name))
- mode-line-process
- minor-mode-alist
- "%n"
- ")%]--"
-@end group
-@group
+ mode-line-modes
  (which-func-mode ("" which-func-format "--"))
- (line-number-mode "L%l--")
- (column-number-mode "C%c--")
- (-3 . "%p")
+ (global-mode-string ("--" global-mode-string))
  "-%-")
 @end group
 @end example
@@ -1480,6 +1519,15 @@
 The title (only on a window system) or the name of the selected frame.
 @xref{Window Frame Parameters}.
 
+@item %i
+The size of the accessible part of the current buffer; basically
+@code{(- (point-max) (point-min))}.
+
+@item %I
+Like @samp{%i}, but the size is printed in a more readable way by using
+@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to
+abbreviate.
+
 @item %l
 The current line number of point, counting within the accessible portion
 of the buffer.
@@ -1554,29 +1602,33 @@
 
 @node Properties in Mode
 @subsection Properties in the Mode Line
+@cindex text properties in the mode line
 
   Starting in Emacs 21, certain text properties are meaningful in the
 mode line.  The @code{face} property affects the appearance of text; the
 @code{help-echo} property associate help strings with the text, and
 @code{local-map} can make the text mouse-sensitive.
 
-  There are three ways to specify text properties for text in the mode
+  There are four ways to specify text properties for text in the mode
 line:
 
 @enumerate
 @item
-Put a string with the @code{local-map} property directly into the
-mode-line data structure.
+Put a string with a text property directly into the mode-line data
+structure.
 
 @item
-Put a @code{local-map} property on a mode-line %-construct
-such as @samp{%12b}; then the expansion of the %-construct
-will have that same text property.
+Put a text property on a mode-line %-construct such as @samp{%12b}; then
+the expansion of the %-construct will have that same text property.
+
+@item
+Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
+give @var{elt} a text property specified by @var{props}.
 
 @item
 Use a list containing @code{:eval @var{form}} in the mode-line data
-structure, and make @var{form} evaluate to a string that has a
-@code{local-map} property.
+structure, and make @var{form} evaluate to a string that has a text
+property.
 @end enumerate
 
   You use the @code{local-map} property to specify a keymap.  Like any
@@ -1591,7 +1643,7 @@
 
   Starting in Emacs 21, a window can have a @dfn{header line} at the
 top, just as it can have a mode line at the bottom.  The header line
-feature works just like the mode line feature, except that it's
+feature works just like the mode-line feature, except that it's
 controlled by different variables.
 
 @tindex header-line-format
@@ -1610,6 +1662,31 @@
 It is normally @code{nil}, so that ordinary buffers have no header line.
 @end defvar
 
+@node Emulating Mode Line
+@subsection Emulating Mode-Line Formatting
+
+  You can use the function @code{format-mode-line} to compute
+the text that would appear in a mode line or header line
+based on certain mode-line specification.
+
+@defun format-mode-line &optional format window no-props
+This function formats a line of text according to @var{format} as if
+it were generating the mode line for @var{window}, but instead of
+displaying the text in the mode line or the header line, it returns
+the text as a string.
+
+If @var{format} is @code{nil}, that means to use
+@code{mode-line-format} and return the text that would appear in the
+mode line.  If @var{format} is @code{t}, that means to use
+@code{header-line-format} so as to return the text that would appear
+in the header line (@code{""} if the window has no header line).
+The argument @var{window} defaults to the selected window.
+
+The value string normally has text properties that correspond to the
+faces, keymaps, etc., that the mode line would have.  If
+@var{no-props} is non-@code{nil}, the value has no text properties.
+@end defun
+
 @node Imenu
 @section Imenu
 
@@ -1629,12 +1706,12 @@
 @code{imenu-generic-expression}:
 
 @defvar imenu-generic-expression
-This variable, if non-@code{nil}, specifies regular expressions for
-finding definitions for Imenu.  In the simplest case, elements should
-look like this:
+This variable, if non-@code{nil}, is a list that specifies regular
+expressions for finding definitions for Imenu.  Simple elements of
+@code{imenu-generic-expression} look like this:
 
 @example
-(@var{menu-title} @var{regexp} @var{subexp})
+(@var{menu-title} @var{regexp} @var{index})
 @end example
 
 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
@@ -1644,10 +1721,10 @@
 in the top level of the buffer index.
 
 The second item in the list, @var{regexp}, is a regular expression
-(@pxref{Regular Expressions}); anything in the buffer that it matches is
-considered a definition, something to mention in the buffer index.  The
-third item, @var{subexp}, indicates which subexpression in @var{regexp}
-matches the definition's name.
+(@pxref{Regular Expressions}); anything in the buffer that it matches
+is considered a definition, something to mention in the buffer index.
+The third item, @var{index}, is a non-negative integer that indicates
+which subexpression in @var{regexp} matches the definition's name.
 
 An element can also look like this:
 
@@ -1655,11 +1732,13 @@
 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
 @end example
 
-Each match for this element creates a special index item which, if
-selected by the user, calls @var{function} with arguments consisting of
-the item name, the buffer position, and @var{arguments}.
-
-For Emacs Lisp mode, @var{pattern} could look like this:
+Like in the previous case, each match for this element creates an
+index item.  However, if this index item is selected by the user, it
+calls @var{function} with arguments consisting of the item name, the
+buffer position, and @var{arguments}.
+
+For Emacs Lisp mode, @code{imenu-generic-expression} could look like
+this:
 
 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
 @example
@@ -1683,9 +1762,10 @@
 @end defvar
 
 @defvar imenu-case-fold-search
-This variable controls whether matching against
-@var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
-means matching should ignore case.
+This variable controls whether matching against the regular
+expressions in the value of @code{imenu-generic-expression} is
+case-sensitive: @code{t}, the default, means matching should ignore
+case.
 
 Setting this variable makes it buffer-local in the current buffer.
 @end defvar
@@ -1713,11 +1793,11 @@
 (setq imenu-syntax-alist '(("_$" . "w")))
 @end example
 
-The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
-instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this technique may be
-inconvenient when the mode needs to limit the initial character
-of a name to a smaller set of characters than are allowed in the rest
-of a name.
+The @code{imenu-generic-expression} regular expressions can then use
+@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}.  Note that this
+technique may be inconvenient when the mode needs to limit the initial
+character of a name to a smaller set of characters than are allowed in
+the rest of a name.
 
 Setting this variable makes it buffer-local in the current buffer.
 @end defvar
@@ -1750,39 +1830,50 @@
 variable @code{imenu-create-index-function}:
 
 @defvar imenu-create-index-function
-This variable specifies the function to use for creating a buffer index.
-The function should take no arguments, and return an index for the
-current buffer.  It is called within @code{save-excursion}, so where it
-leaves point makes no difference.
-
-The default value is a function that uses
-@code{imenu-generic-expression} to produce the index alist.  If you
-specify a different function, then @code{imenu-generic-expression} is
-not used.
+This variable specifies the function to use for creating a buffer
+index.  The function should take no arguments, and return an index
+alist for the current buffer.  It is called within
+@code{save-excursion}, so where it leaves point makes no difference.
+
+The index alist can have three types of elements.  Simple elements
+look like this:
+
+@example
+(@var{index-name} . @var{index-position})
+@end example
+
+Selecting a simple element has the effect of moving to position
+@var{index-position} in the buffer.  Special elements look like this:
+
+@example
+(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{})
+@end example
+
+Selecting a special element performs:
+
+@example
+(funcall @var{function}
+         @var{index-name} @var{index-position} @var{arguments}@dots{})
+@end example
+
+A nested sub-alist element looks like this:
+
+@example
+(@var{menu-title} @var{sub-alist})
+@end example
+
+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-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.
 
 Setting this variable makes it buffer-local in the current buffer.
 @end defvar
 
-@defvar imenu-index-alist
-This variable holds the index alist for the current buffer.
-Setting it makes it buffer-local in the current buffer.
-
-Simple elements in the alist look like @code{(@var{index-name}
-. @var{index-position})}.  Selecting a simple element has the effect of
-moving to position @var{index-position} in the buffer.
-
-Special elements look like @code{(@var{index-name} @var{position}
-@var{function} @var{arguments}@dots{})}.  Selecting a special element
-performs
-
-@example
-(funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
-@end example
-
-A nested sub-alist element looks like @code{(@var{index-name}
-@var{sub-alist})}.
-@end defvar
-
 @node Font Lock Mode
 @section Font Lock Mode
 @cindex Font Lock Mode
@@ -1933,9 +2024,10 @@
 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
 of Regexps}) to calculate the value for @var{match}.
 
-@item (@var{matcher} . @var{facename})
-In this kind of element, @var{facename} is an expression whose value
-specifies the face name to use for highlighting.
+@item (@var{matcher} . @var{facespec})
+In this kind of element, @var{facespec} is an object which specifies
+the face variable to use for highlighting.  In the simplest case, it
+is a Lisp variable (a symbol), whose value should be a face name.
 
 @example
 ;; @r{Highlight occurrences of @samp{fubar},}
@@ -1943,8 +2035,7 @@
 ("fubar" . fubar-face)
 @end example
 
-The value of @var{facename} is usually a face name (a symbol), but it
-can also be a list of the form
+However, @var{facespec} can also be a list of the form
 
 @example
 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{})
@@ -1962,21 +2053,22 @@
 It has the form
 
 @example
-(@var{subexp} @var{facename} @var{override} @var{laxmatch})
+(@var{subexp} @var{facespec} @var{override} @var{laxmatch})
 @end example
 
 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
 of the match to fontify (0 means the entire matching text).  The second
-subelement, @var{facename}, specifies the face, as described above.
+subelement, @var{facespec}, specifies the face, as described above.
 
 The last two values in @var{highlighter}, @var{override} and
-@var{laxmatch}, are flags.  If @var{override} is @code{t}, this element
-can override existing fontification made by previous elements of
-@code{font-lock-keywords}.  If it is @code{keep}, then each character is
-fontified if it has not been fontified already by some other element.
-If it is @code{prepend}, the face @var{facename} is added to the
-beginning of the @code{face} property.  If it is @code{append}, the face
-@var{facename} is added to the end of the @code{face} property.
+@var{laxmatch}, are flags.  If @var{override} is @code{t}, this
+element can override existing fontification made by previous elements
+of @code{font-lock-keywords}.  If it is @code{keep}, then each
+character is fontified if it has not been fontified already by some
+other element.  If it is @code{prepend}, the face specified by
+@var{facespec} is added to the beginning of the @code{font-lock-face}
+property.  If it is @code{append}, the face is added to the end of the
+@code{font-lock-face} property.
 
 If @var{laxmatch} is non-@code{nil}, it means there should be no error
 if there is no subexpression numbered @var{subexp} in @var{matcher}.
@@ -2069,7 +2161,11 @@
 to match text which spans lines; this does not work reliably.  While
 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
 updating when you edit the buffer does not, since it considers text one
-line at a time.
+line at a time.  If you have patterns that typically only span one
+line but can occasionally span two or three, such as
+@samp{<title>...</title>}, you can ask font-lock to be more careful by
+setting @code{font-lock-multiline} to @code{t}.  But it still will not
+work in all cases.
 
 @node Other Font Lock Variables
 @subsection Other Font Lock Variables
@@ -2132,11 +2228,25 @@
 @end defvar
 
 @defvar font-lock-extra-managed-props
-Additional properties (other than @code{face}) that are being managed
-by Font Lock mode.  Font Lock mode normally manages only the @code{face}
-property; if you want it to manage others as well, you must specify
-them in a @var{facename} in @code{font-lock-keywords} as well as adding
-them to this list.
+Additional properties (other than @code{font-lock-face}) that are
+being managed by Font Lock mode.  Font Lock mode normally manages only
+the @code{font-lock-face} property; if you want it to manage others as
+well, you must specify them in a @var{facespec} in
+@code{font-lock-keywords} as well as adding them to this list.
+@end defvar
+
+@defvar font-lock-syntactic-face-function
+A function to determine which face to use for a given syntactic
+element (a string or a comment).  The function is called with one
+argument, the parse state at point returned by
+@code{parse-partial-sexp}, and should return a face.  The default
+value returns @code{font-lock-comment-face} for comments and
+@code{font-lock-string-face} for strings.
+
+This can be used to highlighting different kinds of strings or
+comments differently.  It is also sometimes abused together with
+@code{font-lock-syntactic-keywords} to highlight elements that span
+multiple lines, but this is too obscure to document in this manual.
 @end defvar
 
 @node Levels of Font Lock
@@ -2178,7 +2288,7 @@
 @code{font-lock-face} (@pxref{Special Properties}).  This property
 acts just like the explicit @code{face} property, but its activation
 is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
-@code{font-lock-face} is especially conveninent for special modes
+@code{font-lock-face} is especially convenient for special modes
 which construct their text programmatically, such as
 @code{list-buffers} and @code{occur}.
 
@@ -2242,8 +2352,8 @@
 @vindex font-lock-constant-face
 Used (typically) for constant names.
 
-@item font-locl-preprocessor-face
-@vindex font-locl-preprocessor-face
+@item font-lock-preprocessor-face
+@vindex font-lock-preprocessor-face
 Used (typically) for preprocessor commands.
 
 @item font-lock-warning-face
@@ -2343,9 +2453,10 @@
 
   The recommended way to add a hook function to a normal hook is by
 calling @code{add-hook} (see below).  The hook functions may be any of
-the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
-a Function}).  Most normal hook variables are initially void;
-@code{add-hook} knows how to deal with this.
+the valid kinds of functions that @code{funcall} accepts (@pxref{What
+Is a Function}).  Most normal hook variables are initially void;
+@code{add-hook} knows how to deal with this.  You can add hooks either
+globally or buffer-locally with @code{add-hook}.
 
 @cindex abnormal hook
   If the hook variable's name does not end with @samp{-hook}, that
@@ -2376,17 +2487,17 @@
 been added with @code{add-hook}.
 
 @defun run-hooks &rest hookvars
-This function takes one or more hook variable names as arguments, and
-runs each hook in turn.  Each argument should be a symbol that is a hook
-variable.  These arguments are processed in the order specified.
+This function takes one or more normal hook variable names as
+arguments, and runs each hook in turn.  Each argument should be a
+symbol that is a normal hook variable.  These arguments are processed
+in the order specified.
 
 If a hook variable has a non-@code{nil} value, that value may be a
-function or a list of functions.  If the value is a function (either a
-lambda expression or a symbol with a function definition), it is called.
-If it is a list, the elements are called, in order.  The hook functions
-are called with no arguments.  Nowadays, storing a single function in
-the hook variable is semi-obsolete; you should always use a list of
-functions.
+function or a list of functions.  (The former option is considered
+obsolete.)  If the value is a function (either a lambda expression or
+a symbol with a function definition), it is called.  If it is a list
+that isn't a function, its elements are called, consecutively.  All
+the hook functions are called with no arguments.
 
 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
 
@@ -2408,33 +2519,33 @@
 @end defmac
 
 @defun run-hook-with-args hook &rest args
-This function is the way to run an abnormal hook which passes arguments
-to the hook functions.  It calls each of the hook functions, passing
-each of them the arguments @var{args}.
+This function is the way to run an abnormal hook and always call all
+of the hook functions.  It calls each of the hook functions one by
+one, passing each of them the arguments @var{args}.
 @end defun
 
 @defun run-hook-with-args-until-failure hook &rest args
-This function is the way to run an abnormal hook which passes arguments
-to the hook functions, and stops as soon as any hook function fails.  It
-calls each of the hook functions, passing each of them the arguments
-@var{args}, until some hook function returns @code{nil}.  Then it stops,
-and returns @code{nil} if some hook function returned @code{nil}.
-Otherwise it returns a non-@code{nil} value.
+This function is the way to run an abnormal hook until one of the hook
+functions fails.  It calls each of the hook functions, passing each of
+them the arguments @var{args}, until some hook function returns
+@code{nil}.  It then stops and returns @code{nil}.  If none of the
+hook functions return @code{nil}, it returns a non-@code{nil} value.
 @end defun
 
 @defun run-hook-with-args-until-success hook &rest args
-This function is the way to run an abnormal hook which passes arguments
-to the hook functions, and stops as soon as any hook function succeeds.
-It calls each of the hook functions, passing each of them the arguments
-@var{args}, until some hook function returns non-@code{nil}.  Then it
-stops, and returns whatever was returned by the last hook function
-that was called.
+This function is the way to run an abnormal hook until a hook function
+succeeds.  It calls each of the hook functions, passing each of them
+the arguments @var{args}, until some hook function returns
+non-@code{nil}.  Then it stops, and returns whatever was returned by
+the last hook function that was called.  If all hook functions return
+@code{nil}, it returns @code{nil} as well.
 @end defun
 
 @defun add-hook hook function &optional append local
 This function is the handy way to add function @var{function} to hook
-variable @var{hook}.  The argument @var{function} may be any valid Lisp
-function with the proper number of arguments.  For example,
+variable @var{hook}.  You can use it for abnormal hooks as well as for
+normal hooks.  @var{function} can be any Lisp function that can accept
+the proper number of arguments for @var{hook}.  For example,
 
 @example
 (add-hook 'text-mode-hook 'my-text-hook-function)
@@ -2443,24 +2554,34 @@
 @noindent
 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
 
-You can use @code{add-hook} for abnormal hooks as well as for normal
-hooks.
+If @var{function} is already present in @var{hook} (comparing using
+@code{equal}), then @code{add-hook} does not add it a second time.
 
 It is best to design your hook functions so that the order in which they
 are executed does not matter.  Any dependence on the order is ``asking
-for trouble.''  However, the order is predictable: normally,
+for trouble''.  However, the order is predictable: normally,
 @var{function} goes at the front of the hook list, so it will be
 executed first (barring another @code{add-hook} call).  If the optional
 argument @var{append} is non-@code{nil}, the new hook function goes at
 the end of the hook list and will be executed last.
 
-If @var{local} is non-@code{nil}, that says to add @var{function}
-to the buffer-local hook list instead of to the global hook list.
+If @var{local} is non-@code{nil}, that says to add @var{function} to
+the buffer-local hook list instead of to the global hook list.  If
+needed, this makes the hook buffer-local and adds @code{t} to the
+buffer-local value.  The latter acts as a flag to run the hook
+functions in the default value as well as in the local value.
 @end defun
 
 @defun remove-hook hook function &optional local
-This function removes @var{function} from the hook variable @var{hook}.
+This function removes @var{function} from the hook variable
+@var{hook}.  It compares @var{function} with elements of @var{hook}
+using @code{equal}, so it works for both symbols and lambda
+expressions.
 
 If @var{local} is non-@code{nil}, that says to remove @var{function}
 from the buffer-local hook list instead of from the global hook list.
 @end defun
+
+@ignore
+   arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e
+@end ignore

--- a/lispref/nonascii.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/nonascii.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -4,11 +4,11 @@
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/characters
 @node Non-ASCII Characters, Searching and Matching, Text, Top
-@chapter Non-@sc{ascii} Characters
+@chapter Non-@acronym{ASCII} Characters
 @cindex multibyte characters
-@cindex non-@sc{ascii} characters
+@cindex non-@acronym{ASCII} characters
 
-  This chapter covers the special issues relating to non-@sc{ascii}
+  This chapter covers the special issues relating to non-@acronym{ASCII}
 characters and how they are stored in strings and buffers.
 
 @menu
@@ -17,7 +17,7 @@
 * Selecting a Representation::  Treating a byte sequence as unibyte or multi.
 * Character Codes::         How unibyte and multibyte relate to
                                 codes of individual characters.
-* Character Sets::          The space of possible characters codes
+* Character Sets::          The space of possible character codes
                                 is divided into various character sets.
 * Chars and Bytes::         More information about multibyte encodings.
 * Splitting Characters::    Converting a character to its byte sequence.
@@ -44,8 +44,8 @@
 @cindex unibyte text
   In unibyte representation, each character occupies one byte and
 therefore the possible character codes range from 0 to 255.  Codes 0
-through 127 are @sc{ascii} characters; the codes from 128 through 255
-are used for one non-@sc{ascii} character set (you can choose which
+through 127 are @acronym{ASCII} characters; the codes from 128 through 255
+are used for one non-@acronym{ASCII} character set (you can choose which
 character set by setting the variable @code{nonascii-insert-offset}).
 
 @cindex leading code
@@ -96,13 +96,15 @@
 @defun position-bytes position
 @tindex position-bytes
 Return the byte-position corresponding to buffer position @var{position}
-in the current buffer.
+in the current buffer.  If @var{position} is out of range, the value
+is @code{nil}.
 @end defun
 
 @defun byte-to-position byte-position
 @tindex byte-to-position
 Return the buffer position corresponding to byte-position
-@var{byte-position} in the current buffer.
+@var{byte-position} in the current buffer.  If @var{byte-position} is
+out of range, the value is @code{nil}.
 @end defun
 
 @defun multibyte-string-p string
@@ -134,14 +136,14 @@
 acceptable because the buffer's representation is a choice made by the
 user that cannot be overridden automatically.
 
-  Converting unibyte text to multibyte text leaves @sc{ascii} characters
+  Converting unibyte text to multibyte text leaves @acronym{ASCII} characters
 unchanged, and likewise character codes 128 through 159.  It converts
-the non-@sc{ascii} codes 160 through 255 by adding the value
+the non-@acronym{ASCII} codes 160 through 255 by adding the value
 @code{nonascii-insert-offset} to each character code.  By setting this
 variable, you specify which character set the unibyte characters
 correspond to (@pxref{Character Sets}).  For example, if
 @code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
-'latin-iso8859-1) 128)}, then the unibyte non-@sc{ascii} characters
+'latin-iso8859-1) 128)}, then the unibyte non-@acronym{ASCII} characters
 correspond to Latin 1.  If it is 2688, which is @code{(- (make-char
 'greek-iso8859-7) 128)}, then they correspond to Greek letters.
 
@@ -153,10 +155,10 @@
 text.
 
 @defvar nonascii-insert-offset
-This variable specifies the amount to add to a non-@sc{ascii} character
+This variable specifies the amount to add to a non-@acronym{ASCII} character
 when converting unibyte text to multibyte.  It also applies when
 @code{self-insert-command} inserts a character in the unibyte
-non-@sc{ascii} range, 128 through 255.  However, the functions
+non-@acronym{ASCII} range, 128 through 255.  However, the functions
 @code{insert} and @code{insert-char} do not perform this conversion.
 
 The right value to use to select character set @var{cs} is @code{(-
@@ -173,6 +175,9 @@
 If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
 @end defvar
 
+The next three functions either return the argument @var{string}, or a
+newly created string with no text properties.
+
 @defun string-make-unibyte string
 This function converts the text of @var{string} to unibyte
 representation, if it isn't already, and returns the result.  If
@@ -186,15 +191,35 @@
 @defun string-make-multibyte string
 This function converts the text of @var{string} to multibyte
 representation, if it isn't already, and returns the result.  If
-@var{string} is a multibyte string, it is returned unchanged.
-The function @code{unibyte-char-to-multibyte} is used to convert
-each unibyte character to a multibyte character.
+@var{string} is a multibyte string or consists entirely of
+@acronym{ASCII} characters, it is returned unchanged.  In particular,
+if @var{string} is unibyte and entirely @acronym{ASCII}, the returned
+string is unibyte.  (When the characters are all @acronym{ASCII},
+Emacs primitives will treat the string the same way whether it is
+unibyte or multibyte.)  If @var{string} is unibyte and contains
+non-@acronym{ASCII} characters, the function
+@code{unibyte-char-to-multibyte} is used to convert each unibyte
+character to a multibyte character.
 @end defun
 
 @defun string-to-multibyte string
 This function returns a multibyte string containing the same sequence
-of character codes as @var{string}.  If @var{string} is a multibyte
-string, the value is the equal to @var{string}.
+of character codes as @var{string}.  Unlike
+@code{string-make-multibyte}, this function unconditionally returns a
+multibyte string.  If @var{string} is a multibyte string, it is
+returned unchanged.
+@end defun
+
+@defun multibyte-char-to-unibyte char
+This convert the multibyte character @var{char} to a unibyte
+character, based on @code{nonascii-translation-table} and
+@code{nonascii-insert-offset}.
+@end defun
+
+@defun unibyte-char-to-multibyte char
+This convert the unibyte character @var{char} to a multibyte
+character, based on @code{nonascii-translation-table} and
+@code{nonascii-insert-offset}.
 @end defun
 
 @node Selecting a Representation
@@ -263,7 +288,7 @@
 values in that range are valid.  The values 128 through 255 are not
 entirely proper in multibyte text, but they can occur if you do explicit
 encoding and decoding (@pxref{Explicit Encoding}).  Some other character
-codes cannot occur at all in multibyte text.  Only the @sc{ascii} codes
+codes cannot occur at all in multibyte text.  Only the @acronym{ASCII} codes
 0 through 127 are completely legitimate in both representations.
 
 @defun char-valid-p charcode &optional genericp
@@ -280,8 +305,8 @@
 @end example
 
 If the optional argument @var{genericp} is non-@code{nil}, this
-function returns @code{t} if @var{charcode} is a generic character
-(@pxref{Splitting Characters}).
+function also returns @code{t} if @var{charcode} is a generic
+character (@pxref{Splitting Characters}).
 @end defun
 
 @node Character Sets
@@ -301,8 +326,8 @@
 characters, generally known as Big 5, is divided into two Emacs
 character sets, @code{chinese-big5-1} and @code{chinese-big5-2}.
 
-  @sc{ascii} characters are in character set @code{ascii}.  The
-non-@sc{ascii} characters 128 through 159 are in character set
+  @acronym{ASCII} characters are in character set @code{ascii}.  The
+non-@acronym{ASCII} characters 128 through 159 are in character set
 @code{eight-bit-control}, and codes 160 through 255 are in character set
 @code{eight-bit-graphic}.
 
@@ -311,13 +336,19 @@
 @code{nil} otherwise.
 @end defun
 
+@defvar charset-list
+The value is a list of all defined character set names.
+@end defvar
+
 @defun charset-list
-This function returns a list of all defined character set names.
+This function returns the value of @code{charset-list}.  It is only
+provided for backward compatibility.
 @end defun
 
 @defun char-charset character
 This function returns the name of the character set that @var{character}
-belongs to.
+belongs to, or the symbol @code{unknown} if @var{character} is not a
+valid character.
 @end defun
 
 @defun charset-plist charset
@@ -325,9 +356,7 @@
 This function returns the charset property list of the character set
 @var{charset}.  Although @var{charset} is a symbol, this is not the same
 as the property list of that symbol.  Charset properties are used for
-special purposes within Emacs; for example,
-@code{preferred-coding-system} helps determine which coding system to
-use to encode characters in a charset.
+special purposes within Emacs.
 @end defun
 
 @node Chars and Bytes
@@ -338,8 +367,8 @@
 @cindex dimension (of character set)
   In multibyte representation, each character occupies one or more
 bytes.  Each character set has an @dfn{introduction sequence}, which is
-normally one or two bytes long.  (Exception: the @sc{ascii} character
-set and the @sc{eight-bit-graphic} character set have a zero-length
+normally one or two bytes long.  (Exception: the @code{ascii} character
+set and the @code{eight-bit-graphic} character set have a zero-length
 introduction sequence.)  The introduction sequence is the beginning of
 the byte sequence for any character in the character set.  The rest of
 the character's bytes distinguish it from the other characters in the
@@ -380,6 +409,9 @@
 identify @var{character} within that character set.  The number of byte
 values is the character set's dimension.
 
+If @var{character} is invalid as a character code, @code{split-char}
+returns a list consisting of the symbol @code{unknown} and @var{character}.
+
 @example
 (split-char 2248)
      @result{} (latin-iso8859-1 72)
@@ -401,6 +433,11 @@
 (make-char 'latin-iso8859-1 72)
      @result{} 2248
 @end example
+
+Actually, the eighth bit of both @var{code1} and @var{code2} is zeroed
+before they are used to index @var{charset}.  Thus you may use, for
+instance, an ISO 8859 character code rather than subtracting 128, as
+is necessary to index the corresponding Emacs charset.
 @end defun
 
 @cindex generic characters
@@ -423,8 +460,8 @@
      @result{} (latin-iso8859-1 0)
 @end example
 
-The character sets @sc{ascii}, @sc{eight-bit-control}, and
-@sc{eight-bit-graphic} don't have corresponding generic characters.  If
+The character sets @code{ascii}, @code{eight-bit-control}, and
+@code{eight-bit-graphic} don't have corresponding generic characters.  If
 @var{charset} is one of them and you don't supply @var{code1},
 @code{make-char} returns the character code corresponding to the
 smallest code in @var{charset}.
@@ -460,11 +497,19 @@
 @cindex character translation tables
 @cindex translation tables
 
-  A @dfn{translation table} specifies a mapping of characters
-into characters.  These tables are used in encoding and decoding, and
-for other purposes.  Some coding systems specify their own particular
-translation tables; there are also default translation tables which
-apply to all other coding systems.
+  A @dfn{translation table} is a char-table that specifies a mapping
+of characters into characters.  These tables are used in encoding and
+decoding, and for other purposes.  Some coding systems specify their
+own particular translation tables; there are also default translation
+tables which apply to all other coding systems.
+
+  For instance, the coding-system @code{utf-8} has a translation table
+that maps characters of various charsets (e.g.,
+@code{latin-iso8859-@var{x}}) into Unicode character sets.  This way,
+it can encode Latin-2 characters into UTF-8.  Meanwhile,
+@code{unify-8859-on-decoding-mode} operates by specifying
+@code{standard-translation-table-for-decode} to translate
+Latin-@var{x} characters into corresponding Unicode characters.
 
 @defun make-translation-table &rest translations
 This function returns a translation table based on the argument
@@ -480,24 +525,30 @@
 You can also map one whole character set into another character set with
 the same dimension.  To do this, you specify a generic character (which
 designates a character set) for @var{from} (@pxref{Splitting Characters}).
-In this case, @var{to} should also be a generic character, for another
-character set of the same dimension.  Then the translation table
-translates each character of @var{from}'s character set into the
-corresponding character of @var{to}'s character set.
+In this case, if @var{to} is also a generic character, its character
+set should have the same dimension as @var{from}'s.  Then the
+translation table translates each character of @var{from}'s character
+set into the corresponding character of @var{to}'s character set.  If
+@var{from} is a generic character and @var{to} is an ordinary
+character, then the translation table translates every character of
+@var{from}'s character set into @var{to}.
 @end defun
 
   In decoding, the translation table's translations are applied to the
 characters that result from ordinary decoding.  If a coding system has
-property @code{character-translation-table-for-decode}, that specifies
-the translation table to use.  Otherwise, if
-@code{standard-translation-table-for-decode} is non-@code{nil}, decoding
-uses that table.
+property @code{translation-table-for-decode}, that specifies the
+translation table to use.  (This is a property of the coding system,
+as returned by @code{coding-system-get}, not a property of the symbol
+that is the coding system's name. @xref{Coding System Basics,, Basic
+Concepts of Coding Systems}.)  Otherwise, if
+@code{standard-translation-table-for-decode} is non-@code{nil},
+decoding uses that table.
 
   In encoding, the translation table's translations are applied to the
 characters in the buffer, and the result of translation is actually
 encoded.  If a coding system has property
-@code{character-translation-table-for-encode}, that specifies the
-translation table to use.  Otherwise the variable
+@code{translation-table-for-encode}, that specifies the translation
+table to use.  Otherwise the variable
 @code{standard-translation-table-for-encode} specifies the translation
 table.
 
@@ -513,7 +564,12 @@
 
 @defvar translation-table-for-input
 Self-inserting characters are translated through this translation
-table before they are inserted.
+table before they are inserted.  This variable automatically becomes
+buffer-local when set.
+
+@code{set-buffer-file-coding-system} sets this variable so that your
+keyboard input gets translated into the character sets that the buffer
+is likely to contain.
 @end defvar
 
 @node Coding Systems
@@ -669,6 +725,26 @@
   The variable @code{selection-coding-system} specifies how to encode
 selections for the window system.  @xref{Window System Selections}.
 
+@defvar file-name-coding-system
+The variable @code{file-name-coding-system} specifies the coding
+system to use for encoding file names.  Emacs encodes file names using
+that coding system for all file operations.  If
+@code{file-name-coding-system} is @code{nil}, Emacs uses a default
+coding system determined by the selected language environment.  In the
+default language environment, any non-@acronym{ASCII} characters in
+file names are not encoded specially; they appear in the file system
+using the internal Emacs representation.
+@end defvar
+
+  @strong{Warning:} if you change @code{file-name-coding-system} (or
+the language environment) in the middle of an Emacs session, problems
+can result if you have already visited files whose names were encoded
+using the earlier coding system and are handled differently under the
+new coding system.  If you try to save one of these buffers under the
+visited file name, saving may use the wrong file name, or it may get
+an error.  If such a problem happens, use @kbd{C-x C-w} to specify a
+new file name for that buffer.
+
 @node Lisp and Coding Systems
 @subsection Coding Systems in Lisp
 
@@ -683,7 +759,7 @@
 
 @defun coding-system-p object
 This function returns @code{t} if @var{object} is a coding system
-name.
+name or @code{nil}.
 @end defun
 
 @defun check-coding-system coding-system
@@ -698,6 +774,9 @@
 @var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
 @code{nil}.  If it is @code{nil}, the returned coding system determines
 the end-of-line conversion from the data.
+
+@var{eol-type} may also be 0, 1 or 2, standing for @code{unix},
+@code{dos} and @code{mac}, respectively.
 @end defun
 
 @defun coding-system-change-text-conversion eol-coding text-coding
@@ -741,56 +820,80 @@
 return value is just one coding system, the one that is highest in
 priority.
 
-If the region contains only @sc{ascii} characters, the value
-is @code{undecided} or @code{(undecided)}.
+If the region contains only @acronym{ASCII} characters, the value
+is @code{undecided} or @code{(undecided)}, or a variant specifying
+end-of-line conversion, if that can be deduced from the text.
 @end defun
 
-@defun detect-coding-string string highest
+@defun detect-coding-string string &optional highest
 This function is like @code{detect-coding-region} except that it
 operates on the contents of @var{string} instead of bytes in the buffer.
 @end defun
 
-  @xref{Process Information}, for how to examine or set the coding
-systems used for I/O to a subprocess.
+  @xref{Coding systems for a subprocess,, Process Information}, in
+particular the description of the functions
+@code{process-coding-system} and @code{set-process-coding-system}, for
+how to examine or set the coding systems used for I/O to a subprocess.
 
 @node User-Chosen Coding Systems
 @subsection User-Chosen Coding Systems
 
 @cindex select safe coding system
-@defun select-safe-coding-system from to &optional default-coding-system accept-default-p
+@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file
 This function selects a coding system for encoding specified text,
 asking the user to choose if necessary.  Normally the specified text
-is the text in the current buffer between @var{from} and @var{to},
-defaulting to the whole buffer if they are @code{nil}.  If @var{from}
-is a string, the string specifies the text to encode, and @var{to} is
-ignored.
+is the text in the current buffer between @var{from} and @var{to}.  If
+@var{from} is a string, the string specifies the text to encode, and
+@var{to} is ignored.
 
 If @var{default-coding-system} is non-@code{nil}, that is the first
 coding system to try; if that can handle the text,
 @code{select-safe-coding-system} returns that coding system.  It can
 also be a list of coding systems; then the function tries each of them
-one by one.  After trying all of them, it next tries the user's most
-preferred coding system (@pxref{Recognize Coding,
-prefer-coding-system, the description of @code{prefer-coding-system},
-emacs, GNU Emacs Manual}), and after that the current buffer's value
-of @code{buffer-file-coding-system} (if it is not @code{undecided}).
+one by one.  After trying all of them, it next tries the current
+buffer's value of @code{buffer-file-coding-system} (if it is not
+@code{undecided}), then the value of
+@code{default-buffer-file-coding-system} and finally the user's most
+preferred coding system, which the user can set using the command
+@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing
+Coding Systems, emacs, The GNU Emacs Manual}).
 
 If one of those coding systems can safely encode all the specified
 text, @code{select-safe-coding-system} chooses it and returns it.
 Otherwise, it asks the user to choose from a list of coding systems
 which can encode all the text, and returns the user's choice.
 
+@var{default-coding-system} can also be a list whose first element is
+t and whose other elements are coding systems.  Then, if no coding
+system in the list can handle the text, @code{select-safe-coding-system}
+queries the user immediately, without trying any of the three
+alternatives described above.
+
 The optional argument @var{accept-default-p}, if non-@code{nil},
-should be a function to determine whether the coding system selected
-without user interaction is acceptable.  If this function returns
-@code{nil}, the silently selected coding system is rejected, and the
-user is asked to select a coding system from a list of possible
-candidates.
+should be a function to determine whether a coding system selected
+without user interaction is acceptable. @code{select-safe-coding-system}
+calls this function with one argument, the base coding system of the
+selected coding system.  If @var{accept-default-p} returns @code{nil},
+@code{select-safe-coding-system} rejects the silently selected coding
+system, and asks the user to select a coding system from a list of
+possible candidates.
 
 @vindex select-safe-coding-system-accept-default-p
 If the variable @code{select-safe-coding-system-accept-default-p} is
 non-@code{nil}, its value overrides the value of
 @var{accept-default-p}.
+
+As a final step, before returning the chosen coding system,
+@code{select-safe-coding-system} checks whether that coding system is
+consistent with what would be selected if the contents of the region
+were read from a file.  (If not, this could lead to data corruption in
+a file subsequently re-visited and edited.)  Normally,
+@code{select-safe-coding-system} uses @code{buffer-file-name} as the
+file for this purpose, but if @var{file} is non-@code{nil}, it uses
+that file instead (this can be relevant for @code{write-region} and
+similar functions).  If it detects an apparent inconsistency,
+@code{select-safe-coding-system} queries the user before selecting the
+coding system.
 @end defun
 
   Here are two functions you can use to let the user specify a coding
@@ -851,9 +954,11 @@
 specifies the coding system for decoding, and its @sc{cdr} specifies the
 coding system for encoding.
 
-If @var{coding} is a function name, the function must return a coding
-system or a cons cell containing two coding systems.  This value is used
-as described above.
+If @var{coding} is a function name, the function should take one
+argument, a list of all arguments passed to
+@code{find-operation-coding-system}.  It must return a coding system
+or a cons cell containing two coding systems.  This value has the same
+meaning as described above.
 @end defvar
 
 @defvar process-coding-system-alist
@@ -920,7 +1025,7 @@
 form:
 
 @example
-(@var{decoding-system} @var{encoding-system})
+(@var{decoding-system} . @var{encoding-system})
 @end example
 
 The first element, @var{decoding-system}, is the coding system to use
@@ -945,7 +1050,6 @@
 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}.
-@xref{Default Coding Systems}.
 @end defun
 
 @node Specifying Coding Systems
@@ -972,8 +1076,8 @@
 
 @example
 ;; @r{Read the file with no character code conversion.}
-;; @r{Assume @sc{crlf} represents end-of-line.}
-(let ((coding-system-for-write 'emacs-mule-dos))
+;; @r{Assume @acronym{crlf} represents end-of-line.}
+(let ((coding-system-for-read 'emacs-mule-dos))
   (insert-file-contents filename))
 @end example
 
@@ -1037,33 +1141,41 @@
 are meant to operate on sequences of bytes.  All of these functions
 discard text properties.
 
-@defun encode-coding-region start end coding-system
-This function encodes the text from @var{start} to @var{end} according
+@deffn Command encode-coding-region start end coding-system
+This command encodes the text from @var{start} to @var{end} according
 to coding system @var{coding-system}.  The encoded text replaces the
 original text in the buffer.  The result of encoding is logically a
 sequence of bytes, but the buffer remains multibyte if it was multibyte
 before.
-@end defun
 
-@defun encode-coding-string string coding-system
+This command returns the length of the encoded text.
+@end deffn
+
+@defun encode-coding-string string coding-system &optional nocopy
 This function encodes the text in @var{string} according to coding
 system @var{coding-system}.  It returns a new string containing the
-encoded text.  The result of encoding is a unibyte string.
+encoded text, except when @var{nocopy} is non-@code{nil}, in which
+case the function may return @var{string} itself if the encoding
+operation is trivial.  The result of encoding is a unibyte string.
 @end defun
 
-@defun decode-coding-region start end coding-system
-This function decodes the text from @var{start} to @var{end} according
+@deffn Command decode-coding-region start end coding-system
+This command decodes the text from @var{start} to @var{end} according
 to coding system @var{coding-system}.  The decoded text replaces the
 original text in the buffer.  To make explicit decoding useful, the text
 before decoding ought to be a sequence of byte values, but both
 multibyte and unibyte buffers are acceptable.
-@end defun
 
-@defun decode-coding-string string coding-system
+This command returns the length of the decoded text.
+@end deffn
+
+@defun decode-coding-string string coding-system &optional nocopy
 This function decodes the text in @var{string} according to coding
 system @var{coding-system}.  It returns a new string containing the
-decoded text.  To make explicit decoding useful, the contents of
-@var{string} ought to be a sequence of byte values, but a multibyte
+decoded text, except when @var{nocopy} is non-@code{nil}, in which
+case the function may return @var{string} itself if the decoding
+operation is trivial.  To make explicit decoding useful, the contents
+of @var{string} ought to be a sequence of byte values, but a multibyte
 string is acceptable.
 @end defun
 
@@ -1092,22 +1204,22 @@
 keyboard input---or @code{nil} if no coding system is to be used.
 @end defun
 
-@defun set-keyboard-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to
+@deffn Command set-keyboard-coding-system coding-system
+This command specifies @var{coding-system} as the coding system to
 use for decoding keyboard input.  If @var{coding-system} is @code{nil},
 that means do not decode keyboard input.
-@end defun
+@end deffn
 
 @defun terminal-coding-system
 This function returns the coding system that is in use for encoding
 terminal output---or @code{nil} for no encoding.
 @end defun
 
-@defun set-terminal-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to use
+@deffn Command set-terminal-coding-system coding-system
+This command specifies @var{coding-system} as the coding system to use
 for encoding terminal output.  If @var{coding-system} is @code{nil},
 that means do not encode terminal output.
-@end defun
+@end deffn
 
 @node MS-DOS File Types
 @subsection MS-DOS File Types
@@ -1172,9 +1284,9 @@
 @section Input Methods
 @cindex input methods
 
-  @dfn{Input methods} provide convenient ways of entering non-@sc{ascii}
+  @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII}
 characters from the keyboard.  Unlike coding systems, which translate
-non-@sc{ascii} characters to and from encodings meant to be read by
+non-@acronym{ASCII} characters to and from encodings meant to be read by
 programs, input methods provide human-friendly commands.  (@xref{Input
 Methods,,, emacs, The GNU Emacs Manual}, for information on how users
 use input methods to enter text.)  How to define input methods is not
@@ -1190,18 +1302,18 @@
 buffer now.
 @end defvar
 
-@defvar default-input-method
+@defopt default-input-method
 This variable holds the default input method for commands that choose an
 input method.  Unlike @code{current-input-method}, this variable is
 normally global.
-@end defvar
+@end defopt
 
-@defun set-input-method input-method
-This function activates input method @var{input-method} for the current
+@deffn Command set-input-method input-method
+This command activates input method @var{input-method} for the current
 buffer.  It also sets @code{default-input-method} to @var{input-method}.
-If @var{input-method} is @code{nil}, this function deactivates any input
+If @var{input-method} is @code{nil}, this command deactivates any input
 method for the current buffer.
-@end defun
+@end deffn
 
 @defun read-input-method-name prompt &optional default inhibit-null
 This function reads an input method name with the minibuffer, prompting
@@ -1237,7 +1349,8 @@
 @end defvar
 
   The fundamental interface to input methods is through the
-variable @code{input-method-function}.  @xref{Reading One Event}.
+variable @code{input-method-function}.  @xref{Reading One Event},
+and @ref{Invoking the Input Method}.
 
 @node Locales
 @section Locales
@@ -1291,13 +1404,17 @@
 
 @item paper
 Return a list @code{(@var{width} @var{height})} for the default paper
-size measured in milimeters (locale items @code{PAPER_WIDTH} and
+size measured in millimeters (locale items @code{PAPER_WIDTH} and
 @code{PAPER_HEIGHT}).
 @end table
 
 If the system can't provide the requested information, or if
 @var{item} is not one of those symbols, the value is @code{nil}.  All
 strings in the return value are decoded using
-@code{locale-coding-system}.  @xref{Locales,,, libc, GNU Libc Manual},
+@code{locale-coding-system}.  @xref{Locales,,, libc, The GNU Libc Manual},
 for more information about locales and locale items.
 @end defun
+
+@ignore
+   arch-tag: be705bf8-941b-4c35-84fc-ad7d20ddb7cb
+@end ignore

--- a/lispref/numbers.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/numbers.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/numbers
@@ -36,22 +36,22 @@
 @section Integer Basics
 
   The range of values for an integer depends on the machine.  The
-minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
+minimum range is @minus{}268435456 to 268435455 (29 bits; i.e.,
 @ifnottex
--2**27
+-2**28
 @end ifnottex
 @tex
-@math{-2^{27}}
+@math{-2^{28}}
 @end tex
 to
 @ifnottex
-2**27 - 1),
+2**28 - 1),
 @end ifnottex
 @tex
-@math{2^{27}-1}),
+@math{2^{28}-1}),
 @end tex
 but some machines may provide a wider range.  Many examples in this
-chapter assume an integer has 28 bits.
+chapter assume an integer has 29 bits.
 @cindex overflow
 
   The Lisp reader reads an integer as a sequence of digits with optional
@@ -62,7 +62,7 @@
  1.              ; @r{The integer 1.}
 +1               ; @r{Also the integer 1.}
 -1               ; @r{The integer @minus{}1.}
- 268435457       ; @r{Also the integer 1, due to overflow.}
+ 536870913       ; @r{Also the integer 1, due to overflow.}
  0               ; @r{The integer 0.}
 -0               ; @r{The integer 0.}
 @end example
@@ -70,6 +70,9 @@
 @cindex integers in specific radix
 @cindex radix for reading an integer
 @cindex base for reading an integer
+@cindex hex numbers
+@cindex octal numbers
+@cindex reading numbers in hex, octal, and binary
   In addition, the Lisp reader recognizes a syntax for integers in
 bases other than 10: @samp{#B@var{integer}} reads @var{integer} in
 binary (radix 2), @samp{#O@var{integer}} reads @var{integer} in octal
@@ -83,10 +86,10 @@
 bitwise operators (@pxref{Bitwise Operations}), it is often helpful to
 view the numbers in their binary form.
 
-  In 28-bit binary, the decimal integer 5 looks like this:
+  In 29-bit binary, the decimal integer 5 looks like this:
 
 @example
-0000  0000 0000  0000 0000  0000 0101
+0 0000  0000 0000  0000 0000  0000 0101
 @end example
 
 @noindent
@@ -96,12 +99,12 @@
   The integer @minus{}1 looks like this:
 
 @example
-1111  1111 1111  1111 1111  1111 1111
[phone]  1111 1111  1111 1111
 @end example
 
 @noindent
 @cindex two's complement
-@minus{}1 is represented as 28 ones.  (This is called @dfn{two's
+@minus{}1 is represented as 29 ones.  (This is called @dfn{two's
 complement} notation.)
 
   The negative integer, @minus{}5, is creating by subtracting 4 from
@@ -109,24 +112,24 @@
 @minus{}5 looks like this:
 
 @example
-1111  1111 1111  1111 1111  1111 1011
[phone]  1111 1111  1111 1011
 @end example
 
-  In this implementation, the largest 28-bit binary integer value is
-134,217,727 in decimal.  In binary, it looks like this:
+  In this implementation, the largest 29-bit binary integer value is
+268,435,455 in decimal.  In binary, it looks like this:
 
 @example
-0111  1111 1111  1111 1111  1111 1111
+0 1111  1111 1111  1111 1111  1111 1111
 @end example
 
   Since the arithmetic functions do not check whether integers go
-outside their range, when you add 1 to 134,217,727, the value is the
-negative integer @minus{}134,217,728:
+outside their range, when you add 1 to 268,435,455, the value is the
+negative integer @minus{}268,435,456:
 
 @example
-(+ 1 134217727)
-     @result{} -134217728
-     @result{} 1000  0000 0000  0000 0000  0000 0000
+(+ 1 268435455)
+     @result{} -268435456
+     @result{} 1 0000  0000 0000  0000 0000  0000 0000
 @end example
 
   Many of the functions described in this chapter accept markers for
@@ -160,16 +163,16 @@
 value is 1500.  They are all equivalent.  You can also use a minus sign
 to write negative floating point numbers, as in @samp{-1.0}.
 
-@cindex IEEE floating point
+@cindex @acronym{IEEE} floating point
 @cindex positive infinity
 @cindex negative infinity
 @cindex infinity
 @cindex NaN
-   Most modern computers support the IEEE floating point standard, which
-provides for positive infinity and negative infinity as floating point
+  Most modern computers support the @acronym{IEEE} floating point standard,
+which provides for positive infinity and negative infinity as floating point
 values.  It also provides for a class of values called NaN or
 ``not-a-number''; numerical functions return such values in cases where
-there is no correct answer.  For example, @code{(sqrt -1.0)} returns a
+there is no correct answer.  For example, @code{(/ 0.0 0.0)} returns a
 NaN.  For practical purposes, there's no significant difference between
 different NaN values in Emacs Lisp, and there's no rule for precisely
 which NaN value should be used in a particular case, so Emacs Lisp
@@ -186,8 +189,8 @@
 @end table
 
   In addition, the value @code{-0.0} is distinguishable from ordinary
-zero in IEEE floating point (although @code{equal} and @code{=} consider
-them equal values).
+zero in @acronym{IEEE} floating point (although @code{equal} and
+@code{=} consider them equal values).
 
   You can use @code{logb} to extract the binary exponent of a floating
 point number (or estimate the logarithm of an integer):
@@ -376,10 +379,16 @@
 @end defun
 
 There are four functions to convert floating point numbers to integers;
-they differ in how they round.  These functions accept integer arguments
-also, and return such arguments unchanged.
+they differ in how they round.  All accept an argument @var{number}
+and an optional argument @var{divisor}.  Both arguments may be
+integers or floating point numbers.  @var{divisor} may also be
+@code{nil}.  If @var{divisor} is @code{nil} or omitted, these
+functions convert @var{number} to an integer, or return it unchanged
+if it already is an integer.  If @var{divisor} is non-@code{nil}, they
+divide @var{number} by @var{divisor} and convert the result to an
+integer.  An @code{arith-error} results if @var{divisor} is 0.
 
-@defun truncate number
+@defun truncate number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards
 zero.
 
@@ -399,10 +408,8 @@
 This returns @var{number}, converted to an integer by rounding downward
 (towards negative infinity).
 
-If @var{divisor} is specified, @code{floor} divides @var{number} by
-@var{divisor} and then converts to an integer; this uses the kind of
-division operation that corresponds to @code{mod}, rounding downward.
-An @code{arith-error} results if @var{divisor} is 0.
+If @var{divisor} is specified, this uses the kind of division
+operation that corresponds to @code{mod}, rounding downward.
 
 @example
 (floor 1.2)
@@ -418,7 +425,7 @@
 @end example
 @end defun
 
-@defun ceiling number
+@defun ceiling number &optional divisor
 This returns @var{number}, converted to an integer by rounding upward
 (towards positive infinity).
 
@@ -434,7 +441,7 @@
 @end example
 @end defun
 
-@defun round number
+@defun round number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards the
 nearest integer.  Rounding a value equidistant between two integers
 may choose the integer closer to zero, or it may prefer an even integer,
@@ -465,8 +472,8 @@
 if any argument is floating.
 
   It is important to note that in Emacs Lisp, arithmetic functions
-do not check for overflow.  Thus @code{(1+ 134217727)} may evaluate to
-@minus{}134217728, depending on your hardware.
+do not check for overflow.  Thus @code{(1+ 268435455)} may evaluate to
+@minus{}268435456, depending on your hardware.
 
 @defun 1+ number-or-marker
 This function returns @var{number-or-marker} plus 1.
@@ -562,7 +569,7 @@
 @cindex @code{arith-error} in division
 If you divide an integer by 0, an @code{arith-error} error is signaled.
 (@xref{Errors}.)  Floating point division by zero returns either
-infinity or a NaN if your machine supports IEEE floating point;
+infinity or a NaN if your machine supports @acronym{IEEE} floating point;
 otherwise, it signals an @code{arith-error} error.
 
 @example
@@ -785,19 +792,19 @@
 The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
 not check for overflow, so shifting left can discard significant bits
 and change the sign of the number.  For example, left shifting
-134,217,727 produces @minus{}2 on a 28-bit machine:
+268,435,455 produces @minus{}2 on a 29-bit machine:
 
 @example
-(lsh 134217727 1)          ; @r{left shift}
+(lsh 268435455 1)          ; @r{left shift}
      @result{} -2
 @end example
 
-In binary, in the 28-bit implementation, the argument looks like this:
+In binary, in the 29-bit implementation, the argument looks like this:
 
 @example
 @group
-;; @r{Decimal 134,217,727}
-0111  1111 1111  1111 1111  1111 1111
+;; @r{Decimal 268,435,455}
+0 1111  1111 1111  1111 1111  1111 1111
 @end group
 @end example
 
@@ -807,7 +814,7 @@
 @example
 @group
 ;; @r{Decimal @minus{}2}
-1111  1111 1111  1111 1111  1111 1110
[phone]  1111 1111  1111 1110
 @end group
 @end example
 @end defun
@@ -830,9 +837,9 @@
 @group
 (ash -6 -1) @result{} -3
 ;; @r{Decimal @minus{}6 becomes decimal @minus{}3.}
-1111  1111 1111  1111 1111  1111 1010
[phone]  1111 1111  1111 1010
      @result{}
-1111  1111 1111  1111 1111  1111 1101
[phone]  1111 1111  1111 1101
 @end group
 @end example
 
@@ -841,11 +848,11 @@
 
 @example
 @group
-(lsh -6 -1) @result{} 134217725
-;; @r{Decimal @minus{}6 becomes decimal 134,217,725.}
-1111  1111 1111  1111 1111  1111 1010
+(lsh -6 -1) @result{} 268435453
+;; @r{Decimal @minus{}6 becomes decimal 268,435,453.}
[phone]  1111 1111  1111 1010
      @result{}
-0111  1111 1111  1111 1111  1111 1101
+0 1111  1111 1111  1111 1111  1111 1101
 @end group
 @end example
 
@@ -855,34 +862,34 @@
 @c     with smallbook but not with regular book! --rjc 16mar92
 @smallexample
 @group
-                   ;  @r{             28-bit binary values}
+                   ;  @r{             29-bit binary values}
 
-(lsh 5 2)          ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 20         ;      =  @r{0000  0000 0000  0000 0000  0001 0100}
+(lsh 5 2)          ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 20         ;      =  @r{0 0000  0000 0000  0000 0000  0001 0100}
 @end group
 @group
 (ash 5 2)
      @result{} 20
-(lsh -5 2)         ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
-     @result{} -20        ;      =  @r{1111  1111 1111  1111 1111  1110 1100}
+(lsh -5 2)         ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} -20        ;      =  @r{1 1111  1111 1111  1111 1111  1110 1100}
 (ash -5 2)
      @result{} -20
 @end group
 @group
-(lsh 5 -2)         ;   5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 1          ;      =  @r{0000  0000 0000  0000 0000  0000 0001}
+(lsh 5 -2)         ;   5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 1          ;      =  @r{0 0000  0000 0000  0000 0000  0000 0001}
 @end group
 @group
 (ash 5 -2)
      @result{} 1
 @end group
 @group
-(lsh -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
-     @result{} 4194302    ;      =  @r{0011  1111 1111  1111 1111  1111 1110}
+(lsh -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} 134217726  ;      =  @r{0 0111  1111 1111  1111 1111  1111 1110}
 @end group
 @group
-(ash -5 -2)        ;  -5  =  @r{1111  1111 1111  1111 1111  1111 1011}
-     @result{} -2         ;      =  @r{1111  1111 1111  1111 1111  1111 1110}
+(ash -5 -2)        ;  -5  =  @r{1 1111  1111 1111  1111 1111  1111 1011}
+     @result{} -2         ;      =  @r{1 1111  1111 1111  1111 1111  1111 1110}
 @end group
 @end smallexample
 @end defun
@@ -919,23 +926,23 @@
 
 @smallexample
 @group
-                   ; @r{               28-bit binary values}
+                   ; @r{               29-bit binary values}
 
-(logand 14 13)     ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
-                   ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
-     @result{} 12         ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
+(logand 14 13)     ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
+                   ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
+     @result{} 12         ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
 @end group
 
 @group
-(logand 14 13 4)   ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
-                   ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
-                   ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
-     @result{} 4          ;  4  =  @r{0000  0000 0000  0000 0000  0000 0100}
+(logand 14 13 4)   ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
+                   ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
+                   ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
+     @result{} 4          ;  4  =  @r{0 0000  0000 0000  0000 0000  0000 0100}
 @end group
 
 @group
 (logand)
-     @result{} -1         ; -1  =  @r{1111  1111 1111  1111 1111  1111 1111}
+     @result{} -1         ; -1  =  @r{1 1111  1111 1111  1111 1111  1111 1111}
 @end group
 @end smallexample
 @end defun
@@ -951,18 +958,18 @@
 
 @smallexample
 @group
-                   ; @r{              28-bit binary values}
+                   ; @r{              29-bit binary values}
 
-(logior 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 13         ; 13  =  @r{0000  0000 0000  0000 0000  0000 1101}
+(logior 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 13         ; 13  =  @r{0 0000  0000 0000  0000 0000  0000 1101}
 @end group
 
 @group
-(logior 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-                   ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
-     @result{} 15         ; 15  =  @r{0000  0000 0000  0000 0000  0000 1111}
+(logior 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+                   ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
+     @result{} 15         ; 15  =  @r{0 0000  0000 0000  0000 0000  0000 1111}
 @end group
 @end smallexample
 @end defun
@@ -978,18 +985,18 @@
 
 @smallexample
 @group
-                   ; @r{              28-bit binary values}
+                   ; @r{              29-bit binary values}
 
-(logxor 12 5)      ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-     @result{} 9          ;  9  =  @r{0000  0000 0000  0000 0000  0000 1001}
+(logxor 12 5)      ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+     @result{} 9          ;  9  =  @r{0 0000  0000 0000  0000 0000  0000 1001}
 @end group
 
 @group
-(logxor 12 5 7)    ; 12  =  @r{0000  0000 0000  0000 0000  0000 1100}
-                   ;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
-                   ;  7  =  @r{0000  0000 0000  0000 0000  0000 0111}
-     @result{} 14         ; 14  =  @r{0000  0000 0000  0000 0000  0000 1110}
+(logxor 12 5 7)    ; 12  =  @r{0 0000  0000 0000  0000 0000  0000 1100}
+                   ;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
+                   ;  7  =  @r{0 0000  0000 0000  0000 0000  0000 0111}
+     @result{} 14         ; 14  =  @r{0 0000  0000 0000  0000 0000  0000 1110}
 @end group
 @end smallexample
 @end defun
@@ -1004,9 +1011,9 @@
 @example
 (lognot 5)
      @result{} -6
-;;  5  =  @r{0000  0000 0000  0000 0000  0000 0101}
+;;  5  =  @r{0 0000  0000 0000  0000 0000  0000 0101}
 ;; @r{becomes}
-;; -6  =  @r{1111  1111 1111  1111 1111  1111 1010}
+;; -6  =  @r{1 1111  1111 1111  1111 1111  1111 1010}
 @end example
 @end defun
 
@@ -1040,8 +1047,8 @@
 @tex
 @math{\pi/2}
 @end tex
-(inclusive) whose sine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
+range (outside [-1, 1]), it signals a @code{domain-error} error.
 @end defun
 
 @defun acos arg
@@ -1052,8 +1059,8 @@
 @tex
 @math{\pi}
 @end tex
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg}
-is out of range (outside [-1, 1]), then the result is a NaN.
+(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
+of range (outside [-1, 1]), it signals a @code{domain-error} error.
 @end defun
 
 @defun atan y &optional x
@@ -1105,8 +1112,8 @@
 @ifnottex
 @i{e}
 @end ifnottex
-is used.  If @var{arg}
-is negative, the result is a NaN.
+is used.  If @var{arg} is negative, it signals a @code{domain-error}
+error.
 @end defun
 
 @ignore
@@ -1125,8 +1132,9 @@
 
 @defun log10 arg
 This function returns the logarithm of @var{arg}, with base 10.  If
-@var{arg} is negative, the result is a NaN.  @code{(log10 @var{x})}
-@equiv{} @code{(log @var{x} 10)}, at least approximately.
+@var{arg} is negative, it signals a @code{domain-error} error.
+@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
+approximately.
 @end defun
 
 @defun expt x y
@@ -1138,7 +1146,7 @@
 
 @defun sqrt arg
 This returns the square root of @var{arg}.  If @var{arg} is negative,
-the value is a NaN.
+it signals a @code{domain-error} error.
 @end defun
 
 @node Random Numbers
@@ -1163,7 +1171,7 @@
 
 If you want random numbers that don't always come out the same, execute
 @code{(random t)}.  This chooses a new seed based on the current time of
-day and on Emacs's process @sc{id} number.
+day and on Emacs's process @acronym{ID} number.
 
 @defun random &optional limit
 This function returns a pseudo-random integer.  Repeated calls return a
@@ -1173,10 +1181,14 @@
 nonnegative and less than @var{limit}.
 
 If @var{limit} is @code{t}, it means to choose a new seed based on the
-current time of day and on Emacs's process @sc{id} number.
+current time of day and on Emacs's process @acronym{ID} number.
 @c "Emacs'" is incorrect usage!
 
 On some machines, any integer representable in Lisp may be the result
 of @code{random}.  On other machines, the result can never be larger
 than a certain maximum or less than a certain (negative) minimum.
 @end defun
+
+@ignore
+   arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e
+@end ignore

--- a/lispref/objects.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/objects.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -42,7 +42,9 @@
 variable, and the type is known by the compiler but not represented in
 the data.  Such type declarations do not exist in Emacs Lisp.  A Lisp
 variable can have any type of value, and it remembers whatever value
-you store in it, type and all.
+you store in it, type and all.  (Actually, a small number of Emacs
+Lisp variables can only take on values of a certain type.
+@xref{Variables with Restricted Values}.)
 
   This chapter describes the purpose, printed representation, and read
 syntax of each of the standard types in GNU Emacs Lisp.  Details on how
@@ -161,24 +163,24 @@
 @node Integer Type
 @subsection Integer Type
 
-  The range of values for integers in Emacs Lisp is @minus{}134217728 to
-134217727 (28 bits; i.e.,
+  The range of values for integers in Emacs Lisp is @minus{}268435456 to
[phone] (29 bits; i.e.,
 @ifnottex
--2**27
+-2**28
 @end ifnottex
 @tex
-@math{-2^{27}}
+@math{-2^{28}}
 @end tex
 to
 @ifnottex
-2**27 - 1)
+2**28 - 1)
 @end ifnottex
 @tex
 @math{2^{28}-1})
 @end tex
 on most machines.  (Some machines may provide a wider range.)  It is
 important to note that the Emacs Lisp arithmetic functions do not check
-for overflow.  Thus @code{(1+ 134217727)} is @minus{}134217728 on most
+for overflow.  Thus @code{(1+ 268435455)} is @minus{}268435456 on most
 machines.
 
   The read syntax for integers is a sequence of (base ten) digits with an
@@ -192,7 +194,7 @@
 1                ; @r{The integer 1.}
 1.               ; @r{Also the integer 1.}
 +1               ; @r{Also the integer 1.}
-268435457        ; @r{Also the integer 1 on a 28-bit implementation.}
[phone]        ; @r{Also the integer 1 on a 29-bit implementation.}
 @end group
 @end example
 
@@ -216,7 +218,7 @@
 
 @node Character Type
 @subsection Character Type
-@cindex @sc{ascii} character codes
+@cindex @acronym{ASCII} character codes
 
   A @dfn{character} in Emacs Lisp is nothing more than an integer.  In
 other words, characters are represented by their character codes.  For
@@ -226,11 +228,12 @@
 common to work with @emph{strings}, which are sequences composed of
 characters.  @xref{String Type}.
 
-  Characters in strings, buffers, and files are currently limited to the
-range of 0 to 524287---nineteen bits.  But not all values in that range
-are valid character codes.  Codes 0 through 127 are @sc{ascii} codes; the
-rest are non-@sc{ascii} (@pxref{Non-ASCII Characters}).  Characters that represent
-keyboard input have a much wider range, to encode modifier keys such as
+  Characters in strings, buffers, and files are currently limited to
+the range of 0 to 524287---nineteen bits.  But not all values in that
+range are valid character codes.  Codes 0 through 127 are
+@acronym{ASCII} codes; the rest are non-@acronym{ASCII}
+(@pxref{Non-ASCII Characters}).  Characters that represent keyboard
+input have a much wider range, to encode modifier keys such as
 Control, Meta and Shift.
 
 @cindex read syntax for characters
@@ -323,9 +326,9 @@
 @end example
 
   In strings and buffers, the only control characters allowed are those
-that exist in @sc{ascii}; but for keyboard input purposes, you can turn
+that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
 any character into a control character with @samp{C-}.  The character
-codes for these non-@sc{ascii} control characters include the
+codes for these non-@acronym{ASCII} control characters include the
 @tex
 @math{2^{26}}
 @end tex
@@ -333,7 +336,7 @@
 2**26
 @end ifnottex
 bit as well as the code for the corresponding non-control
-character.  Ordinary terminals have no way of generating non-@sc{ascii}
+character.  Ordinary terminals have no way of generating non-@acronym{ASCII}
 control characters, but you can generate them straightforwardly using X
 and other window systems.
 
@@ -365,9 +368,8 @@
 @ifnottex
 2**27
 @end ifnottex
-bit set (which on most machines makes it a negative number).  We
-use high bits for this and other modifiers to make possible a wide range
-of basic character codes.
+bit set.  We use high bits for this and other modifiers to make
+possible a wide range of basic character codes.
 
   In a string, the
 @tex
@@ -376,11 +378,11 @@
 @ifnottex
 2**7
 @end ifnottex
-bit attached to an @sc{ascii} character indicates a meta character; thus, the
-meta characters that can fit in a string have codes in the range from
-128 to 255, and are the meta versions of the ordinary @sc{ascii}
-characters.  (In Emacs versions 18 and older, this convention was used
-for characters outside of strings as well.)
+bit attached to an @acronym{ASCII} character indicates a meta
+character; thus, the meta characters that can fit in a string have
+codes in the range from 128 to 255, and are the meta versions of the
+ordinary @acronym{ASCII} characters.  (In Emacs versions 18 and older,
+this convention was used for characters outside of strings as well.)
 
   The read syntax for meta characters uses @samp{\M-}.  For example,
 @samp{?\M-A} stands for @kbd{M-A}.  You can use @samp{\M-} together with
@@ -390,8 +392,8 @@
 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
 
   The case of a graphic character is indicated by its character code;
-for example, @sc{ascii} distinguishes between the characters @samp{a}
-and @samp{A}.  But @sc{ascii} has no way to represent whether a control
+for example, @acronym{ASCII} distinguishes between the characters @samp{a}
+and @samp{A}.  But @acronym{ASCII} has no way to represent whether a control
 character is upper case or lower case.  Emacs uses the
 @tex
 @math{2^{25}}
@@ -409,15 +411,16 @@
 @cindex hyper characters
 @cindex super characters
 @cindex alt characters
-  The X Window System defines three other modifier bits that can be set
+  The X Window System defines three other @anchor{modifier bits}
+modifier bits that can be set
 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}.  The syntaxes
 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}.  (Case is
 significant in these prefixes.)  Thus, @samp{?\H-\M-\A-x} represents
 @kbd{Alt-Hyper-Meta-x}.  (Note that @samp{\s} with no following @samp{-}
 represents the space character.)
 @tex
-Numerically, the
-bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
+Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
+for super and @math{2^{24}} for hyper.
 @end tex
 @ifnottex
 Numerically, the
@@ -432,9 +435,9 @@
 mark followed by a backslash and the octal character code (up to three
 octal digits); thus, @samp{?\101} for the character @kbd{A},
 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
-character @kbd{C-b}.  Although this syntax can represent any @sc{ascii}
+character @kbd{C-b}.  Although this syntax can represent any @acronym{ASCII}
 character, it is preferred only when the precise octal value is more
-important than the @sc{ascii} representation.
+important than the @acronym{ASCII} representation.
 
 @example
 @group
@@ -915,11 +918,11 @@
 @end example
 
 @node Non-ASCII in Strings
-@subsubsection Non-@sc{ascii} Characters in Strings
+@subsubsection Non-@acronym{ASCII} Characters in Strings
 
-  You can include a non-@sc{ascii} international character in a string
+  You can include a non-@acronym{ASCII} international character in a string
 constant by writing it literally.  There are two text representations
-for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
+for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
 and multibyte.  If the string constant is read from a multibyte source,
 such as a multibyte buffer or string, or a file that would be visited as
 multibyte, then the character is read as a multibyte character, and that
@@ -927,9 +930,9 @@
 unibyte source, then the character is read as unibyte and that makes the
 string unibyte.
 
-  You can also represent a multibyte non-@sc{ascii} character with its
+  You can also represent a multibyte non-@acronym{ASCII} character with its
 character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
-digits as necessary.  (Multibyte non-@sc{ascii} character codes are all
+digits as necessary.  (Multibyte non-@acronym{ASCII} character codes are all
 greater than 256.)  Any character which is not a valid hex digit
 terminates this construct.  If the next character in the string could be
 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
@@ -938,10 +941,13 @@
 constant is just like backslash-newline; it does not contribute any
 character to the string, but it does terminate the preceding hex escape.
 
-  Using a multibyte hex escape forces the string to multibyte.  You can
-represent a unibyte non-@sc{ascii} character with its character code,
-which must be in the range from 128 (0200 octal) to 255 (0377 octal).
-This forces a unibyte string.
+  You can represent a unibyte non-@acronym{ASCII} character with its
+character code, which must be in the range from 128 (0200 octal) to
+255 (0377 octal).  If you write all such character codes in octal and
+the string contains no other characters forcing it to be multibyte,
+this produces a unibyte string.  However, using any hex escape in a
+string (even for an @acronym{ASCII} character) forces the string to be
+multibyte.
 
   @xref{Text Representations}, for more information about the two
 text representations.
@@ -958,14 +964,14 @@
 
   However, not all of the characters you can write with backslash
 escape-sequences are valid in strings.  The only control characters that
-a string can hold are the @sc{ascii} control characters.  Strings do not
-distinguish case in @sc{ascii} control characters.
+a string can hold are the @acronym{ASCII} control characters.  Strings do not
+distinguish case in @acronym{ASCII} control characters.
 
   Properly speaking, strings cannot hold meta characters; but when a
 string is to be used as a key sequence, there is a special convention
-that provides a way to represent meta versions of @sc{ascii} characters in a
-string.  If you use the @samp{\M-} syntax to indicate a meta character
-in a string constant, this sets the
+that provides a way to represent meta versions of @acronym{ASCII}
+characters in a string.  If you use the @samp{\M-} syntax to indicate
+a meta character in a string constant, this sets the
 @tex
 @math{2^{7}}
 @end tex
@@ -1082,16 +1088,25 @@
 as a bitmap---each ``character'' in the string contains 8 bits, which
 specify the next 8 elements of the bool-vector (1 stands for @code{t},
 and 0 for @code{nil}).  The least significant bits of the character
-correspond to the lowest indices in the bool-vector.  If the length is not a
-multiple of 8, the printed representation shows extra elements, but
-these extras really make no difference.
+correspond to the lowest indices in the bool-vector.
 
 @example
 (make-bool-vector 3 t)
-     @result{} #&3"\007"
+     @result{} #&3"^G"
 (make-bool-vector 3 nil)
-     @result{} #&3"\0"
-;; @r{These are equal since only the first 3 bits are used.}
+     @result{} #&3"^@@"
+@end example
+
+@noindent
+These results make sense, because the binary code for @samp{C-g} is
+111 and @samp{C-@@} is the character with code 0.
+
+  If the length is not a multiple of 8, the printed representation
+shows extra elements, but these extras really make no difference.  For
+instance, in the next example, the two bool-vectors are equal, because
+only the first 3 bits are used:
+
+@example
 (equal #&3"\377" #&3"\007")
      @result{} t
 @end example
@@ -1484,7 +1499,7 @@
 @cindex @samp{#@var{n}=} read syntax
 @cindex @samp{#@var{n}#} read syntax
 
-  In Emacs 21, to represent shared or circular structure within a
+  In Emacs 21, to represent shared or circular structures within a
 complex of Lisp objects, you can use the reader constructs
 @samp{#@var{n}=} and @samp{#@var{n}#}.
 
@@ -1875,9 +1890,12 @@
 @end example
 
 Comparison of strings is case-sensitive, but does not take account of
-text properties---it compares only the characters in the strings.
-A unibyte string never equals a multibyte string unless the
-contents are entirely @sc{ascii} (@pxref{Text Representations}).
+text properties---it compares only the characters in the strings.  For
+technical reasons, a unibyte string and a multibyte string are
+@code{equal} if and only if they contain the same sequence of
+character codes and all these codes are either in the range 0 through
+127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
+(@pxref{Text Representations}).
 
 @example
 @group
@@ -1902,3 +1920,7 @@
 
 Because of this recursive method, circular lists may therefore cause
 infinite recursion (leading to an error).
+
+@ignore
+   arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096
+@end ignore

--- a/lispref/os.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/os.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -590,7 +590,7 @@
 
   Emacs provides access to variables in the operating system environment
 through various functions.  These variables include the name of the
-system, the user's @sc{uid}, and so on.
+system, the user's @acronym{UID}, and so on.
 
 @defvar system-configuration
 This variable holds the GNU configuration name for the hardware/software
@@ -796,6 +796,11 @@
 If @var{use-float} is non-@code{nil}, then they are returned
 as floating point numbers and without multiplying by 100.
 
+If it is impossible to obtain the load average, this function signals
+an error.  On some platforms, access to load averages requires
+installing Emacs as setuid or setgid so that it can read kernel
+information, and that usually isn't advisable.
+
 @example
 @group
 (load-average)
@@ -815,7 +820,7 @@
 @end defun
 
 @defun emacs-pid
-This function returns the process @sc{id} of the Emacs process.
+This function returns the process @acronym{ID} of the Emacs process.
 @end defun
 
 @defvar tty-erase-char
@@ -865,7 +870,7 @@
 which the user is logged in.  If the environment variable @code{LOGNAME}
 is set, that value is used.  Otherwise, if the environment variable
 @code{USER} is set, that value is used.  Otherwise, the value is based
-on the effective @sc{uid}, not the real @sc{uid}.
+on the effective @acronym{UID}, not the real @acronym{UID}.
 
 If you specify @var{uid}, the value is the user name that corresponds
 to @var{uid} (which should be an integer).
@@ -880,7 +885,7 @@
 
 @defun user-real-login-name
 This function returns the user name corresponding to Emacs's real
-@sc{uid}.  This ignores the effective @sc{uid} and ignores the
+@acronym{UID}.  This ignores the effective @acronym{UID} and ignores the
 environment variables @code{LOGNAME} and @code{USER}.
 @end defun
 
@@ -916,7 +921,7 @@
 Titles}).
 
 @defun user-real-uid
-This function returns the real @sc{uid} of the user.
+This function returns the real @acronym{UID} of the user.
 The value may be a floating point number.
 
 @example
@@ -928,7 +933,7 @@
 @end defun
 
 @defun user-uid
-This function returns the effective @sc{uid} of the user.
+This function returns the effective @acronym{UID} of the user.
 The value may be a floating point number.
 @end defun
 
@@ -1005,6 +1010,13 @@
 (see above) and from @code{file-attributes} (@pxref{File Attributes}).
 @end defun
 
+@defun set-time-zone-rule tz
+This function specifies the local time zone according to @var{tz}.  If
+@var{tz} is @code{nil}, that means to use an implementation-defined
+default time zone.  If @var{tz} is @code{t}, that means to use
+Universal Time.
+@end defun
+
 @defun float-time &optional time-value
 This function returns the current time as a floating-point number of
 seconds since the epoch.  The argument @var{time-value}, if given,
@@ -1233,6 +1245,8 @@
 
 The operating system puts limits on the range of possible time values;
 if you try to encode a time that is out of range, an error results.
+For instance, years before 1970 do not work on some systems;
+on others, years as early as 1901 do work.
 @end defun
 
 @node Time Calculations
@@ -1292,7 +1306,7 @@
 function, because quitting out of many timer functions can leave
 things in an inconsistent state.  This is normally unproblematical
 because most timer functions don't do a lot of work.  Indeed, for a
-timer to calls a function that takes substantial time to run is likely
+timer to call a function that takes substantial time to run is likely
 to be annoying.
 
 @defun run-at-time time repeat function &rest args
@@ -1928,7 +1942,7 @@
 @code{C-s} and @kbd{C-q} for flow control.  Therefore, the choice of
 @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
 was natural and uncontroversial.  With so many commands needing key
-assignments, of course we assigned meanings to nearly all @sc{ascii}
+assignments, of course we assigned meanings to nearly all @acronym{ASCII}
 control characters.
 
   Later, some terminals were introduced which required these characters
@@ -2073,3 +2087,7 @@
   nil)
 @end group
 @end example
+
+@ignore
+   arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7
+@end ignore

--- a/lispref/positions.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/positions.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -18,7 +18,11 @@
   Positions are usually represented as integers starting from 1, but can
 also be represented as @dfn{markers}---special objects that relocate
 automatically when text is inserted or deleted so they stay with the
-surrounding characters.  @xref{Markers}.
+surrounding characters.  Functions that expect an argument to be a
+position (an integer), but accept a marker as a substitute, normally
+ignore the marker buffer.  Of course, markers used this way usually
+point to a position in the buffer that the function operates on, but
+that is entirely the programmer's responsibility.  @xref{Markers}.
 
   See also the ``field'' feature (@pxref{Fields}), which provides
 functions that are used by many cursor-motion commands.
@@ -89,8 +93,9 @@
 @end defun
 
 @defun buffer-end flag
-This function returns @code{(point-min)} if @var{flag} is less than 1,
-@code{(point-max)} otherwise.  The argument @var{flag} must be a number.
+This function returns @code{(point-max)} if @var{flag} is greater than
+0, @code{(point-min)} otherwise.  The argument @var{flag} must be a
+number.
 @end defun
 
 @defun buffer-size &optional buffer
@@ -185,7 +190,7 @@
   These functions for parsing words use the syntax table to decide
 whether a given character is part of a word.  @xref{Syntax Tables}.
 
-@deffn Command forward-word count
+@deffn Command forward-word &optional count
 This function moves point forward @var{count} words (or backward if
 @var{count} is negative).  ``Moving one word'' means moving until point
 crosses a word-constituent character and then encounters a
@@ -203,19 +208,12 @@
 this function ignores field boundaries.
 
 In an interactive call, @var{count} is specified by the numeric prefix
-argument.
+argument.  If @var{count} is omitted or @code{nil}, it defaults to 1.
 @end deffn
 
-@deffn Command backward-word count
+@deffn Command backward-word &optional count
 This function is just like @code{forward-word}, except that it moves
 backward until encountering the front of a word, rather than forward.
-
-In an interactive call, @var{count} is set to the numeric prefix
-argument.
-
-@c [Now optimized by compiler.]
-@c This function is rarely used in programs, as it is more efficient to
-@c call @code{forward-word} with a negative argument.
 @end deffn
 
 @defvar words-include-escapes
@@ -405,12 +403,18 @@
 (defun current-line ()
   "Return the vertical position of point@dots{}"
   (+ (count-lines (window-start) (point))
-     (if (= (current-column) 0) 1 0)
-     -1))
+     (if (= (current-column) 0) 1 0)))
 @end group
 @end example
 @end defun
 
+@defun line-number-at-pos &optional pos
+@cindex line number
+This function returns the line number in the current buffer
+corresponding the buffer position @var{pos}.  If @var{pos} is @code{nil}
+or omitted, the current buffer position is used.
+@end defun
+
 @ignore
 @c ================
 The @code{previous-line} and @code{next-line} commands are functions
@@ -662,8 +666,8 @@
 @end deffn
 
 @deffn Command down-list &optional arg
-This function moves forward into @var{arg} (default 1) levels of parentheses.  A
-negative argument means move backward but still go
+This function moves forward into @var{arg} (default 1) levels of
+parentheses.  A negative argument means move backward but still go
 deeper in parentheses (@minus{}@var{arg} levels).
 @end deffn
 
@@ -695,13 +699,13 @@
 This function moves backward across @var{arg} (default 1) balanced expressions.
 @end deffn
 
-@deffn Command beginning-of-defun arg
+@deffn Command beginning-of-defun &optional arg
 This function moves back to the @var{arg}th beginning of a defun.  If
 @var{arg} is negative, this actually moves forward, but it still moves
 to the beginning of a defun, not to the end of one.
 @end deffn
 
-@deffn Command end-of-defun arg
+@deffn Command end-of-defun &optional arg
 This function moves forward to the @var{arg}th end of a defun.  If
 @var{arg} is negative, this actually moves backward, but it still moves
 to the end of a defun, not to the beginning of one.
@@ -794,7 +798,7 @@
 Note that char classes are not currently supported in
 @var{character-set}; they will be treated as literals.  Thus you
 cannot use @code{"[:alpha:]"} instead of @code{"a-zA-Z"} to include
-non-ASCII letters.  A way to skip forward over all letters is:
+non-@acronym{ASCII} letters.  A way to skip forward over all letters is:
 
 @example
 (re-search-forward "\\=[[:alpha:]]*" nil t)
@@ -874,8 +878,9 @@
 
   @strong{Warning:} Ordinary insertion of text adjacent to the saved
 point value relocates the saved value, just as it relocates all markers.
-Therefore, when the saved point value is restored, it normally comes
-before the inserted text.
+More precisely, the saved value is a marker with insertion type
+@code{nil}.  @xref{Marker Insertion Types}.  Therefore, when the saved
+point value is restored, it normally comes before the inserted text.
 
   Although @code{save-excursion} saves the location of the mark, it does
 not prevent functions which modify the buffer from setting
@@ -916,7 +921,7 @@
 of the current region (point and the mark, with the smallest first).
 @end deffn
 
-@deffn Command narrow-to-page move-count
+@deffn Command narrow-to-page &optional move-count
 This function sets the accessible portion of the current buffer to
 include just the current page.  An optional first argument
 @var{move-count} non-@code{nil} means to move forward or backward by
@@ -996,3 +1001,7 @@
 @end group
 @end example
 @end defspec
+
+@ignore
+   arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87
+@end ignore

--- a/lispref/processes.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/processes.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -48,6 +48,10 @@
 * Query Before Exit::        Whether to query if exiting will kill a process.
 * Transaction Queues::	     Transaction-based communication with subprocesses.
 * Network::                  Opening network connections.
+* Network Servers::          Network servers let Emacs accept net connections.
+* Datagrams::
+* Low-Level Network::        Lower-level but more general function
+                               to create connections and servers.
 @end menu
 
 @node Subprocess Creation
@@ -261,7 +265,7 @@
 the buffer as output is inserted.  (However, if the coding system chosen
 for decoding output is @code{undecided}, meaning deduce the encoding
 from the actual data, then redisplay sometimes cannot continue once
-non-@sc{ascii} characters are encountered.  There are fundamental
+non-@acronym{ASCII} characters are encountered.  There are fundamental
 reasons why it is hard to fix this; see @ref{Output from Processes}.)
 
 Otherwise the function @code{call-process} does no redisplay, and the
@@ -376,6 +380,13 @@
 @end smallexample
 @end defun
 
+@defun call-process-shell-command command &optional infile destination display &rest args
+This function executes the shell command @var{command} synchronously
+in a separate process.  The final arguments @var{args} are additional
+arguments to add at the end of @var{command}.  The other arguments
+are handled as in @code{call-process}.
+@end defun
+
 @defun shell-command-to-string command
 This function executes @var{command} (a string) as a shell command,
 then returns the command's output as a string.
@@ -457,17 +468,17 @@
 
 @defvar process-connection-type
 @cindex pipes
-@cindex @sc{pty}s
+@cindex @acronym{PTY}s
 This variable controls the type of device used to communicate with
-asynchronous subprocesses.  If it is non-@code{nil}, then @sc{pty}s are
+asynchronous subprocesses.  If it is non-@code{nil}, then @acronym{PTY}s are
 used, when available.  Otherwise, pipes are used.
 
-@sc{pty}s are usually preferable for processes visible to the user, as
+@acronym{PTY}s are usually preferable for processes visible to the user, as
 in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
 etc.) to work between the process and its children, whereas pipes do
 not.  For subprocesses used for internal purposes by programs, it is
 often better to use a pipe, because they are more efficient.  In
-addition, the total number of @sc{pty}s is limited on many systems and
+addition, the total number of @acronym{PTY}s is limited on many systems and
 it is good not to waste them.
 
 The value of @code{process-connection-type} takes effect when
@@ -483,7 +494,7 @@
 @end smallexample
 
 To determine whether a given subprocess actually got a pipe or a
-@sc{pty}, use the function @code{process-tty-name} (@pxref{Process
+@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process
 Information}).
 @end defvar
 
@@ -539,10 +550,13 @@
   Several functions return information about processes.
 @code{list-processes} is provided for interactive use.
 
-@deffn Command list-processes
+@deffn Command list-processes &optional query-only
 This command displays a listing of all living processes.  In addition,
 it finally deletes any process whose status was @samp{Exited} or
 @samp{Signaled}.  It returns @code{nil}.
+
+If @var{query-only} is non-@code{nil} then it lists only processes
+whose query flag is non-@code{nil}.  @xref{Query Before Exit}.
 @end deffn
 
 @defun process-list
@@ -583,10 +597,10 @@
 @end defun
 
 @defun process-id process
-This function returns the @sc{pid} of @var{process}.  This is an
+This function returns the @acronym{PID} of @var{process}.  This is an
 integer that distinguishes the process @var{process} from all other
 processes running on the same computer at the current time.  The
-@sc{pid} of a process is chosen by the operating system kernel when the
+@acronym{PID} of a process is chosen by the operating system kernel when the
 process is started and remains constant as long as the process exists.
 @end defun
 
@@ -594,12 +608,6 @@
 This function returns the name of @var{process}.
 @end defun
 
-@defun process-contact process
-This function returns @code{t} for an ordinary child process, and
-@code{(@var{hostname} @var{service})} for a net connection
-(@pxref{Network}).
-@end defun
-
 @defun process-status process-name
 This function returns the status of @var{process-name} as a symbol.
 The argument @var{process-name} must be a process, a buffer, a
@@ -622,6 +630,12 @@
 for a network connection that is closed.  Once a connection
 is closed, you cannot reopen it, though you might be able to open
 a new connection to the same place.
+@item connect
+for a non-blocking connection that is waiting to complete.
+@item failed
+for a non-blocking connection that has failed to complete.
+@item listen
+for a network server that is listening.
 @item nil
 if @var{process-name} is not the name of an existing process.
 @end table
@@ -662,6 +676,7 @@
 @ref{Asynchronous Processes}).
 @end defun
 
+@anchor{Coding systems for a subprocess}
 @defun process-coding-system process
 This function returns a cons cell describing the coding systems in use
 for decoding output from @var{process} and for encoding input to
@@ -679,6 +694,27 @@
 input.
 @end defun
 
+  Every process also has a property list that you can use to store
+miscellaneous values associated with the process.
+
+@defun process-get process propname
+This function returns the value of the @var{propname} property
+of @var{process}.
+@end defun
+
+@defun process-put process propname value
+This function sets the value of the @var{propname} property
+of @var{process} to @var{value}.
+@end defun
+
+@defun process-plist process
+This function returns the process plist of @var{process}.
+@end defun
+
+@defun set-process-plist process plist
+This function sets the process plist of @var{process} to @var{plist}.
+@end defun
+
 @node Input to Processes
 @section Sending Input to Processes
 @cindex process input
@@ -689,9 +725,9 @@
 data appears on the ``standard input'' of the subprocess.
 
   Some operating systems have limited space for buffered input in a
-@sc{pty}.  On these systems, Emacs sends an @sc{eof} periodically amidst
+@acronym{PTY}.  On these systems, Emacs sends an @acronym{EOF} periodically amidst
 the other characters, to force them through.  For most programs,
-these @sc{eof}s do no harm.
+these @acronym{EOF}s do no harm.
 
   Subprocess input is normally encoded using a coding system before the
 subprocess receives it, much like text written into a file.  You can use
@@ -747,10 +783,10 @@
 
 @defun process-send-eof &optional process-name
   This function makes @var{process-name} see an end-of-file in its
-input.  The @sc{eof} comes after any text already sent to it.
+input.  The @acronym{EOF} comes after any text already sent to it.
 
   If @var{process-name} is not supplied, or if it is @code{nil}, then
-this function sends the @sc{eof} to the current buffer's process.  An
+this function sends the @acronym{EOF} to the current buffer's process.  An
 error is signaled if the current buffer has no process.
 
   The function returns @var{process-name}.
@@ -859,10 +895,12 @@
 @end defun
 
 @c Emacs 19 feature
-@defun signal-process pid signal
-This function sends a signal to process @var{pid}, which need not be
-a child of Emacs.  The argument @var{signal} specifies which signal
-to send; it should be an integer.
+@defun signal-process process signal
+This function sends a signal to process @var{process}.  The argument
+@var{signal} specifies which signal to send; it should be an integer.
+
+You can specify the target process by its process @acronym{ID}; that allows
+you to send signals to processes that are not children of Emacs.
 @end defun
 
 @node Output from Processes
@@ -1436,25 +1474,59 @@
 @section Network Connections
 @cindex network connection
 @cindex TCP
+@cindex UDP
 
-  Emacs Lisp programs can open TCP network connections to other processes on
-the same machine or other machines.  A network connection is handled by Lisp
-much like a subprocess, and is represented by a process object.
-However, the process you are communicating with is not a child of the
-Emacs process, so you can't kill it or send it signals.  All you can do
-is send and receive data.  @code{delete-process} closes the connection,
-but does not kill the process at the other end; that process must decide
-what to do about closure of the connection.
+  Emacs Lisp programs can open stream (TCP) and datagram (UDP) network
+connections to other processes on the same machine or other machines.
+A network connection is handled by Lisp much like a subprocess, and is
+represented by a process object.  However, the process you are
+communicating with is not a child of the Emacs process, so it has no
+process @acronym{ID}, and you can't kill it or send it signals.  All you
+can do is send and receive data.  @code{delete-process} closes the
+connection, but does not kill the program at the other end; that
+program must decide what to do about closure of the connection.
+
+  Lisp programs can listen for connections by creating network
+servers.  A network server is also represented by a kind of process
+object, but unlike a network connection, the network server never
+transfers data itself.  When it receives a connection request, it
+creates a new network connection to represent the connection just
+made.  (The network connection inherits certain information, including
+the process plist, from the server.)  The network server then goes
+back to listening for more connection requests.
+
+  Network connections and servers are created by calling
+@code{make-network-process} with an argument list consisting of
+keyword/argument pairs, for example @code{:server t} to create a
+server process, or @code{:type 'datagram} to create a datagram
+connection.  @xref{Low-Level Network}, for details.  You can also use
+one of the @code{open-network-...} functions descibed below;
+internally, they just call @code{make-network-process} with suitable
+arguments.
 
   You can distinguish process objects representing network connections
-from those representing subprocesses with the @code{process-status}
-function.  It always returns either @code{open} or @code{closed} for a
-network connection, and it never returns either of those values for a
-real subprocess.  @xref{Process Information}.
+and servers from those representing subprocesses with the
+@code{process-status} function.  The possible status values for
+network connections are @code{open}, @code{closed}, @code{connect},
+and @code{failed}.  For a network server, the status is always
+@code{listen}.  None of those values is possible for a real
+subprocess.  @xref{Process Information}.
+
+  You can stop and resume operation of a network process by calling
+@code{stop-process} and @code{continue-process}.  For a server
+process, being stopped means not accepting new connections.  (Up to 5
+connection requests will be queued for when you resume the server; you
+can increase this limit, unless it is imposed by the operating
+systems.)  For a network stream connection, being stopped means not
+processing input (any arriving input waits until you resume the
+connection).  For a datagram connection, some number of packets may be
+queued but input may be lost.  You can use the function
+@code{process-command} to determine whether a network connection or
+server is stopped; a non-@code{nil} value means yes.
 
 @defun open-network-stream name buffer-or-name host service
-This function opens a TCP connection for a service to a host.  It
-returns a process object to represent the connection.
+This function opens a TCP connection, and returns a process object
+that represents the connection.
 
 The @var{name} argument specifies the name for the process object.  It
 is modified as necessary to make it unique.
@@ -1469,3 +1541,461 @@
 @var{host} is the host name (a string), and @var{service} is the name of
 a defined network service (a string) or a port number (an integer).
 @end defun
+
+@defun open-network-stream-nowait name buffer-or-name host service &optional sentinel filter
+This function opens a TCP connection, like @code{open-network-stream},
+but it returns immediately without waiting for the request to be
+accepted or rejected by the remote server.  When the request is
+subsequently accepted or rejected, the process's sentinel function
+will be called with a string that starts with @code{"open"} (on
+success) or @code{"failed"} (on error).
+
+Some systems do not support non-blocking connections; on those
+systems, @code{open-network-stream-nowait} returns @code{nil}
+and does nothing.
+
+The optional arguments @var{sentinel} and @var{filter} specify the
+sentinel and filter functions for this network connection.  It is
+useful to specify them when opening the connection, because they will
+be used later asynchronously.  The other arguments mean the same as in
+@code{open-network-stream}.
+@end defun
+
+@defun process-contact process &optional key
+This function returns information about how a network process was set
+up.  For a connection, when @var{key} is @code{nil}, it returns
+@code{(@var{hostname} @var{service})} which specifies what you
+connected to.
+
+If @var{key} is @code{t}, the value is the complete status information
+for the connection or server; that is, the list of keywords and values
+specified in @code{make-network-process}, except that some of the
+values represent the current status instead of what you specified:
+
+@table @code
+@item :buffer
+The associated value is the process buffer.
+@item :filter
+The associated value is the process filter function.
+@item :sentinel
+The associated value is the process sentinel function.
+@item :remote
+In a connection, this is the address in internal format of the remote peer.
+@item :local
+The local address, in internal format.
+@item :service
+In a server, if you specified @code{t} for @var{service},
+this value is the actual port number.
+@end table
+
+@code{:local} and @code{:remote} are included even if they were not
+specified explicitly in @code{make-network-process}.
+
+If @var{key} is a keyword, the function returns the value corresponding
+to that keyword.
+
+For an ordinary child process, this function always returns @code{t}.
+@end defun
+
+@node Network Servers
+@section Network Servers
+
+  You create a server by calling @code{make-network-process} with
+@code{:server t}.  The server will listen for connection requests from
+clients.  When it accepts a client connection request, that creates a
+new network connection, itself a process object, with the following
+parameters:
+
+@itemize @bullet
+@item
+The connection's process name is constructed by concatenating the
+server process' @var{name} with a client identification string.  The
+client identification string for an IPv4 connection looks like
+@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}.  Otherwise, it is a
+unique number in brackets, as in @samp{<@var{nnn}>}.  The number
+is unique for each connection in the Emacs session.
+
+@item
+If the server's filter is non-@code{nil}, the connection process does
+not get a separate process buffer; otherwise, Emacs creates a new
+buffer for the purpose.  The buffer name is the server's buffer name
+or process name, concatenated with the client identification string.
+
+The server's process buffer value is never used directly by Emacs, but
+it is passed to the log function, which can log connections by
+inserting text there.
+
+@item
+The communication type and the process filter and sentinel are
+inherited from those of the server.  The server never directly
+uses its filter and sentinel; their sole purpose is to initialize
+connections made to the server.
+
+@item
+The connection's process contact info is set according to the client's
+addressing information (typically an IP address and a port number).
+This information is associated with the @code{process-contact}
+keywords @code{:host}, @code{:service}, @code{:remote}.
+
+@item
+The connection's local address is set up according to the port
+number used for the connection.
+
+@item
+The client process' plist is initialized from the server's plist.
+@end itemize
+
+@defun open-network-stream-server name buffer-or-name service &optional sentinel filter
+Create a network server process for a TCP service.
+It returns @code{nil} if server processes are not supported; otherwise,
+it returns a subprocess-object to represent the server.
+
+When a client connects to the specified service, Emacs creates a new
+subprocess to handle the new connection, and then calls its sentinel
+function (which it has inherited from the server).
+
+The optional arguments @var{sentinel} and @var{filter} specify the
+sentinel and filter functions for the server.  It is useful to specify
+them now, because they will be used later asynchronously when the
+server receives a connection request.  The three arguments @var{name},
+@var{buffer-or-name} and @var{service} mean the same thing as in
+@code{open-network-stream}, but @var{service} can be @code{t}
+meaning ask the system to allocate an unused port to listen on.
+@end defun
+
+@node Datagrams
+@section Datagrams 
+@cindex datagrams
+
+  A datagram connection communicates with individual packets rather
+than streams of data.  Each call to @code{process-send} sends one
+datagram packet (@pxref{Input to Processes}), and each datagram
+received results in one call to the filter function.
+
+  The datagram connection doesn't have to talk with the same remote
+peer all the time.  It has a @dfn{remote peer address} which specifies
+where to send datagrams to.  Each time an incoming datagram is passed
+to the filter function, the peer address is set to the address that
+datagram came from; that way, if the filter function sends a datagram,
+it will go back to that place.  You can specify the remote peer
+address when you create the datagram connection using the
+@code{:remote} keyword.  You can change it later on by calling
+@code{set-process-datagram-address}.
+
+@defun process-datagram-address process
+If @var{process} is a datagram connection or server, this function
+returns its remote peer address.
+@end defun
+
+@defun set-process-datagram-address process address
+If @var{process} is a datagram connection or server, this function
+sets its remote peer address to @var{address}.
+@end defun
+
+@node Low-Level Network
+@section Low-Level Network Access
+
+   The basic function for creating network connections and network
+servers is @code{make-network-process}.  It can do either of those
+jobs, depending on the arguments you give it.
+
+@defun make-network-process &rest args
+This function creates a network connection or server and returns the
+process object that represents it.  The arguments @var{args} are a
+list of keyword/argument pairs.  Omitting a keyword is always
+equivalent to specifying it with value @code{nil}, except for
+@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}.  Here
+are the meaningful keywords:
+
+@table @asis
+@item :name name
+Use the string @var{name} as the process name.  It is modified if
+necessary to make it unique.
+
+@item :type @var{type}
+Specify the communication type.  A value of @code{nil} specifies a
+stream connection (the default); @code{datagram} specifies a datagram
+connection.  Both connections and servers can be of either type.
+
+@item :server @var{server-flag}
+If @var{server-flag} is non-@code{nil}, create a server.  Otherwise,
+create a connection.  For a stream type server, @var{server-flag} may
+be an integer which then specifies the length of the queue of pending
+connections to the server.  The default queue length is 5.
+
+@item :host @var{host}
+Specify the host to connect to.  @var{host} should be a host name or
+internet address, as a string, or the symbol @code{local} to specify
+the local host.  If you specify @var{host} for a server, it must
+specify a valid address for the local host, and only clients
+connecting to that address will be accepted.
+
+@item :service @var{service}
+@var{service} specifies a port number to connect to, or, for a server,
+the port number to listen on.  It should be a service name that
+translates to a port number, or an integer specifying the port number
+directly.  For a server, it can also be @code{t}, which means to let
+the system select an unused port number.
+
+@item :family @var{family}
+@var{family} specifies the address (and protocol) family for
+communication.  @code{nil} stands for IPv4.  @code{local} specifies a
+Unix socket, in which case @var{host} is ignored.
+
+@item :local @var{local-address}
+For a server process, @var{local-address} is the address to listen on.
+It overrides @var{family}, @var{host} and @var{service}, and you
+may as well not specify them.
+
+@item :remote @var{remote-address}
+For a connection, @var{remote-address} is the address to connect to.
+It overrides @var{family}, @var{host} and @var{service}, and you
+may as well not specify them.
+
+For a datagram server, @var{remote-address} specifies the initial
+setting of the remote datagram address.
+
+The format of @var{local-address} or @var{remote-address} depends on
+the address family:
+
+@itemize -
+@item
+An IPv4 address is represented as a vector of integers @code{[@var{a}
+@var{b} @var{c} @var{d} @var{p}]} corresponding to numeric IP address
+@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
+
+@item
+A local address is represented as a string which specifies the address
+in the local address space.
+
+@item
+An ``unsupported family'' address is represented by a cons
+@code{(@var{f} . @var{av})}, where @var{f} is the family number and
+@var{av} is a vector specifying the socket address using one element
+per address data byte.  Do not rely on this format in portable code,
+as it may depend on implementation defined constants, data sizes, and
+data structure alignment.
+@end itemize
+
+@item :nowait @var{bool}
+If @var{bool} is non-@code{nil} for a stream connection, return
+without waiting for the connection to complete.  When the connection
+succeeds or fails, Emacs will call the sentinel function, with a
+second argument matching @code{"open"} (if successful) or
+@code{"failed"}.  The default is to block, so that
+@code{make-network-process} does not return until the connection
+has succeeded or failed.
+
+@item :stop @var{stopped}
+Start the network connection or server in the `stopped' state if
+@var{stopped} is non-@code{nil}.
+
+@item :buffer @var{buffer}
+Use @var{buffer} as the process buffer.
+
+@item :coding @var{coding}
+Use @var{coding} as the coding system for this process.  To specify
+different coding systems for decoding data from the connection and for
+encoding data sent to it, specify @code{(@var{decoding} .
+@var{encoding})} for @var{coding}.
+
+If you don't specify this keyword at all, the default
+is to determine the coding systems from the data.
+
+@item :noquery @var{query-flag}
+Initialize the process query flag to @var{query-flag}.  @xref{Query Before Exit}.
+
+@item :filter @var{filter}
+Initialize the process filter to @var{filter}.
+
+@item :filter-multibyte @var{bool}
+If @var{bool} is non-@code{nil}, strings given to the process filter
+are multibyte, otherwise they are unibyte.  If you don't specify this
+keyword at all, the default is that the strings are multibyte if
+@code{default-enable-multibyte-characters} is non-@code{nil}.
+
+@item :sentinel @var{sentinel}
+Initialize the process sentinel to @var{sentinel}.
+
+@item :log @var{log}
+Initialize the log function of a server process to @var{log}.  The log
+function is called each time the server accepts a network connection
+from a client.  The arguments passed to the log function are
+@var{server}, @var{connection}, and @var{message}, where @var{server}
+is the server process, @var{connection} is the new process for the
+connection, and @var{message} is a string describing what has
+happened.
+
+@item :plist @var{plist}
+Initialize the process plist to @var{plist}.
+@end table
+
+The following network options can be specified for the network
+process.  Except for @code{:reuseaddr}, you can set or modify these
+options later using @code{set-network-process-option}.
+
+For a server process, the options specified with
+@code{make-network-process} are not inherited by the client
+connections, so you will need to set the necessary options for each
+child connection as they are created.
+
+@table @asis
+@item :bindtodevice @var{device-name}
+If @var{device-name} is a non-empty string identifying a network
+interface name (see @code{network-interface-list}), only handle
+packets received on that interface.  If @var{device-name} is @code{nil}
+(the default), handle packets received on any interface.
+
+Using this option may require special privileges on some systems.
+
+@item :broadcast @var{broadcast-flag}
+If @var{broadcast-flag} is non-@code{nil} for a datagram process, the
+process will receive datagram packet sent to a broadcast address, and
+be able to send packets to a broadcast address.  Ignored for a stream
+connection.
+
+@item :dontroute @var{dontroute-flag}
+If @var{dontroute-flag} is non-@code{nil}, the process can only send
+to hosts on the same network as the local host.
+
+@item :keepalive @var{keepalive-flag}
+If @var{keepalive-flag} is non-@code{nil} for a stream connection,
+enable exchange of low-level keep-alive messages.
+
+@item :linger @var{linger-arg}
+If @var{linger-arg} is non-@code{nil}, wait for successful
+transmission of all queued packets on the connection before it is
+deleted (see @code{delete-process}).  If @var{linger-arg} is an
+integer, it specifies the maximum time in seconds to wait for queued
+packets to be sent before closing the connection.  Default is
+@code{nil} which means to discard unsent queued packets when the
+process is deleted.
+
+@item :oobinline @var{oobinline-flag}
+If @var{oobinline-flag} is non-@code{nil} for a stream connection,
+receive out-of-band data in the normal data stream.  Otherwise, ignore
+out-of-band data.
+
+@item :priority @var{priority}
+Set the priority for packets sent on this connection to the integer
+@var{priority}.  The interpretation of this number is protocol
+specific, such as setting the TOS (type of service) field on IP
+packets sent on this connection.  It may also have system dependent
+effects, such as selecting a specific output queue on the network
+interface.
+
+@item :reuseaddr @var{reuseaddr-flag}
+If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream
+server process, allow this server to reuse a specific port number (see
+@code{:service}) unless another process on this host is already
+listening on that port.  If @var{reuseaddr-flag} is @code{nil}, there
+may be a period of time after the last use of that port (by any
+process on the host), where it is not possible to make a new server on
+that port.
+
+@end table
+
+The original argument list, modified with the actual connection
+information, is available via the @code{process-contact} function.
+@end defun
+
+@defun set-network-process-option process option value
+This function sets or modifies a network option for network process
+@var{process}.  See @code{make-network-process} for details of options
+@var{option} and their corresponding values @var{value}.
+
+The current setting of an option is available via the
+@code{process-contact} function.
+@end defun
+
+@defun network-interface-list
+This function returns a list describing the network interfaces
+of the machine you are using.  The value is an alist whose
+elements have the form @code{(@var{name} . @var{address})}.
+@var{address} has the same form as the @var{local-address}
+and @var{remote-address} arguments to @code{make-network-process}.
+@end defun
+
+@defun network-interface-info ifname
+This function returns information about the network interface named
+@var{ifname}.  The value is a list of the form @code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}.
+
+@table @var
+@item addr
+The internet protocol address.
+@item bcast
+The broadcast address.
+@item netmask
+The network mask.
+@item hwaddr
+The layer 2 address (Ethernet MAC address, for instance).
+@item flags
+The current flags of the interface.
+@end table
+@end defun
+
+@defun format-network-address address &optional omit-port
+This function converts the Lisp representation of a network address to
+a string.  For example, a five-element vector @code{[@var{a} @var{b}
+@var{c} @var{d} @var{p}]} represents an IP address
+@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}.
+@code{format-network-address} converts that to the string
+@code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}.
+
+If @var{omit-port} is non-@code{nil}, the value does not include
+the port number.
+@end defun
+
+  To test for the availability of a given network feature, use
+@code{featurep} like this:
+
+@example
+(featurep 'make-network-process '(@var{keyword} @var{value}))
+@end example 
+
+@noindent
+The result of the first form is @code{t} if it works to specify
+@var{keyword} with value @var{value} in @code{make-network-process}.
+The result of the second form is @code{t} if @var{keyword} is
+supported by @code{make-network-process}.  Here are some of the
+@var{keyword}---@var{value} pairs you can test in
+this way.
+
+@table @code
+@item (:nowait t)
+Non-@code{nil} if non-blocking connect is supported.
+@item (:type datagram)
+Non-@code{nil} if datagrams are supported.
+@item (:family local)
+Non-@code{nil} if local (aka ``UNIX domain'') sockets are supported.
+@item (:service t)
+Non-@code{nil} if the system can select the port for a server.
+@end table
+
+  To test for the availability of a given network option, use
+@code{featurep} like this:
+
+@example
+(featurep 'make-network-process '@var{keyword})
+@end example 
+
+Here are some of the option @var{keyword}s you can test in
+this way.
+
+@table @code
+@item :bindtodevice
+@itemx :broadcast
+@itemx :dontroute
+@itemx :keepalive
+@itemx :linger
+@itemx :oobinline
+@itemx :priority
+@itemx :reuseaddr
+That particular network option is supported by
+@code{make-network-process} and @code{set-network-process-option}.
+@end table
+
+@ignore
+   arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a
+@end ignore
+

--- a/lispref/searching.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/searching.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -20,8 +20,8 @@
 * Regexp Search::         Searching for a match for a regexp.
 * POSIX Regexps::         Searching POSIX-style for the longest match.
 * Search and Replace::	  Internals of @code{query-replace}.
-* Match Data::            Finding out which part of the text matched
-                            various parts of a regexp, after regexp search.
+* Match Data::            Finding out which part of the text matched,
+                            after a string or regexp search.
 * Searching and Case::    Case-independent or case-significant searching.
 * Standard Regexps::      Useful regexps for finding sentences, pages,...
 @end menu
@@ -90,7 +90,8 @@
 search is repeated that many times (each time starting at the end of the
 previous time's match).  If these successive searches succeed, the
 function succeeds, moving point and returning its new value.  Otherwise
-the search fails, leaving point where it started.
+the search fails, with results depending on the value of
+@var{noerror}, as described above.
 @end deffn
 
 @deffn Command search-backward string &optional limit noerror repeat
@@ -143,7 +144,7 @@
 an error if the search fails.  If @var{noerror} is @code{t}, then it
 returns @code{nil} instead of signaling an error.  If @var{noerror} is
 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
-end of the buffer) and returns @code{nil}.
+end of the accessible portion of the buffer) and returns @code{nil}.
 
 If @var{repeat} is non-@code{nil}, then the search is repeated that many
 times.  Point is positioned at the end of the last match.
@@ -168,8 +169,8 @@
 
 @menu
 * Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.
 * Regexp Functions::        Functions for operating on regular expressions.
-* Regexp Example::          Illustrates regular expression syntax.
 @end menu
 
 @node Syntax of Regexps
@@ -293,10 +294,10 @@
 
 You can also include character ranges in a character alternative, by
 writing the starting and ending characters with a @samp{-} between them.
-Thus, @samp{[a-z]} matches any lower-case @sc{ascii} letter.  Ranges may be
-intermixed freely with individual characters, as in @samp{[a-z$%.]},
-which matches any lower case @sc{ascii} letter or @samp{$}, @samp{%} or
-period.
+Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
+Ranges may be intermixed freely with individual characters, as in
+@samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
+or @samp{$}, @samp{%} or period.
 
 Note that the usual regexp special characters are not special inside a
 character alternative.  A completely different set of characters is
@@ -326,14 +327,14 @@
 @var{c1} is the first character of the charset to which @var{c2}
 belongs.
 
-You cannot always match all non-@sc{ascii} characters with the regular
+You cannot always match all non-@acronym{ASCII} characters with the regular
 expression @code{"[\200-\377]"}.  This works when searching a unibyte
 buffer or string (@pxref{Text Representations}), but not in a multibyte
-buffer or string, because many non-@sc{ascii} characters have codes
+buffer or string, because many non-@acronym{ASCII} characters have codes
 above octal 0377.  However, the regular expression @code{"[^\000-\177]"}
-does match all non-@sc{ascii} characters (see below regarding @samp{^}),
+does match all non-@acronym{ASCII} characters (see below regarding @samp{^}),
 in both multibyte and unibyte representations, because only the
-@sc{ascii} characters are excluded.
+@acronym{ASCII} characters are excluded.
 
 Starting in Emacs 21, a character alternative can also specify named
 character classes (@pxref{Char Classes}).  This is a POSIX feature whose
@@ -358,10 +359,11 @@
 
 @item @samp{^}
 @cindex beginning of line in regexp
-is a special character that matches the empty string, but only at the
-beginning of a line in the text being matched.  Otherwise it fails to
-match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
-the beginning of a line.
+When matching a buffer, @samp{^} matches the empty string, but only at the
+beginning of a line in the text being matched (or the beginning of the
+accessible portion of the buffer).  Otherwise it fails to match
+anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at the
+beginning of a line.
 
 When matching a string instead of a buffer, @samp{^} matches at the
 beginning of the string or after a newline character.
@@ -372,8 +374,9 @@
 @item @samp{$}
 @cindex @samp{$} in regexp
 @cindex end of line in regexp
-is similar to @samp{^} but matches only at the end of a line.  Thus,
-@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
+is similar to @samp{^} but matches only at the end of a line (or the
+end of the accessible portion of the buffer).  Thus, @samp{x+$}
+matches a string of one @samp{x} or more at the end of a line.
 
 When matching a string instead of a buffer, @samp{$} matches at the end
 of the string or before a newline character.
@@ -415,7 +418,7 @@
 
 @table @samp
 @item [:ascii:]
-This matches any @sc{ascii} (unibyte) character.
+This matches any @acronym{ASCII} (unibyte) character.
 @item [:alnum:]
 This matches any letter or digit.  (At present, for multibyte
 characters, it matches anything that has word syntax.)
@@ -425,20 +428,20 @@
 @item [:blank:]
 This matches space and tab only.
 @item [:cntrl:]
-This matches any @sc{ascii} control character.
+This matches any @acronym{ASCII} control character.
 @item [:digit:]
 This matches @samp{0} through @samp{9}.  Thus, @samp{[-+[:digit:]]}
 matches any digit, as well as @samp{+} and @samp{-}.
 @item [:graph:]
-This matches graphic characters---everything except @sc{ascii} control
+This matches graphic characters---everything except @acronym{ASCII} control
 characters, space, and the delete character.
 @item [:lower:]
 This matches any lower-case letter, as determined by
 the current case table (@pxref{Case Tables}).
 @item [:nonascii:]
-This matches any non-@sc{ascii} (multibyte) character.
+This matches any non-@acronym{ASCII} (multibyte) character.
 @item [:print:]
-This matches printing characters---everything except @sc{ascii} control
+This matches printing characters---everything except @acronym{ASCII} control
 characters and the delete character.
 @item [:punct:]
 This matches any punctuation character.  (At present, for multibyte
@@ -494,7 +497,7 @@
 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
 
 @item \@{@var{m},@var{n}\@}
-is more general postfix operator that specifies repetition with a
+is a more general postfix operator that specifies repetition with a
 minimum of @var{m} repeats and a maximum of @var{n} repeats.  If @var{m}
 is omitted, the minimum is 0; if @var{n} is omitted, there is no
 maximum.
@@ -542,7 +545,7 @@
 operators), but it does not get a number, so you cannot refer back to
 its value with @samp{\@var{digit}}.
 
-Shy groups are particulary useful for mechanically-constructed regular
+Shy groups are particularly useful for mechanically-constructed regular
 expressions because they can be added automatically without altering the
 numbering of any ordinary, non-shy groups.
 
@@ -567,6 +570,10 @@
 half, which may be anything, but the @samp{\1} that follows must match
 the same exact text.
 
+If a @samp{\( @dots{} \)} construct matches more than once (which can
+happen, for instance, if it is followed by @samp{*}), only the last
+match is recorded.
+
 If a particular grouping construct in the regular expression was never
 matched---for instance, if it appears inside of an alternative that
 wasn't used, or inside of a repetition that repeated zero times---then
@@ -611,7 +618,9 @@
 
   The following regular expression constructs match the empty string---that is,
 they don't use up any characters---but whether they match depends on the
-context.
+context.  For all, the beginning and end of the accessible portion of
+the buffer are treated as if they were the actual beginning and end of
+the buffer.
 
 @table @samp
 @item \`
@@ -636,25 +645,25 @@
 @samp{foo} as a separate word.  @samp{\bballs?\b} matches
 @samp{ball} or @samp{balls} as a separate word.@refill
 
-@samp{\b} matches at the beginning or end of the buffer
+@samp{\b} matches at the beginning or end of the buffer (or string)
 regardless of what text appears next to it.
 
 @item \B
 @cindex @samp{\B} in regexp
 matches the empty string, but @emph{not} at the beginning or
-end of a word.
+end of a word, nor at the beginning or end of the buffer (or string).
 
 @item \<
 @cindex @samp{\<} in regexp
 matches the empty string, but only at the beginning of a word.
-@samp{\<} matches at the beginning of the buffer only if a
+@samp{\<} matches at the beginning of the buffer (or string) only if a
 word-constituent character follows.
 
 @item \>
 @cindex @samp{\>} in regexp
 matches the empty string, but only at the end of a word.  @samp{\>}
-matches at the end of the buffer only if the contents end with a
-word-constituent character.
+matches at the end of the buffer (or string) only if the contents end
+with a word-constituent character.
 @end table
 
 @kindex invalid-regexp
@@ -668,9 +677,11 @@
 @comment  node-name,  next,  previous,  up
 @subsection Complex Regexp Example
 
-  Here is a complicated regexp, used by Emacs to recognize the end of a
-sentence together with any whitespace that follows.  It is the value of
-the variable @code{sentence-end}.
+  Here is a complicated regexp which was formerly used by Emacs to
+recognize the end of a sentence together with any whitespace that
+follows.  It was used as the variable @code{sentence-end}.  (Its value
+nowadays contains alternatives for @samp{.}, @samp{?} and @samp{!} in
+other character sets.)
 
   First, we show the regexp as a string in Lisp syntax to distinguish
 spaces from tab characters.  The string constant begins and ends with a
@@ -679,17 +690,16 @@
 tab and @samp{\n} for a newline.
 
 @example
-"[.?!][]\"')@}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
+"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
 @end example
 
 @noindent
-In contrast, if you evaluate the variable @code{sentence-end}, you
-will see the following:
+In contrast, if you evaluate this string, you will see the following:
 
 @example
 @group
-sentence-end
-     @result{} "[.?!][]\"')@}]*\\($\\| $\\|  \\|  \\)[
+"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
+     @result{} "[.?!][]\"')@}]*\\($\\| $\\|  \\|@ @ \\)[
 ]*"
 @end group
 @end example
@@ -704,7 +714,10 @@
 @item [.?!]
 The first part of the pattern is a character alternative that matches
 any one of three characters: period, question mark, and exclamation
-mark.  The match must begin with one of these three characters.
+mark.  The match must begin with one of these three characters.  (This
+is the one point where the new value of @code{sentence-end} differs
+from the old.  The new value also lists sentence ending
+non-@acronym{ASCII} characters.)
 
 @item []\"')@}]*
 The second part of the pattern matches any closing braces and quotation
@@ -764,13 +777,14 @@
 
 @defun regexp-opt strings &optional paren
 This function returns an efficient regular expression that will match
-any of the strings @var{strings}.  This is useful when you need to make
-matching or searching as fast as possible---for example, for Font Lock
-mode.
+any of the strings in the list @var{strings}.  This is useful when you
+need to make matching or searching as fast as possible---for example,
+for Font Lock mode.
 
 If the optional argument @var{paren} is non-@code{nil}, then the
 returned regular expression is always enclosed by at least one
-parentheses-grouping construct.
+parentheses-grouping construct.  If @var{paren} is @code{words}, then
+that construct is additionally surrounded by @samp{\<} and @samp{\>}.
 
 This simplified definition of @code{regexp-opt} produces a
 regular expression which is equivalent to the actual value
@@ -788,7 +802,8 @@
 
 @defun regexp-opt-depth regexp
 This function returns the total number of grouping constructs
-(parenthesized expressions) in @var{regexp}.
+(parenthesized expressions) in @var{regexp}.  (This does not include
+shy groups.)
 @end defun
 
 @node Regexp Search
@@ -830,7 +845,7 @@
 @code{re-search-forward} does nothing and returns @code{nil}.  If
 @var{noerror} is neither @code{nil} nor @code{t}, then
 @code{re-search-forward} moves point to @var{limit} (or the end of the
-buffer) and returns @code{nil}.
+accessible portion of the buffer) and returns @code{nil}.
 
 In the following example, point is initially before the @samp{T}.
 Evaluating the search call moves point to the end of that line (between
@@ -866,9 +881,10 @@
 beginning is as close as possible to the starting point.  If
 @code{re-search-backward} were a perfect mirror image, it would find the
 match whose end is as close as possible.  However, in fact it finds the
-match whose beginning is as close as possible.  The reason for this is that
-matching a regular expression at a given spot always works from
-beginning to end, and starts at a specified beginning position.
+match whose beginning is as close as possible (and yet ends before the
+starting point).  The reason for this is that matching a regular
+expression at a given spot always works from beginning to end, and
+starts at a specified beginning position.
 
 A true mirror-image of @code{re-search-forward} would require a special
 feature for matching regular expressions from end to beginning.  It's
@@ -1069,7 +1085,8 @@
 commands.  It searches for occurrences of @var{from-string} in the
 text between positions @var{start} and @var{end} and replaces some or
 all of them.  If @var{start} is @code{nil} (or omitted), point is used
-instead, and the buffer's end is used for @var{end}.
+instead, and the end of the buffer's accessible portion is used for
+@var{end}.
 
 If @var{query-flag} is @code{nil}, it replaces all
 occurrences; otherwise, it asks the user what to do about each one.
@@ -1090,7 +1107,7 @@
 
 If @var{repeat-count} is non-@code{nil}, it should be an integer.  Then
 it specifies how many times to use each of the strings in the
-@var{replacements} list before advancing cyclicly to the next one.
+@var{replacements} list before advancing cyclically to the next one.
 
 If @var{from-string} contains upper-case letters, then
 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
@@ -1099,6 +1116,22 @@
 Normally, the keymap @code{query-replace-map} defines the possible user
 responses for queries.  The argument @var{map}, if non-@code{nil}, is a
 keymap to use instead of @code{query-replace-map}.
+
+@strong{Usage note:} Do not use this function in your own programs
+unless you want to do something very similar to what
+@code{query-replace} does, including setting the mark and possibly
+querying the user.  For most purposes a simple loop like, for
+instance:
+
+@example
+(while (re-search-forward "foo[ \t]+bar" nil t)
+  (replace-match "foobar"))
+@end example
+
+@noindent
+is preferable.  It runs faster and avoids side effects, such as
+setting the mark.  @xref{Replacing Match,, Replacing the Text that
+Matched}, for a description of @code{replace-match}.
 @end defun
 
 @defvar query-replace-map
@@ -1173,10 +1206,9 @@
 @cindex match data
 
   Emacs keeps track of the start and end positions of the segments of
-text found during a regular expression search.  This means, for example,
-that you can search for a complex pattern, such as a date in an Rmail
-message, and then extract parts of the match under control of the
-pattern.
+text found during a search.  This means, for example, that you can
+search for a complex pattern, such as a date in an Rmail message, and
+then extract parts of the match under control of the pattern.
 
   Because the match data normally describe the most recent search only,
 you must be careful not to do another search inadvertently between the
@@ -1205,9 +1237,11 @@
 @var{replacement}.
 
 If you did the last search in a buffer, you should specify @code{nil}
-for @var{string}.  Then @code{replace-match} does the replacement by
-editing the buffer; it leaves point at the end of the replacement text,
-and returns @code{t}.
+for @var{string} and make sure that the current buffer when you call
+@code{replace-match} is the one in which you did the searching or
+matching.  Then @code{replace-match} does the replacement by editing
+the buffer; it leaves point at the end of the replacement text, and
+returns @code{t}.
 
 If you did the search in a string, pass the same string as @var{string}.
 Then @code{replace-match} does the replacement by constructing and
@@ -1239,6 +1273,7 @@
 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
 matched the @var{n}th subexpression in the original regexp.
 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
+If the @var{n}th subexpression never matched, an empty string is substituted.
 
 @item @samp{\\}
 @cindex @samp{\} in replacement
@@ -1396,7 +1431,7 @@
   The functions @code{match-data} and @code{set-match-data} read or
 write the entire match data, all at once.
 
-@defun match-data
+@defun match-data &optional integers reuse
 This function returns a newly constructed list containing all the
 information on what text the last search matched.  Element zero is the
 position of the beginning of the match for the whole expression; element
@@ -1420,8 +1455,20 @@
 corresponds to @code{(match-end @var{n})}.
 
 All the elements are markers or @code{nil} if matching was done on a
-buffer, and all are integers or @code{nil} if matching was done on a
-string with @code{string-match}.
+buffer and all are integers or @code{nil} if matching was done on a
+string with @code{string-match}.   If @var{integers} is
+non-@code{nil}, then all elements are integers or @code{nil}, even if
+matching was done on a buffer.  Also, @code{match-beginning} and
+@code{match-end} always return integers or @code{nil}.
+
+If @var{reuse} is non-@code{nil}, it should be a list.  In that case,
+@code{match-data} stores the match data in @var{reuse}.  That is,
+@var{reuse} is destructively modified.  @var{reuse} does not need to
+have the right length.  If it is not long enough to contain the match
+data, it is extended.  If it is too long, the length of @var{reuse}
+stays the same, but the elements that were not used are set to
+@code{nil}.  The purpose of this feature is to avoid producing too
+much garbage, that would later have to be collected.
 
 As always, there must be no possibility of intervening searches between
 the call to a search function and the call to @code{match-data} that is
@@ -1474,7 +1521,8 @@
 
 @defmac save-match-data body@dots{}
 This macro executes @var{body}, saving and restoring the match
-data around it.
+data around it.  The return value is the value of the last form in
+@var{body}.
 @end defmac
 
   You could use @code{set-match-data} together with @code{match-data} to
@@ -1544,10 +1592,11 @@
 searching functions used in Lisp code.
 
 @defopt case-replace
-This variable determines whether the replacement functions should
-preserve case.  If the variable is @code{nil}, that means to use the
-replacement text verbatim.  A non-@code{nil} value means to convert the
-case of the replacement text according to the text being replaced.
+This variable determines whether the higher level replacement
+functions should preserve case.  If the variable is @code{nil}, that
+means to use the replacement text verbatim.  A non-@code{nil} value
+means to convert the case of the replacement text according to the
+text being replaced.
 
 This variable is used by passing it as an argument to the function
 @code{replace-match}.  @xref{Replacing Match}.
@@ -1600,23 +1649,28 @@
 @defvar paragraph-start
 This is the regular expression for recognizing the beginning of a line
 that starts @emph{or} separates paragraphs.  The default value is
-@w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
-newline, or form feed (after its left margin).
+@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
+whitespace or starting with a form feed (after its left margin).
 @end defvar
 
 @defvar sentence-end
 This is the regular expression describing the end of a sentence.  (All
-paragraph boundaries also end sentences, regardless.)  The default value
-is:
+paragraph boundaries also end sentences, regardless.)  The (slightly
+simplified) default value is:
 
 @example
-"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
+"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
 @end example
 
-This means a period, question mark or exclamation mark, followed
-optionally by a closing parenthetical character, followed by tabs,
-spaces or new lines.
+This means a period, question mark or exclamation mark (the actual
+default value also lists their alternatives in other character sets),
+followed optionally by closing parenthetical characters, followed by
+tabs, spaces or new lines.
 
 For a detailed explanation of this regular expression, see @ref{Regexp
 Example}.
 @end defvar
+
+@ignore
+   arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f
+@end ignore

--- a/lispref/sequences.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/sequences.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -69,8 +69,8 @@
 sequence.
 
 @defun sequencep object
-Returns @code{t} if @var{object} is a list, vector, or
-string, @code{nil} otherwise.
+Returns @code{t} if @var{object} is a list, vector,
+string, bool-vector, or char-table, @code{nil} otherwise.
 @end defun
 
 @defun length sequence
@@ -78,10 +78,12 @@
 @cindex list length
 @cindex vector length
 @cindex sequence length
+@cindex char-table length
 This function returns the number of elements in @var{sequence}.  If
 @var{sequence} is a cons cell that is not a list (because the final
 @sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
-signaled.
+signaled.  For a char-table, the value returned is always one more
+than the maximum Emacs character code.
 
 @xref{List Elements}, for the related function @code{safe-length}.
 
@@ -109,6 +111,13 @@
 @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
+
 @defun elt sequence index
 @cindex elements of sequences
 This function returns the element of @var{sequence} indexed by
@@ -163,8 +172,8 @@
 @xref{Text Properties}.
 
 See also @code{append} in @ref{Building Lists}, @code{concat} in
-@ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for other
-ways to copy sequences.
+@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
+for other ways to copy sequences.
 
 @example
 @group
@@ -313,7 +322,7 @@
 @end group
 @group
 (aref "abcdefg" 1)
-     @result{} 98           ; @r{@samp{b} is @sc{ascii} code 98.}
+     @result{} 98           ; @r{@samp{b} is @acronym{ASCII} code 98.}
 @end group
 @end example
 
@@ -489,14 +498,11 @@
 arguments.  This is a special feature to make it easy to access the entire
 contents of a byte-code function object.  @xref{Byte-Code Objects}.
 
-The @code{vconcat} function also allows integers as arguments.  It
-converts them to strings of digits, making up the decimal print
-representation of the integer, and then uses the strings instead of the
-original integers.  @strong{Don't use this feature; we plan to eliminate
-it.  If you already use this feature, change your programs now!}  The
-proper way to convert an integer to a decimal number in this way is with
-@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
-(@pxref{String Conversion}).
+In Emacs versions before 21, the @code{vconcat} function allowed
+integers as arguments, converting them to strings of digits, but that
+feature has been eliminated.  The proper way to convert an integer to
+a decimal number in this way is with @code{format} (@pxref{Formatting
+Strings}) or @code{number-to-string} (@pxref{String Conversion}).
 
 For other concatenation functions, see @code{mapconcat} in @ref{Mapping
 Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
@@ -722,3 +728,6 @@
 These results make sense because the binary codes for control-_ and
 control-W are 11111 and 10111, respectively.
 
+@ignore
+   arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386
+@end ignore

--- a/lispref/streams.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/streams.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -361,7 +361,9 @@
 points into, at the marker position.  The marker position advances as
 characters are inserted.  The value of point in the buffer has no effect
 on printing when the stream is a marker, and this kind of printing
-does not move point.
+does not move point (except that if the marker points at or before the
+position of point, point advances with the surrounding text, as
+usual).
 
 @item @var{function}
 @cindex function output stream
@@ -685,6 +687,13 @@
 that print functions use when the @var{stream} argument is @code{nil}.
 @end defvar
 
+@defvar print-quoted
+If this is non-@code{nil}, that means to print quoted forms using
+abbreviated reader syntax.  @code{(quote foo)} prints as @code{'foo},
+@code{(function foo)} as @code{#'foo}, and backquoted forms print
+using modern backquote syntax.
+@end defvar
+
 @defvar print-escape-newlines
 @cindex @samp{\n} in print
 @cindex escape characters
@@ -721,24 +730,24 @@
 @end defvar
 
 @defvar print-escape-nonascii
-If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
+If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII}
 characters in strings are unconditionally printed as backslash sequences
 by the print functions @code{prin1} and @code{print} that print with
 quoting.
 
-Those functions also use backslash sequences for unibyte non-@sc{ascii}
+Those functions also use backslash sequences for unibyte non-@acronym{ASCII}
 characters, regardless of the value of this variable, when the output
 stream is a multibyte buffer or a marker pointing into one.
 @end defvar
 
 @defvar print-escape-multibyte
-If this variable is non-@code{nil}, then multibyte non-@sc{ascii}
+If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII}
 characters in strings are unconditionally printed as backslash sequences
 by the print functions @code{prin1} and @code{print} that print with
 quoting.
 
 Those functions also use backslash sequences for multibyte
-non-@sc{ascii} characters, regardless of the value of this variable,
+non-@acronym{ASCII} characters, regardless of the value of this variable,
 when the output stream is a unibyte buffer or a marker pointing into
 one.
 @end defvar
@@ -771,6 +780,14 @@
 @code{nil} (which is the default) means no limit.
 @end defvar
 
+@defopt eval-expression-print-length
+@defoptx eval-expression-print-level
+These are the values for @code{print-length} and @code{print-level}
+used by @code{eval-expression}, and thus, indirectly, by many
+interactive evaluation commands (@pxref{Lisp Eval,, Evaluating
+Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}).
+@end defopt
+
   These variables are used for detecting and reporting circular
 and shared structure---but they are only defined in Emacs 21.
 
@@ -803,3 +820,7 @@
 the @code{print-circle} feature.  You should not use it except
 to bind it to @code{nil} when you bind @code{print-continuous-numbering}.
 @end defvar
+
+@ignore
+   arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
+@end ignore

--- a/lispref/strings.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/strings.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -44,7 +44,7 @@
   The length of a string (like any array) is fixed, and cannot be
 altered once the string exists.  Strings in Lisp are @emph{not}
 terminated by a distinguished character code.  (By contrast, strings in
-C are terminated by a character with @sc{ascii} code 0.)
+C are terminated by a character with @acronym{ASCII} code 0.)
 
   Since strings are arrays, and therefore sequences as well, you can
 operate on them with the general array and sequence functions.
@@ -52,10 +52,10 @@
 change individual characters in a string using the functions @code{aref}
 and @code{aset} (@pxref{Array Functions}).
 
-  There are two text representations for non-@sc{ascii} characters in
+  There are two text representations for non-@acronym{ASCII} characters in
 Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
-Representations}).  An @sc{ascii} character always occupies one byte in a
-string; in fact, when a string is all @sc{ascii}, there is no real
+Representations}).  An @acronym{ASCII} character always occupies one byte in a
+string; in fact, when a string is all @acronym{ASCII}, there is no real
 difference between the unibyte and multibyte representations.
 For most Lisp programming, you don't need to be concerned with these two
 representations.
@@ -66,8 +66,8 @@
 codes in the range 128 to 255.
 
   Strings cannot hold characters that have the hyper, super or alt
-modifiers; they can hold @sc{ascii} control characters, but no other
-control characters.  They do not distinguish case in @sc{ascii} control
+modifiers; they can hold @acronym{ASCII} control characters, but no other
+control characters.  They do not distinguish case in @acronym{ASCII} control
 characters.  If you want to store such characters in a sequence, such as
 a key sequence, you must use a vector instead of a string.
 @xref{Character Type}, for more information about the representation of meta
@@ -172,7 +172,7 @@
 @samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1.
 Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded.
 
-When @code{nil} is used as an index, it stands for the length of the
+When @code{nil} is used for @var{end}, it stands for the length of the
 string.  Thus,
 
 @example
@@ -208,10 +208,11 @@
      @result{} [b (c)]
 @end example
 
-A @code{wrong-type-argument} error is signaled if either @var{start} or
-@var{end} is not an integer or @code{nil}.  An @code{args-out-of-range}
-error is signaled if @var{start} indicates a character following
-@var{end}, or if either integer is out of range for @var{string}.
+A @code{wrong-type-argument} error is signaled if @var{start} is not
+an integer or if @var{end} is neither an integer nor @code{nil}.  An
+@code{args-out-of-range} error is signaled if @var{start} indicates a
+character following @var{end}, or if either integer is out of range
+for @var{string}.
 
 Contrast this function with @code{buffer-substring} (@pxref{Buffer
 Contents}), which returns a string containing a portion of the text in
@@ -219,6 +220,14 @@
 beginning of a buffer is at index 1.
 @end defun
 
+@defun substring-no-properties string &optional start end
+This works like @code{substring} but discards all text properties from
+the value.  Also, @var{start} may be omitted or @code{nil}, which is
+equivalent to 0.  Thus, @w{@code{(substring-no-properties
+@var{string})}} returns a copy of @var{string}, with all text
+properties removed.
+@end defun
+
 @defun concat &rest sequences
 @cindex copying strings
 @cindex concatenating strings
@@ -255,11 +264,11 @@
 
 For information about other concatenation functions, see the
 description of @code{mapconcat} in @ref{Mapping Functions},
-@code{vconcat} in @ref{Vectors}, and @code{append} in @ref{Building
+@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building
 Lists}.
 @end defun
 
-@defun split-string string separators omit-nulls
+@defun split-string string &optional separators omit-nulls
 This function splits @var{string} into substrings at matches for the
 regular expression @var{separators}.  Each match for @var{separators}
 defines a splitting point; the substrings between the splitting points
@@ -280,42 +289,71 @@
 
 @example
 (split-string "  two words ")
-@result{} ("two" "words")
+     @result{} ("two" "words")
 @end example
 
 The result is not @samp{("" "two" "words" "")}, which would rarely be
-useful.  If you need such a result, use an explict value for
+useful.  If you need such a result, use an explicit value for
 @var{separators}:
 
 @example
 (split-string "  two words " split-string-default-separators)
-@result{} ("" "two" "words" "")
+     @result{} ("" "two" "words" "")
 @end example
 
 More examples:
 
 @example
 (split-string "Soup is good food" "o")
-@result{} ("S" "up is g" "" "d f" "" "d")
+     @result{} ("S" "up is g" "" "d f" "" "d")
 (split-string "Soup is good food" "o" t)
-@result{} ("S" "up is g" "d f" "d")
+     @result{} ("S" "up is g" "d f" "d")
 (split-string "Soup is good food" "o+")
-@result{} ("S" "up is g" "d f" "d")
+     @result{} ("S" "up is g" "d f" "d")
+@end example
+
+Empty matches do count, except that @code{split-string} will not look
+for a final empty match when it already reached the end of the string
+using a non-empty match or when @var{string} is empty:
+
+@example
+(split-string "aooob" "o*")
+     @result{} ("" "a" "" "b" "")
+(split-string "ooaboo" "o*")
+     @result{} ("" "" "a" "b" "")
+(split-string "" "")
+     @result{} ("")
 @end example
 
-Empty matches do count, when not adjacent to another match:
+However, when @var{separators} can match the empty string,
+@var{omit-nulls} is usually @code{t}, so that the subtleties in the
+three previous examples are rarely relevant:
 
 @example
-(split-string "Soup is good food" "o*")
-@result{}("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
-(split-string "Nice doggy!" "")
-@result{}("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
+(split-string "Soup is good food" "o*" t)
+     @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
+(split-string "Nice doggy!" "" t)
+     @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
+(split-string "" "" t)
+     @result{} nil
+@end example
+
+Somewhat odd, but predictable, behavior can occur for certain
+``non-greedy'' values of @var{separators} that can prefer empty
+matches over non-empty matches.  Again, such values rarely occur in
+practice:
+
+@example
+(split-string "ooo" "o*" t)
+     @result{} nil
+(split-string "ooo" "\\|o+" t)
+     @result{} ("o" "o" "o")
 @end example
 @end defun
 
 @defvar split-string-default-separators
 The default value of @var{separators} for @code{split-string}, initially
-@samp{"[ \f\t\n\r\v]+"}.
+@w{@samp{"[ \f\t\n\r\v]+"}}.
 @end defvar
 
 @node Modifying Strings
@@ -341,6 +379,14 @@
 character currently present at that point in @var{string}.
 @end defun
 
+  To clear out a string that contained a password, use
+@code{clear-string}:
+
+@defun clear-string string
+This clears the contents of @var{string} to zeros
+and may change its length.
+@end defun
+
 @need 2000
 @node Text Comparison
 @section Comparison of Characters and Strings
@@ -362,7 +408,8 @@
 
 @defun string= string1 string2
 This function returns @code{t} if the characters of the two strings
-match exactly.
+match exactly.  Symbols are also allowed as arguments, in which case
+their print names are used.
 Case is always significant, regardless of @code{case-fold-search}.
 
 @example
@@ -378,8 +425,20 @@
 strings.  When @code{equal} (@pxref{Equality Predicates}) compares two
 strings, it uses @code{string=}.
 
-If the strings contain non-@sc{ascii} characters, and one is unibyte
-while the other is multibyte, then they cannot be equal.  @xref{Text
+For technical reasons, a unibyte and a multibyte string are
+@code{equal} if and only if they contain the same sequence of
+character codes and all these codes are either in the range 0 through
+127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
+However, when a unibyte string gets converted to a multibyte string,
+all characters with codes in the range 160 through 255 get converted
+to characters with higher codes, whereas @acronym{ASCII} characters
+remain unchanged.  Thus, a unibyte string and its conversion to
+multibyte are only @code{equal} if the string is all @acronym{ASCII}.
+Character codes 160 through 255 are not entirely proper in multibyte
+text, even though they can occur.  As a consequence, the situation
+where a unibyte and a multibyte string are @code{equal} without both
+being all @acronym{ASCII} is a technical oddity that very few Emacs
+Lisp programmers ever get confronted with.  @xref{Text
 Representations}.
 @end defun
 
@@ -400,11 +459,11 @@
 
 Pairs of characters are compared according to their character codes.
 Keep in mind that lower case letters have higher numeric values in the
-@sc{ascii} character set than their upper case counterparts; digits and
+@acronym{ASCII} character set than their upper case counterparts; digits and
 many punctuation characters have a lower numeric value than upper case
-letters.  An @sc{ascii} character is less than any non-@sc{ascii}
-character; a unibyte non-@sc{ascii} character is always less than any
-multibyte non-@sc{ascii} character (@pxref{Text Representations}).
+letters.  An @acronym{ASCII} character is less than any non-@acronym{ASCII}
+character; a unibyte non-@acronym{ASCII} character is always less than any
+multibyte non-@acronym{ASCII} character (@pxref{Text Representations}).
 
 @example
 @group
@@ -436,6 +495,9 @@
      @result{} nil
 @end group
 @end example
+
+Symbols are also allowed as arguments, in which case their print names
+are used.
 @end defun
 
 @defun string-lessp string1 string2
@@ -451,9 +513,10 @@
 the string).
 
 The strings are both converted to multibyte for the comparison
-(@pxref{Text Representations}) so that a unibyte string can be equal to
-a multibyte string.  If @var{ignore-case} is non-@code{nil}, then case
-is ignored, so that upper case letters can be equal to lower case letters.
+(@pxref{Text Representations}) so that a unibyte string and its
+conversion to multibyte are always regarded as equal.  If
+@var{ignore-case} is non-@code{nil}, then case is ignored, so that
+upper case letters can be equal to lower case letters.
 
 If the specified portions of the two strings match, the value is
 @code{t}.  Otherwise, the value is an integer which indicates how many
@@ -463,16 +526,14 @@
 portion) is less.
 @end defun
 
-@defun assoc-ignore-case key alist
+@defun assoc-string key alist &optional case-fold
 This function works like @code{assoc}, except that @var{key} must be a
-string, and comparison is done using @code{compare-strings}, ignoring
-case differences.  @xref{Association Lists}.
-@end defun
-
-@defun assoc-ignore-representation key alist
-This function works like @code{assoc}, except that @var{key} must be a
-string, and comparison is done using @code{compare-strings}.
-Case differences are significant.
+string, and comparison is done using @code{compare-strings}.  If
+@var{case-fold} is non-@code{nil}, it ignores case differences.
+Unlike @code{assoc}, this function can also match elements of the alist
+that are strings rather than conses.  In particular, @var{alist} can
+be a list of strings rather than an actual alist.
+@xref{Association Lists}.
 @end defun
 
   See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
@@ -509,7 +570,7 @@
 @cindex string to character
   This function returns the first character in @var{string}.  If the
 string is empty, the function returns 0.  The value is also 0 when the
-first character of @var{string} is the null character, @sc{ascii} code
+first character of @var{string} is the null character, @acronym{ASCII} code
 0.
 
 @example
@@ -540,8 +601,10 @@
 @example
 (number-to-string 256)
      @result{} "256"
+@group
 (number-to-string -23)
      @result{} "-23"
+@end group
 (number-to-string -23.5)
      @result{} "-23.5"
 @end example
@@ -555,20 +618,22 @@
 @defun string-to-number string &optional base
 @cindex string to number
 This function returns the numeric value of the characters in
-@var{string}.  If @var{base} is non-@code{nil}, integers are converted
-in that base.  If @var{base} is @code{nil}, then base ten is used.
-Floating point conversion always uses base ten; we have not implemented
-other radices for floating point numbers, because that would be much
-more work and does not seem useful.  If @var{string} looks like an
-integer but its value is too large to fit into a Lisp integer,
+@var{string}.  If @var{base} is non-@code{nil}, it must be an integer
+between 2 and 16 (inclusive), and integers are converted in that base.
+If @var{base} is @code{nil}, then base ten is used.  Floating point
+conversion only works in base ten; we have not implemented other
+radices for floating point numbers, because that would be much more
+work and does not seem useful.  If @var{string} looks like an integer
+but its value is too large to fit into a Lisp integer,
 @code{string-to-number} returns a floating point result.
 
-The parsing skips spaces and tabs at the beginning of @var{string}, then
-reads as much of @var{string} as it can interpret as a number.  (On some
-systems it ignores other whitespace at the beginning, not just spaces
-and tabs.)  If the first character after the ignored whitespace is
-neither a digit, nor a plus or minus sign, nor the leading dot of a
-floating point number, this function returns 0.
+The parsing skips spaces and tabs at the beginning of @var{string},
+then reads as much of @var{string} as it can interpret as a number in
+the given base.  (On some systems it ignores other whitespace at the
+beginning, not just spaces and tabs.)  If the first character after
+the ignored whitespace is neither a digit in the given base, nor a
+plus or minus sign, nor the leading dot of a floating point number,
+this function returns 0.
 
 @example
 (string-to-number "256")
@@ -670,16 +735,12 @@
 copied into the output.  The text properties of the @samp{%s} itself
 are also copied, but those of the object take priority.
 
-If there is no corresponding object, the empty string is used.
-
 @item %S
 Replace the specification with the printed representation of the object,
 made with quoting (that is, using @code{prin1}---@pxref{Output
 Functions}).  Thus, strings are enclosed in @samp{"} characters, and
 @samp{\} characters appear where necessary before special characters.
 
-If there is no corresponding object, the empty string is used.
-
 @item %o
 @cindex integer to octal
 Replace the specification with the base-eight representation of an
@@ -737,17 +798,20 @@
 @end group
 @end example
 
-@cindex numeric prefix
 @cindex field width
 @cindex padding
-  All the specification characters allow an optional numeric prefix
-between the @samp{%} and the character.  The optional numeric prefix
-defines the minimum width for the object.  If the printed representation
-of the object contains fewer characters than this, then it is padded.
-The padding is on the left if the prefix is positive (or starts with
-zero) and on the right if the prefix is negative.  The padding character
-is normally a space, but if the numeric prefix starts with a zero, zeros
-are used for padding.  Here are some examples of padding:
+  All the specification characters allow an optional ``width'', which
+is a digit-string between the @samp{%} and the 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:
 
 @example
 (format "%06d is padded on the left with zeros" 123)
@@ -757,10 +821,9 @@
      @result{} "123    is padded on the right"
 @end example
 
-  @code{format} never truncates an object's printed representation, no
-matter what width you specify.  Thus, you can use a numeric prefix to
-specify a minimum spacing between columns with no risk of losing
-information.
+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
@@ -788,6 +851,32 @@
 @end group
 @end smallexample
 
+@cindex precision in format specifications
+  All the specification characters allow an optional ``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.
+
+@cindex flags in format specifications
+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 (otherwise
+nothing is inserted for positive numbers).  This flag is ignored
+except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}.
+
+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.
+
 @node Case Conversion
 @comment node-name, next, previous, up
 @section Case Conversion in Lisp
@@ -799,7 +888,7 @@
   The character case functions change the case of single characters or
 of the contents of strings.  The functions normally convert only
 alphabetic characters (the letters @samp{A} through @samp{Z} and
-@samp{a} through @samp{z}, as well as non-@sc{ascii} letters); other
+@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other
 characters are not altered.  You can specify a different case
 conversion mapping by specifying a case table (@pxref{Case Tables}).
 
@@ -807,7 +896,7 @@
 arguments.
 
   The examples below use the characters @samp{X} and @samp{x} which have
-@sc{ascii} codes 88 and 120 respectively.
+@acronym{ASCII} codes 88 and 120 respectively.
 
 @defun downcase string-or-char
 This function converts a character or a string to lower case.
@@ -867,11 +956,15 @@
 has the same result as @code{upcase}.
 
 @example
+@group
 (capitalize "The cat in the hat")
      @result{} "The Cat In The Hat"
+@end group
 
+@group
 (capitalize "THE 77TH-HATTED CAT")
      @result{} "The 77th-Hatted Cat"
+@end group
 
 @group
 (capitalize ?x)
@@ -880,16 +973,20 @@
 @end example
 @end defun
 
-@defun upcase-initials string
-This function capitalizes the initials of the words in @var{string},
-without altering any letters other than the initials.  It returns a new
-string whose contents are a copy of @var{string}, in which each word has
+@defun upcase-initials string-or-char
+If @var{string-or-char} is a string, this function capitalizes the
+initials of the words in @var{string-or-char}, without altering any
+letters other than the initials.  It returns a new string whose
+contents are a copy of @var{string-or-char}, in which each word has
 had its initial letter converted to upper case.
 
 The definition of a word is any sequence of consecutive characters that
 are assigned to the word constituent syntax class in the current syntax
 table (@pxref{Syntax Class Table}).
 
+When the argument to @code{upcase-initials} is a character,
+@code{upcase-initials} has the same result as @code{upcase}.
+
 @example
 @group
 (upcase-initials "The CAT in the hAt")
@@ -944,9 +1041,9 @@
 canonical equivalent character (which should be either @samp{a} for both
 of them, or @samp{A} for both of them).
 
-  The extra table @var{equivalences} is a map that cyclicly permutes
+  The extra table @var{equivalences} is a map that cyclically permutes
 each equivalence class (of characters with the same canonical
-equivalent).  (For ordinary @sc{ascii}, this would map @samp{a} into
+equivalent).  (For ordinary @acronym{ASCII}, this would map @samp{a} into
 @samp{A} and @samp{A} into @samp{a}, and likewise for each set of
 equivalent characters.)
 
@@ -983,7 +1080,7 @@
 @end defun
 
   The following three functions are convenient subroutines for packages
-that define non-@sc{ascii} character sets.  They modify the specified
+that define non-@acronym{ASCII} character sets.  They modify the specified
 case table @var{case-table}; they also modify the standard syntax table.
 @xref{Syntax Tables}.  Normally you would use these functions to change
 the standard case table.
@@ -1007,3 +1104,7 @@
 This command displays a description of the contents of the current
 buffer's case table.
 @end deffn
+
+@ignore
+   arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4
+@end ignore

--- a/lispref/symbols.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/symbols.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -360,6 +360,7 @@
 @code{read}.
 @end defvar
 
+@anchor{Definition of mapatoms}
 @defun mapatoms function &optional obarray
 This function calls @var{function} once with each symbol in the obarray
 @var{obarray}.  Then it returns @code{nil}.  If @var{obarray} is
@@ -475,7 +476,7 @@
 @defun setplist symbol plist
 This function sets @var{symbol}'s property list to @var{plist}.
 Normally, @var{plist} should be a well-formed property list, but this is
-not enforced.
+not enforced.  The return value is @var{plist}.
 
 @smallexample
 (setplist 'foo '(a 1 b (2 3) c nil))
@@ -560,6 +561,16 @@
             (plist-put (symbol-plist symbol) prop value)))
 @end example
 
+@defun lax-plist-get plist property
+Like @code{plist-get} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
+@defun lax-plist-put plist property value
+Like @code{plist-put} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
 @defun plist-member plist property
 @tindex plist-member
 This returns non-@code{nil} if @var{plist} contains the given
@@ -568,3 +579,7 @@
 The value is actually the tail of @var{plist} whose @code{car} is
 @var{property}.
 @end defun
+
+@ignore
+   arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce
+@end ignore

--- a/lispref/syntax.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/syntax.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -397,10 +397,13 @@
   In this section we describe functions for creating, accessing and
 altering syntax tables.
 
-@defun make-syntax-table
-This function creates a new syntax table.  It inherits the syntax for
-letters and control characters from the standard syntax table.  For
-other characters, the syntax is copied from the standard syntax table.
+@defun make-syntax-table &optional table
+This function creates a new syntax table, with all values initialized
+to @code{nil}.  If @var{table} is non-@code{nil}, it becomes the
+parent of the new syntax table, otherwise the standard syntax table is
+the parent.  Like all char-tables, a syntax table inherits from its
+parent.  Thus the original syntax of all characters in the returned
+syntax table is determined by the parent.  @xref{Char-Tables}.
 
 Most major mode syntax tables are created in this way.
 @end defun
@@ -408,7 +411,7 @@
 @defun copy-syntax-table &optional table
 This function constructs a copy of @var{table} and returns it.  If
 @var{table} is not supplied (or is @code{nil}), it returns a copy of the
-current syntax table.  Otherwise, an error is signaled if @var{table} is
+standard syntax table.  Otherwise, an error is signaled if @var{table} is
 not a syntax table.
 @end defun
 
@@ -425,7 +428,7 @@
 the table for this character is discarded.
 
 An error is signaled if the first character of the syntax descriptor is not
-one of the twelve syntax class designator characters.  An error is also
+one of the seventeen syntax class designator characters.  An error is also
 signaled if @var{char} is not a character.
 
 @example
@@ -559,10 +562,11 @@
 have certain syntax classes.
 
 @defun skip-syntax-forward syntaxes &optional limit
-This function moves point forward across characters having syntax classes
-mentioned in @var{syntaxes}.  It stops when it encounters the end of
-the buffer, or position @var{limit} (if specified), or a character it is
-not supposed to skip.
+This function moves point forward across characters having syntax
+classes mentioned in @var{syntaxes} (a string of syntax code
+characters).  It stops when it encounters the end of the buffer, or
+position @var{limit} (if specified), or a character it is not supposed
+to skip.
 
 If @var{syntaxes} starts with @samp{^}, then the function skips
 characters whose syntax is @emph{not} in @var{syntaxes}.
@@ -697,9 +701,10 @@
 The minimum parenthesis depth encountered during this scan.
 
 @item
-What kind of comment is active: @code{nil} for a comment of style ``a'',
-@code{t} for a comment of style ``b'', and @code{syntax-table} for
-a comment that should be ended by a generic comment delimiter character.
+What kind of comment is active: @code{nil} for a comment of style
+``a'' or when not inside a comment, @code{t} for a comment of style
+``b'', and @code{syntax-table} for a comment that should be ended by a
+generic comment delimiter character.
 
 @item
 The string or comment start position.  While inside a comment, this is
@@ -710,6 +715,12 @@
 
 Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
 
+Actually, the return value is currently a list of ten, rather than
+nine, elements and @var{state} is allowed to be a list of ten elements
+as well.  However, the meaning of the tenth element is subject to
+change and only the first eight elements of @var{state} need to be
+specified.
+
 @cindex indenting with parentheses
 This function is most often used to compute indentation for languages
 that have nested parentheses.
@@ -752,22 +763,20 @@
 @defvar multibyte-syntax-as-symbol
 @tindex multibyte-syntax-as-symbol
 If this variable is non-@code{nil}, @code{scan-sexps} treats all
-non-@sc{ascii} characters as symbol constituents regardless
+non-@acronym{ASCII} characters as symbol constituents regardless
 of what the syntax table says about them.  (However, text properties
 can still override the syntax.)
 @end defvar
 
-@defvar parse-sexp-ignore-comments
+@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}.
+@end defopt
 
-In older Emacs versions, this feature worked only when the comment
-terminator is something like @samp{*/}, and appears only to end a
-comment.  In languages where newlines terminate comments, it was
-necessary make this variable @code{nil}, since not every newline is the
-end of a comment.  This limitation no longer exists.
-@end defvar
+@vindex parse-sexp-lookup-properties
+The behaviour of @code{parse-partial-sexp} is also affected by
+@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).
 
 You can use @code{forward-comment} to move forward or backward over
 one comment or several comments.
@@ -781,7 +790,9 @@
 place where it stopped.  This includes (for instance) finding the end
 of a comment when moving forward and expecting the beginning of one.
 The function also stops immediately after moving over the specified
-number of complete comments.
+number of complete comments.  If @var{count} comments are found as
+expected, with nothing except whitespace between them, it returns
+@code{t}; otherwise it returns @code{nil}.
 
 This function cannot tell whether the ``comments'' it traverses are
 embedded within a string.  If they look like comments, it treats them
@@ -940,7 +951,7 @@
 initialized by copying from the standard categories table, so that the
 standard categories are available in all modes.
 
-  Each category has a name, which is an @sc{ascii} printing character in
+  Each category has a name, which is an @acronym{ASCII} printing character in
 the range @w{@samp{ }} to @samp{~}.  You specify the name of a category
 when you define it with @code{define-category}.
 
@@ -951,12 +962,12 @@
 @code{t}, that means category @var{cat} is a member of the set, and that
 character @var{c} belongs to category @var{cat}.
 
+For the next three functions, the optional argument @var{table}
+defaults to the current buffer's category table.
+
 @defun define-category char docstring &optional table
 This function defines a new category, with name @var{char} and
-documentation @var{docstring}.
-
-The new category is defined for category table @var{table}, which
-defaults to the current buffer's category table.
+documentation @var{docstring}, for the category table @var{table},
 @end defun
 
 @defun category-docstring category &optional table
@@ -971,7 +982,7 @@
 @end example
 @end defun
 
-@defun get-unused-category table
+@defun get-unused-category &optional table
 This function returns a category name (a character) which is not
 currently defined in @var{table}.  If all possible categories are in use
 in @var{table}, it returns @code{nil}.
@@ -993,7 +1004,7 @@
 @defun copy-category-table &optional table
 This function constructs a copy of @var{table} and returns it.  If
 @var{table} is not supplied (or is @code{nil}), it returns a copy of the
-current category table.  Otherwise, an error is signaled if @var{table}
+standard category table.  Otherwise, an error is signaled if @var{table}
 is not a category table.
 @end defun
 
@@ -1023,11 +1034,11 @@
 @end defun
 
 @defun char-category-set char
-This function returns the category set for character @var{char}.  This
-is the bool-vector which records which categories the character
-@var{char} belongs to.  The function @code{char-category-set} does not
-allocate storage, because it returns the same bool-vector that exists in
-the category table.
+This function returns the category set for character @var{char} in the
+current buffer's category table.  This is the bool-vector which
+records which categories the character @var{char} belongs to.  The
+function @code{char-category-set} does not allocate storage, because
+it returns the same bool-vector that exists in the category table.
 
 @example
 (char-category-set ?a)
@@ -1056,8 +1067,13 @@
 instead.
 @end defun
 
-@deffn Command describe-categories
+@deffn Command describe-categories &optional buffer-or-name
 This function describes the category specifications in the current
-category table.  The descriptions are inserted in a buffer, which is
-then displayed.
+category table.  It inserts the descriptions in a buffer, and then
+displays that buffer.  If @var{buffer-or-name} is non-@code{nil}, it
+describes the category table of that buffer instead.
 @end deffn
+
+@ignore
+   arch-tag: 4d914e96-0283-445c-9233-75d33662908c
+@end ignore

--- a/lispref/text.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/text.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -58,6 +58,7 @@
                        position stored in a register.
 * Base 64::          Conversion to or from base 64 encoding.
 * MD5 Checksum::     Compute the MD5 ``message digest''/``checksum''.
+* Atomic Changes::   Installing several buffer changes ``atomically''.
 * Change Hooks::     Supplying functions to be run when text is changed.
 @end menu
 
@@ -68,6 +69,9 @@
 Several simple functions are described here.  See also @code{looking-at}
 in @ref{Regexp Search}.
 
+In the following four functions, ``beginning'' or ``end'' of buffer
+refers to the beginning or end of the accessible portion.
+
 @defun char-after &optional position
 This function returns the character in the current buffer at (i.e.,
 immediately after) position @var{position}.  If @var{position} is out of
@@ -158,7 +162,7 @@
 @node Buffer Contents
 @section Examining Buffer Contents
 
-  This section describes two functions that allow a Lisp program to
+  This section describes functions that allow a Lisp program to
 convert any portion of the text in the buffer into a string.
 
 @defun buffer-substring start end
@@ -229,9 +233,9 @@
 This function returns the symbol (or word) at or near point, as a string.
 The return value includes no text properties.
 
-The optional argument @var{really-word} is non-@code{nil}, it finds a
-word; otherwise, it finds a symbol (which includes word characters and
-both symbol constituent characters).
+If the optional argument @var{really-word} is non-@code{nil}, it finds a
+word; otherwise, it finds a symbol (which includes both word
+characters and symbol constituent characters).
 
 If the optional argument @var{strict} is non-@code{nil}, then point
 must be in or next to the symbol or word---if no symbol or word is
@@ -272,10 +276,10 @@
 @defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2
 This function lets you compare two substrings of the same buffer or two
 different buffers.  The first three arguments specify one substring,
-giving a buffer and two positions within the buffer.  The last three
-arguments specify the other substring in the same way.  You can use
-@code{nil} for @var{buffer1}, @var{buffer2}, or both to stand for the
-current buffer.
+giving a buffer (or a buffer name) and two positions within the
+buffer.  The last three arguments specify the other substring in the
+same way.  You can use @code{nil} for @var{buffer1}, @var{buffer2}, or
+both to stand for the current buffer.
 
 The value is negative if the first substring is less, positive if the
 first is greater, and zero if they are equal.  The absolute value of
@@ -350,16 +354,16 @@
 
 This function is unlike the other insertion functions in that it
 relocates markers initially pointing at the insertion point, to point
-after the inserted text.  If an overlay begins the insertion point, the
-inserted text falls outside the overlay; if a nonempty overlay ends at
-the insertion point, the inserted text falls inside that overlay.
+after the inserted text.  If an overlay begins at the insertion point,
+the inserted text falls outside the overlay; if a nonempty overlay
+ends at the insertion point, the inserted text falls inside that
+overlay.
 @end defun
 
 @defun insert-char character count &optional inherit
 This function inserts @var{count} instances of @var{character} into the
 current buffer before point.  The argument @var{count} should be a
-number (@code{nil} means 1), and @var{character} must be a character.
-The value is @code{nil}.
+number, and @var{character} must be a character.  The value is @code{nil}.
 
 This function does not convert unibyte character codes 128 through 255
 to multibyte characters, not even if the current buffer is a multibyte
@@ -373,7 +377,7 @@
 @defun insert-buffer-substring from-buffer-or-name &optional start end
 This function inserts a portion of buffer @var{from-buffer-or-name}
 (which must already exist) into the current buffer before point.  The
-text inserted is the region from @var{start} and @var{end}.  (These
+text inserted is the region between @var{start} and @var{end}.  (These
 arguments default to the beginning and end of the accessible portion of
 that buffer.)  This function returns @code{nil}.
 
@@ -398,6 +402,11 @@
 @end example
 @end defun
 
+@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end
+This is like @code{insert-buffer-substring} except that it does not
+copy any text properties.
+@end defun
+
   @xref{Sticky Properties}, for other insertion functions that inherit
 text properties from the nearby text in addition to inserting it.
 Whitespace inserted by indentation functions also inherits text
@@ -411,9 +420,10 @@
 programs.
 
 @deffn Command insert-buffer from-buffer-or-name
-This command inserts the entire contents of @var{from-buffer-or-name}
-(which must exist) into the current buffer after point.  It leaves
-the mark after the inserted text.  The value is @code{nil}.
+This command inserts the entire accessible contents of
+@var{from-buffer-or-name} (which must exist) into the current buffer
+after point.  It leaves the mark after the inserted text.  The value
+is @code{nil}.
 @end deffn
 
 @deffn Command self-insert-command count
@@ -494,11 +504,11 @@
 Some deletion functions do save text in the kill ring in some special
 cases.
 
-  All of the deletion functions operate on the current buffer, and all
-return a value of @code{nil}.
+  All of the deletion functions operate on the current buffer.
 
 @deffn Command erase-buffer
-This function deletes the entire text of the current buffer, leaving it
+This function deletes the entire text of the current buffer
+(@emph{not} just the accessible portion), leaving it
 empty.  If the buffer is read-only, it signals a @code{buffer-read-only}
 error; if some of the text in it is read-only, it signals a
 @code{text-read-only} error.  Otherwise, it deletes the text without
@@ -584,8 +594,9 @@
 This option specifies how @code{backward-delete-char-untabify} should
 deal with whitespace.  Possible values include @code{untabify}, the
 default, meaning convert a tab to many spaces and delete one;
-@code{hungry}, meaning delete all the whitespace characters before point
-with one command, and @code{nil}, meaning do nothing special for
+@code{hungry}, meaning delete all tabs and spaces before point with
+one command; @code{all} meaning delete all tabs, spaces and newlines
+before point, and @code{nil}, meaning do nothing special for
 whitespace characters.
 @end defopt
 
@@ -596,11 +607,14 @@
 commands intended primarily for the user but useful also in Lisp
 programs.
 
-@deffn Command delete-horizontal-space
+@deffn Command delete-horizontal-space &optional backward-only
 @cindex deleting whitespace
 This function deletes all spaces and tabs around point.  It returns
 @code{nil}.
 
+If @var{backward-only} is non-@code{nil}, the function deletes
+spaces and tabs before point, but not after point.
+
 In the following examples, we call @code{delete-horizontal-space} four
 times, once on each line, with point between the second and third
 characters on the line each time.
@@ -666,9 +680,10 @@
 responsible for deciding whether to leave a space at the junction.
 @end deffn
 
-@defun fixup-whitespace
-This function replaces all the whitespace surrounding point with either
-one space or no space, according to the context.  It returns @code{nil}.
+@deffn Command fixup-whitespace
+This function replaces all the horizontal whitespace surrounding point
+with either one space or no space, according to the context.  It
+returns @code{nil}.
 
 At the beginning or end of a line, the appropriate amount of space is
 none.  Before a character with close parenthesis syntax, or after a
@@ -702,7 +717,7 @@
 ---------- Buffer: foo ----------
 @end group
 @end smallexample
-@end defun
+@end deffn
 
 @deffn Command just-one-space
 @comment !!SourceFile simple.el
@@ -715,7 +730,7 @@
 blank line with one or more blank lines before or after it, then all but
 one of them are deleted.  If point is on an isolated blank line, then it
 is deleted.  If point is on a nonblank line, the command deletes all
-blank lines following it.
+blank lines immediately following it.
 
 A blank line is defined as a line containing only tabs and spaces.
 
@@ -761,9 +776,10 @@
 @menu
 * Kill Ring Concepts::     What text looks like in the kill ring.
 * Kill Functions::         Functions that kill text.
+* Yanking::                How yanking is done.
 * Yank Commands::          Commands that access the kill ring.
 * Low-Level Kill Ring::	   Functions and variables for kill ring access.
-* Internals of Kill Ring:: Variables that hold kill-ring data.
+* Internals of Kill Ring:: Variables that hold kill ring data.
 @end menu
 
 @node Kill Ring Concepts
@@ -783,7 +799,7 @@
 
   When kill commands are interwoven with other commands, each kill
 command makes a new entry in the kill ring.  Multiple kill commands in
-succession build up a single kill-ring entry, which would be yanked as a
+succession build up a single kill ring entry, which would be yanked as a
 unit; the second and subsequent consecutive kill commands add text to
 the entry made by the first one.
 
@@ -805,7 +821,7 @@
 @code{last-command}) whether the previous command was a kill command,
 and if so appends the killed text to the most recent entry.
 
-@deffn Command kill-region start end
+@deffn Command kill-region start end &optional yank-handler
 This function kills the text in the region defined by @var{start} and
 @var{end}.  The text is deleted but saved in the kill ring, along with
 its text properties.  The value is always @code{nil}.
@@ -818,6 +834,12 @@
 ring just the same, then signals an error without modifying the buffer.
 This is convenient because it lets the user use a series of kill
 commands to copy text from a read-only buffer into the kill ring.
+
+If @var{yank-handler} is non-@code{nil}, this puts that value onto
+the string of killed text, as a @code{yank-handler} text property.
+@xref{Yanking}.  Note that if @var{yank-handler} is @code{nil}, any
+@code{yank-handler} properties present on the killed text are copied
+onto the kill ring, like other text properties.
 @end deffn
 
 @defopt kill-read-only-ok
@@ -829,9 +851,7 @@
 @deffn Command copy-region-as-kill start end
 This command saves the region defined by @var{start} and @var{end} on
 the kill ring (including text properties), but does not delete the text
-from the buffer.  It returns @code{nil}.  It also indicates the extent
-of the text copied by moving the cursor momentarily, or by displaying a
-message in the echo area.
+from the buffer.  It returns @code{nil}.
 
 The command does not set @code{this-command} to @code{kill-region}, so a
 subsequent kill command does not append to the same kill ring entry.
@@ -842,6 +862,67 @@
 Ring}.
 @end deffn
 
+@node Yanking
+@subsection Yanking
+
+  Yanking means inserting text from the kill ring, but it does
+not insert the text blindly.  Yank commands and some other commands
+use @code{insert-for-yank} to perform special processing on the
+text that they copy into the buffer.
+
+@defun insert-for-yank string
+This function normally works like @code{insert} except that it doesn't
+insert the text properties in the @code{yank-excluded-properties}
+list.  However, if any part of @var{string} has a non-@code{nil}
+@code{yank-handler} text property, that property can do various
+special processing on that part of the text being inserted.
+@end defun
+
+@defun insert-buffer-substring-as-yank buf &optional start end
+This function resembles @code{insert-buffer-substring} except that it
+doesn't insert the text properties in the
+@code{yank-excluded-properties} list.
+@end defun
+
+  You can put a @code{yank-handler} text property on all or part of
+the text to control how it will be inserted if it is yanked.  The
+@code{insert-for-yank} function looks for that property.  The property
+value must be a list of one to four elements, with the following
+format (where elements after the first may be omitted):
+
+@example
+(@var{function} @var{param} @var{noexclude} @var{undo})
+@end example
+
+  Here is what the elements do:
+
+@table @var
+@item function
+When @var{function} is present and non-@code{nil}, it is called instead of
+@code{insert} to insert the string.  @var{function} takes one
+argument---the string to insert.
+
+@item param
+If @var{param} is present and non-@code{nil}, it replaces @var{string}
+(or the part of @var{string} being processed) as the object passed to
+@var{function} (or @code{insert}); for example, if @var{function} is
+@code{yank-rectangle}, @var{param} should be a list of strings to
+insert as a rectangle.
+
+@item noexclude
+If @var{noexclude} is present and non-@code{nil}, the normal removal of the
+yank-excluded-properties is not performed; instead @var{function} is
+responsible for removing those properties.  This may be necessary
+if @var{function} adjusts point before or after inserting the object.
+
+@item undo
+If @var{undo} is present and non-@code{nil}, it is a function that will be
+called by @code{yank-pop} to undo the insertion of the current object.
+It is called with two arguments, the start and end of the current
+region.  @var{function} can set @code{yank-undo-function} to override
+the @var{undo} value.
+@end table
+
 @node Yank Commands
 @comment  node-name,  next,  previous,  up
 @subsection Functions for Yanking
@@ -851,23 +932,29 @@
 
 @deffn Command yank &optional arg
 @cindex inserting killed text
-This command inserts before point the text in the first entry in the
+This command inserts before point the text at the front of the
 kill ring.  It positions the mark at the beginning of that text, and
 point at the end.
 
-If @var{arg} is a list (which occurs interactively when the user
-types @kbd{C-u} with no digits), then @code{yank} inserts the text as
-described above, but puts point before the yanked text and puts the mark
-after it.
-
-If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most
-recently killed text---the @var{arg}th element of the kill ring list.
-
-@code{yank} does not alter the contents of the kill ring or rotate it.
-It returns @code{nil}.
+If @var{arg} is a non-@code{nil} list (which occurs interactively when
+the user types @kbd{C-u} with no digits), then @code{yank} inserts the
+text as described above, but puts point before the yanked text and
+puts the mark after it.
+
+If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
+most recently killed text---the @var{arg}th element of the kill ring
+list, counted cyclically from the front, which is considered the
+first element for this purpose.
+
+@code{yank} does not alter the contents of the kill ring, unless it
+used text provided by another program, in which case it pushes that text
+onto the kill ring.  However if @var{arg} is an integer different from
+one, it rotates the kill ring to place the yanked string at the front.
+
+@code{yank} returns @code{nil}.
 @end deffn
 
-@deffn Command yank-pop arg
+@deffn Command yank-pop &optional arg
 This command replaces the just-yanked entry from the kill ring with a
 different entry from the kill ring.
 
@@ -876,6 +963,8 @@
 inserted by yanking.  @code{yank-pop} deletes that text and inserts in
 its place a different piece of killed text.  It does not add the deleted
 text to the kill ring, since it is already in the kill ring somewhere.
+It does however rotate the kill ring to place the newly yanked string at
+the front.
 
 If @var{arg} is @code{nil}, then the replacement text is the previous
 element of the kill ring.  If @var{arg} is numeric, the replacement is
@@ -889,6 +978,18 @@
 The return value is always @code{nil}.
 @end deffn
 
+@defvar yank-undo-function
+If this variable is non-@code{nil}, the function @code{yank-pop} uses
+its value instead of @code{delete-region} to delete the text
+inserted by the previous @code{yank} or
+@code{yank-pop} command.  The value must be a function of two
+arguments, the start and end of the current region.
+
+The function @code{insert-for-yank} automatically sets this variable
+according to the @var{undo} element of the @code{yank-handler}
+text property, if there is one.
+@end defvar
+
 @node Low-Level Kill Ring
 @subsection Low-Level Kill Ring
 
@@ -908,23 +1009,44 @@
 
 If @var{n} is zero, indicating a request for the latest kill,
 @code{current-kill} calls the value of
-@code{interprogram-paste-function} (documented below) before consulting
-the kill ring.
+@code{interprogram-paste-function} (documented below) before
+consulting the kill ring.  If that value is a function and calling it
+returns a string, @code{current-kill} pushes that string onto the kill
+ring and returns it.  It also sets the yanking pointer to point to
+that new entry, regardless of the value of @var{do-not-move}.
+Otherwise, @code{current-kill} does not treat a zero value for @var{n}
+specially: it returns the entry pointed at by the yanking pointer and
+does not move the yanking pointer.
 @end defun
 
-@defun kill-new string
-This function puts the text @var{string} into the kill ring as a new
-entry at the front of the ring.  It discards the oldest entry if
-appropriate.  It also invokes the value of
+@defun kill-new string &optional replace yank-handler
+This function pushes the text @var{string} onto the kill ring and
+makes the yanking pointer point to it.  It discards the oldest entry
+if appropriate.  It also invokes the value of
 @code{interprogram-cut-function} (see below).
+
+If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the
+first element of the kill ring with @var{string}, rather than pushing
+@var{string} onto the kill ring.
+
+If @var{yank-handler} is non-@code{nil}, this puts that value onto
+the string of killed text, as a @code{yank-handler} property.
+@xref{Yanking}.  Note that if @var{yank-handler} is @code{nil}, then
+@code{kill-new} copies any @code{yank-handler} properties present on
+@var{string} onto the kill ring, as it does with other text properties.
 @end defun
 
-@defun kill-append string before-p
+@defun kill-append string before-p &optional yank-handler
 This function appends the text @var{string} to the first entry in the
-kill ring.  Normally @var{string} goes at the end of the entry, but if
+kill ring and makes the yanking pointer point to the combined entry.
+Normally @var{string} goes at the end of the entry, but if
 @var{before-p} is non-@code{nil}, it goes at the beginning.  This
-function also invokes the value of @code{interprogram-cut-function} (see
-below).
+function also invokes the value of @code{interprogram-cut-function}
+(see below).  This handles @var{yank-handler} just like
+@code{kill-new}, except that if @var{yank-handler} is different from
+the @code{yank-handler} property of the first entry of the kill ring,
+@code{kill-append} pushes the concatenated string onto the kill ring,
+instead of replacing the original first entry with it.
 @end defun
 
 @defvar interprogram-paste-function
@@ -935,7 +1057,7 @@
 If the value is a function, @code{current-kill} calls it to get the
 ``most recent kill''.  If the function returns a non-@code{nil} value,
 then that value is used as the ``most recent kill''.  If it returns
-@code{nil}, then the first element of @code{kill-ring} is used.
+@code{nil}, then the front of the kill ring is used.
 
 The normal use of this hook is to get the window system's primary
 selection as the most recent kill, even if the selection belongs to
@@ -945,13 +1067,17 @@
 @defvar interprogram-cut-function
 This variable provides a way of communicating killed text to other
 programs, when you are using a window system.  Its value should be
-@code{nil} or a function of one argument.
+@code{nil} or a function of one required and one optional argument.
 
 If the value is a function, @code{kill-new} and @code{kill-append} call
-it with the new first element of the kill ring as an argument.
+it with the new first element of the kill ring as the first argument.
+The second, optional, argument has the same meaning as the @var{push}
+argument to @code{x-set-cut-buffer} (@pxref{Definition of
+x-set-cut-buffer}) and only affects the second and later cut buffers.
 
 The normal use of this hook is to set the window system's primary
-selection from the newly killed text.  @xref{Window System Selections}.
+selection (and first cut buffer) from the newly killed text.
+@xref{Window System Selections}.
 @end defvar
 
 @node Internals of Kill Ring
@@ -1024,7 +1150,7 @@
 @defopt kill-ring-max
 The value of this variable is the maximum length to which the kill
 ring can grow, before elements are thrown away at the end.  The default
-value for @code{kill-ring-max} is 30.
+value for @code{kill-ring-max} is 60.
 @end defopt
 
 @node Undo
@@ -1061,7 +1187,9 @@
 @item (@var{text} . @var{position})
 This kind of element indicates how to reinsert text that was deleted.
 The deleted text itself is the string @var{text}.  The place to
-reinsert it is @code{(abs @var{position})}.
+reinsert it is @code{(abs @var{position})}.  If @var{position} is
+positive, point was at the beginning of the deleted text, otherwise it
+was at the end.
 
 @item (t @var{high} . @var{low})
 This kind of element indicates that an unmodified buffer became
@@ -1153,13 +1281,13 @@
 You cannot specify any other buffer.
 @end deffn
 
-@deffn Command buffer-disable-undo &optional buffer
-@deffnx Command buffer-flush-undo &optional buffer
+@deffn Command buffer-disable-undo &optional buffer-or-name
+@deffnx Command buffer-flush-undo &optional buffer-or-name
 @cindex disable undo
-This function discards the undo list of @var{buffer}, and disables
+This function discards the undo list of @var{buffer-or-name}, and disables
 further recording of undo information.  As a result, it is no longer
 possible to undo either previous changes or any subsequent changes.  If
-the undo list of @var{buffer} is already disabled, this function
+the undo list of @var{buffer-or-name} is already disabled, this function
 has no effect.
 
 This function returns @code{nil}.
@@ -1622,7 +1750,7 @@
  BEG and END (region to sort).
 The variable `sort-fold-case' determines\
  whether alphabetic case affects
-the sort order.
+the sort order."
 @end group
 @group
   (interactive "P\nr")
@@ -1803,7 +1931,8 @@
 
   Column number computations ignore the width of the window and the
 amount of horizontal scrolling.  Consequently, a column value can be
-arbitrarily high.  The first (or leftmost) column is numbered 0.
+arbitrarily high.  The first (or leftmost) column is numbered 0.  They
+also ignore overlays and text properties, aside from invisibility.
 
 @defun current-column
 This function returns the horizontal position of point, measured in
@@ -2145,16 +2274,18 @@
 @code{nil}.
 @end deffn
 
-@deffn Command backward-to-indentation arg
+@deffn Command backward-to-indentation &optional arg
 @comment !!SourceFile simple.el
 This command moves point backward @var{arg} lines and then to the
 first nonblank character on that line.  It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
 @end deffn
 
-@deffn Command forward-to-indentation arg
+@deffn Command forward-to-indentation &optional arg
 @comment !!SourceFile simple.el
 This command moves point forward @var{arg} lines and then to the first
 nonblank character on that line.  It returns @code{nil}.
+If @var{arg} is omitted or @code{nil}, it defaults to 1.
 @end deffn
 
 @node Case Changes
@@ -2320,7 +2451,7 @@
 the @var{prop} property of that symbol.
 @end defun
 
-@defun get-char-property pos prop &optional object
+@defun get-char-property position prop &optional object
 This function is like @code{get-text-property}, except that it checks
 overlays first and then text properties.  @xref{Overlays}.
 
@@ -2333,6 +2464,20 @@
 overlays.
 @end defun
 
+@defun get-char-property-and-overlay position prop &optional object
+This is like @code{get-char-property}, but gives extra information
+about the overlay that the property value comes from.
+
+Its value is a cons cell whose @sc{car} is the property value, the
+same value @code{get-char-property} would return with the same
+arguments.  Its @sc{cdr} is the overlay in which the property was
+found, or @code{nil}, if it was found as a text property or not found
+at all.
+
+If @var{position} is at the end of @var{object}, both the @sc{car} and
+the @sc{cdr} of the value are @code{nil}.
+@end defun
+
 @defvar char-property-alias-alist
 This variable holds an alist which maps property names to a list of
 alternative property names.  If a character does not specify a direct
@@ -2435,6 +2580,12 @@
 list.
 @end defun
 
+@defun remove-list-of-text-properties start end list-of-properties &optional object
+Like @code{remove-list-properties} except that
+@var{list-of-properties} is a list property names only, not an
+alternating list of property values.
+@end defun
+
 @defun set-text-properties start end props &optional object
 This function completely replaces the text property list for the text
 between @var{start} and @var{end} in the string or buffer @var{object}.
@@ -2765,11 +2916,13 @@
 commands.  The property's value for the character before point applies
 if it is non-@code{nil} and rear-sticky, and the property's value for
 the character after point applies if it is non-@code{nil} and
-front-sticky.  When the value applies, it is used for key lookup
-before the buffer's local map.  (For mouse clicks, the position of the
-click is used instead of the position of point.)  If the property
-value is a symbol, the symbol's function definition is used as the
-keymap.  @xref{Active Keymaps}.
+front-sticky.  (For mouse clicks, the position of the click is used
+instead of the position of point.)  If the property value is a symbol,
+the symbol's function definition is used as the keymap.
+
+When this keymap applies, it is used for key lookup before the minor
+mode keymaps and before the buffer's local map.  @xref{Active
+Keymaps}.
 
 @item local-map
 @kindex local-map @r{(text property)}
@@ -2876,9 +3029,9 @@
 @code{point-left} functions are called first, followed by all the
 @code{point-entered} functions.
 
-It is possible using @code{char-after} to examine characters at various
-positions without moving point to those positions.  Only an actual
-change in the value of point runs these hook functions.
+It is possible with @code{char-after} to examine characters at various
+buffer positions without moving point to those positions.  Only an
+actual change in the value of point runs these hook functions.
 @end table
 
 @defvar inhibit-point-motion-hooks
@@ -3425,7 +3578,7 @@
 
   A register is a sort of variable used in Emacs editing that can hold a
 variety of different kinds of values.  Each register is named by a
-single character.  All @sc{ascii} characters and their meta variants
+single character.  All @acronym{ASCII} characters and their meta variants
 (but with the exception of @kbd{C-g}) can be used to name registers.
 Thus, there are 255 possible registers.  A register is designated in
 Emacs Lisp by the character that is its name.
@@ -3593,7 +3746,7 @@
 @cindex base 64 encoding
 
   Base 64 code is used in email to encode a sequence of 8-bit bytes as
-a longer sequence of @sc{ascii} graphic characters.  It is defined in
+a longer sequence of @acronym{ASCII} graphic characters.  It is defined in
 Internet RFC@footnote{
 An RFC, an acronym for @dfn{Request for Comments}, is a numbered
 Internet informational document describing a standard.  RFCs are
@@ -3697,6 +3850,96 @@
 coding instead.
 @end defun
 
+@node Atomic Changes
+@section Atomic Change Groups
+@cindex atomic changes
+
+  In data base terminology, an @dfn{atomic} change is an indivisible
+change---it can succeed entirely or it can fail entirely, but it
+cannot partly succeed.  A Lisp program can make a series of changes to
+one or several buffers as an @dfn{atomic change group}, meaning that
+either the entire series of changes will be installed in their buffers
+or, in case of an error, none of them will be.
+
+  To do this for one buffer, the one already current, simply write a
+call to @code{atomic-change-group} around the code that makes the
+changes, like this:
+
+@example
+(atomic-change-group
+  (insert foo)
+  (delete-region x y))
+@end example
+
+@noindent
+If an error (or other nonlocal exit) occurs inside the body of
+@code{atomic-change-group}, it unmakes all the changes in that buffer
+that were during the execution of the body.  This kind of change group
+has no effect on any other buffers--any such changes remain.
+
+  If you need something more sophisticated, such as to make changes in
+various buffers constitute one atomic group, you must directly call
+lower-level functions that @code{atomic-change-group} uses.
+
+@defun prepare-change-group &optional buffer
+This function sets up a change group for buffer @var{buffer}, which
+defaults to the current buffer.  It returns a ``handle'' that
+represents the change group.  You must use this handle to activate the
+change group and subsequently to finish it.
+@end defun
+
+  To use the change group, you must @dfn{activate} it.  You must do
+this before making any changes in the text of @var{buffer}.
+
+@defun activate-change-group handle
+This function activates the change group that @var{handle} designates.
+@end defun
+
+  After you activate the change group, any changes you make in that
+buffer become part of it.  Once you have made all the desired changes
+in the buffer, you must @dfn{finish} the change group.  There are two
+ways to do this: you can either accept (and finalize) all the changes,
+or cancel them all.
+
+@defun accept-change-group handle
+This function accepts all the changes in the change group specified by
+@var{handle}, making them final.
+@end defun
+
+@defun cancel-change-group handle
+This function cancels and undoes all the changes in the change group
+specified by @var{handle}.
+@end defun
+
+  Your code should use @code{unwind-protect} to make sure the group is
+always finished.  The call to @code{activate-change-group} should be
+inside the @code{unwind-protect}, in case the user types @kbd{C-g}
+just after it runs.  (This is one reason why
+@code{prepare-change-group} and @code{activate-change-group} are
+separate functions, because normally you would call
+@code{prepare-change-group} before the start of that
+@code{unwind-protect}.)  Once you finish the group, don't use the
+handle again---in particular, don't try to finish the same group
+twice.
+
+  To make a multibuffer change group, call @code{prepare-change-group}
+once for each buffer you want to cover, then use @code{nconc} to
+combine the returned values, like this:
+
+@example
+(nconc (prepare-change-group buffer-1)
+       (prepare-change-group buffer-2))
+@end example
+
+You can then activate the multibuffer change group with a single call
+to @code{activate-change-group}, and finish it with a single call to
+@code{accept-change-group} or @code{cancel-change-group}.
+
+  Nested use of several change groups for the same buffer works as you
+would expect.  Non-nested use of change groups for the same buffer
+will get Emacs confused, so don't let it happen; the first change
+group you start for any given buffer should be the last one finished.
+
 @node Change Hooks
 @section Change Hooks
 @cindex change hooks
@@ -3732,7 +3975,7 @@
 arguments.
 @end defvar
 
-  Output of messges into the @samp{*Messages*} buffer does not
+  Output of messages into the @samp{*Messages*} buffer does not
 call these functions.
 
 @defmac combine-after-change-calls body...
@@ -3751,7 +3994,7 @@
 @code{after-change-functions} within
 the body of a @code{combine-after-change-calls} form.
 
-@strong{Note:} If the changes you combine occur in widely scattered
+@strong{Warning:} if the changes you combine occur in widely scattered
 parts of the buffer, this will still work, but it is not advisable,
 because it may lead to inefficient behavior for some change hook
 functions.
@@ -3801,3 +4044,7 @@
 
 This variable is available starting in Emacs 21.
 @end defvar
+
+@ignore
+   arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b
+@end ignore

--- a/lispref/tindex.pl	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/tindex.pl	Mon Apr 19 07:01:43 2004 +0000
@@ -123,3 +123,4 @@
     print "  $key\n";
 }
 
+# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa

--- a/lispref/tips.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/tips.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -126,6 +126,12 @@
 name that ends in @samp{-flag}.
 
 @item
+If the purpose of a variable is to store a single function, give it a
+name that ends in @samp{-function}.  If the purpose of a variable is
+to store a list of functions (i.e., the variable is a hook), please
+follow the naming conventions for hooks.  @xref{Hooks}.
+
+@item
 @cindex reserved keys
 @cindex keys, reserved
 Please do not define @kbd{C-c @var{letter}} as a key in your major
@@ -204,7 +210,15 @@
 that simply loading it has no visible effect---that should not enable
 the feature.@footnote{Consider that the package may be loaded
 arbitrarily by Custom for instance.}  Users will request the feature by
-invoking the command.
+invoking the command.  It is a good idea to define this command
+as a minor mode.
+
+@cindex unloading packages
+If loading the file adds functions to hooks, define a function
+@code{@var{feature}-unload-hook}, where @var{feature} is the name of
+the feature the package provides, and make it undo any such changes.
+Using @code{unload-feature} to unload the file will run this function.
+@xref{Unloading}.
 
 @item
 It is a bad idea to define aliases for the Emacs primitives.  Use the
@@ -236,6 +250,13 @@
 replacements differs from that of the originals.
 
 @item
+Avoid using macros that define functions and variables with names that
+are constructed.  It is best for maintenance when the name of the
+function or variable being defined is given explicitly in the source
+code, as the second element of the list---as it is when you use
+@code{defun}, @code{defalias}, @code{defvar} and @code{defopt}.
+
+@item
 Please keep the names of your Emacs Lisp source files to 13 characters
 or less.  This way, if the files are compiled, the compiled files' names
 will be 14 characters or less, which is short enough to fit on all kinds
@@ -517,7 +538,7 @@
 
 @item
 For consistency, phrase the verb in the first sentence of a function's
-documentation string as an imperative--for instance, use ``Return the
+documentation string as an imperative---for instance, use ``Return the
 cons of A and B.'' in preference to ``Returns the cons of A and B@.''
 Usually it looks good to do likewise for the rest of the first
 paragraph.  Subsequent paragraphs usually look better if each sentence
@@ -626,6 +647,7 @@
 This prevents the open-parenthesis from being treated as the start of a
 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
 
+@anchor{Docstring hyperlinks}
 @item
 @iftex
 When a documentation string refers to a Lisp symbol, write it as it
@@ -674,9 +696,20 @@
 does not make a hyperlink to the documentation, irrelevant here, of the
 function @code{list}.
 
+Normally, no hyperlink is made for a variable without variable
+documentation.  You can force a hyperlink for such variables by
+preceding them with one of the words @samp{variable} or
+@samp{option}.
+
+Hyperlinks for faces are only made if the face name is preceded or
+followed by the word @samp{face}.  In that case, only the face
+documentation will be shown, even if the symbol is also defined as a
+variable or as a function.
+
 To make a hyperlink to Info documentation, write the name of the Info
-node in single quotes, preceded by @samp{info node} or @samp{Info
-node}.  The Info file name defaults to @samp{emacs}.  For example,
+node (or anchor) in single quotes, preceded by @samp{info node},
+@samp{Info node}, @samp{info anchor} or @samp{Info anchor}.  The Info
+file name defaults to @samp{emacs}.  For example,
 
 @smallexample
 See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
@@ -769,19 +802,30 @@
 the left margin.  These are used, occasionally, for comments within
 functions that should start at the margin.  We also use them sometimes
 for comments that are between functions---whether to use two or three
-semicolons there is a matter of style.
+semicolons depends on whether the comment should be considered a
+``heading'' by Outline minor mode.  By default, comments starting with
+at least three semicolons (followed by a single space and a
+non-whitespace character) are considered headings, comments starting
+with two or less are not.
 
 Another use for triple-semicolon comments is for commenting out lines
 within a function.  We use three semicolons for this precisely so that
-they remain at the left margin.
+they remain at the left margin.  By default, Outline minor mode does
+not consider a comment to be a heading (even if it starts with at
+least three semicolons) if the semicolons are followed by at least two
+spaces.  Thus, if you add an introductory comment to the commented out
+code, make sure to indent it by at least two spaces after the three
+semicolons.
 
 @smallexample
 (defun foo (a)
-;;; This is no longer necessary.
+;;;  This is no longer necessary.
 ;;;  (force-mode-line-update)
   (message "Finished with %s" a))
 @end smallexample
 
+When commenting out entire functions, use two semicolons.
+
 @item ;;;;
 Comments that start with four semicolons, @samp{;;;;}, should be aligned
 to the left margin and are used for headings of major sections of a
@@ -850,7 +894,8 @@
 @end example
 
 @noindent
-The description should be complete in one line.
+The description should be complete in one line.  If the file
+needs a @samp{-*-} specification, put it after @var{description}.
 
   After the copyright notice come several @dfn{header comment} lines,
 each beginning with @samp{;; @var{header-name}:}.  Here is a table of
@@ -926,9 +971,9 @@
 text is used by the Finder package, so it should make sense in that
 context.
 
-@item ;;; Documentation
-This has been used in some files in place of @samp{;;; Commentary:},
-but @samp{;;; Commentary:} is preferred.
+@item ;;; Documentation:
+This was used in some files in place of @samp{;;; Commentary:},
+but it is deprecated.
 
 @item ;;; Change Log:
 This begins change log information stored in the library file (if you
@@ -945,3 +990,7 @@
 Its purpose is to enable people to detect truncated versions of the file
 from the lack of a footer line.
 @end table
+
+@ignore
+   arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e
+@end ignore

--- a/lispref/two.el	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/two.el	Mon Apr 19 07:01:43 2004 +0000
@@ -57,3 +57,5 @@
 
 (defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I"))
 (defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II"))
+
+;;; arch-tag: 848955fe-e9cf-45e7-a2f1-570ef156d6a5

--- a/lispref/variables.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/variables.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -43,6 +43,8 @@
 * Future Local Variables::  New kinds of local values we might add some day.
 * Variable Aliases::      Variables that are aliases for other variables.
 * File Local Variables::  Handling local variable lists in files.
+* Variables with Restricted Values::  Non-constant variables whose value can
+                                        @emph{not} be an arbitrary Lisp object.
 @end menu
 
 @node Global Variables
@@ -198,18 +200,18 @@
 
 All of the @var{value-form}s in @var{bindings} are evaluated in the
 order they appear and @emph{before} binding any of the symbols to them.
-Here is an example of this: @code{Z} is bound to the old value of
-@code{Y}, which is 2, not the new value of @code{Y}, which is 1.
+Here is an example of this: @code{z} is bound to the old value of
+@code{y}, which is 2, not the new value of @code{y}, which is 1.
 
 @example
 @group
-(setq Y 2)
+(setq y 2)
      @result{} 2
 @end group
 @group
-(let ((Y 1)
-      (Z Y))
-  (list Y Z))
+(let ((y 1)
+      (z y))
+  (list y z))
      @result{} (1 2)
 @end group
 @end example
@@ -225,13 +227,13 @@
 
 @example
 @group
-(setq Y 2)
+(setq y 2)
      @result{} 2
 @end group
 @group
-(let* ((Y 1)
-       (Z Y))    ; @r{Use the just-established value of @code{Y}.}
-  (list Y Z))
+(let* ((y 1)
+       (z y))    ; @r{Use the just-established value of @code{y}.}
+  (list y z))
      @result{} (1 1)
 @end group
 @end example
@@ -258,19 +260,21 @@
 they are localized depending on ``where'' you are in Emacs, rather than
 localized in time.
 
+@anchor{Definition of max-specpdl-size}
 @defvar max-specpdl-size
 @cindex variable limit error
 @cindex evaluation error
 @cindex infinite recursion
 This variable defines the limit on the total number of local variable
-bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
-that are allowed before signaling an error (with data @code{"Variable
-binding depth exceeds max-specpdl-size"}).
+bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
+Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
+error (with data @code{"Variable binding depth exceeds
+max-specpdl-size"}).
 
 This limit, with the associated error when it is exceeded, is one way
 that Lisp avoids infinite recursion on an ill-defined function.
 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
-@xref{Eval}.
+@xref{Definition of max-lisp-eval-depth,, Eval}.
 
 The default value is 600.  Entry to the Lisp debugger increases the
 value, if there is little room left, to make sure the debugger itself
@@ -518,7 +522,7 @@
 at top level in a file where its value does not matter.
 @end defspec
 
-@defspec defconst symbol [value [doc-string]]
+@defspec defconst symbol value [doc-string]
 This special form defines @var{symbol} as a value and initializes it.
 It informs a person reading your code that @var{symbol} has a standard
 global value, established here, that should not be changed by the user
@@ -526,10 +530,10 @@
 symbol to be defined must appear explicitly in the @code{defconst}.
 
 @code{defconst} always evaluates @var{value}, and sets the value of
-@var{symbol} to the result if @var{value} is given.  If @var{symbol}
-does have a buffer-local binding in the current buffer, @code{defconst}
-sets the default value, not the buffer-local value.  (But you should not
-be making buffer-local bindings for a symbol that is defined with
+@var{symbol} to the result.  If @var{symbol} does have a buffer-local
+binding in the current buffer, @code{defconst} sets the default value,
+not the buffer-local value.  (But you should not be making
+buffer-local bindings for a symbol that is defined with
 @code{defconst}.)
 
 Here, @code{pi} is a constant that presumably ought not to be changed
@@ -858,11 +862,16 @@
   One other function for setting a variable is designed to add
 an element to a list if it is not already present in the list.
 
-@defun add-to-list symbol element
+@defun add-to-list symbol element &optional append
 This function sets the variable @var{symbol} by consing @var{element}
 onto the old value, if @var{element} is not already a member of that
 value.  It returns the resulting list, whether updated or not.  The
 value of @var{symbol} had better be a list already before the call.
+Membership is tested using @code{equal}.
+
+Normally, if @var{element} is added, it is added to the front of
+@var{symbol}, but if the optional argument @var{append} is
+non-@code{nil}, it is added at the end.
 
 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
 is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
@@ -904,6 +913,7 @@
 @cindex scope
 @cindex extent
 @cindex dynamic scoping
+@cindex lexical scoping
   Local bindings in Emacs Lisp have @dfn{indefinite scope} and
 @dfn{dynamic extent}.  @dfn{Scope} refers to @emph{where} textually in
 the source code the binding can be accessed.  ``Indefinite scope'' means
@@ -1281,9 +1291,9 @@
 variables cannot have buffer-local bindings as well.  @xref{Multiple
 Displays}.
 
-@strong{Note:} Do not use @code{make-local-variable} for a hook
-variable.  The hook variables are automatically made buffer-local
-as needed if you use the @var{local} argument to @code{add-hook} or
+@strong{Warning:} do not use @code{make-local-variable} for a hook
+variable.  The hook variables are automatically made buffer-local as
+needed if you use the @var{local} argument to @code{add-hook} or
 @code{remove-hook}.
 @end deffn
 
@@ -1295,7 +1305,14 @@
 A peculiar wrinkle of this feature is that binding the variable (with
 @code{let} or other binding constructs) does not create a buffer-local
 binding for it.  Only setting the variable (with @code{set} or
-@code{setq}) does so.
+@code{setq}), while the variable does not have a @code{let}-style
+binding that was made in the current buffer, does so.
+
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+Subsequently calling @code{makunbound} on @var{variable} will result
+in a void buffer-local value and leave the default value unaffected.
 
 The value returned is @var{variable}.
 
@@ -1318,10 +1335,17 @@
 @code{nil}.
 @end defun
 
+@defun local-variable-if-set-p variable &optional buffer
+This returns @code{t} if @var{variable} will become buffer-local in
+buffer @var{buffer} (which defaults to the current buffer) if it is
+set there.
+@end defun
+
 @defun buffer-local-value variable buffer
-This returns the value of @var{variable} that is currently in
-effect in @var{buffer}.  If it has no buffer-local binding in
-@var{buffer}, this function returns the default value.
+This function returns the buffer-local binding of @var{variable} (a
+symbol) in buffer @var{buffer}.  If @var{variable} does not have a
+buffer-local binding in buffer @var{buffer}, it returns the default
+value (@pxref{Default Value}) of @var{variable} instead.
 @end defun
 
 @defun buffer-local-variables &optional buffer
@@ -1358,13 +1382,6 @@
 list does @emph{not} change the buffer-local values of the variables.
 @end defun
 
-@defun buffer-local-value variable buffer
-This function returns the buffer-local binding of @var{variable} (a
-symbol) in buffer @var{buffer}.  If @var{variable} does not have a
-buffer-local binding in buffer @var{buffer}, it returns the default
-value (@pxref{Default Value}) of @var{variable} instead.
-@end defun
-
 @deffn Command kill-local-variable variable
 This function deletes the buffer-local binding (if any) for
 @var{variable} (a symbol) in the current buffer.  As a result, the
@@ -1561,11 +1578,17 @@
 if some frame already has a value for @var{variable} as a frame
 parameter, that value automatically becomes a frame-local binding.
 
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+
 If the variable is terminal-local, this function signals an error,
 because such variables cannot have frame-local bindings as well.
 @xref{Multiple Displays}.  A few variables that are implemented
 specially in Emacs can be (and usually are) buffer-local, but can never
 be frame-local.
+
+This command returns @var{variable}.
 @end deffn
 
   Buffer-local bindings take precedence over frame-local bindings.  Thus,
@@ -1680,13 +1703,20 @@
 
 If the @var{docstring} argument is non-@code{nil}, it specifies the
 documentation for @var{alias-var}; otherwise, the alias gets the same
-documentation as @var{base-var} has, if any.
+documentation as @var{base-var} has, if any, unless @var{base-var} is
+itself an alias, in which case @var{alias-var} gets the documentation
+of the variable at the end of the chain of aliases.
+
+This function returns @var{base-var}.
 @end defun
 
 @defun indirect-variable variable
 This function returns the variable at the end of the chain of aliases
 of @var{variable}.  If @var{variable} is not a symbol, or if @var{variable} is
 not defined as an alias, the function returns @var{variable}.
+
+This function signals a @code{cyclic-variable-indirection} error if
+there is a loop in the chain of symbols.
 @end defun
 
 @example
@@ -1698,8 +1728,10 @@
 (setq bar 2)
 bar
      @result{} 2
+@group
 foo
      @result{} 2
+@end group
 (setq foo 0)
 bar
      @result{} 0
@@ -1711,7 +1743,9 @@
 @section File Local Variables
 
   This section describes the functions and variables that affect
-processing of local variables lists in files.
+processing of local variables lists in files. @xref{File variables, ,
+Local Variables in Files, emacs, The GNU Emacs Manual}, for basic
+information about file local variables.
 
 @defopt enable-local-variables
 This variable controls whether to process file local variables lists.  A
@@ -1720,13 +1754,19 @@
 the user what to do for each file.  The default value is @code{t}.
 @end defopt
 
-@defun hack-local-variables &optional force
+@defun hack-local-variables &optional mode-only
 This function parses, and binds or evaluates as appropriate, any local
 variables specified by the contents of the current buffer.  The variable
-@code{enable-local-variables} has its effect here.
+@code{enable-local-variables} has its effect here.  However, this
+function does not look for the @samp{mode:} local variable in the
+@w{@samp{-*-}} line.  @code{set-auto-mode} does that, also taking
+@code{enable-local-variables} into account.
 
-The argument @var{force} usually comes from the argument @var{find-file}
-given to @code{normal-mode}.
+If the optional argument @var{mode-only} is non-@code{nil}, then all
+this function does is return @code{t} if the @w{@samp{-*-}} line
+specifies a mode and @code{nil} otherwise.  It does not set the mode
+nor any other file local variable.  It does not check whether a mode
+is specified in the local variables list at the end of the file.
 @end defun
 
   If a file local variable list could specify a function that will
@@ -1743,7 +1783,15 @@
 variable's meaning.  The variables @samp{font-lock-keywords},
 @samp{font-lock-keywords-[0-9]}, and
 @samp{font-lock-syntactic-keywords} cannot be set in a local variable
-list, either.
+list, either.  These rules can be overridden by giving the variable's
+name a non-@code{nil} @code{safe-local-variable} property.  If one
+gives it a @code{safe-local-variable} property of @code{t}, then one
+can give the variable any file local value.  One can also give any
+symbol, including the above, a @code{safe-local-variable} property
+that is a function taking exactly one argument.  In that case, giving
+a variable with that name a file local value is only allowed if the
+function returns non-@code{nil} when called with that value as
+argument.
 
   In addition, any variable whose name has a non-@code{nil}
 @code{risky-local-variable} property is also ignored.  So are all
@@ -1755,9 +1803,12 @@
 for one of these variables is ignored.
 @end defvar
 
-@defun risky-local-variable-p sym
-Returns non-@code{nil} if @var{sym} is risky for any of the reasons
-stated above.
+@defun risky-local-variable-p sym &optional val
+If @var{val} is non-@code{nil}, returns non-@code{nil} if giving
+@var{sym} a file local value of @var{val} would be risky, for any of
+the reasons stated above.  If @var{val} is @code{nil} or omitted, only
+returns @code{nil} if @var{sym} can be safely assigned any file local
+value whatsoever.
 @end defun
 
   The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
@@ -1769,3 +1820,47 @@
 unconditionally; @code{nil} means ignore them; anything else means ask
 the user what to do for each file.  The default value is @code{maybe}.
 @end defopt
+
+  Text properties are also potential loopholes, since their values
+could include functions to call.  So Emacs discards all text
+properties from string values specified in a file's local variables
+list.
+
+@node Variables with Restricted Values
+@section Variables with Restricted Values
+
+  Ordinary Lisp variables can be assigned any value that is a valid
+Lisp object.  However, certain Lisp variables are not defined in Lisp,
+but in C.  Most of these variables are defined in the C code using
+@code{DEFVAR_LISP}.  Like variables defined in Lisp, these can take on
+any value.  However, some variables are defined using
+@code{DEFVAR_INT} or @code{DEFVAR_BOOL}.  @xref{Defining Lisp
+variables in C,, Writing Emacs Primitives}, in particular the
+description of functions of the type @code{syms_of_@var{filename}},
+for a brief discussion of the C implementation.
+
+  Variables of type @code{DEFVAR_BOOL} can only take on the values
+@code{nil} or @code{t}.  Attempting to assign them any other value
+will set them to @code{t}:
+
+@example
+(let ((display-hourglass 5))
+  display-hourglass)
+     @result{} t
+@end example
+
+@defvar byte-boolean-vars
+This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
+@end defvar
+
+  Variables of type @code{DEFVAR_INT} can only take on integer values.
+Attempting to assign them any other value will result in an error:
+
+@example
+(setq window-min-height 5.0)
+@error{} Wrong type argument: integerp, 5.0
+@end example
+
+@ignore
+   arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
+@end ignore

--- a/lispref/vol1.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/vol1.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -1017,3 +1017,7 @@
 
 
 These words prevent "local variables" above from confusing Emacs.
+
+@ignore
+   arch-tag: 9594760d-8801-4d1b-aeb9-f3b3166b5be2
+@end ignore

--- a/lispref/vol2.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/vol2.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -1017,3 +1017,7 @@
 
 
 These words prevent "local variables" above from confusing Emacs.
+
+@ignore
+   arch-tag: dfdbecf8-fec2-49c1-8427-3e8ac8b0b849
+@end ignore

--- a/lispref/windows.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/windows.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -18,7 +18,7 @@
 * Selecting Windows::       The selected window is the one that you edit in.
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
-* Displaying Buffers::      Higher-lever functions for displaying a buffer
+* Displaying Buffers::      Higher-level functions for displaying a buffer
                               and choosing a window for it.
 * Choosing Window::	    How to choose a window for displaying a buffer.
 * Window Point::            Each window has its own location of point.
@@ -97,6 +97,15 @@
 
 @item
 how recently the window was selected
+
+@item
+fringe settings
+
+@item
+display margins
+
+@item
+scroll-bar settings
 @end itemize
 
 @cindex multiple windows
@@ -149,6 +158,7 @@
 window @var{window} remains the selected window, but occupies only
 part of its former screen area.  The rest is occupied by a newly created
 window which is returned as the value of this function.
+This function returns the newly created window.
 
 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
 two side by side windows.  The original window @var{window} keeps the
@@ -291,8 +301,7 @@
 This function returns non-@code{nil} if there is only one window.  The
 argument @var{no-mini}, if non-@code{nil}, means don't count the
 minibuffer even if it is active; otherwise, the minibuffer window is
-included, if active, in the total number of windows, which is compared
-against one.
+counted when it is active.
 
 The argument @var{all-frames} specifies which frames to consider.  Here
 are the possible values and their meanings:
@@ -422,7 +431,7 @@
 @end defun
 
 @defmac save-selected-window forms@dots{}
-This macro records the selected window of eac frame, executes
+This macro records the selected window of each frame, executes
 @var{forms} in sequence, then restores the earlier selected windows.
 
 This macro does not save or restore anything about the sizes,
@@ -446,7 +455,8 @@
 
 @defun get-lru-window &optional frame
 This function returns the window least recently ``used'' (that is,
-selected).  The selected window is always the most recently used window.
+selected).  If any full-width windows are present, it only considers
+these.  The selected window is always the most recently used window.
 
 The selected window can be the least recently used window if it is the
 only window.  A newly created window becomes the least recently used
@@ -558,6 +568,9 @@
 @item 0
 Consider all windows in all visible or iconified frames.
 
+@item a frame
+Consider all windows on that frame.
+
 @item anything else
 Consider precisely the windows in @var{window}'s frame, and no others.
 @end table
@@ -643,7 +656,7 @@
 employ heuristics in choosing or creating a window; use these functions
 when you need complete control.
 
-@defun set-window-buffer window buffer-or-name
+@defun set-window-buffer window buffer-or-name &optional keep-margins
 This function makes @var{window} display @var{buffer-or-name} as its
 contents.  It returns @code{nil}.  This is the fundamental primitive
 for changing which buffer is displayed in a window, and all ways
@@ -655,6 +668,12 @@
      @result{} nil
 @end group
 @end example
+
+Normally, displaying @var{buffer} in @var{window} resets the window's
+display margins, fringe widths, scroll bar settings, and position
+based on the local variables of @var{buffer}.  However, if
+@var{keep-margins} is non-@code{nil}, the display margins and fringe
+widths of @var{window} remain unchanged.  @xref{Fringes}.
 @end defun
 
 @defun window-buffer &optional window
@@ -702,21 +721,6 @@
 like the single optional argument of @code{get-buffer-window}.  Perhaps
 we should change @code{get-buffer-window} in the future to make it
 compatible with the other functions.
-
-The argument @var{all-frames} controls which windows to consider.
-
-@itemize @bullet
-@item
-If it is @code{nil}, consider windows on the selected frame.
-@item
-If it is @code{t}, consider windows on all frames.
-@item
-If it is @code{visible}, consider windows on all visible frames.
-@item
-If it is 0, consider windows on all visible or iconified frames.
-@item
-If it is a frame, consider windows on that frame.
-@end itemize
 @end defun
 
 @defvar buffer-display-time
@@ -800,6 +804,8 @@
 switches to it in some window, preferably not the window previously
 selected.  The ``popped-to'' window becomes the selected window within
 its frame.  The return value is the buffer that was switched to.
+If @var{buffer-or-name} is @code{nil}, that means to choose some
+other buffer, but you don't specify which.
 
 If the variable @code{pop-up-frames} is non-@code{nil},
 @code{pop-to-buffer} looks for a window in any visible frame already
@@ -943,7 +949,7 @@
 @end defopt
 
 @c Emacs 19 feature
-@defvar pop-up-frame-function
+@defopt pop-up-frame-function
 This variable specifies how to make a new frame if @code{pop-up-frames}
 is non-@code{nil}.
 
@@ -952,7 +958,7 @@
 function, which should return a frame.  The default value of the
 variable is a function that creates a frame using parameters from
 @code{pop-up-frame-alist}.
-@end defvar
+@end defopt
 
 @defopt pop-up-frame-alist
 This variable holds an alist specifying frame parameters used when
@@ -984,6 +990,14 @@
 @noindent
 specifies to display a buffer named @samp{myfile} in a dedicated frame
 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
+
+The list of frame parameters can also use the phony frame parameters
+@code{same-frame} and @code{same-window}.  If the specified frame
+parameters include @code{(same-window . @var{value})} and @var{value}
+is non-@code{nil}, that means to display the buffer in the current
+selected window.  Otherwise, if they include @code{(same-frame .
+@var{value})} and @var{value} is non-@code{nil}, that means to display
+the buffer in a new window in the currently selected frame.
 @end defopt
 
 @defopt special-display-regexps
@@ -999,6 +1013,14 @@
 create the frame.  See above, under @code{special-display-buffer-names}.
 @end defopt
 
+@defun special-display-p buffer-name
+This function returns non-@code{nil} if displaying a buffer
+named @var{buffer-name} with @code{display-buffer} would
+create a special frame.  The value is @code{t} if it would
+use the default frame paramaters, or else the specified list
+of frame parameters.
+@end defun
+
 @defvar special-display-function
 This variable holds the function to call to display a buffer specially.
 It receives the buffer as an argument, and should return the window in
@@ -1047,6 +1069,12 @@
 buffer by switching to it in the selected window.
 @end defopt
 
+@defun same-window-p buffer-name
+This function returns @code{t} if displaying a buffer
+named @var{buffer-name} with @code{display-buffer} would
+put it in the selected window.
+@end defun
+
 @c Emacs 19 feature
 @defvar display-buffer-function
 This variable is the most flexible way to customize the behavior of
@@ -1067,8 +1095,8 @@
 other buffer.
 
 @defun window-dedicated-p window
-This function returns @code{t} if @var{window} is marked as dedicated;
-otherwise @code{nil}.
+This function returns non-@code{nil} if @var{window} is marked as
+dedicated; otherwise @code{nil}.
 @end defun
 
 @defun set-window-dedicated-p window flag
@@ -1322,7 +1350,8 @@
 is @code{next-screen-context-lines} lines less than the usable height of
 the window (not counting its mode line).
 
-@code{scroll-up} returns @code{nil}.
+@code{scroll-up} returns @code{nil}, unless it gets an error
+because it can't scroll any further.
 @end deffn
 
 @deffn Command scroll-down &optional count
@@ -1334,7 +1363,8 @@
 is @code{next-screen-context-lines} lines less than the usable height of
 the window (not counting its mode line).
 
-@code{scroll-down} returns @code{nil}.
+@code{scroll-down} returns @code{nil}, unless it gets an error because
+it can't scroll any further.
 @end deffn
 
 @deffn Command scroll-other-window &optional count
@@ -1568,12 +1598,12 @@
 left edge.
 
 @vindex auto-hscroll-mode
-  In Emacs 21, redisplay automatically alters the horizontal scrolling
-of a window as necessary to ensure that point is always visible, if
-@code{auto-hscroll-mode} is set.  However, you can still set the
-horizontal scrolling value explicitly.  The value you specify serves as
-a lower bound for automatic scrolling, i.e. automatic scrolling
-will not scroll a window to a column less than the specified one.
+  If @code{auto-hscroll-mode} is set, redisplay automatically alters
+the horizontal scrolling of a window as necessary to ensure that point
+is always visible.  However, you can still set the horizontal
+scrolling value explicitly.  The value you specify serves as a lower
+bound for automatic scrolling, i.e. automatic scrolling will not
+scroll a window to a column less than the specified one.
 
 @deffn Command scroll-left &optional count
 This function scrolls the selected window @var{count} columns to the
@@ -1626,10 +1656,11 @@
 @end defun
 
 @defun set-window-hscroll window columns
-This function sets the number of columns from the left margin that
-@var{window} is scrolled from the value of @var{columns}.  The argument
-@var{columns} should be zero or positive; if not, it is taken as zero.
-Fractional values of @var{columns} are not supported at present.
+This function sets horizontal scrolling of @var{window}.  The value of
+@var{columns} specifies the amount of scrolling, in terms of columns
+from the left margin.  The argument @var{columns} should be zero or
+positive; if not, it is taken as zero.  Fractional values of
+@var{columns} are not supported at present.
 
 Note that @code{set-window-hscroll} may appear not to work if you test
 it by evaluating a call with @kbd{M-:} in a simple way.  What happens
@@ -1680,9 +1711,8 @@
 @defun window-height &optional window
 This function returns the number of lines in @var{window}, including
 its mode line and header line, if any.  If @var{window} fills its
-entire frame except for the echo area, and there is no tool bar, this
-is typically one less than the value of @code{frame-height} on that
-frame.
+entire frame except for the echo area, this is typically one less than
+the value of @code{frame-height} on that frame.
 
 If @var{window} is @code{nil}, the function uses the selected window.
 
@@ -2007,6 +2037,14 @@
 have a scroll bar; positions in a scroll bar are considered outside the
 window for these purposes.
 
+@item left-fringe
+@itemx right-fringe
+The coordinates are in the left or right fringe of the window.
+
+@item left-margin
+@itemx right-margin
+The coordinates are in the left or right margin of the window.
+
 @item nil
 The coordinates are not in any part of @var{window}.
 @end table
@@ -2023,7 +2061,8 @@
   A @dfn{window configuration} records the entire layout of one
 frame---all windows, their sizes, which buffers they contain, what
 part of each buffer is displayed, and the values of point and the
-mark.  It also includes the values of @code{window-min-height},
+mark; also their fringes, margins, and scroll bar settings.  It also
+includes the values of @code{window-min-height},
 @code{window-min-width} and @code{minibuffer-scroll-window}.  An
 exception is made for point in the selected window for the current
 buffer; its value is not saved in the window configuration.
@@ -2124,10 +2163,15 @@
 saved point or mark.
 @end defun
 
-  Primitives to look inside of window configurations would make sense,
-but none are implemented.  It is not clear they are useful enough to
-be worth implementing.  See the file @file{winner.el} for some more
-operations on windows configurations.
+@defun window-configuration-frame config
+This function returns the frame for which the window configuration
+@var{config} was made.
+@end defun
+
+  Other primitives to look inside of window configurations would make
+sense, but are not implemented because we did not need them.  See the
+file @file{winner.el} for some more operations on windows
+configurations.
 
 @node Window Hooks
 @section Hooks for Window Scrolling and Changes
@@ -2202,3 +2246,7 @@
 window.  The frame whose window configuration has changed is the
 selected frame when this hook runs.
 @end defvar
+
+@ignore
+   arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
+@end ignore