Merge from trunk

20 files changed, 570 insertions, 126 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index fe64ca9d835..e3df5fab9e9 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,72 @@
+2010-09-11  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * syntax.texi (Syntax Flags): Document new `c' flag.
+
+2010-09-09  Glenn Morris  <rgm@gnu.org>
+
+        * display.texi (ImageMagick Images): General cleanup.
+
+2010-09-06  Alexander Klimov  <alserkli@inbox.ru>  (tiny change)
+
+        * files.texi (Directory Names): Use \` rather than ^.
+
+2010-09-02  Jan Djärv  <jan.h.d@swipnet.se>
+
+        * text.texi (Low-Level Kill Ring):
+        * frames.texi (Window System Selections): Remove cut buffer
+        documentation.
+
+2010-08-28  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Fringe Size/Pos): Add a cross-reference to "Layout
+        Parameters", where the default fringe width is described.
+
+        * frames.texi (Window Frame Parameters, Basic Parameters)
+        (Position Parameters, Layout Parameters, Management Parameters)
+        (Cursor Parameters, Font and Color Parameters): Add indexing for
+        frame parameters.  (Bug#6929)
+
+2010-08-25  Tom Tromey  <tromey@redhat.com>
+
+        * vol2.texi (Top): Update.
+        * vol1.texi (Top): Update.
+        * tips.texi (Library Headers): Mention Package-Version and
+        Package-Requires.
+        * package.texi: New file.
+        * os.texi (System Interface): Update pointers.
+        * elisp.texi (Top): Link to new nodes.  Include package.texi.
+        * anti.texi (Antinews): Update pointers.
+
+2010-08-25  Eli Zaretskii  <eliz@gnu.org>
+
+        * processes.texi (Filter Functions): Fix last change.
+
+2010-08-24  Markus Triska  <triska@gmx.at>
+
+        * processes.texi (Filter Functions): Use `buffer-live-p' instead
+        of `buffer-name' in the main text as well as in the example
+        (Bug#3098).
+
+2010-08-22  Chong Yidong  <cyd@stupidchicken.com>
+
+        * nonascii.texi (Text Representations):
+        * loading.texi (Loading Non-ASCII):
+        * compile.texi (Byte Compilation): Don't mention obsolete
+        --unibyte command-line argument.
+
+2010-08-22  Chong Yidong  <cyd@stupidchicken.com>
+
+        * modes.texi (Defining Minor Modes): Doc fix (Bug#6880).
+
+2010-08-22  Chong Yidong  <cyd@stupidchicken.com>
+
+        * objects.texi (Bool-Vector Type): Minor definition tweak (Bug#6878).
+
+2010-08-20  Eli Zaretskii  <eliz@gnu.org>
+
+        * commands.texi (Misc Events): Add cross-references to where
+        POSITION of a mouse event is described in detail.
+
 2010-08-08  Christoph  <cschol2112@googlemail.com>
 
         * control.texi (Handling Errors) <error-message-string>: Fix arg name.
diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi
index 11b8220d290..92e0432b842 100644
--- a/doc/lispref/anti.texi
+++ b/doc/lispref/anti.texi
@@ -6,7 +6,7 @@
 
 @c This node must have no pointers.
 
-@node Antinews, GNU Free Documentation License, System Interface, Top
+@node Antinews, GNU Free Documentation License, Packaging, Top
 @appendix Emacs 22 Antinews
 @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries
 @c with the above version number.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index d22cfd955cb..17cfcc0def8 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1616,7 +1616,8 @@ These kinds of event are generated by moving a mouse wheel.  Their
 usual meaning is a kind of scroll or zoom.
 
 The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event.
+event, in the same format as used in a mouse-click event (@pxref{Click
+Events}).
 
 @vindex mouse-wheel-up-event
 @vindex mouse-wheel-down-event
@@ -1633,9 +1634,10 @@ selected in an application outside of Emacs, and then dragged and
 dropped onto an Emacs frame.
 
 The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event, and
-@var{files} is the list of file names that were dragged and dropped.
-The usual way to handle this event is by visiting these files.
+event, in the same format as used in a mouse-click event (@pxref{Click
+Events}), and @var{files} is the list of file names that were dragged
+and dropped.  The usual way to handle this event is by visiting these
+files.
 
 This kind of event is generated, at present, only on some kinds of
 systems.
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 1c28664e7c3..69b57f19ea7 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -22,12 +22,6 @@ hardware (as true compiled code is), byte-code is completely
 transportable from machine to machine without recompilation.  It is not,
 however, as fast as true compiled code.
 
-  Compiling a Lisp file with the Emacs byte compiler always reads the
-file as multibyte text, even if Emacs was started with @samp{--unibyte},
-unless the file specifies otherwise.  This is so that compilation gives
-results compatible with running the same file without compilation.
-@xref{Loading Non-ASCII}.
-
   In general, any version of Emacs can run byte-compiled code produced
 by recent earlier versions of Emacs, but the reverse is not true.
 
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 9f07fb42ef4..037c334ab88 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3214,7 +3214,9 @@ width from the window's frame.
   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.
+same window, to make the changes take effect.  A buffer that does not
+specify values for these variables will use the default values
+specified for the frame; see @ref{Layout Parameters}.
 
 @defun set-window-fringes window left &optional right outside-margins
 This function sets the fringe widths of window @var{window}.
@@ -4039,6 +4041,7 @@ displayed (@pxref{Display Feature Testing}).
 * GIF Images::          Special features for GIF format.
 * TIFF Images::         Special features for TIFF format.
 * PostScript Images::   Special features for PostScript format.
+* ImageMagick Images::  Special features available through ImageMagick.
 * Other Image Types::   Various other formats are supported.
 * Defining Images::     Convenient ways to define an image for later use.
 * Showing Images::      Convenient ways to display an image once it is defined.
@@ -4463,6 +4466,60 @@ specifying the bounding box of the PostScript image, analogous to the
 @end example
 @end table
 
+@node ImageMagick Images
+@subsection ImageMagick Images
+@cindex ImageMagick images
+@cindex images, support for more formats
+
+  If you build Emacs with ImageMagick (@url{http://www.imagemagick.org})
+support, you can use the ImageMagick library to load many image formats.
+
+@findex imagemagick-types
+The function @code{imagemagick-types} returns a list of image file
+extensions that your installation of ImageMagick supports.  To enable
+support, you must call the function @code{imagemagick-register-types}.
+
+@vindex imagemagick-types-inhibit
+The variable @code{imagemagick-types-inhibit} specifies a list of
+image types that you do @emph{not} want ImageMagick to handle.  There
+may be overlap between image loaders in your Emacs installation, and
+you may prefer to use a different one for a given image type (which
+@c FIXME how is this priority determined?
+loader will be used in practice depends on the priority of the loaders).
+@c FIXME why are these uppercase when image-types is lower-case?
+@c FIXME what are the possibe options?  Are these actually file extensions?
+For example, if you never want to use the ImageMagick loader to use
+JPEG files, add @code{JPG} to this list.
+
+@vindex imagemagick-render-type
+You can set the variable @code{imagemagick-render-type} to choose
+between screen render methods for the ImageMagick loader.  The options
+are: @code{0}, a conservative method which works with older
+@c FIXME details of this "newer method"?
+@c Presumably it is faster but may be less "robust"?
+ImageMagick versions (it is a bit slow, but robust); and @code{1},
+a newer ImageMagick method.
+
+Images loaded with ImageMagick support a few new display specifications:
+
+@table @code
+@item :width, :height
+The @code{:width} and @code{:height} keywords are used for scaling the
+image.  If only one of them is specified, the other one will be
+calculated so as to preserve the aspect ratio.  If both are specified,
+aspect ratio may not be preserved.
+
+@item :rotation
+Specifies a rotation angle in degrees.
+
+@item :index
+Specifies which image to view inside an image bundle file format, such
+as TIFF or DJVM.  You can use the @code{image-metadata} function to
+retrieve the total number of images in an image bundle (this is
+similar to how GIF files work).
+@end table
+
+
 @node Other Image Types
 @subsection Other Image Types
 @cindex PBM
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 30f085f69de..7f0a2ff5a37 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -159,6 +159,8 @@ Cover art by Etienne Suvasa.
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1395,6 +1397,12 @@ Operating System Interface
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
@@ -1491,6 +1499,8 @@ Object Internals
 @include display.texi
 @include os.texi
 
+@include package.texi
+
 @c MOVE to Emacs Manual:  include misc-modes.texi
 
 @c appendices
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index abdd2814b56..23fd2376a57 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1933,7 +1933,7 @@ The variable @code{directory-abbrev-alist} contains an alist of
 abbreviations to use for file directories.  Each element has the form
 @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{^}.
+actually a regular expression; it should always start with @samp{\`}.
 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.
@@ -1946,9 +1946,9 @@ and so on are normally accessed through symbolic links named @file{/fsf}
 and so on.
 
 @example
-(("^/home/fsf" . "/fsf")
- ("^/home/gp" . "/gp")
- ("^/home/gd" . "/gd"))
+(("\\`/home/fsf" . "/fsf")
+ ("\\`/home/gp" . "/gp")
+ ("\\`/home/gd" . "/gd"))
 @end example
 @end defopt
 
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index a54a65b0743..d27010d2096 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -461,6 +461,7 @@ Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
 
 @node Window Frame Parameters
 @subsection Window Frame Parameters
