[locale] Update to use newer configuration

- deprecate the old entries
 - use a geoip sub-map for GeoIP configuration
 - polish up documentation
 - drop mention of blank and "legacy" styles for GeoIP config,
   just update your URLs already.

CHANGES

@@ -24,6 +24,11 @@ This release contains contributions from (alphabetically by first name):
 
 ## Modules ##
 
+ - *locale* module GeoIP configuration has a new preferred format.
+   See `locale.conf` for details. The old configuration is still
+   supported but will be phased out before 3.3.0 -- in particular,
+   support for "legacy" format will be removed, since that was a
+   crutch for the disappearance of one GeoIP provider in 2018.
  - *oemid* is a new module for configuring OEM phase-0 (image pre-mastering,
    or pre-deployment) things. It has limited functionality at the moment,
    writing only a single batch-identifier file.

src/modules/locale/LocaleViewStep.cpp

@@ -225,14 +225,28 @@ LocaleViewStep::setConfigurationMap( const QVariantMap& configurationMap )
     if ( m_localeGenPath.isEmpty() )
         m_localeGenPath = QStringLiteral( "/etc/locale.gen" );
 
-    // Optional
+    bool ok = false;
-    m_geoipUrl = CalamaresUtils::getString( configurationMap, "geoipUrl" );
+    QVariantMap geoip = CalamaresUtils::getSubMap( configurationMap, "geoip", ok );
-    m_geoipStyle = CalamaresUtils::getString( configurationMap, "geoipStyle" );
+    if ( ok )
-    m_geoipSelector = CalamaresUtils::getString( configurationMap, "geoipSelector" );
-
-    if ( !m_geoipUrl.isEmpty() && ( m_geoipStyle.isEmpty() || m_geoipStyle == "legacy" ) )
     {
-        m_geoipStyle = "json";
+        m_geoipUrl = CalamaresUtils::getString( geoip, "url" );
-        m_geoipUrl.append( "/json/" );
+        m_geoipStyle = CalamaresUtils::getString( geoip, "style" );
+        m_geoipSelector = CalamaresUtils::getString( geoip, "selector" );
+    }
+    else
+    {
+        // Optional
+        m_geoipUrl = CalamaresUtils::getString( configurationMap, "geoipUrl" );
+        m_geoipStyle = CalamaresUtils::getString( configurationMap, "geoipStyle" );
+        m_geoipSelector = CalamaresUtils::getString( configurationMap, "geoipSelector" );
+
+        if ( !m_geoipUrl.isEmpty() && ( m_geoipStyle.isEmpty() || m_geoipStyle == "legacy" ) )
+        {
+            m_geoipStyle = "json";
+            m_geoipUrl.append( "/json/" );
+        }
+
+        if ( !m_geoipUrl.isEmpty() )
+            cWarning() << "Legacy-style GeoIP configuration is deprecated. Use geoip: map.";
     }
 }

src/modules/locale/locale.conf

@@ -25,21 +25,46 @@ zone:                       "New_York"
 # custom path for locale.gen
 #localeGenPath:             "PATH_TO/locale.gen"
 
-# GeoIP based Language settings:
+# GeoIP based Language settings: Leave commented out to disable GeoIP.
 #
-# GeoIP need an working Internet connection.
+# GeoIP needs a working Internet connection.
 # This can be managed from `welcome.conf` by adding
 # internet to the list of required conditions.
 #
-# Leave commented out to disable GeoIP.
+# The configuration
+# is in three parts: a *style*, which can be "json" or "xml"
+# depending on the kind of data returned by the service, and
+# a *url* where the data is retrieved, and an optional *selector*
+# to pick the right field out of the returned data (e.g. field
+# name in JSON or element name in XML).
 #
-# An HTTP request is made to *geoipUrl* -- depending on the geoipStyle,
+# The default selector (when the setting is blank) is picked to
-# the URL may be modified before use. The request should return
+# work with existing JSON providers (which use "time_zone") and
-# valid data in a suitable format, depending on geoipStyle;
+# Ubiquity's XML providers (which use "TimeZone").
+#
+# If the service configured via *url* uses
+# a different attribute name (e.g. "timezone") in JSON or a
+# different element tag (e.g. "<Time_Zone>") in XML, set this
+# string to the name or tag to be used.
+#
+# In JSON:
+#  - if the string contains "." characters, this is used as a
+#    multi-level selector, e.g. "a.b" will select the timezone
+#    from data "{a: {b: "Europe/Amsterdam" } }".
+#  - each part of the string split by "." characters is used as
+#    a key into the JSON data.
+# In XML:
+#  - all elements with the named tag (e.g. all TimeZone) elements
+#    from the document are checked; the first one with non-empty
+#    text value is used.
+#
+#
+# An HTTP(S) request is made to *url*. The request should return
+# valid data in a suitable format, depending on *style*;
 # generally this includes a string value with the timezone
 # in <region>/<zone> format. For services that return data which
 # does not follow the conventions of "suitable data" described
-# below, *geoIPSelector* may be used to pick different data.
+# below, *selector* may be used to pick different data.
 #
 # Note that this example URL works, but the service is shutting
 # down in June 2018.
@@ -58,40 +83,9 @@ zone:                       "New_York"
 #  - backslashes are removed
 #  - spaces are replaced with _
 #
-#geoipUrl:                  "freegeoip.net"
+# Legacy settings "geoipStyle", "geoipUrl" and "geoipSelector"
-
+# in the top-level are still supported, but I'd advise against.
-# GeoIP style. Leave commented out for the "legacy" interpretation.
+geoip:
-# This setting only makes sense if geoipUrl is set, enabliing geoIP.
+    style:  "json"
-#
+    url:    "https://geoip.kde.org/v1/calamares"
-# Possible values are:
+    selector: ""  # leave blank for the default
-#   unset       same as "legacy"
-#   blank       same as "legacy"
-#   "legacy"    appends "/json" to geoipUrl, above, and uses JSON format
-#               (which is what freegeoip.net provides there).
-#   "json"      URL is not modified, uses JSON format.
-#   "xml"       URL is not modified, uses XML format.
-#
-# The JSON format is provided by freegeoip.net, but that service is
-# shutting down in June 2018. There are other providers with the same
-# format. XML format is provided for Ubiquity.
-#geoipStyle:    "legacy"
-
-# GeoIP selector. Leave commented out for the default selector
-# (which depends on the style: JSON uses "time_zone" and XML
-# uses TimeZone, for the FreeGeoIP-alike and the Ubiquity-alike
-# respectively). If the service configured via *geoipUrl* uses
-# a different attribute name (e.g. "timezone") in JSON or a
-# different element tag (e.g. "<Time_Zone>") in XML, set this
-# string to the name or tag to be used.
-#
-# In JSON:
-#  - if the string contains "." characters, this is used as a
-#    multi-level selector, e.g. "a.b" will select the timezone
-#    from data "{a: {b: "Europe/Amsterdam" } }".
-#  - each part of the string split by "." characters is used as
-#    a key into the JSON data.
-# In XML:
-#  - all elements with the named tag (e.g. all TimeZone) elements
-#    from the document are checked; the first one with non-empty
-#    text value is used.
-#geoipSelector: ""