-

5 files changed, 193 insertions, 60 deletions

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 6fa802d9fdd..3f48c458c02 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -304,15 +304,15 @@ is useful to select alternatives based on more general conditions that
 distinguish between broad classes of values.  The @code{pcase} macro
 allows you to choose between alternatives based on matching the value
 of an expression against a series of patterns.  A pattern can be a
-literal value (comparison to literal values is what @code{cond} does),
-or it can be a more general description of the expected structure of
-the expression's value.
+literal value (for comparisons to literal values you'd use
+@code{cond}), or it can be a more general description of the expected
+structure of the expression's value.
 
 @defmac pcase expression &rest clauses
 Evaluate @var{expression} and choose among an arbitrary number of
 alternatives based on the value of @var{expression}.  The possible
 alternatives are specified by @var{clauses}, each of which must be a
-list of the form @code{(@var{pattern} @var{body-forms})}.
+list of the form @code{(@var{pattern} @var{body-forms}@dots{})}.
 @code{pcase} tries to match the value of @var{expression} to the
 @var{pattern} of each clause, in textual order.  If the value matches,
 the clause succeeds; @code{pcase} then evaluates its @var{body-forms},
@@ -328,7 +328,7 @@ Note: In the description of the patterns below, we use ``the value
 being matched'' to refer to the value of the @var{expression} that is
 the first argument of @code{pcase}.
 
-A UPattern can have one of the following forms:
+A UPattern can have the following forms:
 
 @table @code
 