+@cindex frame parameters for windowed displays
 
   Just what parameters a frame has depends on what display mechanism
 it uses.  This section describes the parameters that have special
@@ -489,16 +490,19 @@ terminal frames.
 frame.  @code{title} and @code{name} are meaningful on all terminals.
 
 @table @code
+@vindex display, a frame parameter
 @item display
 The display on which to open this frame.  It should be a string of the
 form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
 @code{DISPLAY} environment variable.
 
+@vindex display-type, a frame parameter
 @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
 @code{mono}.
 
+@vindex title, a frame parameter
 @item title
 If a frame has a non-@code{nil} title, it appears in the window
 system's title bar at the top of the frame, and also in the mode line
@@ -507,6 +511,7 @@ of windows in that frame if @code{mode-line-frame-identification} uses
 Emacs is not using a window system, and can only display one frame at
 a time.  @xref{Frame Titles}.
 
+@vindex name, a frame parameter
 @item name
 The name of the frame.  The frame name serves as a default for the frame
 title, if the @code{title} parameter is unspecified or @code{nil}.  If
@@ -520,11 +525,13 @@ looking up X resources for the frame.
 
 @node Position Parameters
 @subsubsection Position Parameters
+@cindex window position on display
 
   Position parameters' values are normally measured in pixels, but on
 text-only terminals they count characters or lines instead.
 
 @table @code
+@vindex left, a frame parameter
 @item left
 The position, in pixels, of the left (or right) edge of the frame with
 respect to the left (or right) edge of the screen.  The value may be:
@@ -550,11 +557,13 @@ Some window managers ignore program-specified positions.  If you want to
 be sure the position you specify is not ignored, specify a
 non-@code{nil} value for the @code{user-position} parameter as well.
 
