[libgweather/ebassi/gtk4] docs: Move readmes in data under docs

[Emmanuele Bassi <ebassi src gnome org>]

commit 7df02058e921900fa28883a54a0cd674312590c0
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Oct 11 21:56:26 2021 +0100

    docs: Move readmes in data under docs
    
    They are very non-descriptive as "read me" files.

 data/README             | 95 ------------------------------------------------
 data/README.timezones   | 47 ------------------------
 doc/locations-format.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/time-zones.md       | 42 +++++++++++++++++++++
 4 files changed, 139 insertions(+), 142 deletions(-)
---
diff --git a/doc/locations-format.md b/doc/locations-format.md
new file mode 100644
index 00000000..cd911bbe
--- /dev/null
+++ b/doc/locations-format.md
@@ -0,0 +1,97 @@
+## The Locations file format
+
+The format of `Locations.xml` is the following:
+
+```xml
+<gweather format="1.0">
+  <region>
+    <_name>North America</_name>
+    <country>
+      <_name>United States</_name>
+      <iso-code>US</iso-code>
+      <state>
+        <_name>Alabama</_name>
+        <tz-hint>America/Chicago</tz-hint>
+        <location>
+          <!-- Translators: This is in Alabama in the United States. -->
+          <_name>Alabaster</_name>
+          <code>KEET</code>
+          <zone>ALZ019</zone>
+          <radar>bhm</radar>
+          <coordinates>33-10-42N 086-46-54W</coordinates>
+        </location>
+        <city>
+          <!-- Translators: This is in Alabama in the United States. -->
+          <_name>Mobile</_name>
+          <location>
+            <!-- Translators: This is in Mobile, Alabama in the United States. -->
+            <_name>Mobile Downtown Airport</_name>
+            <code>KBFM</code>
+            <zone>ALZ061</zone>
+            <radar>bix</radar>
+            <coordinates>30-36-50N 088-03-48W</coordinates>
+          </location>
+        </city>
+        ...
+```
+
+Translatable elements are prefixed with an underscore (`_`) in the
+`Locations.xml` file, to allow localization.
+
+Most of the data in the file appears inside `<location>` entries.
+However, various larger geographic divisions exist to make things
+easier for both users and maintainers.
+
+At the top level are `<region>`s. These mostly correspond to continents,
+but not entirely. They are arbitrary, and could be changed in the
+future if we wanted.
+
+Each `<region>` is divided into `<country>` elements. Every internationally-
+recognized country for which at least one `<location>` is defined should
+have its own `<country>`. For the most part, "dependencies",
+"territories", "protectorates" and the like are listed as `<location>`s
+within their ruling country if they are in the same `<region>`, but
+separately if they are in a different `<region>`. This is not followed
+100% consistently.
+
+Every `<country>` must have an `<iso-code>` tag giving its ISO 3166-1
+alpha-2 code. Sub-country `<location>`s can also specify their own
+`<iso-code>` if they have one.
+
+A `<country>` MAY specify a `<tz-hint>`, giving the default time zone name
+for the country. Countries that only have one timezone (or where the
+majority of the country is covered by a single timezone) should list it at
+the `<country>` level. Countries with multiple timezones and no obvious
+"default" should not list anything here. (See the [time zones
+documentation](./time-zones.md) for more information about time zones in
+`Locations.xml`.)
+
+A `<country>` can contain `<city>`s and `<location>`s directly, or can be
+split into `<state>`s which contain `<city>`s and `<location>`s. The name
+"state" comes from the US states, but it can be used to represent any
+sort of well-defined sub-country region that has a name which will be
+familiar to local users. A `<state>` may specify a `<tz-hint>` which will
+override the `<country>`'s `<tz-hint>` for `<location>`s within the state.
+
+`<city>` is an optional element used to group together multiple
+`<location>`s within the same city.
+
+Finally, a `<location>` represents a location for which weather data can
+be retrieved. Its fields are:
+
+- `<_name>`: required, the name of the location as a translatable string
+- `<iso-code>`: optional, the ISO 3166 code of the location, if not the same
+  as its parent `<country>`
+- `<tz-hint>`: optional, the timezone of the location, if not the same as
+  its parent `<state>` or `<country>`
+- `<code>`: required, the METAR code identifying this location
+- `<zone>`: optional, secondary weather source information:
+  - US: the NOAA IWIN zone
+  - UK: the Met Office region name, prefixed with ":"
+  - AU: the BOM forecast name, prefixed with "@"
+- `<radar>`: optional, the Weather.com radar map name for the location
+  (North America only)
+- `<coordinates>`: optional, the latitude and longitude of the location, as
+  `"[-]ddd.dddddd [-]ddd.dddddd"`:
+  - positive values are North and East, respectively
+  - negative values are South and West, respectively
diff --git a/doc/time-zones.md b/doc/time-zones.md
new file mode 100644
index 00000000..9134542b
--- /dev/null
+++ b/doc/time-zones.md
@@ -0,0 +1,42 @@
+Notes on assigning `<tz-hint>`s
+-----------------------------
+
+The `<tz-hint>` field in `Locations.xml` is used by GNOME Clocks to
+guess the correct time zone that goes with a particular location. As
+the tag name suggests, it is just a hint; the user could be allowed
+to override it if the guess is wrong. Still, it is nice to have
+them be as close to correct as possible.
+
+The timezone names come from the tzdata database; you should have a
+complete list of the current timezones names in
+`/usr/share/zoneinfo/zone.tab`. If you are going to be figuring out the
+timezones for a region, it may also be useful to grab the source data
+from ftp://elsie.nci.nih.gov/pub/. (The `tzdataXXXXX.tar.gz` file)
+
+The most important thing to realize about tzdata is that it has a separate
+time zone name for every region that has had its own distinct timezone rules
+*at any point since 1970* (the start of UNIX `time_t`).  This means that
+many of the timezones listed are no longer in use and can mostly be ignored.
+Eg, `zone.tab` lists 11 timezones for Argentina, even though as of 2008 all
+of Argentina is in the same timezone.
+
+In the cases where tzdata has more timezones for a country than the
+government of that country recognizes, `Locations.xml` tries to pick one
+tzdata timezone to correspond to each government-defined timezone, and uses
+those timezones throughout the country rather than using the
+historically-more-specific ones. (This will make it easier to localize the
+names of the timezones in the future.) So, eg, in the mainland United
+States, the four official timezones (Eastern, Central, Mountain, and
+Pacific) are mapped to "America/New\_York", "America/Chicago",
+"America/Denver", and "America/Los\_Angeles", respectively. Regions that
+have switched from one timezone to another in the past (such as parts of
+Kentucky and Indiana) are simply listed according to whichever timezone they
+are *currently* in, rather than picking an appropriate "micro-timezone" such
+as "America/Indiana/Indianapolis".
+
+Finally, the names of timezones will occasionally change between releases of
+tzdata. (Eg, "Asia/Calcutta" was recently renamed to "Asia/Kolkata" to match
+the new preferred spelling of that city.) `Locations.xml` should always use
+the most recent names, because distributions should always be shipping the
+most recent tzdata, to ensure that the daylight-savings-time rules for
+different countries match the latest government decrees.