@@ -337,7 +337,8 @@ Matches if the value being matched is @code{equal} to @var{val}.
 @item @var{atom}
 Matches any @var{atom}, which can be a keyword, a number, or a string.
 (These are self-quoting, so this kind of UPattern is actually a
-shorthand for @code{'@var{atom}}.)
+shorthand for @code{'@var{atom}}.)  Note that a string or a float
+matches any string or float with the same contents/value.
 @item _
 Matches any value.  This is known as @dfn{don't care} or @dfn{wildcard}.
 @item @var{symbol}
@@ -362,7 +363,8 @@ Matches if the specified @var{expression} matches the specified
 an @emph{arbitrary} expression, not just the expression that is the
 first argument to @code{pcase}.  (It is called @code{let} because
 @var{upattern} can bind symbols to values using the @var{symbol}
-UPattern.)
+UPattern.  For example:
+@w{@code{((or `(key . ,val) (let val 5)) val)}}.)
 @item (app @var{function} @var{upattern})
 Matches if @var{function} applied to the value being matched returns a
 value that matches @var{upattern}.  This is like the @code{pred}
@@ -407,24 +409,27 @@ Here's an illustrative example of using UPatterns:
   (code           (message "Unknown return code %S" code)))
 @end example
 
-The QPatterns are more powerful.  They allow matching the value of the
-@var{expression} that is the first argument of @code{pcase} against
-specifications of its @emph{structure}.  For example, you can specify
-that the value must be a list of 2 elements whose first element is a
-string and the second element is a number.  QPatterns can have one of
-the following forms:
+In addition, you can use backquoted patterns that are more powerful.
+They allow matching the value of the @var{expression} that is the
+first argument of @code{pcase} against specifications of its
+@emph{structure}.  For example, you can specify that the value must be
+a list of 2 elements whose first element is a specific string and the
+second element is any value with a backquoted pattern like
+@code{`("first" ,second-elem)}.
+
+Backquoted patterns have the form @code{`@var{qpattern}} where
+@var{qpattern} can have the following forms:
 
 @table @code
-@item `(@var{qpattern1} . @var{qpattern2})
+@item (@var{qpattern1} . @var{qpattern2})
 Matches if the value being matched is a cons cell whose @code{car}
 matches @var{qpattern1} and whose @code{cdr} matches @var{qpattern2}.
-@item `[@var{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}]
+This readily generalizes to backquoted lists as in
+@w{@code{(@var{qpattern1} @var{qpattern2} @dots{})}}.
+@item [@var{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}]
 Matches if the value being matched is a vector of length @var{m} whose
 @code{0}..@code{(@var{m}-1)}th elements match @var{qpattern1},
 @var{qpattern2} @dots{} @var{qpatternm}, respectively.
-@item `(,@var{upattern1} ,@var{upattern2} @dots{})
-Matches if the value being matched is a list whose elements match the
-corresponding @var{upattern1}, @var{upattern2}, etc.
 @item @var{atom}
 Matches if corresponding element of the value being matched is
 @code{equal} to the specified @var{atom}.
@@ -433,6 +438,13 @@ Matches if the corresponding element of the value being matched
 matches the specified @var{upattern}.
 @end table
 
+Note that uses of QPatterns can be expressed using only UPatterns, as
+QPatterns are implemented on top of UPatterns using
+@code{pcase-defmacro}, described below.  However, using QPatterns will
+in many cases lead to a more readable code.
+@c FIXME: There should be an example here showing how a 'pcase' that
+@c uses QPatterns can be rewritten using UPatterns.
+
 @end defmac
 
 Here is an example of using @code{pcase} to implement a simple
@@ -476,8 +488,11 @@ Additional UPatterns can be defined using the @code{pcase-defmacro}
 macro.
 
 @defmac pcase-defmacro name args &rest body
-Define a new UPattern for @code{pcase}.  The UPattern will have the
-form @code{(@var{name} @var{args})}.
+Define a new kind of UPattern for @code{pcase}.  The new UPattern will
+be invoked as @code{(@var{name} @var{actual-args})}.  The @var{body}
+should describe how to rewrite the UPattern @var{name} into some other
+UPattern.  The rewriting will be the result of evaluating @var{body}
+in an environment where @var{args} are bound to @var{actual-args}.
 @end defmac
 
 @node Combining Conditions
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 1f207dce823..994c346331f 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -334,7 +334,8 @@ macro accepts the following keywords:
 @item :type @var{type}
 Use @var{type} as the data type for this option.  It specifies which
 values are legitimate, and how to display the value
-(@pxref{Customization Types}).
+(@pxref{Customization Types}).  Every @code{defcustom} should specify
+a value for this keyword.
 
 @item :options @var{value-list}
 @kindex options@r{, @code{defcustom} keyword}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index eaba03d5739..aa98ed40ee5 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -27,6 +27,7 @@ that Emacs presents to the user.
 * Window Dividers::     Separating windows visually.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
+* Xwidgets::            Displaying native widgets in Emacs buffers.
 * Buttons::             Adding clickable buttons to Emacs buffers.
 * Abstract Display::    Emacs's Widget for Object Collections.
 * Blinking::            How Emacs shows the matching open parenthesis.
@@ -5612,6 +5613,118 @@ except when you explicitly clear it.  This mode can be useful for
 debugging.
 @end defvar
 
+@node Xwidgets
+@section Embedded Native Widgets
+@cindex xwidget
+@cindex embedded widgets
+@cindex webkit browser widget
+
+  Emacs is able to display native widgets, such as GTK WebKit widgets,
+in Emacs buffers when it was built with the necessary support
+libraries and is running on a graphical terminal.  To test whether
+Emacs supports display of embedded widgets, check that the
+@code{xwidget-internal} feature is available (@pxref{Named Features}).
+
+  To display an embedded widget in a buffer, you must first create an
+xwidget object, and then use that object as the display specifier
+in a @code{display} text or overlay property (@pxref{Display
+Property}).
+
+@defun make-xwidget beg end type title width height arguments &optional buffer
+This creates an xwidget object between @var{beg} and @var{end}, buffer
+positions in @var{buffer}, and returns the new object.  If
+@var{buffer} is omitted or @code{nil}, it defaults to the current
+buffer.  If @var{buffer} names a buffer that doesn't exist, it will be
+created.  The @var{type} identifies the type of the xwidget component,
+it can be one of the following:
+
+@table @code
+@item webkit-osr
+The WebKit OSR (@dfn{on-stack replacement}) component.
+@end table
+
+The @var{width} and @var{height} arguments specify the widget size in
+pixels, and @var{title}, a string, specifies its title.
+@end defun
+
+@defun xwidgetp object
+This function returns @code{t} if @var{object} is an xwidget,
+@code{nil} otherwise.
+@end defun
+
+@defun xwidget-plist xwidget
+This function returns the property list of @var{xwidget}.
+@end defun
+
+@defun set-xwidget-plist xwidget plist
+This function replaces the property list of @var{xwidget} with a new
+property list given by @var{plist}.
+@end defun
+
+@defun xwidget-buffer xwidget
+This function returns the buffer of @var{xwidget}.
+@end defun
+
+@defun get-buffer-xwidgets buffer
+This function returns a list of xwidget objects associated with the
+@var{buffer}, which can be specified as a buffer object or a name of
+an existing buffer, a string.  The value is @code{nil} if @var{buffer}
+contains no xwidgets.
+@end defun
+
+@defun xwidget-webkit-goto-uri xwidget uri
+This function browses the specified @var{uri} in the given
+@var{xwidget}.  The @var{uri} is a string that specifies the name of a
+file or a URL.  @c FIXME: What else can a URI specify in this context?
+@end defun
+
+@defun xwidget-webkit-execute-script xwidget script
+This function causes the browser widget specified by @var{xwidget} to
+execute the specified JavaScript @code{script}.
+@end defun
+
+@defun xwidget-webkit-execute-script-rv xwidget script &optional default
+This function executes the specified @var{script} like
+@code{xwidget-webkit-execute-script} does, but it also returns the
+script's return value as a string.  If @var{script} doesn't return a
+value, this function returns @var{default}, or @code{nil} if
+@var{default} was omitted.
+@end defun
+
+@defun xwidget-webkit-get-title xwidget
+This function returns the title of @var{xwidget} as a string.
+@end defun
+
+@defun xwidget-resize xwidget width height
+This function resizes the specified @var{xwidget} to the size
+@var{width}x@var{height} pixels.
+@end defun
+
+@defun xwidget-size-request xwidget
+This function returns the desired size of @var{xwidget} as a list of
+the form @code{(@var{width} @var{height})}.  The dimensions are in
+pixels.
+@end defun
+
+@defun xwidget-info xwidget
+This function returns the attributes of @var{xwidget} as a vector of
+the form @code{[@var{type} @var{title} @var{width} @var{height}]}.
+The attributes are usually determined by @code{make-xwidget} when the
+xwidget is created.
+@end defun
+
+@defun set-xwidget-query-on-exit-flag xwidget flag
+This function allows you to arrange that Emacs will ask the user for
+confirmation before exiting or before killing a buffer that has
+@var{xwidget} associated with it.  If @var{flag} is non-@code{nil},
+Emacs will query the user, otherwise it will not.
+@end defun
+
+@defun xwidget-query-on-exit-flag xwidget
+This function returns the current setting of @var{xwidget}s
+query-on-exit flag, either @code{t} or @code{nil}.
+@end defun
+
 @node Buttons
 @section Buttons
 @cindex buttons in buffers
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 55d72427548..b98e3a5cdd1 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -714,9 +714,12 @@ Sizes}) or splitting (@pxref{Splitting Windows}) windows.
 
 @cindex line height
 @cindex column width
-The term @dfn{line height} is sometimes used instead of ``default
-character height''.  Similarly, the term @dfn{column width} is used as
-shorthand for ``default character width''.
+@cindex canonical character height
+@cindex canonical character width
+The terms @dfn{line height} and @dfn{canonical character height} are
+sometimes used instead of ``default character height''.  Similarly, the
+terms @dfn{column width} and @dfn{canonical character width} are used
+instead of ``default character width''.
 
 @defun frame-char-height &optional frame
 @defunx frame-char-width &optional frame
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index ca756e3ff7f..771bd4eeb29 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -371,14 +371,14 @@ means to use the left or top edge of @var{window} as reference position.
 If the optional argument @var{wrap} is non-@code{nil}, this means to
 wrap @var{direction} around frame borders.  For example, if @var{window}
 is at the top of the frame and @var{direction} is @code{above}, then
-return the minibuffer window provided the frame has one, and a window at
-the bottom of the frame otherwise.
+this function usually returns the frame's minibuffer window if it's
+active and a window at the bottom of the frame otherwise.
 
 If the optional argument @var{mini} is @code{nil}, this means to return
 the minibuffer window if and only if it is currently active.  If
-@var{mini} is non-@code{nil}, it returns the minibuffer window even when
-it's not active.  However, if @var{wrap} non-@code{nil}, it always acts
-as if @var{mini} were @code{nil}.
+@var{mini} is non-@code{nil}, this function may return the minibuffer
+window even when it's not active.  However, if @var{wrap} is
+non-@code{nil}, it always acts as if @var{mini} were @code{nil}.
 
 If it doesn't find a suitable window, this function returns @code{nil}.
 @end defun
@@ -664,15 +664,17 @@ following function useful:
 
 @defun window-max-chars-per-line &optional window face
 This function returns the number of characters displayed in the
-specified @var{face} in the specified @var{window} (which must be a
-live window).  If @var{face} was remapped (@pxref{Face Remapping}),
-the information is returned for the remapped face.  If omitted or
-@code{nil}, @var{face} defaults to the default face, and @var{window}
-defaults to the selected window.  Unlike @code{window-body-width},
-this function accounts for the actual size of the @var{face}'s font,
-instead of working in units of frame's canonical character width.  It
-also accounts for space used by the continuation glyph, if
-@var{window} lacks one or both of its fringes.
+specified face @var{face} in the specified window @var{window} (which
+must be a live window).  If @var{face} was remapped (@pxref{Face
+Remapping}), the information is returned for the remapped face.  If
+omitted or @code{nil}, @var{face} defaults to the default face, and
+@var{window} defaults to the selected window.
+
+Unlike @code{window-body-width}, this function accounts for the actual
+size of @var{face}'s font, instead of working in units of the canonical
+character width of @var{window}'s frame (@pxref{Frame Font}).  It also
+accounts for space used by the continuation glyph, if @var{window} lacks
+one or both of its fringes.
 @end defun
 
 @cindex fixed-size window
@@ -701,7 +703,7 @@ margins, fringes, a scroll bar and a right divider, if present.
 The following function tells how small a specific window can get taking
 into account the sizes of its areas and the values of
 @code{window-min-height}, @code{window-min-width} and
-@code{window-size-fixed}.
+@code{window-size-fixed} (@pxref{Preserving Window Sizes}).
 
 @defun window-min-size &optional window horizontal ignore pixelwise
 This function returns the minimum size of @var{window}.  @var{window}
@@ -713,10 +715,9 @@ of @var{window}'s lines.
 The return value makes sure that all components of @var{window} remain
 fully visible if @var{window}'s size were actually set to it.  With
 @var{horizontal} @code{nil} it includes the mode and header line, the
-horizontal scroll bar and the bottom divider.  With @var{horizontal}
-non-@code{nil} it includes the fringes, a scroll bar, and a right
-divider, if present.  It does not, however, include the space reserved
-for the margins.
+horizontal scroll bar and the bottom divider, if present.  With
+@var{horizontal} non-@code{nil} it includes the margins and fringes, the
+vertical scroll bar and the right divider, if present.
 
 The optional argument @var{ignore}, if non-@code{nil}, means ignore
 restrictions imposed by fixed size windows, @code{window-min-height} or
@@ -1263,8 +1264,8 @@ frame), an error is signaled.
 By default, the space taken up by @var{window} is given to one of its
 adjacent sibling windows, if any.  However, if the variable
 @code{window-combination-resize} is non-@code{nil}, the space is
-proportionally distributed among any remaining windows in the window
-combination.  @xref{Recombining Windows}.
+proportionally distributed among any remaining windows in the same
+window combination.  @xref{Recombining Windows}.
 
 The behavior of this function may be altered by the window parameters
 of @var{window}, so long as the variable
@@ -1771,11 +1772,13 @@ nor the buffer list.
 @defun window-use-time &optional window
 This functions returns the use time of window @var{window}.
 @var{window} must be a live window and defaults to the selected one.
-The @dfn{use time} of a window is not really a time value, but it does
-increase monotonically with each window selection, so the window with
-the lowest use time is the least recently selected one, and the
-window with the highest use time is the most recently selected
-one.
+
+The @dfn{use time} of a window is not really a time value, but an
+integer that does increase monotonically with each call of
+@code{select-window} with a @code{nil} @var{norecord} argument.  The
+window with the lowest use time is usually called the least recently
+used window while the window with the highest use time is called the
+most recently used one (@pxref{Cyclic Window Ordering}).
 @end defun
 
 
@@ -1790,11 +1793,11 @@ some other window, it moves through live windows in a specific order.
 For any given configuration of windows, this order never varies.  It
 is called the @dfn{cyclic ordering of windows}.
 
-  The ordering is determined by a depth-first traversal of the frame's
-window tree, retrieving the live windows which are the leaf nodes of
-the tree (@pxref{Windows and Frames}).  If the minibuffer is active,
-the minibuffer window is included too.  The ordering is cyclic, so the
-last window in the sequence is followed by the first one.
+  The ordering is determined by a depth-first traversal of each frame's
+window tree, retrieving the live windows which are the leaf nodes of the
+tree (@pxref{Windows and Frames}).  If the minibuffer is active, the
+minibuffer window is included too.  The ordering is cyclic, so the last
+window in the sequence is followed by the first one.
 
 @defun next-window &optional window minibuf all-frames
 @cindex minibuffer window, and @code{next-window}
@@ -2146,9 +2149,8 @@ Invokes @code{pop-to-buffer} to proceed.
 Marks the selected window as non-dedicated and proceeds.
 @end table
 
-When called non-interactively, @code{switch-to-buffer} always signals an
-error when the selected window is dedicated to its buffer and
-@var{force-same-window} is non-@code{nil}.
+This option does not affect non-interactive calls of
+@code{switch-to-buffer}.
 @end defopt
 
 By default, @code{switch-to-buffer} shows the buffer at its position of
@@ -2209,7 +2211,7 @@ for the documentation of @code{display-buffer}.
 
 @deffn Command pop-to-buffer buffer-or-name &optional action norecord
 This function makes @var{buffer-or-name} the current buffer and
-displays it in some window, preferably not the window previously
+displays it in some window, preferably not the window currently
 selected.  It then selects the displaying window.  If that window is
 on a different graphical frame, that frame is given input focus if
 possible (@pxref{Input Focus}).  The return value is the buffer that
@@ -2420,7 +2422,6 @@ frame is a candidate; this function replaces the default predicate.
 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
 the selected window is used; thus if the selected frame has a single
 window, it is not used.
-
 @end defun
 
 @defun display-buffer-pop-up-window buffer alist