+@vindex top, a frame parameter
 @item top
 The screen position of the top (or bottom) edge, in pixels, with respect
 to the top (or bottom) edge of the screen.  It works just like
 @code{left}, except vertically instead of horizontally.
 
+@vindex icon-left, a frame parameter
 @item icon-left
 The screen position of the left edge @emph{of the frame's icon}, in
 pixels, counting from the left edge of the screen.  This takes effect if
@@ -564,11 +573,13 @@ If you specify a value for this parameter, then you must also specify
 a value for @code{icon-top} and vice versa.  The window manager may
 ignore these two parameters.
 
+@vindex icon-top, a frame parameter
 @item icon-top
 The screen position of the top edge @emph{of the frame's icon}, in
 pixels, counting from the top edge of the screen.  This takes effect if
 and when the frame is iconified.
 
+@vindex user-position, a frame parameter
 @item user-position
 When you create a frame and specify its screen position with the
 @code{left} and @code{top} parameters, use this parameter to say whether
@@ -576,6 +587,7 @@ the specified position was user-specified (explicitly requested in some
 way by a human user) or merely program-specified (chosen by a program).
 A non-@code{nil} value says the position was user-specified.
 
+@cindex window positions and window managers
 Window managers generally heed user-specified positions, and some heed
 program-specified positions too.  But many ignore program-specified
 positions, placing the window in a default fashion or letting the user
@@ -591,24 +603,31 @@ parameters represent the user's stated preference; otherwise, use
 
 @node Size Parameters
 @subsubsection Size Parameters
+@cindex window size on display
 
   Size parameters' values are normally measured in pixels, but on
 text-only terminals they count characters or lines instead.
 
 @table @code
+@vindex height, a frame parameter
 @item height
 The height of the frame contents, in characters.  (To get the height in
 pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
 
+@vindex width, a frame parameter
 @item width
 The width of the frame contents, in characters.  (To get the width in
 pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
 
+@vindex user-size, a frame parameter
 @item user-size
 This does for the size parameters @code{height} and @code{width} what
-the @code{user-position} parameter (see above) does for the position
-parameters @code{top} and @code{left}.
+the @code{user-position} parameter (@pxref{Position Parameters,
+user-position}) does for the position parameters @code{top} and
+@code{left}.
 
+@cindex full-screen frames
+@vindex fullscreen, a frame parameter
 @item fullscreen
 Specify that width, height or both shall be maximized.  The value
 @code{fullwidth} specifies that width shall be as wide as possible.
@@ -623,33 +642,42 @@ covers the whole screen.
 
 @node Layout Parameters
 @subsubsection Layout Parameters
+@cindex layout parameters of frames
+@cindex frame layout parameters
 
   These frame parameters enable or disable various parts of the
 frame, or control their sizes.
 
 @table @code
+@vindex border-width, a frame parameter
 @item border-width
 The width in pixels of the frame's border.
 
+@vindex internal-border-width, a frame parameter
 @item internal-border-width
 The distance in pixels between text (or fringe) and the frame's border.
 
+@vindex vertical-scroll-bars, a frame parameter
 @item vertical-scroll-bars
 Whether the frame has scroll bars for vertical scrolling, and which side
 of the frame they should be on.  The possible values are @code{left},
 @code{right}, and @code{nil} for no scroll bars.
 
 @ignore
+@vindex horizontal-scroll-bars, a frame parameter
 @item horizontal-scroll-bars
 Whether the frame has scroll bars for horizontal scrolling
 (non-@code{nil} means yes).  Horizontal scroll bars are not currently
 implemented.
 @end ignore
 
+@vindex scroll-bar-width, a frame parameter
 @item scroll-bar-width
 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
 use the default width.
 
+@vindex left-fringe, a frame parameter
+@vindex right-fringe, a frame parameter
 @item left-fringe
 @itemx right-fringe
 The default width of the left and right fringes of windows in this
@@ -666,22 +694,26 @@ fringe.  However, you can force one fringe or the other to a precise
 width by specifying that width as a negative integer.  If both widths are
 negative, only the left fringe gets the specified width.
 
+@vindex menu-bar-lines, a frame parameter
 @item menu-bar-lines
 The number of lines to allocate at the top of the frame for a menu
 bar.  The default is 1.  A value of @code{nil} means don't display a
 menu bar.  @xref{Menu Bar}.  (The X toolkit and GTK allow at most one
 menu bar line; they treat larger values as 1.)
 
+@vindex tool-bar-lines, a frame parameter
 @item tool-bar-lines
 The number of lines to use for the tool bar.  A value of @code{nil}
 means don't display a tool bar.  (GTK and Nextstep allow at most one
 tool bar line; they treat larger values as 1.)
 
+@vindex tool-bar-position, a frame parameter
 @item tool-bar-position
 The position of the tool bar.  Currently only for the GTK tool bar.
 Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
 The default is  @code{top}.
 
+@vindex line-spacing, a frame parameter
 @item line-spacing
 Additional space to leave below each text line, in pixels (a positive
 integer).  @xref{Line Height}, for more information.
@@ -694,6 +726,7 @@ integer).  @xref{Line Height}, for more information.
 with which buffers have been, or should, be displayed in the frame.
 
 @table @code
+@vindex minibuffer, a frame parameter
 @item minibuffer
 Whether this frame has its own minibuffer.  The value @code{t} means
 yes, @code{nil} means no, @code{only} means this frame is just a
@@ -703,6 +736,7 @@ frame), the frame uses that minibuffer.
 This frame parameter takes effect when the frame is created, and can
 not be changed afterwards.
 
+@vindex buffer-predicate, a frame parameter
 @item buffer-predicate
 The buffer-predicate function for this frame.  The function
 @code{other-buffer} uses this predicate (from the selected frame) to
@@ -711,61 +745,73 @@ decide which buffers it should consider, if the predicate is not
 each buffer; if the predicate returns a non-@code{nil} value, it
 considers that buffer.
 
+@vindex buffer-list, a frame parameter
 @item buffer-list
-A list of buffers that have been selected in this frame,
-ordered most-recently-selected first.
+A list of buffers that have been selected in this frame, ordered
+most-recently-selected first.
 
+@vindex unsplittable, a frame parameter
 @item unsplittable
 If non-@code{nil}, this frame's window is never split automatically.
 @end table
 
 @node Management Parameters
 @subsubsection Window Management Parameters
-@cindex window manager, and frame parameters
+@cindex window manager interaction, and frame parameters
 
   These frame parameters, meaningful only on window system displays,
 interact with the window manager.
 
 @table @code
+@vindex visibility, a frame parameter
 @item visibility
 The state of visibility of the frame.  There are three possibilities:
 @code{nil} for invisible, @code{t} for visible, and @code{icon} for
 iconified.  @xref{Visibility of Frames}.
 
+@vindex auto-raise, a frame parameter
 @item auto-raise
 Whether selecting the frame raises it (non-@code{nil} means yes).
 
+@vindex auto-lower, a frame parameter
 @item auto-lower
 Whether deselecting the frame lowers it (non-@code{nil} means yes).
 
+@vindex icon-type, a frame parameter
 @item icon-type
 The type of icon to use for this frame when it is iconified.  If the
 value is a string, that specifies a file containing a bitmap to use.
 Any other non-@code{nil} value specifies the default bitmap icon (a
 picture of a gnu); @code{nil} specifies a text icon.
 
+@vindex icon-name, a frame parameter
 @item icon-name
 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.
 
+@vindex window-id, a frame parameter
 @item window-id
 The number of the window-system window used by the frame
 to contain the actual Emacs windows.
 
+@vindex outer-window-id, a frame parameter
 @item outer-window-id
 The number of the outermost window-system window used for the whole frame.
 
+@vindex wait-for-wm, a frame parameter
 @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.
 
+@vindex sticky, a frame parameter
 @item sticky
 If non-@code{nil}, the frame is visible on all virtual desktops on systems
 with virtual desktops.
 
 @ignore
+@vindex parent-id, a frame parameter
 @item parent-id
 @c ??? Not yet working.
 The X window number of the window that should be the parent of this one.
@@ -777,10 +823,12 @@ it and see if it works.)
 
 @node Cursor Parameters
 @subsubsection Cursor Parameters
