Document xwidget commands and functions

* doc/lispref/display.texi (Xwidgets): New section, describes some
of the xwidget primitives.
* doc/lispref/display.texi (Display): Update the chapter menu.
* doc/emacs/misc.texi (Embedded WebKit Widgets): New section.
* doc/emacs/emacs.texi (Top): Update the master menu to include
the xwidget node.

4 files changed, 143 insertions, 5 deletions

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index ac8988b4020..dc99d493241 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -192,6 +192,7 @@ Advanced Features
 * Network Security::    Managing the network security.
 * Document View::       Viewing PDF, PS and DVI files.
 * EWW::                 A web browser in Emacs.
+* Embedded WebKit Widgets:: Embedding browser widgets in Emacs buffers.
 * Shell::               Executing shell commands from Emacs.
 * Emacs Server::        Using Emacs as an editing server.
 * Printing::            Printing hardcopies of buffers or regions.
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 2d8137e832f..b5a21500fcb 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -604,6 +604,28 @@ using the command @kbd{M-x eww-open-file}.  You can use EWW as the
 web browser for @code{browse-url}, @pxref{Browse-URL}.  For full
 details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}.
 
+@node Embedded WebKit Widgets
+@section Embedded WebKit Widgets
+@cindex xwidget
+@cindex webkit widgets
+@cindex embedded widgets
+
+@findex xwidget-webkit-browse-url
+@findex xwidget-webkit-mode
+@cindex Xwidget-WebKit mode
+  If Emacs was compiled with the appropriate support packages, it is
+able to show browser widgets in its buffers.  The command @kbd{M-x
+xwidget-webkit-browse-url} asks for a URL to display in the browser
+widget.  The URL normally defaults to the URL at or before point, but
+if there is an active region (@pxref{Mark}), the default URL comes
+from the region instead, after removing any whitespace from it.  The
+command then creates a new buffer with the embedded browser showing
+the specified URL.  The buffer is put in the Xwidget-WebKit mode
+(similar to Image mode, @pxref{File Conveniences}), which provides
+one-key commands for scrolling the widget, changing its size, and
+reloading it.  Type @w{@kbd{C-h b}} in that buffer to see the key
+bindings.
+
 @node Shell
 @section Running Shell Commands from Emacs
 @cindex subshell
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/etc/NEWS b/etc/NEWS
index 09bced4b000..af2dee931f3 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -126,13 +126,15 @@ and can contain escape sequences for command keys, quotes, and the like.
 
 * Changes in Emacs 25.1
 
++++
 ** Xwidgets: a new feature for embedding native widgets inside Emacs buffers.
-If you have gtk3 and webkitgtk3 installed, you can access the
-embedded webkit browser with `M-x xwidget-webkit-browse-url'.  This
-opens a new buffer with the embedded browser.  The buffer will
-have a new mode, `xwidget-webkit-mode' (similar to `image-mode'),
-which supports the webkit widget.
+If you have gtk3 and webkitgtk3 installed, and Emacs was built with
+xwidget support, you can access the embedded webkit browser with `M-x
+xwidget-webkit-browse-url'.  This opens a new buffer with the embedded
+browser.  The buffer will have a new mode, `xwidget-webkit-mode'
+(similar to `image-mode'), which supports the webkit widget.
 
++++
 *** New functions for xwidget-webkit mode `xwidget-webkit-insert-string',
 `xwidget-webkit-adjust-size-dispatch', `xwidget-webkit-back',
 `xwidget-webkit-browse-url', `xwidget-webkit-reload',