GSettings - add 'deprecate' and 'obsolete' conversions for user preferences

'deprecate' is technically a noop. It serves to remind maintainers
the 'deprecated' preference is to be obsoleted in the next major
release.
'obsolete' goes one step further in that it will cause gnucash to reset
the preference, effectively clearing the value stored in the preferences
backend. This is the final phase of a preference. Following this it
will be completely removed from the GSettings schema in the next
major release.

Notes
* 'deprecate' and 'migrate' are related. Both are a reminder the
preference is to be obsoleted in the next major release. 'deprecate'
does only that though while 'migrate' will also trigger a copy of
the old value to a new location in the databse.

* This commit readds a couple of preferences that had been removed
in the past to be able to properly obsolete them (and to test
the obsoleting code)

gnucash/gschemas/org.gnucash.GnuCash.deprecated.gschema.xml.in

@@ -5,6 +5,12 @@
   </schema>
 
   <schema id="org.gnucash.general" path="/org/gnucash/general/">
+    <key name="migrate-prefs-done" type="b">
+      <default>false</default>
+      <summary>-Obsolete-</summary>
+      <description>This setting is obsolete and will be removed in the next major @PROJECT_NAME@ release series.</description>
+    </key>
+
     <key name="prefs-version" type="i">
       <default>0</default>
       <summary>The version of these settings</summary>
@@ -419,6 +425,26 @@ For example setting this to 2.0 will display reports at twice their typical size
     <child name="options" schema="org.gnucash.dialogs.options"/>
   </schema>
 
+  <schema id="org.gnucash.dialogs.business-assoc" path="/org/gnucash/dialogs/business-assoc/">
+    <key type="(iiii)" name="last-geometry">
+      <default>(-1,-1,-1,-1)</default>
+      <summary>Last window position and size</summary>
+      <description>This setting describes the size and position of the window when it was last closed.
+        The numbers are the X and Y coordinates of the top left corner of the window
+        followed by the width and height of the window.</description>
+    </key>
+  </schema>
+
+  <schema id="org.gnucash.dialogs.trans-assoc" path="/org/gnucash/dialogs/trans-assoc/">
+    <key type="(iiii)" name="last-geometry">
+      <default>(-1,-1,-1,-1)</default>
+      <summary>Last window position and size</summary>
+      <description>This setting describes the size and position of the window when it was last closed.
+        The numbers are the X and Y coordinates of the top left corner of the window
+        followed by the width and height of the window.</description>
+    </key>
+  </schema>
+
   <schema id="org.gnucash.dialogs.account" path="/org/gnucash/dialogs/account/">
     <key name="last-geometry" type="(iiii)">
       <default>(-1,-1,-1,-1)</default>

gnucash/gschemas/org.gnucash.GnuCash.gschema.xml.in

@@ -230,6 +230,7 @@
       <summary>Set book option on new files to use split "action" field for "Num" field on registers/reports</summary>
       <description>If selected, the default book option for new files is set so that the 'Num' cell on registers shows/updates the split 'action' field and the transaction 'num' field is shown on the second line in double line mode (and is not visible in single line mode). Otherwise, the default book option for new files is set so that the 'Num' cell on registers shows/updates the transaction 'num' field.</description>
     </key>
+
     <child name="register" schema="org.gnucash.GnuCash.general.register"/>
     <child name="report" schema="org.gnucash.GnuCash.general.report"/>
   </schema>

gnucash/gschemas/pref_transformations.xml

@@ -29,12 +29,42 @@
 
     Within a release node the following rules are currently supported:
 
+    <deprecate ... /> : does nothing other than informing GnuCash devs this
+                        preference will eventually be removed with no
+                        replacement. The preference should not be used anymore
+                        in GnuCash code directly.
+                        It takes two arguments (old-path and old-key) that
+                        together define the preference
+    <migrate   ... /> : informs GnuCash a preference has moved or has been
+                        renamed. The old preference should be treated  as
+                        deprecated and should not be used anymore in GnuCash
+                        code directly.
+                        It takes four arguments (old-path, old-key and
+                        new-path, new-key). The first two define the deprecated
+                        preference the last two the replacement preference.
+    <obsolete  ... /> : informs GnuCash this preference is ready to be removed
+                        in the next major release and will be unset in this
+                        major release series. This intermediary step is to
+                        clean up the settings database over time.
+                        It takes two arguments (old-path and old-key) that
+                        together define the preference
+    Example
+    =======
+
+    <release version="4007">
+
+    <deprecate old-path="org.gnucash.GnuCash.general"
+               old-key="prefname" />
+
     <migrate old-path="org.gnucash.general"
              old-key="prefs-version"
              new-path="org.gnucash.GnuCash.general"
              new-key="prefs-version" />
 
-    This will migrate the preference at old-path:old-key to new-path:new-key.
+    <obsolete old-path="org.gnucash.general"
+              old-key="migrate-prefs-done" />
+
+    </release>
 
 
     Note