+@cindex cursor, and frame parameters
 
   This frame parameter controls the way the cursor looks.
 
 @table @code
+@vindex cursor-type, a frame parameter
 @item cursor-type
 How to display the cursor.  Legitimate values are:
 
@@ -832,10 +880,12 @@ and bar becomes a narrower bar).
 
 @node Font and Color Parameters
 @subsubsection Font and Color Parameters
+@cindex font and color, frame parameters
 
   These frame parameters control the use of fonts and colors.
 
 @table @code
+@vindex font-backend, a frame parameter
 @item font-backend
 A list of symbols, specifying the @dfn{font backends} to use for
 drawing fonts in the frame, in order of priority.  On X, there are
@@ -844,10 +894,12 @@ driver) and @code{xft} (the Xft font driver).  On other systems, there
 is only one available font backend, so it does not make sense to
 modify this frame parameter.
 
+@vindex background-mode, a frame parameter
 @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.
 
+@vindex tty-color-mode, a frame parameter
 @item tty-color-mode
 @cindex standard colors for character terminals
 This parameter overrides the terminal's color support as given by the
@@ -863,6 +915,7 @@ If the parameter's value is a symbol, it specifies a number through
 the value of @code{tty-color-mode-alist}, and the associated number is
 used instead.
 
+@vindex screen-gamma, a frame parameter
 @item screen-gamma
 @cindex gamma correction
 If this is a number, Emacs performs ``gamma correction'' which adjusts
@@ -882,6 +935,7 @@ If your monitor displays colors too light, you should specify a
 that makes colors darker.  A screen gamma value of 1.5 may give good
 results for LCD color displays.
 
+@vindex alpha, a frame parameter
 @item alpha
 @cindex opacity, frame
 @cindex transparency, frame
@@ -909,37 +963,45 @@ automatically equivalent to particular face attributes of particular
 faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
 
 @table @code
+@vindex font, a frame parameter
 @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.
 
+@vindex foreground-color, a frame parameter
 @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.
 
+@vindex background-color, a frame parameter
 @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.
 
+@vindex mouse-color, a frame parameter
 @item mouse-color
 The color for the mouse pointer.  It is equivalent to the @code{:background}
 attribute of the @code{mouse} face.
 
+@vindex cursor-color, a frame parameter
 @item cursor-color
 The color for the cursor that shows point.  It is equivalent to the
 @code{:background} attribute of the @code{cursor} face.
 
+@vindex border-color, a frame parameter
 @item border-color
 The color for the border of the frame.  It is equivalent to the
 @code{:background} attribute of the @code{border} face.
 
+@vindex scroll-bar-foreground, a frame parameter
 @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.
 
+@vindex scroll-bar-background, a frame parameter
 @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
