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@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
