Re: desktop schemas review [was: Re: GSettings migration status]

[Ryan Lortie <desrt desrt ca>]

On Sat, 2010-07-03 at 13:37 +0200, Christian Persch wrote:
> Coincidentally, taking a look at all the <summary> and <description>
> strings, it seems to me that once these value enumerations are taken
> out, not too much remains that justifies the split between two
> strings.
> IMHO we should consider dropping <summary> from gschema and only
> provide for the one <description> strings.
> 
I'm of a mixed mind on this.

On one hand I'm sort of sick of coming up with 3 strings (of slightly
increasing verbosity) to describe my GObject properties and the same
sort of logic comes into play here.

On the other hand, I notice that the typical format for git commit
messages is actually extremely helpful.  Just because we presently don't
have any tools that take advantage of the summary (ie: by showing it
somewhere that the full description is not showing) doesn't mean that
it's pointless as a concept.

One thing I'd like to point to:

   https://bugzilla.gnome.org/show_bug.cgi?id=620562

The intention is that everything that interacts with the description
will do whitespace handling similar to the way Owen described in the
bug.

As implemented, in intltool for example:

<description>
  This is a description.

  Woo.  Multiple paragraphs.
</description>

will end up as "This is a description.\n\nWoo. Multiple paragraphs."
which should end up being shown reasonably well in UIs.

((note the folding of the spaces between "Woo." and "Multiple"))

So as a matter of style, I recommend writing summary and description
like so:

<key>
  <summary>This is a short summary (50 char rule, anyone?)</summary>
  <description>
    Even short one-paragraph descriptions should be done like this.
    Wrap at 72, please.
  </description>
</key>


Since we're discussing style, I'll also mention that I'm a fan of
vertical whitespace and that each key should probably have a newline
between:

     ...
   </key>

   <key name='next' type='s'>
     ...

and schemas definitely.  Maybe even two newlines there.


Cheers