@@ -1923,28 +1985,6 @@ with X conventions.)  The default for @var{data-type} is
 @code{STRING}.
 @end defun
 
-@cindex cut buffer
-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.  Cut buffers are numbered from 0 to 7.
-
-@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
-
-@defun x-set-cut-buffer string &optional push
-@anchor{Definition of x-set-cut-buffer}
-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.
-If @var{push} is non-@code{nil}, that says to move the values down
-through the series of cut buffers, much like the way successive kills in
-Emacs move down the kill ring.  In other words, the previous value of
-the first cut buffer moves into the second cut buffer, and the second to
-the third, and so on through all eight cut buffers.
-@end defun
-
 @defopt selection-coding-system
 This variable specifies the coding system to use when reading and
 writing selections or the clipboard.  @xref{Coding
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index bbdd67fc3a5..dee2a0252eb 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -367,13 +367,6 @@ example) is read without decoding, the text of the program will be
 unibyte text, and its string constants will be unibyte strings.
 @xref{Coding Systems}.
 
-  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-@acronym{ASCII} characters translate into multibyte
-strings.  The only exception is when a particular file specifies no
-decoding.
-
   The reason Emacs is designed this way is so that Lisp programs give
 predictable results, regardless of how Emacs was started.  In addition,
 this enables programs that depend on using multibyte text to work even
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 3953da59b93..12f16b67663 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1411,14 +1411,20 @@ The string @var{lighter} says what to display in the mode line
 when the mode is enabled; if it is @code{nil}, the mode is not displayed
 in the mode line.
 
-The optional argument @var{keymap} specifies the keymap for the minor mode.
-It can be a variable name, whose value is the keymap, or it can be an alist
-specifying bindings in this form:
+The optional argument @var{keymap} specifies the keymap for the minor
+mode.  If non-@code{nil}, it should be a variable name (whose value is
+a keymap), a keymap, or an alist of the form
 
 @example
 (@var{key-sequence} . @var{definition})
 @end example
 
+@noindent
+where each @var{key-sequence} and @var{definition} are arguments
+suitable for passing to @code{define-key} (@pxref{Changing Key
+Bindings}).  If @var{keymap} is a keymap or an alist, this also
+defines the variable @code{@var{mode}-map}.
+
 The above three arguments @var{init-value}, @var{lighter}, and
 @var{keymap} can be (partially) omitted when @var{keyword-args} are
 used.  The @var{keyword-args} consist of keywords followed by
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index 00a1dffed6a..40c78d97da7 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -102,9 +102,6 @@ it contains unibyte encoded text or binary non-text data.
 
 You cannot set this variable directly; instead, use the function
 @code{set-buffer-multibyte} to change a buffer's representation.
-
-The @samp{--unibyte} command line option does its job by setting the
-default value to @code{nil} early in startup.
 @end defvar
 
 @defun position-bytes position
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 1a72fdf671c..b0b0e1d0042 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -1189,8 +1189,8 @@ Syntax tables (@pxref{Syntax Tables}).
 @node Bool-Vector Type
 @subsection Bool-Vector Type
 
