wayland.xml style guide and whitespace fix

[Jonas Ådahl]

On Wed, Mar 30, 2016 at 08:40:46AM -0500, Yong Bakos wrote:
> 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"/>

I think these types of changes are fine.

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

It was at some point concluded that a tab were far more common than
8 spaces, so lets not change that. More or less all new protocols in
wayland-protocols use this. Writing XML style guidelines seems like a
good idea to me though. Note that at some places the summary="..." is
written on a separate line, aligned with the first attribute, when the
summary is long enough to make it stand out too much.

FWIW, I see no point fixing all the indentation inconsistencies
wayland.xml; it adds nothing significant of value and still complicates
backtracking changes (yes, I know of -w).


Jonas

> 
> Thanks for your time and all things Wayland,
> yong
> 
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel