From fe98b789f0bb6714a13de30ca056267de62950df Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Thu, 29 Mar 2018 16:50:02 -0400
Subject: [PATCH] [locale] Document the settings in locale.conf

 - The geoipUrl is weird, because it is not a complete URL.
   Document that, and what kind of data is expected.

FIXES #920
---
 src/modules/locale/locale.conf | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/modules/locale/locale.conf b/src/modules/locale/locale.conf
index 824c8abeb..88148f47a 100644
--- a/src/modules/locale/locale.conf
+++ b/src/modules/locale/locale.conf
@@ -1,7 +1,33 @@
 ---
+# The starting timezone (e.g. the pin-on-the-map) when entering
+# the locale page can be set through keys *region* and *zone*.
+# If either is not set, defaults to America/New_York.
+#
 region:                     "America"
 zone:                       "New_York"
 
-# GeoIP settings. Leave commented out to disable GeoIP.
+# Some distros come with a meaningfully commented and easy to parse
+# `/etc/locale.gen`, and others ship a separate file
+# `/usr/share/i18n/SUPPORTED` with a clean list of supported locales.
+# We first try SUPPORTED, and if it doesn't exist, we fall back
+# to parsing the lines from `locale.gen`. For distro's that ship
+# the `locale.gen` file installed elsewhere, the key *localeGenPath*
+# can be used to specify where it is. If not set, the default
+# `/etc/locale.gen` is used.
+#
 #localeGenPath:             "/etc/locale.gen"
+
+# GeoIP settings. Leave commented out to disable GeoIP.
+#
+# An HTTP request is made to http://*geoipUrl*/json (which just happens
+# to be the GET path needed by freegeoip.net, so calling this a URL
+# is a stretch). The request must return valid JSON data; there should
+# be an attribute *time_zone*, with a string value set to the
+# timezone, in <region>/<zone> form.
+#
+# Suitable data looks like
+# ```
+#    {"time_zone":"America/New_York"}
+# ```
+#
 #geoipUrl:                  "freegeoip.net"