-  A @dfn{bool-vector} is a one-dimensional array of elements that
-must be @code{t} or @code{nil}.
+  A @dfn{bool-vector} is a one-dimensional array whose elements must
+be @code{t} or @code{nil}.
 
   The printed representation of a bool-vector is like a string, except
 that it begins with @samp{#&} followed by the length.  The string
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 4f37eb10b7a..dd827234272 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -5,7 +5,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/os
-@node System Interface, Antinews, Display, Top
+@node System Interface, Packaging, Display, Top
 @chapter Operating System Interface
 
   This chapter is about starting and getting out of Emacs, access to
diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
new file mode 100644
index 00000000000..138f8d934e6
--- /dev/null
+++ b/doc/lispref/package.texi
@@ -0,0 +1,197 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 2010
+@c   Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../../info/package
+@node Packaging, Antinews, System Interface, Top
+@chapter Preparing Lisp code for distribution
+@cindex packaging
+
+  Emacs provides a standard way for Emacs Lisp code to be distributed
+to users.  This approach lets users easily download, install,
+uninstall, and upgrade Lisp code that they might want to use.
+
+  A @dfn{package} is simply one or more files, formatted and bundled
+in a particular way.  Typically a package includes primarily Emacs
+Lisp code, but it is possible to create other kinds of packages as
+well.
+
+@menu
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+@end menu
+
+@node Packaging Basics
+@section Packaging Basics
+@cindex packaging basics
+
+  A package has a few attributes:
+@cindex package attributes
+
+@table @asis
+@item Name
+A string, the name of the package.  This attribute is mandatory.  If
+it does not exist, the package cannot be installed by the package
+manager.
+
+@item Version
+A version number, which is anything that can be parsed by
+@code{version-to-list}.  This attribute is mandatory.  If it does not
+exist, the package cannot be installed by the package manager.
+
+@item Brief description
+This is shown to the user in the package menu buffer.  It is just a
+single line.  On a terminal with 80 characters per line, there are
+only 36 characters available in the package menu mode for showing the
+brief description, so it is best to keep it very brief.  If no brief
+name is given, an empty string is used.
+
+@item Long description
+This can be a @file{README} file or the like.  This is available to
+the user before the package is installed, via the package menu.  It
+should more fully describe the package and its capabilities, so a user
+can read it to decide whether he wants to install the package.  This
+attribute is optional.
+
+@item Dependencies
+This is a list of other packages and their minimal acceptable
+versions.  This is used both at download time (to make sure all the
+needed code is available) and at activation time (to ensure a package
+is only activated if all its dependencies have been successfully
+activated).  This attribute is optional.
+
+@item Manual
+A package can optionally include an Info manual.
+@end table
+
+  Conceptually, a package goes through several state transitions (in
+reality some of these transitions are grouped together):
+
+@table @asis
+@item Download
+Fetch the package from somewhere.
+
+@item Install
+Unpack the package, or write a @file{.el} file into the appropriate
+install directory.  This step also includes extracting autoloads and
+byte-compiling the Emacs Lisp code.
+
+@item Activate
+Update @code{load-path} and @code{Info-directory-list} and evaluate
+the autoloads, so that the package is ready for the user to use.
+@end table
+
+  It is best for users if packages do not do too much work at
+activation time.  The best approach is to have activation consist of
+some autoloads and little more.
+
+@node Simple Packages
+@section Simple Packages
+@cindex single file packages
+
+  The simplest package consists of a single Emacs Lisp source file.
+In this case, all the attributes of the package (@pxref{Packaging
+Basics}) are taken from this file.
+
+  The package system expects this @file{.el} file to conform to the
+Emacs Lisp library header conventions.  @xref{Library Headers}.
+
+  The name of the package is the same as the base name of the
+@file{.el} file, as written in the first comment line.  For example,
+given the header line:
+
+@smallexample
+;;; superfrobnicator.el --- frobnicate and bifurcate flanges
+@end smallexample
+
+the package name will be @samp{superfrobnicator}.
+
+  The short description of the package is also taken from the first
+line of the file.
+
+  If the file has a ``Commentary'' header, then it is used as the long
+description.
+
+  The version of the package comes either from the ``Package-Version''
+header, if it exists, or from the ``Version'' header.  A package is
+required to have a version number.  Each release of a package must be
+accompanied by an increase in the version number.
+
+  If the file has a ``Package-Requires'' header, then that is used as
+the package dependencies.  Otherwise, the package is assumed not to
+have any dependencies.
+
+  A single-file package cannot have an Info manual.
+
+  The file will be scanned for autoload cookies at install time.
+@xref{Autoload}.
+
+@node Multi-file Packages
+@section Multi-file Packages
+@cindex multi-file packages
+
+  A multi-file package is just a @file{.tar} file.  While less
+convenient to create than a single-file package, a multi-file package
+also offers more features: it can include an Info manual, multiple
+Emacs Lisp files, and also other data files needed by a package.
+
+  The contents of the @file{.tar} file must all appear beneath a
+single directory, named after the package and version.  Files can
+appear in subdirectories of this top-most directory, but Emacs Lisp
+code will only be found (and thus byte-compiled) at the top-most
+level.  Also, the @file{.tar} file is typically also given this same
+name.  For example, if you are distributing version 1.3 of the
+superfrobnicator, the package file would be named
+``superfrobnicator-1.3.tar'' and the contents would all appear in the
+directory @file{superfrobnicator-1.3} in that @file{.tar}.
+
+  The package must include a @file{-pkg.el} file, named after the
+package.  In our example above, this file would be called
+@file{superfrobnicator-pkg.el}.  This file must have a single form in
+it, a call to @code{define-package}.  The package dependencies and
+brief description are taken from this form.
+
+@defun define-package name version &optional docstring requirements
+Define a package.  @var{name} is the name of the package, a string.
+@var{version} is the package's version, a string.  It must be in a
+form that can be understood by @code{version-to-list}.
+@var{docstring} is the short description of the package.
+@var{requirements} is a list of required packages and their versions.
+@end defun
+
+  If a @file{README} file exists in the content directory, then it is
+used as the long description.
+
+  If the package has an Info manual, you should distribute the needed
+info files, plus a @file{dir} file made with @command{install-info}.
+@xref{Invoking install-info, Invoking install-info, Invoking
+install-info, texinfo, Texinfo}.
+
+  Do not include any @file{.elc} files in the package.  Those will be
+created at install time.  Note that there is no way to control the
+order in which files are byte-compiled; your package must be robust
+here.
+
+  The installation process will scan all the @file{.el} files in the
+package for autoload cookies.  @xref{Autoload}.  They are extracted
+into a @file{-autoloads.el} file (e.g.,
+@file{superfrobnicator-autoloads.el}), so do not include a file of
+that name in your package.
+
+  Any other files in the @file{.tar} file are simply unpacked when the
+package is installed.  This can be useful if your package needs
+auxiliary data files --- e.g., icons or sounds.
+
+  Emacs Lisp code installed via the package manager must take special
+care to be location-independent.  One easy way to do this is to make
+references to auxiliary data files relative to @var{load-file-name}.
+For example:
+
+@smallexample
+(defconst superfrobnicator-base (file-name-directory load-file-name))
+
+(defun superfrobnicator-fetch-image (file)
+  (expand-file-name file superfrobnicator-base))
+@end smallexample
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 747d865b0e1..89f97f99de3 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1273,22 +1273,24 @@ process's buffer, mimicking the actions of Emacs when there is no
 filter.  Such filter functions need to use @code{set-buffer} in order to
 be sure to insert in that buffer.  To avoid setting the current buffer
 semipermanently, these filter functions must save and restore the
-current buffer.  They should also update the process marker, and in some
-cases update the value of point.  Here is how to do these things:
+current buffer.  They should also check whether the buffer is still
+alive, update the process marker, and in some cases update the value
+of point.  Here is how to do these things:
 
 @smallexample
 @group
 (defun ordinary-insertion-filter (proc string)
-  (with-current-buffer (process-buffer proc)
-    (let ((moving (= (point) (process-mark proc))))
+  (when (buffer-live-p (process-buffer proc))
+    (with-current-buffer (process-buffer proc)
+      (let ((moving (= (point) (process-mark proc))))
 @end group
 @group
-      (save-excursion
-        ;; @r{Insert the text, advancing the process marker.}
-        (goto-char (process-mark proc))
-        (insert string)
-        (set-marker (process-mark proc) (point)))
-      (if moving (goto-char (process-mark proc))))))
+        (save-excursion
+          ;;  @r{Insert the text, advancing the process marker.}
+          (goto-char (process-mark proc))
+          (insert string)
+          (set-marker (process-mark proc) (point)))
+        (if moving (goto-char (process-mark proc)))))))
 @end group
 @end smallexample
 
