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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 07 Nov 2021 14:33:21 +0200

> From: Po Lu <[email-masked]>
> Cc: [email-masked],  [email-masked]
> Date: Sun, 07 Nov 2021 20:03:04 +0800
> 
> > The printed representation of xwidget objects should be documented in
> > the ELisp manual, under the "Editing Types" section.  In fact, we lack
> > a subsection there for xwidgets; it should be added.
> >
> > Thanks.
> 
> Will this work?

With some minor changes, yes.

> +@node Xwidget Type
> +@subsection Xwidget Type

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.

> +                                                Each window such an
> +xwidget is be displayed in

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).

>                                                           , which on
> +X-Windows corresponds to a single X window used to display the widget.

What about NS?  And what about Wayland?

> +Neither of these objects are readable; their print syntaxes look like
> +@samp{#<xwidget>} and @samp{#<xwidget-view>}, respectively.  Lisp
> +programmers should not be interested in the functionality of xwidget
> +views.

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

Thanks.