wayland.xml style guide and whitespace fix

Yong Bakos junk at humanoriented.com
Wed Mar 30 13:40:46 UTC 2016

Hi fellow hackers,
I'm working on documentation fixes within wayland.xml and I'm noticing two major inconsistencies that I would like to address. The first is writing-related.

Some enum entry summary attribute values start with a capital letter, while the majority do not. I'd like to standardize this so all attribute summaries are consistent. Are we cool with me fixing the inconsistencies in existing summary values? Example:

<entry name="pointer" value="1" summary="The seat has pointer devices"/>

Would become:

<entry name="pointer" value="1" summary="the seat has pointer devices"/>

More importantly, I'd like to incorporate some simple "writing rules" in a style guide for wayland.xml. 

Second, the existing whitespace "rule" that is followed is a bit inconsistent. In short, the precedent is "use two spaces to indent, unless you're indenting >= 8 spaces, in which case use a tab and use a tab width of 8 spaces in your editor." This isn't followed consistently, and a simple rule would be "indent two spaces."

I know that whitespace fixes can clutter a blame, but blame's -w option should alleviate this annoyance. I'd like to a) standardize the whitespace in wayland.xml and b) add the rule to the style guide. (Note: This isn't about tabs v spaces, rather, just making sure that all indentation follows the same rule. I do personally feel a more simple rule "indent 2 spaces" is easier to follow than the existing convention, which has led to the inconsistency.)

To summarize, I'd like to know if you'd be ok with these two kinds of changes (capitalization and whitespace), and that I'll create a patch for a style guide that we can comment on separately.

Thanks for your time and all things Wayland,

More information about the wayland-devel mailing list