@@ -1315,12 +1317,6 @@ expression searching or matching had to explicitly save and restore the
 match data.  Now Emacs does this automatically for filter functions;
 they never need to do it explicitly.  @xref{Match Data}.
 
-  A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive.  If it tries to
-insert into a dead buffer, it will get an error.  The expression
-@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
-if the buffer is dead.
-
   The output to the function may come in chunks of any size.  A program
 that produces the same output twice in a row may send it as one batch of
 200 characters one time, and five batches of 40 characters the next.  If
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 9add9b76e79..a608db16f89 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -292,19 +292,21 @@ identifying them as generic string delimiters.
 @cindex syntax flags
 
   In addition to the classes, entries for characters in a syntax table
-can specify flags.  There are seven possible flags, represented by the
-characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n},
-and @samp{p}.
-
-  All the flags except @samp{n} and @samp{p} are used to describe
-multi-character comment delimiters.  The digit flags indicate that a
-character can @emph{also} be part of a comment sequence, in addition to
-the syntactic properties associated with its character class.  The flags
-are independent of the class and each other for the sake of characters
-such as @samp{*} in C mode, which is a punctuation character, @emph{and}
-the second character of a start-of-comment sequence (@samp{/*}),
-@emph{and} the first character of an end-of-comment sequence
-(@samp{*/}).
+can specify flags.  There are eight possible flags, represented by the
+characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{c},
+@samp{n}, and @samp{p}.
+
+  All the flags except @samp{p} are used to describe comment
+delimiters.  The digit flags are used for comment delimiters made up
+of 2 characters.  They indicate that a character can @emph{also} be
+part of a comment sequence, in addition to the syntactic properties
+associated with its character class.  The flags are independent of the
+class and each other for the sake of characters such as @samp{*} in
+C mode, which is a punctuation character, @emph{and} the second
+character of a start-of-comment sequence (@samp{/*}), @emph{and} the
+first character of an end-of-comment sequence (@samp{*/}).  The flags
+@samp{b}, @samp{c}, and @samp{n} are used to qualify the corresponding
+comment delimiter.
 
   Here is a table of the possible flags for a character @var{c},
 and what they mean:
@@ -325,63 +327,62 @@ sequence.
 @samp{4} means @var{c} is the second character of such a sequence.
 
 @item
-@c Emacs 19 feature
 @samp{b} means that @var{c} as a comment delimiter belongs to the
-alternative ``b'' comment style.
+alternative ``b'' comment style.  For a two-character comment starter,
+this flag is only significant on the second char, and for a 2-character
+comment ender it is only significant on the first char.
 
-Emacs supports two comment styles simultaneously in any one syntax
-table.  This is for the sake of C++.  Each style of comment syntax has
-its own comment-start sequence and its own comment-end sequence.  Each
-comment must stick to one style or the other; thus, if it starts with
-the comment-start sequence of style ``b,'' it must also end with the
-comment-end sequence of style ``b.''
+@item
+@samp{c} means that @var{c} as a comment delimiter belongs to the
+alternative ``c'' comment style.  For a two-character comment
+delimiter, @samp{c} on either character makes it of style ``c''.
 
-The two comment-start sequences must begin with the same character; only
-the second character may differ.  Mark the second character of the
-``b''-style comment-start sequence with the @samp{b} flag.
+@item
+@samp{n} on a comment delimiter character specifies
+that this kind of comment can be nested.  For a two-character
+comment delimiter, @samp{n} on either character makes it
+nestable.
 
-A comment-end sequence (one or two characters) applies to the ``b''
-style if its first character has the @samp{b} flag set; otherwise, it
-applies to the ``a'' style.
+Emacs supports several comment styles simultaneously in any one syntax
+table.  A comment style is a set of flags @samp{b}, @samp{c}, and
+@samp{n}, so there can be up to 8 different comment styles.
+Each comment delimiter has a style and only matches comment delimiters
+of the same style.  Thus if a comment starts with the comment-start
+sequence of style ``bn'', it will extend until the next matching
+comment-end sequence of style ``bn''.
 
-The appropriate comment syntax settings for C++ are as follows:
+The appropriate comment syntax settings for C++ can be as follows:
 
 @table @asis
 @item @samp{/}
-@samp{124b}
+@samp{124}
 @item @samp{*}
-@samp{23}
+@samp{23b}
 @item newline
-@samp{>b}
+@samp{>}
 @end table
 
 This defines four comment-delimiting sequences:
 
 @table @asis
 @item @samp{/*}
-This is a comment-start sequence for ``a'' style because the
-second character, @samp{*}, does not have the @samp{b} flag.
+This is a comment-start sequence for ``b'' style because the
+second character, @samp{*}, has the @samp{b} flag.
 
 @item @samp{//}
-This is a comment-start sequence for ``b'' style because the second
-character, @samp{/}, does have the @samp{b} flag.
+This is a comment-start sequence for ``a'' style because the second
+character, @samp{/}, does not have the @samp{b} flag.
 
 @item @samp{*/}