@@ -1342,3 +1372,16 @@
          new-key="end-period"/>
 
 </release>
+
+<release version="4009">
+
+<obsolete old-path="org.gnucash.dialogs.business-assoc"
+          old-key="last-geometry"/>
+
+<obsolete old-path="org.gnucash.dialogs.trans-assoc"
+          old-key="last-geometry"/>
+
+<obsolete old-path="org.gnucash.general"
+          old-key="migrate-prefs-done"/>
+
+</release>

libgnucash/app-utils/gnc-gsettings.cpp

@@ -655,15 +655,51 @@ gnc_gsettings_get_user_value (const gchar *schema,
     }
 }
 
+using opt_str_vec = boost::optional<std::string>;
+
+static void
+deprecate_one_key (const opt_str_vec &oldpath, const opt_str_vec &oldkey)
+{
+    if (!oldpath || !oldkey )
+    {
+        DEBUG ("Skipping <deprecate> node - missing attribute (old-path or old-key)");
+        return;
+    }
+
+    PINFO ("'%s:%s' has been marked deprecated", oldpath->c_str(), oldkey->c_str());
+    /* This does nothing really, but is a reminder for future maintainers
+     * to mark this pref as obsolete in the next major release. */
+}
+
 static void
-migrate_one_key (const std::string &oldpath, const std::string &oldkey,
-                 const std::string &newpath, const std::string &newkey)
+migrate_one_key (const opt_str_vec &oldpath, const opt_str_vec &oldkey,
+                 const opt_str_vec &newpath, const opt_str_vec &newkey)
 {
-    PINFO ("Migrating '%s:%s' to '%s:%s'", oldpath.c_str(), oldkey.c_str(),
-           newpath.c_str(), newkey.c_str());
-    auto user_value = gnc_gsettings_get_user_value (oldpath.data(), oldkey.data());
+    if (!oldpath || !oldkey || !newpath || !newkey)
+    {
+        DEBUG ("Skipping <migrate> node - missing attribute (old-path, old-key, new-path or new-key)");
+        return;
+    }
+
+    PINFO ("Migrating '%s:%s' to '%s:%s'", oldpath->c_str(), oldkey->c_str(),
+           newpath->c_str(), newkey->c_str());
+
+    auto user_value = gnc_gsettings_get_user_value (oldpath->c_str(), oldkey->c_str());
     if (user_value)
-        gnc_gsettings_set_value (newpath.data(), newkey.data(), user_value);
+        gnc_gsettings_set_value (newpath->c_str(), newkey->c_str(), user_value);
+}
+
+static void
+obsolete_one_key (const opt_str_vec &oldpath, const opt_str_vec &oldkey)
+{
+    if (!oldpath || !oldkey )
+    {
+        DEBUG ("Skipping <obsolete> node - missing attribute (old-path or old-key)");
+        return;
+    }
+
+    PINFO ("Resetting obsolete '%s:%s'", oldpath->c_str(), oldkey->c_str());
+    gnc_gsettings_reset (oldpath->c_str(), oldkey->c_str());
 }
 
 static void
@@ -675,19 +711,17 @@ parse_one_release_node (bpt::ptree &pt)
             {
                 if (node.first == "<xmlattr>")
                     return;
-                if (node.first == "migrate")
-                {
-                    auto oldpath = node.second.get_optional<std::string> ("<xmlattr>.old-path");
-                    auto oldkey = node.second.get_optional<std::string> ("<xmlattr>.old-key");
-                    auto newpath = node.second.get_optional<std::string> ("<xmlattr>.new-path");
-                    auto newkey = node.second.get_optional<std::string> ("<xmlattr>.new-key");
-                    if (!oldpath || !oldkey || !newpath || !newkey)
-                    {
-                        DEBUG ("Skipping migration node - missing attribute (old-path, old-key, new-path or new-key)");
-                        return;
-                    }
-                    migrate_one_key (*oldpath, *oldkey, *newpath, *newkey);
-                }
+                else if (node.first == "deprecate")
+                    deprecate_one_key (node.second.get_optional<std::string> ("<xmlattr>.old-path"),
+                                       node.second.get_optional<std::string> ("<xmlattr>.old-key"));
+                else if (node.first == "migrate")
+                    migrate_one_key (node.second.get_optional<std::string> ("<xmlattr>.old-path"),
+                                     node.second.get_optional<std::string> ("<xmlattr>.old-key"),
+                                     node.second.get_optional<std::string> ("<xmlattr>.new-path"),
+                                     node.second.get_optional<std::string> ("<xmlattr>.new-key"));
+                else if (node.first == "obsolete")
+                    obsolete_one_key (node.second.get_optional<std::string> ("<xmlattr>.old-path"),
+                                      node.second.get_optional<std::string> ("<xmlattr>.old-key"));
                 else
                 {
                     DEBUG ("Skipping unknown node <%s>", node.first.c_str());