locale: add documentation

4 files changed, 134 insertions, 1 deletions

diff --git a/doc/admin/CMakeLists.txt b/doc/admin/CMakeLists.txt
index 96e7616..d33427f 100644
--- a/doc/admin/CMakeLists.txt
+++ b/doc/admin/CMakeLists.txt
@@ -62,6 +62,12 @@ if (WITH-SOFTWARE)
     set(PROVIDER_MOFS ${PROVIDER_MOFS} "60_LMI_Software.mof")
 endif (WITH-SOFTWARE)
 
+if (WITH-LOCALE)
+    set(PROVIDERS ${PROVIDERS} "locale")
+    set(PROVIDER_CAPTIONS ${PROVIDER_CAPTIONS} "Locale")
+    set(PROVIDER_MOFS ${PROVIDER_MOFS} "60_LMI_Locale.mof")
+endif (WITH-LOCALE)
+
 list(LENGTH PROVIDERS LEN)
 math(EXPR LEN '${LEN}-1')
 
diff --git a/doc/admin/locale/index.rst b/doc/admin/locale/index.rst
new file mode 100644
index 0000000..179c659
--- /dev/null
+++ b/doc/admin/locale/index.rst
@@ -0,0 +1,39 @@
+OpenLMI Locale Provider documentation
+=====================================
+OpenLMI Locale is CIM provider for managing Linux locale settings (using the
+`systemd/localed D-Bus interface <http://www.freedesktop.org/wiki/Software/systemd/localed/>`_).
+
+It allows to set system locale represented by environment variables (LANG,
+LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, LC_PAPER,
+LC_NAME, LC_ADDRESS, LC_TELEPHONE, LC_MEASUREMENT and LC_IDENTIFICATION),
+set the default key mapping of the X11 servers (keyboard layouts, model, variant
+and options) and the default key mapping for virtual console.
+
+If you set a new system locale with SetLocale() method, all old system locale
+settings will be dropped, and the new settings will be saved to disk. It will
+also be passed to the system manager, and subsequently started daemons will
+inherit the new system locale from it.
+
+Note that already running daemons will not learn about the new system locale.
+
+Also note that setting key mapping with SetVConsoleKeyboard() method instantly
+applies the new keymapping to the console, while setting the key mapping of X11
+server using SetX11Keyboard() method simply sets a default that may be used by
+later sessions.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+
+.. ifconfig:: includeClasses
+
+    OpenLMI Locale CIM Classes:
+
+    .. toctree::
+       :maxdepth: 1
+
+       mof/tree
+       mof/index
diff --git a/doc/admin/locale/usage.rst b/doc/admin/locale/usage.rst
new file mode 100644
index 0000000..2afad86
--- /dev/null
+++ b/doc/admin/locale/usage.rst
@@ -0,0 +1,71 @@
+OpenLMI Locale usage
+====================
+
+Some common use cases are described in the following parts.
+
+Getting locale settings
+-----------------------
+Create connection, get instance (assuming the default namespace 'root/cimv2' is used)::
+
+    c = connect("https://myhost")
+    # optionally create namespace alias
+    ns = c.root.cimv2
+    locale = ns.LMI_Locale.first_instance()
+
+Print what you're interested in::
+
+    # get LANG setting
+    print locale.Lang
+    # get X11Layouts
+    print locale.X11Layouts
+    # get VConsoleKeymap
+    print locale.VConsoleKeymap
+
+Or print everything::
+
+    # get all available settings
+    locale.doc()
+
+Setting system locale
+---------------------
+Set LANG and/or set individual locale variables. Lang, LCCType, LCAddress, LCNumeric,
+LCTelephone, LCCollate, LCPaper, LCMonetary, LCTime, LCMessages, LCIdentification,
+LCName and LCMeasurement properties correspond to likewise named Linux locale
+environmental variables::
+
+    # set LANG (LANG value is used also for all other locale categories by default)
+    locale.SetLocale(Lang="en_US.UTF-8")
+    # set LANG and set different value for LC_TELEPHONE
+    # note that SetLocale() clears previous setting - if you want to preserve
+    # LANG value, you have to set it again
+    locale.SetLocale(Lang="en_US.UTF-8",LCTelephone="cs_CZ.UTF-8")
+
+Setting default key mapping of the X11 servers
+----------------------------------------------
+Set default key mapping for X11 server::
+
+    locale.SetX11Keyboard(Layouts="de")
+
+Optionally set keyboard model and variant::
+
+    locale.SetX11Keyboard(Layouts="us",Model="dellsk8125",Variant="qwertz")
+
+Set more than one layout and set option for switching between them::
+
+    locale.SetX11Keyboard(Layouts="us,cz,de",Options="grp:alt_shift_toggle")
+
+You can set Convert parameter to 'True', mapping for virtual console will be set
+also then (nearest console keyboard setting for the chosen X11 setting)::
+
+    locale.SetX11Keyboard(Layouts="us",Convert="True")
+
+Setting default key mapping of the virtual console
+--------------------------------------------------
+Set default key mapping for virtual console::
+
+    locale.SetVConsoleKeyboard(Keymap="us")
+
+Again, setting Convert to 'True' will set the nearest X11 keyboard setting for
+the chosen console setting::
+
+    locale.SetVConsoleKeyboard(Keymap="us",Convert="True")
diff --git a/openlmi-providers.spec b/openlmi-providers.spec
index 6f962e6..4f3fc27 100644
--- a/openlmi-providers.spec
+++ b/openlmi-providers.spec
@@ -38,7 +38,7 @@
 
 Name:           openlmi-providers
 Version:        0.4.2
-Release:        12%{?dist}
+Release:        13%{?dist}
 Summary:        Set of basic CIM providers
 
 %if 0%{?suse_version}
@@ -517,6 +517,14 @@ Requires:       %{name}%{?_isa} = %{version}-%{release}
 
 %description -n openlmi-locale
 %{summary}.
+
+%package -n openlmi-locale-doc
+Summary:        CIM Locale provider documentation
+Group:          Documentation
+BuildArch:      noarch
+
+%description -n openlmi-locale-doc
+This package contains the documents for OpenLMI Locale provider.
 %endif
 
 %prep
@@ -655,6 +663,9 @@ for provider in \
 %if 0%{?with_realmd}
     realmd \
 %endif
+%if 0%{?with_locale}
+    locale \
+%endif
     software; do
 
     install -m 755 -d $RPM_BUILD_ROOT/%{_docdir}/%{name}/${provider}/admin_guide
@@ -890,6 +901,9 @@ cp -pr tools/openlmitheme/* $RPM_BUILD_ROOT/%{python_sitelib}/sphinx/themes/open
 %{_datadir}/%{name}/60_LMI_Locale.reg
 %{_datadir}/%{name}/90_LMI_Locale_Profile.mof
 %attr(755, root, root) %{_libexecdir}/pegasus/cmpiLMI_Locale-cimprovagt
+
+%files -n openlmi-locale-doc
+%{_docdir}/%{name}/locale/
 %endif
 
 %pre
@@ -1290,6 +1304,9 @@ fi >> %logfile 2>&1
 %endif
 
 %changelog
+* Mon Jun 09 2014 Vitezslav Crhonek <vcrhonek@redhat.com> - 0.4.2-13
+- Add openlmi-locale-doc subpackage
+
 * Thu May 29 2014 Vitezslav Crhonek <vcrhonek@redhat.com> - 0.4.2-12
 - Add openlmi-locale subpackage