-This is a comment-end sequence for ``a'' style because the first
-character, @samp{*}, does not have the @samp{b} flag.
+This is a comment-end sequence for ``b'' style because the first
+character, @samp{*}, does have the @samp{b} flag.
 
 @item newline
-This is a comment-end sequence for ``b'' style, because the newline
-character has the @samp{b} flag.
+This is a comment-end sequence for ``a'' style, because the newline
+character does not have the @samp{b} flag.
 @end table
 
 @item
-@samp{n} on a comment delimiter character specifies
-that this kind of comment can be nested.  For a two-character
-comment delimiter, @samp{n} on either character makes it
-nestable.
-
-@item
 @c Emacs 19 feature
 @samp{p} identifies an additional ``prefix character'' for Lisp syntax.
 These characters are treated as whitespace when they appear between
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index a7c4a3e62f4..ff4e65d299f 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -59,6 +59,7 @@ the character after point.
                        position stored in a register.
 * Base 64::          Conversion to or from base 64 encoding.
 * MD5 Checksum::     Compute the MD5 "message digest"/"checksum".
+* Parsing HTML::     Parsing HTML and XML.
 * Atomic Changes::   Installing several buffer changes "atomically".
 * Change Hooks::     Supplying functions to be run when text is changed.
 @end menu
@@ -1126,16 +1127,13 @@ use @code{string=} to compare it with the last text Emacs provided.)
 @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 required and one optional argument.
+@code{nil} or a function of one required 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 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.
+it with the new first element of the kill ring as the argument.
 
 The normal use of this function is to set the window system's primary
-selection (and first cut buffer) from the newly killed text.
+selection from the newly killed text.
 @xref{Window System Selections}.
 @end defvar
 
@@ -4109,6 +4107,49 @@ using the specified or chosen coding system.  However, if
 coding instead.
 @end defun
 
+@node Parsing HTML
+@section Parsing HTML
+@cindex parsing html
+@cindex parsing xml
+
+Emacs provides an interface to the @code{libxml2} library via two
+functions: @code{html-parse-buffer} and @code{xml-parse-buffer}.  The
+HTML function will parse ``real world'' HTML and try to return a
+sensible parse tree, while the XML function is somewhat stricter about
+syntax.
+
+They both take a two optional parameter.  The first is a buffer, and
+the second is a base URL to be used to expand relative URLs in the
+document, if any.
+
+Here's an example demonstrating the structure of the parsed data you
+get out.  Given this HTML document:
+
+@example
+<html><hEad></head><body width=101><div class=thing>Foo<div>Yes
+@end example
+
+You get this parse tree:
+
+@example
+(html
+ (head)
+ (body
+  (:width . "101")
+  (div
+   (:class . "thing")
+   (text . "Foo")
+   (div
+    (text . "Yes\n")))))
+@end example
+
+It's a simple tree structure, where the @code{car} for each node is
+the name of the node, and the @code{cdr} is the value, or the list of
+values.
+
+Attributes are coded the same way as child nodes, but with @samp{:} as
+the first character.
+
 @node Atomic Changes
 @section Atomic Change Groups
 @cindex atomic changes
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index de281b0e147..bf3afcf53ee 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -1052,6 +1052,31 @@ Please use that command to see a list of the meaningful keywords.
 This field is important; it's how people will find your package when
 they're looking for things by topic area.  To separate the keywords, you
 can use spaces, commas, or both.
+
+@item Package-Version
+If @samp{Version} is not suitable for use by the package manager, then
+a package can define @samp{Package-Version}; it will be used instead.
+This is handy if @samp{Version} is an RCS id or something else that
+cannot be parsed by @code{version-to-list}.  @xref{Packaging Basics}.
+
+@item Package-Requires
+If this exists, it names packages on which the current package depends
+for proper operation.  @xref{Packaging Basics}.  This is used by the
+package manager both at download time (to ensure that a complete set
+of packages is downloaded) and at activation time (to ensure that a
+package is activated if and only if all its dependencies have been).
+
+Its format is a list of lists.  The @code{car} of each sub-list is the
+name of a package, as a symbol.  The @code{cadr} of each sub-list is
+the minimum acceptable version number, as a string.  For instance:
+
+@smallexample
+;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2"))
+@end smallexample
+
+The package code automatically defines a package named @samp{emacs}
+with the version number of the currently running Emacs.  This can be
+used to require a minimal version of Emacs for a package.
 @end table
 
   Just about every Lisp library ought to have the @samp{Author} and
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 4c0ae27c043..cbc26ebcec6 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -180,6 +180,8 @@ Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1415,6 +1417,12 @@ Operating System Interface
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 195b89ce3f6..44052e5bd5d 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -179,6 +179,8 @@ Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
 * System Interface::        Getting the user id, system type, environment
                               variables, and other such things.
 
+* Packaging::               Preparing Lisp code for distribution.
+
 Appendices
 
 * Antinews::                Info for users downgrading to Emacs 22.
@@ -1414,6 +1416,12 @@ Operating System Interface
 * Session Management::      Saving and restoring state with
                               X Session Management.
 
+Preparing Lisp code for distribution
+
+* Packaging Basics::        The basic concepts of Emacs Lisp packages.
+* Simple Packages::         How to package a single .el file.
+* Multi-file Packages::     How to package multiple files.
+
 Starting Up Emacs
 
 * Startup Summary::         Sequence of actions Emacs performs at startup.