standardizing "surface-local coordinates"

[Yong Bakos]

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