[PATCH wayland 1/4] doc: Improve Wire Format section

[Pekka Paalanen]

On Tue, 09 Oct 2012 14:31:49 +0300
Tiago Vignatti <tiago.vignatti at linux.intel.com> wrote:

> On 10/09/2012 09:34 AM, Pekka Paalanen wrote:
> > On Mon,  8 Oct 2012 18:39:57 +0300
> > Tiago Vignatti <tiago.vignatti at intel.com> wrote:
> >
> >> Fixed the wayland socket name and added documentation for fixed format.
> >>
> >> Signed-off-by: Tiago Vignatti <tiago.vignatti at intel.com>
> >
> > Hi Tiago,
> >
> > nice!
> >
> >> ---
> >>   doc/Wayland/en_US/Protocol.xml |   22 +++++++++++++++++-----
> >>   1 file changed, 17 insertions(+), 5 deletions(-)
> >>
> >> diff --git a/doc/Wayland/en_US/Protocol.xml b/doc/Wayland/en_US/Protocol.xml
> >> index 9a7db53..8927837 100644
> >> --- a/doc/Wayland/en_US/Protocol.xml
> >> +++ b/doc/Wayland/en_US/Protocol.xml
> >> @@ -59,9 +59,10 @@
> >>     <section id="sect-Protocol-Wire-Format">
> >>       <title>Wire Format</title>
> >>       <para>
> >> -      The protocol is sent over a UNIX domain stream socket.  Currently, the
> >> -      endpoint is named <systemitem class="service">\wayland</systemitem>,
> >> -      but it is subject to change.  The protocol is message-based.  A
> >> +      The protocol is sent over a UNIX domain stream socket, where the endpoint
> >> +      usually is named <systemitem class="service">wayland-0</systemitem>
> >> +      (although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis>
> >> +      in the environment).  The protocol is message-based.  A
> >>         message sent by a client to the server is called request.  A message
> >>         from the server to a client is called event.  Every message is
> >>         structured as 32-bit words, values are represented in the host's
> >> @@ -102,12 +103,23 @@
> >>   	  </listitem>
> >>   	</varlistentry>
> >>   	<varlistentry>
> >> +	  <term>fixed</term>
> >> +	  <listitem>
> >> +	    <para>
> >> +	      Signed 24.8 decimal numbers. It is a signed decimal type which
> >> +	      offers a sign bit, 23 bits of integer precision and 8 bits of
> >> +	      decimal precision. This is exposed as an opaque struct with
> >> +	      conversion helpers to and from double and int on the C API side.
> >
> > I don't think there is such thing as a decimal number, unless it's
> > maybe a BCD or a string. More proper terms are a fixed point value, and
> > 8 bits of fractional precision, IMO.
> >
> > It's not an (opaque) struct, either. It's just a typedef from int32_t.
> 
> Actually I just copied verbatim from this commit and haven't carefully 
> checked myself the correctness:
> 
> commit c5aba11accad178a81a373bd5d1de888b2a51101
> Author: Daniel Stone <daniel at fooishbar.org>
> Date:   Tue May 8 17:17:25 2012 +0100
> 
>      Add support for signed 24.8 decimal numbers
> 
>      'fixed' is a signed decimal type which offers a sign bit, 23 bits of
>      integer precision, and 8 bits of decimal precision.  This is exposed as
>      an opaque struct with conversion helpers to and from double and int on
>      the C API side.

That's probably just leftovers from when Daniel first made it an
opaque struct, and then got told to change it.

- pq