Naming Policy; was: gnucash 2.6.19 dutch translation [and all others]

[Geert Janssens]

Op vrijdag 19 januari 2018 19:47:39 CET schreef John Ralls:
> > On Jan 19, 2018, at 9:08 AM, Frank H. Ellenberger
> > <frank.h.ellenberger at gmail.com> wrote:> 
> > Am 19.01.2018 um 16:00 schrieb Geert Janssens:
> >> As we're changing option strings I decided to verify this as well simply
> >> because we have to be extra careful in this area: option *names* can't be
> >> marked  for translation with '(_...)' except when actually printed on
> >> screen. That's probably why the '(N_...)' meaning "mark as translatable,
> >> but don't translate here". Luckily the strings that are the subject of
> >> this thread are not option *names* but option *default values*.
> > 
> > From my GUI review there is often a third: *Label*, usualy the
> > translatable name containing an underscore marking the mnemonic in
> > dialogs and menus.
> > 
> > Perhaps we should define and start to apply a naming convention for
> > this, eg.:
> > 
> > Id: untranslatable Key
> > 
> > Name: may have the same content in english, but is translatable, can be
> > used as parameter "This %s ..."
> > 
> > Label(s): gets as default a copy of Name, but should be adjusted to have
> > a mnemonic. In rare cases there migth be colissions of mnenoics in the
> > context of one or the other dialog.
> > 
> > Default:
> > 
> > Other Content?
> > 
> > Your thoughts?
> 
> Frank started https://wiki.gnucash.org/wiki/GUI_Guidelines with some quotes
> from an IRC discussion he and I had a couple of weeks ago about mnemonics
> and accelerators. It could use some more detail.
> 
> Regards,
> John Ralls

Depending on which option code you check, there will be even more strings 
involved. For example, aside from the label, there is often also a description 
or a tooltip still. Or for multi-choice and combobox options the combobox 
alternatives have translatable strings as well.

The ones requiring most attention here are id, name and label.

Let me start with a small detour to give some context. In the current code we 
use different options/preference systems.

For example we have the report options and book properties that are built on 
top of the option code written primarily in scheme (app-utils/options.scm) 
using a gui that's mostly hard-coded/pre-programmed (gnome-utils/dialog-
options.c).

But we also have a preferences system based on gsettings which stores settings 
in a platform dependent backend (dconf/win-registry/osx-defaults-plists). Part 
of these settings are not even gui related or gui controllable. Many of them 
are controlled via the Preferences dialog, which is laid out via a glade file. 
But another part is controlled by gui's throughout the code.

There are a few other ways we store settings or state, but they are not gui 
related so I'll just ignore those for the remainder of this mail.

I'm mentioning this because the gui capabilities/requirements of the different 
options systems vary. For example you mention labels. In the case of the 
Preferences dialog the developer has complete control over them as they can be 
set in the glade file. The use of glade files comes with the advantage that 
the presentation of the option is separate from it's internal model. So the 
label, the name and the id are independent of each other.

For the options.scm/dialog-options.c based system this is not the case. Here 
this label is constructed by taking the option name and adding a colon to it. 
And the id is the same as the name, except when we wan the name, we translate 
it and when we want the id we don't.

So in that system the option name, label and id are hardwired together. Each 
change will always change all three of these, because that's how the code is 
currently written. It's a design pattern that unfortunately appears in many 
places in gnucash, not only in the options code.

This is a serious design flaw we will have to fix in the conversion to C++. It 
will be a challenge to do so in a backwards compatible way. This may not be 
possible so it may be we have to break compatibility at that point, though at 
least we should be able to convert from the old to the new. That may already 
become a huge challenge in itself...

Geert