Subject: Re: bug#51473: [PATCH] Enable xwidget scrolling optimizations, and other xwidgets improvements

From: Po Lu <[email-masked]>
Date: Sun, 07 Nov 2021 20:40:49 +0800

Eli Zaretskii <[email-masked]> writes:

> It is generally a good idea to have a @cindex entry with the name of
> the section (but with lower-case letters), so that the section could
> be easily found via Info-index.

Thanks, done.

> This style is better avoided: it produces long sentences that are hard
> to grasp for non-native speakers, because the important part ("in") is
> at the end.  It is better to say it simply:
>
>   Each window that displays an xwidget will also have a @dfn{xwidget
>   view}, ...
>
> And add a @cindex for "xwidget-view", again generally a good practice
> of indexing each place that introduces new terminology (indicated by
> @dfn).

Likewise.

> What about NS?  And what about Wayland?

I don't know exactly how it is handled on NS.  On Wayland, it's still an
X window that runs through Wayland's compatibility layer for X
applications.  (Like the rest of Emacs, at present.)

> I'd drop the second of these sentences.  It doesn't add anything to
> the description.

Done as well, please check the attached patch.

>From 728f07e20bfb8e16182ef7dae816e3512665d64b Mon Sep 17 00:00:00 2001
From: Po Lu <[email-masked]>
Date: Sun, 7 Nov 2021 20:02:06 +0800
Subject: [PATCH] Document the xwidget type

* doc/lispref/elisp.texi: Add Xwidget Type to the menu.
* doc/lispref/objects.texi (Editing Types): Add Xwidget Type to the
menu.
(Xwidget Type): New node.
---
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/objects.texi | 15 +++++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index d0bfd8c901..1c0b0fa1b5 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -365,6 +365,7 @@ Top
 * Keymap Type::             What function a keystroke invokes.
 * Overlay Type::            How an overlay is represented.
 * Font Type::               Fonts for displaying text.
+* Xwidget Type::            Embeddable widgets.
 
 Numbers
 
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 0551bb5673..bbd3973f61 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -1535,6 +1535,7 @@ Editing Types
 * Keymap Type::         What function a keystroke invokes.
 * Overlay Type::        How an overlay is represented.
 * Font Type::           Fonts for displaying text.
+* Xwidget Type::        Embeddable widgets.
 @end menu
 
 @node Buffer Type
@@ -1860,6 +1861,20 @@ Font Type
 @samp{#<font-entity>} respectively.  @xref{Low-Level Font}, for a
 description of these Lisp objects.
 
+@node Xwidget Type
+@subsection Xwidget Type
+@cindex xwidget type
+@cindex xwidget-view type
+
+  An @dfn{xwidget} is a special display element, such as a web
+browser, that can be embedded inside a buffer.  Each window that
+displays an xwidget will also have an @dfn{xwidget view}, which on
+X-Windows corresponds to a single X window used to display the widget.
+
+Neither of these objects are readable; their print syntaxes look like
+@samp{#<xwidget>} and @samp{#<xwidget-view>}, respectively.
+@xref{Xwidgets}, for a more detailed description of xwidgets.
+
 @node Circular Objects
 @section Read Syntax for Circular Objects
 @cindex circular structure, read syntax
-- 
2.31.1