Re: schema files

[Ole Laursen <olau hardworking dk>]

Christian Rose <menthos@gnome.org> writes:

> mån 2003-07-14 klockan 14.35 skrev Ole Laursen:

[...]

> > I agree with that - but many things are more or less self-evident. For
> > instance, the key "applet_height". Having "Applet height" is OK for a
> > short text, but adding "Height of the applet in pixels." for the long
> > text is non-sensical. One might as well reformulate the short text to
> > "Applet height in pixels".
> 
> I think having the <short> description as short as possible is a useful
> goal -- this makes the relevant keys easier to find in long listings of
> keys. Further details about units used, different possible values etc.
> should go into the <long> one. This helps keeping the <short>
> descriptions as just short, human-readable "names" for the keys.

What listing?

I think your goal is a worthwhile one in it self, but not what has
happened and what was intended. It is called "short description" after
all. Most of the <short> texts out there are descriptions, not names.
If everyone agrees to changing that, I agree that any extra info
should be pushed to the long descriptions.

> > > More work for us, but fulfilling the user's needs are more important.
> > 
> > Sure. I think the advice needs to be elaborated. What about:
> > 
> >   i) Make sure you have <short> and _useful_ <long> descriptions for
> >      all keys. If a <long> description does not contain any new
> >      information (e.g. if it is just a reformulation of the <short>
> >      description), it is usually better to leave it out; it will just
> >      create more work for the translators.
> 
> As mentioned above, I don't think I agree with this. Even if a <long>
> description is just a slightly more verbose reformulation of the <short>
> one, I do think it helps.

Could you provide an example? Of course, sometimes using other words
might help. But I don't want to waste time on texts as:

  Applet height (short)
  Height of applet. (long)

Without a reformulation, that is what you is going to get (in fact, it
is what we have today for some modules). I have an example from the panel:

  <key>/schemas/apps/fish_applet/prefs/command</key>

  <short>Command to execute on click</short>

  <long>This key specifies the command that will be tried to execute
  when the fish is clicked. </long>

If you cut the completely superfluous "This key specifies" away (which
I would in the translation), the long text only adds the information
that it is the fish that is clicked. But it adds a lot of verbosity
which is very time consuming to translate.

OTOH, if <short> is to be a human-readable meaningful name, e.g. if it
is "Command on click", I think "The command that will be tried to
execute when the fish is clicked." is OK.

-- 
Ole Laursen
http://www.cs.auc.dk/~olau/