From 64c1056af13cac752560fedf02e079b849660fdd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Imobach=20Gonz=C3=A1lez=20Sosa?= <igonzalezsosa@suse.com>
Date: Wed, 29 Nov 2023 07:19:35 +0000
Subject: [PATCH] Update Locale D-Bus documentation

---
 .../bus/org.opensuse.Agama1.Locale.bus.xml    | 48 +++++++++------
 doc/dbus/org.opensuse.Agama1.Locale.doc.xml   | 61 ++++++++++---------
 2 files changed, 59 insertions(+), 50 deletions(-)

diff --git a/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml b/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml
index 38416bd6bc..850570b618 100644
--- a/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml
+++ b/doc/dbus/bus/org.opensuse.Agama1.Locale.bus.xml
@@ -38,39 +38,47 @@
   </interface>
   <interface name="org.opensuse.Agama1.Locale">
     <!--
-     Get labels for locales. The first pair is english language and territory
-     and second one is localized one to target language from locale.
+     Gets the supported locales information.
+
+     Each element of the list has these parts:
+
+     * The locale code (e.g., "es_ES.UTF-8").
+     * A pair composed by the language and the territory names in english
+       (e.g. ("Spanish", "Spain")).
+     * A pair composed by the language and the territory names in its own language
+       (e.g. ("Español", "España")).
      -->
-    <method name="LabelsForLocales">
-      <arg type="a((ss)(ss))" direction="out"/>
+    <method name="ListLocales">
+      <arg type="a(sss)" direction="out"/>
     </method>
     <!--
-     Gets list of locales available on system.
+     Returns a list of the supported keymaps.
 
-     # Examples
+     Each element of the list contains:
 
-     ```
-       use agama_dbus_server::locale::Locale;
-       let locale = Locale::new();
-       assert!(locale.list_ui_locales().unwrap().len() > 0);
-     ```
+     * The keymap identifier (e.g., "es" or "es(ast)").
+     * The name of the keyboard in language set by the UILocale property.
      -->
-    <method name="ListUILocales">
-      <arg type="as" direction="out"/>
-    </method>
-    <method name="ListVConsoleKeyboards">
-      <arg type="as" direction="out"/>
+    <method name="ListKeymaps">
+      <arg type="a(ss)" direction="out"/>
     </method>
+    <!--
+     Returns a list of the supported timezones.
+
+     Each element of the list contains:
+
+     * The timezone identifier (e.g., "Europe/Berlin").
+     * A list containing each part of the name in the language set by the
+       UILocale property.
+     -->
     <method name="ListTimezones">
-      <arg name="locale" type="s" direction="in"/>
-      <arg type="a(ss)" direction="out"/>
+      <arg type="a(sas)" direction="out"/>
     </method>
     <method name="Commit">
     </method>
+    <property name="Keymap" type="s" access="readwrite"/>
     <property name="Locales" type="as" access="readwrite"/>
-    <property name="SupportedLocales" type="as" access="readwrite"/>
     <property name="Timezone" type="s" access="readwrite"/>
     <property name="UILocale" type="s" access="readwrite"/>
-    <property name="VConsoleKeyboard" type="s" access="readwrite"/>
   </interface>
 </node>
diff --git a/doc/dbus/org.opensuse.Agama1.Locale.doc.xml b/doc/dbus/org.opensuse.Agama1.Locale.doc.xml
index 8844528be1..03120855a6 100644
--- a/doc/dbus/org.opensuse.Agama1.Locale.doc.xml
+++ b/doc/dbus/org.opensuse.Agama1.Locale.doc.xml
@@ -1,47 +1,48 @@
-
-<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
- "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<?xml version="1.0" encoding="UTF-8"?>
 <node>
-  <!--
-      org.opensuse.Agama1.Locale:
-
-      Implementation note about language identifiers:
-
-      Maybe use <ulink url="https://www.rubydoc.info/github/yast/yast-packager/master/LanguageTag">yast2-packager/LanguageTag</ulink>.
-      See <ulink url="https://lists.opensuse.org/archives/list/yast-devel&commat;lists.opensuse.org/message/D52PSZ7TRID2RVM6CE6K2C2RUNNGOS6Z/">its announcement on yast-devel</ulink>.
-      See also <ulink url="https://tools.ietf.org/html/rfc4647">RFC 4647 Matching of Language Tags</ulink>.
-  -->
   <interface name="org.opensuse.Agama1.Locale">
     <!--
-     Get labels for locales. The first pair is english language and territory
-     and second one is localized one to target language from locale.
+     Gets the supported locales information.
+
+     Each element of the list has these parts:
+
+     * The locale code (e.g., "es_ES.UTF-8").
+     * A pair composed by the language and the territory names in english
+       (e.g. ("Spanish", "Spain")).
+     * A pair composed by the language and the territory names in its own language
+       (e.g. ("Español", "España")).
      -->
-    <method name="LabelsForLocales">
-      <arg type="a((ss)(ss))" direction="out"/>
+    <method name="ListLocales">
+      <arg type="a(sss)" direction="out"/>
     </method>
     <!--
-     Gets list of locales available on system.
+     Returns a list of the supported keymaps.
+
+     Each element of the list contains:
+
+     * The keymap identifier (e.g., "es" or "es(ast)").
+     * The name of the keyboard in language set by the UILocale property.
      -->
-    <method name="ListUILocales">
-      <arg type="as" direction="out"/>
-    </method>
-    <method name="ListVConsoleKeyboards">
-      <arg type="as" direction="out"/>
+    <method name="ListKeymaps">
+      <arg type="a(ss)" direction="out"/>
     </method>
+    <!--
+     Returns a list of the supported timezones.
+
+     Each element of the list contains:
+
+     * The timezone identifier (e.g., "Europe/Berlin").
+     * A list containing each part of the name in the language set by the
+       UILocale property.
+     -->
     <method name="ListTimezones">
-      <arg name="locale" type="s" direction="in"/>
-      <arg type="a(ss)" direction="out"/>
+      <arg type="a(sas)" direction="out"/>
     </method>
     <method name="Commit">
     </method>
+    <property name="Keymap" type="s" access="readwrite"/>
     <property name="Locales" type="as" access="readwrite"/>
-    <property name="SupportedLocales" type="as" access="readwrite"/>
     <property name="Timezone" type="s" access="readwrite"/>
-    <!--
-     Property that controls in which localization human string from backend will come.
-     -->
     <property name="UILocale" type="s" access="readwrite"/>
-    <property name="VConsoleKeyboard" type="s" access="readwrite"/>
   </interface>
 </node>
-