standardizing "surface-local coordinates"

Thu Apr 21 21:17:02 UTC 2016

On Thu, Apr 21, 2016 at 09:17:32AM -0500, Yong Bakos wrote:
> > On Apr 19, 2016, at 12:26 PM, Daniel Stone <daniel at fooishbar.org> wrote:
> > 
> > On 19 April 2016 at 17:55, Yong Bakos <junk at humanoriented.com> wrote:
> >> There was a little discussion recently about standardizing occurrences of "surface local coordinates" to the grammatically correct "surface-local coordinates." (It's a compound adjective.)
> >> 
> >> https://lists.freedesktop.org/archives/wayland-devel/2016-April/028241.html
> >> 
> >> Doing so would affect documentation in:
> >> wayland: protocol/wayland.xml
> >> wayland-protocols: pointer-constraints, tablet, xdg-shell
> >> weston: protocol/ivi-application.xml, compositor.c (1 comment header)
> >> 
> >> Currently, both the dashed and dashless versions are used in description paragraphs. Standardizing this would help protocol authors adhere to one grammatically correct convention, and also improve succinctness of arg summaries. For example "x coordinate in surface local coordinates" can become "surface-local x coordinate."
> >> 
> >> I know this contribution isn't huge, but wanted to give you the chance to discourage me from doing this before I send a handful of patches. You might suggest alternative terms entirely, but prior discussion seems to indicate that "surface-local" is concise and less susceptible to misinterpretation than alternatives (eg. "surface relative").
> > 
> > No, please do go for it. And also, surely 'surface relative' is in
> > fact 'surface-relative'? :)
> > 
> > Cheers,
> > Daniel
> 
> 
> Hi everyone,
> 
> (Tip: The main question is at the end.)
> 
> I have ten patches that hyphenate all occurrences of surface local,
> window local, and buffer local in wayland, weston, wayland-web and
> wayland-protocols, per recent discussion. Consider this
> email as a 00/10 cover letter (which I didn't formalize since this
> patchset spans multiple repositories), but note that I have
> decided to not clutter the list with these ten patches yet due to
> something that deserves discussion (main question at the end).
> 
> In all cases, these are only documentation changes.
> 
> wayland-web: architecture.html
> wayland-protocols: tablet, pointer-constraints
> wayland: doc, protocol[1]
> weston: desktop-shell, fullscreen-shell, ivi-layout, ivi-application,
>         compositor[2]
> 
> The rationale is that 'foo local coordinates' uses a compound adjective,
> 'foo local', which should be hyphenated. Standardizing upon the correct
> grammar helps authors adhere to what is correct.
> 
> One thing I noticed while writing these patches is that perhaps we
> should consider not using 'local' at all, except in cases where it is
> necessary. Consider:
> 
> "transform the screen coordinates to window-local coordinates"
> "the pointer location, in surface-local coordinates"
> "which may differ from the buffer-local coordinates of the pixel content"
> 
> In just about every case within the documentation, I felt that if we
> omit the the '-local' entirely, it is still clear from the context
> that we are referring to the object's /coordinate space/, and not, say,
> its /position/ in some other coordinate system. There are numerous
> cases within the documentation where the author does not use the term
> 'local', yet the meaning remains clear, for example:
> 
> "transform a rectangle from surface coordinates to buffer coordinates"
> "the region in surface coordinates"
> "after scaling device coordinates to screen coordinates"
> 
> The exception to this is where using '-local' imparts clarity and
> succinctness. Consider:
> 
> "x coordinate in surface-local coordinates"
> 
> Stating "surface x coordinate" would mean the surface's position,
> and "surface-local x coordinate" is necessary to express the intended
> meaning. I was going to assert that "x coordinate in surface coordinates"
> is repetitive, but once I wrote/read it, I don't feel it's that bad.
> 
> I believe that less is more, except where it jeopardizes clarity. My
> question is, do you think we're better off with this patchset, that
> hyphenates the use of '-local', or another patchset that:
> 
> 1) removes the verbose occurrences of 'local'
> 2) hyphenates the few occurrences of 'local' when it preserves clarity

I agree that clarity is the paramount consideration.  But like you I'm
unsure if the extra verbosity adds clarity.  I am imagining a situation
in the future when a contributor is adding a new feature that documents
something about coordinates, who might not be versed on this discussion.
Would they use the -local form by default in cases like those you
mentioned?  And if they used the wrong form, would a typical reviewer
flag it?

In the case of "surface-local coordinates" I think precident and
convention is strong enough that the answer to at least one of those
questions would likely be 'yes'.  But I don't imagine very many people
would be using the "window-local coordinates" phrasing; "window
coordinates" seems the more likely convention to stick.  For buffers, I
suspect the same to be true.

> I am in favor of the latter, despite this meaning that I'm arguing
> against my own patches.[3]
> 
> Thanks for reading,
> yong
> 
> 
> [1] The cover letter notes that this will contain a couple of merge
>     conflicts with https://patchwork.freedesktop.org/patch/79737/.
>     Correcting the conflicts should be straightforward when merging.

Well let's go ahead and land that one then.  There's been ample time for
comment by now, and further waiting is likely to accumulate further
merge conflicts.

> [2] The cover letter notes that the changes to the ivi-* stuff only
>     corrects the use of surface-local, and intentionally does not 
>     attempt to improve the clarity of the docs. As such, a couple
>     lines are still unclear or use incorrect grammar, which is
>     outside the scope of these patches.
> [3] Thanks for discussing something that feels a little mundane,
>     despite the importance of documentation. One day I'll contribute
>     actual code like the big boys and girls.

Thanks for your work on this.

Don't discount the importance of documentation work.  The protocol and
its docs are really the core essence of the Wayland project so I should
think doc improvements are at least on par with improvements to the code
itself.

Bryce