[PATCH 1/2] protocol: Grammar copyedits of the xdg-shell and desktop protocol docs
Bryce W. Harrington
b.harrington at samsung.com
Mon Jan 27 15:09:18 PST 2014
Signed-off-by: Bryce Harrington <b.harrington at samsung.com>
---
protocol/desktop-shell.xml | 10 ++---
protocol/xdg-shell.xml | 89 ++++++++++++++++++++++----------------------
2 files changed, 49 insertions(+), 50 deletions(-)
diff --git a/protocol/desktop-shell.xml b/protocol/desktop-shell.xml
index 65e44a7..7b34213 100644
--- a/protocol/desktop-shell.xml
+++ b/protocol/desktop-shell.xml
@@ -35,10 +35,10 @@
<request name="desktop_ready" since="2">
<description summary="desktop is ready to be shown">
- Tell the server, that enough desktop elements have been drawn
- to make the desktop look ready for use. During start-up, the
+ Tell the server that enough desktop elements have been drawn
+ to make the desktop look ready for use. During start-up for instance, the
server can wait for this request with a black screen before
- starting to fade in the desktop, for instance. If the client
+ starting to fade-in the desktop. If the client
parts of a desktop take a long time to initialize, we avoid
showing temporary garbage.
</description>
@@ -55,8 +55,8 @@
<event name="prepare_lock_surface">
<description summary="tell the client to create, set the lock surface">
- Tell the shell we want it to create and set the lock surface, which is
- a GUI asking the user to unlock the screen. The lock surface is
+ Tell the shell we want it to create and set the lock surface (i.e.
+ a GUI asking the user to unlock the screen.) The lock surface is
announced with 'set_lock_surface'. Whether or not the shell actually
implements locking, it MUST send 'unlock' request to let the normal
desktop resume.
diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
index 4e5cff8..a29a5f1 100644
--- a/protocol/xdg-shell.xml
+++ b/protocol/xdg-shell.xml
@@ -40,7 +40,7 @@
<enum name="version">
<description summary="latest protocol version">
- Use this enum to check the protocol version, and it will be updated
+ Use this enum to check the protocol version. It will be updated
automatically.
</description>
<entry name="current" value="1" summary="Always the latest version"/>
@@ -51,8 +51,8 @@
<description summary="enable use of this unstable version">
Use this request in order to enable use of this interface.
- Understand and agree that one is using an unstable interface,
- that will likely change in the future, breaking the API.
+ Be aware that this is an unstable interface, that will likely
+ change in the future, breaking the API.
</description>
<arg name="version" type="int"/>
</request>
@@ -92,9 +92,10 @@
An interface that may be implemented by a wl_surface, for
implementations that provide a desktop-style user interface.
- It provides requests to treat surfaces like windows, allowing to set
- properties like maximized, fullscreen, minimized, and to move and resize
- them, and associate metadata like title and app id.
+ This provides requests to treat surfaces like windows, allowing
+ properties like maximized, fullscreen, minimized to be set. It
+ also allows windows to be moved and resized, and to
+ associate metadata like title and app id with them.
On the server side the object is automatically destroyed when
the related wl_surface is destroyed. On client side,
@@ -114,12 +115,11 @@
<request name="set_transient_for">
<description summary="surface is a child of another surface">
- Setting a surface as transient of another means that it is child
- of another surface.
+ Set a surface as transient (child) of another surface.
Child surfaces are stacked above their parents, and will be
unmapped if the parent is unmapped too. They should not appear
- on task bars and alt+tab.
+ on task bars or alt+tab.
</description>
<arg name="parent" type="object" interface="wl_surface" allow-null="true"/>
</request>
@@ -139,7 +139,7 @@
<request name="set_app_id">
<description summary="set surface class">
- Set an id for the surface.
+ Set an application identifier for the surface.
The app id identifies the general class of applications to which
the surface belongs.
@@ -153,7 +153,7 @@
<request name="pong">
<description summary="respond to a ping event">
A client must respond to a ping event with a pong request or
- the client may be deemed unresponsive.
+ the display server may deem the client unresponsive.
</description>
<arg name="serial" type="uint" summary="serial of the ping event"/>
</request>
@@ -214,7 +214,7 @@
The configure event asks the client to resize its surface.
The size is a hint, in the sense that the client is free to
- ignore it if it doesn't resize, pick a smaller size (to
+ ignore it if it doesn't resize, or even pick a smaller size (to
satisfy aspect ratio or resize in steps of NxM pixels).
The edges parameter provides a hint about how the surface
@@ -226,7 +226,7 @@
The client is free to dismiss all but the last configure
event it received.
- The width and height arguments specify the size of the window
+ The width and height parameters specify the size of the window
in surface local coordinates.
</description>
@@ -240,7 +240,7 @@
Set the default output used by this surface when it is first mapped.
If this value is NULL (default), it's up to the compositor to choose
- which display will be used to map this surface.
+ which output will be used to map this surface.
When fullscreen or maximized state are set on this surface, and it
wasn't mapped yet, the output set with this method will be used.
@@ -252,17 +252,17 @@
<event name="request_set_fullscreen">
<description summary="server requests that the client set fullscreen">
- Event sent from the compositor to the client requesting that the client
- goes to a fullscreen state. It's the client job to call set_fullscreen
- and really trigger the fullscreen state.
+ Event sent by the compositor to request the client
+ go to a fullscreen state. It's the client's responsibility to call set_fullscreen
+ and actually trigger the fullscreen state.
</description>
</event>
<event name="request_unset_fullscreen">
<description summary="server requests that the client unset fullscreen">
- Event sent from the compositor to the client requesting that the client
- leaves the fullscreen state. It's the client job to call
- unset_fullscreen and really leave the fullscreen state.
+ Event sent by the compositor to request the client
+ leave the fullscreen state. It's the client's responsibility to call
+ unset_fullscreen and actually leave the fullscreen state.
</description>
</event>
@@ -270,13 +270,13 @@
<description summary="set the surface state as fullscreen">
Set the surface as fullscreen.
- After this request, the compositor should send a configure event
- informing the output size.
+ After this request, the compositor will send a configure event
+ with the new output size.
This request informs the compositor that the next attached buffer
committed will be in a fullscreen state. The buffer size should be the
- same size as the size informed in the configure event, if the client
- doesn't want to leave any empty area.
+ same as specified by the configure event, otherwise the client
+ may be forced to leave an area empty.
In other words: the next attached buffer after set_maximized is the new
maximized buffer. And the surface will be positioned at the maximized
@@ -303,17 +303,17 @@
<event name="request_set_maximized">
<description summary="server requests that the client set maximized">
- Event sent from the compositor to the client requesting that the client
- goes to a maximized state. It's the client job to call set_maximized
- and really trigger the maximized state.
+ Event sent by the compositor to request the client
+ go to a maximized state. It's the client's responsibility to call set_maximized
+ and actually trigger the maximized state.
</description>
</event>
<event name="request_unset_maximized">
<description summary="server requests that the client unset maximized">
- Event sent from the compositor to the client requesting that the client
- leaves the maximized state. It's the client job to call unset_maximized
- and really leave the maximized state.
+ Event sent by the compositor to request the client
+ leave the maximized state. It's the client's responsibility to call unset_maximized
+ and actually leave the maximized state.
</description>
</event>
@@ -322,7 +322,7 @@
Set the surface as maximized.
After this request, the compositor will send a configure event
- informing the output size minus panel and other MW decorations.
+ with the new output size minus panel and other MW decorations.
This request informs the compositor that the next attached buffer
committed will be in a maximized state. The buffer size should be the
@@ -362,14 +362,14 @@
<event name="focused_set">
<description summary="surface was focused">
- The focused_set event is sent when this surface has been
+ Event sent when this surface has been
activated. Window decorations should be updated accordingly.
</description>
</event>
<event name="focused_unset">
<description summary="surface was unfocused">
- The focused_unset event is sent when this surface has been
+ Event sent when this surface has been
deactivated, because another surface has been activated. Window
decorations should be updated accordingly.
</description>
@@ -378,21 +378,20 @@
<interface name="xdg_popup" version="1">
<description summary="desktop-style metadata interface">
- An interface that may be implemented by a wl_surface, for
- implementations that provide a desktop-style popups/menus. A popup
- surface is a transient surface with an added pointer grab.
+ An interface for desktop-style popups/menus, implemented via a
+ transient wl_surface and a pointer grab.
- An existing implicit grab will be changed to owner-events mode,
+ If there is an existing implicit grab, it will be changed to owner-events mode,
and the popup grab will continue after the implicit grab ends
(i.e. releasing the mouse button does not cause the popup to be
unmapped).
- The popup grab continues until the window is destroyed or a mouse
- button is pressed in any other clients window. A click in any of
- the clients surfaces is reported as normal, however, clicks in
- other clients surfaces will be discarded and trigger the callback.
+ The popup grab lasts until the window is destroyed or a mouse
+ button is pressed in another client's window. A click in any of
+ the client's surfaces is reported as normal, but clicks in
+ other clients' surfaces will be discarded and trigger the callback.
- The x and y arguments specify the locations of the upper left
+ The x and y parameters specify the locations of the upper left
corner of the surface relative to the upper left corner of the
parent surface, in surface local coordinates.
@@ -411,8 +410,8 @@
<request name="pong">
<description summary="respond to a ping event">
- A client must respond to a ping event with a pong request or
- the client may be deemed unresponsive.
+ A client must respond to a ping event with a pong request or
+ the display server may deem the client unresponsive.
</description>
<arg name="serial" type="uint" summary="serial of the ping event"/>
</request>
@@ -427,7 +426,7 @@
<event name="popup_done">
<description summary="popup interaction is done">
- The popup_done event is sent out when a popup grab is broken,
+ The popup_done event is sent when a popup grab is broken,
that is, when the users clicks a surface that doesn't belong
to the client owning the popup surface.
</description>
--
1.7.9.5
More information about the wayland-devel
mailing list