[PATCH 05/21] doc: Improve various sections of the documentation
Jason Ekstrand
jason at jlekstrand.net
Sat Mar 30 13:52:45 PDT 2013
Looks Good!
--Jason Ekstrand
On Sat, Mar 30, 2013 at 12:11 AM, <matthias.clasen at gmail.com> wrote:
> From: Matthias Clasen <mclasen at redhat.com>
>
> ---
> doc/Wayland/en_US/Protocol.xml | 71 ++++++++++++++++++------------------------
> 1 file changed, 31 insertions(+), 40 deletions(-)
>
> diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
> index 955b054..9bc8232 100644
> --- a/doc/Wayland/en_US/Protocol.xml
> +++ b/doc/Wayland/en_US/Protocol.xml
> @@ -196,19 +196,10 @@
> <section id="sect-Protocol-Creating-Objects">
> <title>Creating Objects</title>
> <para>
> - <itemizedlist>
> - <listitem>
> - <para>
> - client allocates object ID, uses range protocol
> - </para>
> - </listitem>
> - <listitem>
> - <para>
> - server tracks how many IDs are left in current range, sends
> - new range when client is about to run out.
> - </para>
> - </listitem>
> - </itemizedlist>
> + Each object has a unique ID. The IDs are allocated by the
> + client, from a range of IDs. The server tracks how many
> + IDs are left in the current range and sends a new range
> + when the client is about to run out.
> </para>
> </section>
> <section id="sect-Protocol-Compositor">
> @@ -222,24 +213,22 @@
> </para>
> </section>
> <section id="sect-Protocol-Surface">
> - <title>Surface</title>
> + <title>Surfaces</title>
> <para>
> - Created by the client.
> + Surfaces are created by the client.
> </para>
> <para>
> See <xref linkend="protocol-spec-interface-wl_surface"/> for the protocol
> description.
> </para>
> - <para>
> - Needs a way to set input region, opaque region.
> - </para>
> </section>
> <section id="sect-Protocol-Input">
> <title>Input</title>
> <para>
> - Represents a group of input devices, including mice, keyboards. Has a
> - keyboard and pointer focus. Global object. Pointer events are
> - delivered in both screen coordinates and surface local coordinates.
> + A seat represents a group of input devices including mice,
> + keyboards and touchscreens. It has a keyboard and pointer
> + focus. Seats are global objects. Pointer events are delivered
> + in surface local coordinates.
> </para>
> <para>
> See <xref linkend="protocol-spec-interface-wl_seat"/> for the
> @@ -331,21 +320,23 @@
> </itemizedlist>
> </section>
> <section id="sect-Protocol-data-sharing">
> - <title>Data sharing between client (selection and drag and drop)</title>
> + <title>Data sharing between clients</title>
> <para>
> - The Wayland 1.0 protocol provides its clients a mechanism for sharing
> - data that allows the implementation of selection and drag and drop.
> - The client providing the data creates a wl_data_source object and the
> - clients obtaining the data will see it as wl_data_offer object. This
> - interface allows the clients to agree on a mutually supported mime type
> - and transfer the data through an fd that is passed through the protocol.
> + The Wayland protocol provides clients a mechanism for sharing
> + data that allows the implementation of copy-paste and
> + drag-and-drop. The client providing the data creates a
> + <function>wl_data_source</function> object and the clients
> + obtaining the data will see it as <function>wl_data_offer</function>
> + object. This interface allows the clients to agree on a mutually
> + supported mime type and transfer the data via a file descriptor
> + that is passed through the protocol.
> </para>
> <para>
> - The next section explains the negotiation between data source and data
> - offer objects. <xref linkend="sect-Protocol-data-sharing-devices"/>
> - explains how these objects are created and passed to different client
> - using the wl_data_device interface, that implements selection and drag
> - and drop support.
> + The next section explains the negotiation between data source and
> + data offer objects. <xref linkend="sect-Protocol-data-sharing-devices"/>
> + explains how these objects are created and passed to different
> + clients using the <function>wl_data_device</function> interface
> + that implements copy-paste and drag-and-drop support.
> </para>
> <para>
> See <xref linkend="protocol-spec-interface-wl_data_offer"/>,
> @@ -363,7 +354,7 @@
> <section>
> <title>Data negotiation</title>
> <para>
> - A client providing data to other clients will create a wl_data_source
> + A client providing data to other clients will create a <function>wl_data_source</function>
> object and advertise the mime types for the formats it supports for
> that data through the <function>wl_data_source.offer</function>
> request. On the receiving end, the data offer object will generate one
> @@ -373,18 +364,18 @@
> <para>
> The actual data transfer happens when the receiving client sends a
> <function>wl_data_offer.receive</function> request. This request takes
> - a mime type and an fd as arguments. This request will generate a
> + a mime type and a file descriptor as arguments. This request will generate a
> <function>wl_data_source.send</function> event on the sending client
> with the same arguments, and the latter client is expected to write its
> - data to the given fd using the chosen mime type.
> + data to the given file descriptor using the chosen mime type.
> </para>
> </section>
> <section id="sect-Protocol-data-sharing-devices">
> <title>Data devices</title>
> <para>
> Data devices glue data sources and offers together. A data device is
> - associated with a wl_seat and is obtained by the clients using the
> - wl_data_device_manager factory object, which is also responsible for
> + associated with a <function>wl_seat</function> and is obtained by the clients using the
> + <function>wl_data_device_manager</function> factory object, which is also responsible for
> creating data sources.
> </para>
> <para>
> @@ -392,7 +383,7 @@
> <function>wl_data_device.data_offer</function> event. After this
> event is generated the data offer will advertise the available mime
> types. New data offers are introduced prior to their use for
> - selection or drag and drop.
> + copy-paste or drag-and-drop.
> </para>
> <section>
> <title>Selection</title>
> @@ -414,7 +405,7 @@
> <section>
> <title>Drag and Drop</title>
> <para>
> - A drag and drop operation is started using the
> + A drag-and-drop operation is started using the
> <function>wl_data_device.start_drag</function> request. This
> requests causes a pointer grab that will generate enter, motion and
> leave events on the data device. A data source is supplied as
> --
> 1.8.1.4
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list