some gtk-doc improvement

8 files changed, 900 insertions, 3 deletions

diff --git a/doc/reference/.cvsignore b/doc/reference/.cvsignore
index 10c9dba..8d312a1 100644
--- a/doc/reference/.cvsignore
+++ b/doc/reference/.cvsignore
@@ -1,10 +1,7 @@
 *.txt
 html
-sgml
-tmpl
 xml
 .libs
-*.sgml
 Makefile
 Makefile.in
 libxklavier.*
diff --git a/doc/reference/libxklavier-docs.sgml b/doc/reference/libxklavier-docs.sgml
new file mode 100644
index 0000000..c560224
--- /dev/null
+++ b/doc/reference/libxklavier-docs.sgml
@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>Libxklavier Reference Manual</title>
+  </bookinfo>
+
+  <chapter>
+    <title>Libxklavier Objects</title>
+    <xi:include href="xml/xkl_engine.xml"/>
+    <xi:include href="xml/xkl_config_item.xml"/>
+    <xi:include href="xml/xkl_config_rec.xml"/>
+    <xi:include href="xml/xkl_config_registry.xml"/>
+  </chapter>
+  <chapter>
+    <title>Libxklavier Utilities</title>
+    <xi:include href="xml/xklavier.xml"/>
+  </chapter>
+</book>
diff --git a/doc/reference/tmpl/libxklavier-unused.sgml b/doc/reference/tmpl/libxklavier-unused.sgml
new file mode 100644
index 0000000..0c29e4e
--- /dev/null
+++ b/doc/reference/tmpl/libxklavier-unused.sgml
@@ -0,0 +1,49 @@
+<!-- ##### USER_FUNCTION GroupProcessFunc ##### -->
+<para>
+
+</para>
+
+@item: 
+@allow_multiple_selection: 
+@data: 
+
+<!-- ##### FUNCTION xkl_backup_names_prop ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+<!-- ##### FUNCTION xkl_config_registry_free ##### -->
+<para>
+
+</para>
+
+@config: 
+
+<!-- ##### FUNCTION xkl_config_registry_load_from_file ##### -->
+<para>
+
+</para>
+
+@config: 
+@file_name: 
+@Returns: 
+
+<!-- ##### FUNCTION xkl_engine_group_get_default ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+<!-- ##### FUNCTION xkl_engine_group_set_default ##### -->
+<para>
+
+</para>
+
+@engine: 
+@group: 
+
diff --git a/doc/reference/tmpl/xkl_config_item.sgml b/doc/reference/tmpl/xkl_config_item.sgml
new file mode 100644
index 0000000..91b7e59
--- /dev/null
+++ b/doc/reference/tmpl/xkl_config_item.sgml
@@ -0,0 +1,69 @@
+<!-- ##### SECTION Title ##### -->
+XklConfigItem
+
+<!-- ##### SECTION Short_Description ##### -->
+X keyboard configuration registry item
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### MACRO XKL_MAX_CI_NAME_LENGTH ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO XKL_MAX_CI_SHORT_DESC_LENGTH ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO XKL_MAX_CI_DESC_LENGTH ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### STRUCT XklConfigItem ##### -->
+<para>
+
+</para>
+
+@parent: 
+@name: 
+@short_description: 
+@description: 
+
+<!-- ##### FUNCTION xkl_config_item_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION ConfigItemProcessFunc ##### -->
+<para>
+
+</para>
+
+@config: 
+@item: 
+@data: 
+
+
diff --git a/doc/reference/tmpl/xkl_config_rec.sgml b/doc/reference/tmpl/xkl_config_rec.sgml
new file mode 100644
index 0000000..b488540
--- /dev/null
+++ b/doc/reference/tmpl/xkl_config_rec.sgml
@@ -0,0 +1,132 @@
+<!-- ##### SECTION Title ##### -->
+XklConfigRec
+
+<!-- ##### SECTION Short_Description ##### -->
+X keyboard configuration container
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT XklConfigRec ##### -->
+<para>
+
+</para>
+
+@parent: 
+@model: 
+@layouts: 
+@variants: 
+@options: 
+
+<!-- ##### FUNCTION xkl_config_rec_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_activate ##### -->
+<para>
+
+</para>
+
+@data: 
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_get_from_server ##### -->
+<para>
+
+</para>
+
+@data: 
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_get_from_backup ##### -->
+<para>
+
+</para>
+
+@data: 
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_write_to_file ##### -->
+<para>
+
+</para>
+
+@engine: 
+@file_name: 
+@data: 
+@Param4: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_get_from_root_window_property ##### -->
+<para>
+
+</para>
+
+@config_out: 
+@Param2: 
+@rules_file_out: 
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_set_to_root_window_property ##### -->
+<para>
+
+</para>
+
+@config: 
+@Param2: 
+@rules_file: 
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_restore_names_prop ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_reset ##### -->
+<para>
+
+</para>
+
+@data: 
+
+
+<!-- ##### FUNCTION xkl_config_rec_equals ##### -->
+<para>
+
+</para>
+
+@data1: 
+@data2: 
+@Returns: 
+
+
diff --git a/doc/reference/tmpl/xkl_config_registry.sgml b/doc/reference/tmpl/xkl_config_registry.sgml
new file mode 100644
index 0000000..a3f5f2e
--- /dev/null
+++ b/doc/reference/tmpl/xkl_config_registry.sgml
@@ -0,0 +1,147 @@
+<!-- ##### SECTION Title ##### -->
+XklConfigRegistry
+
+<!-- ##### SECTION Short_Description ##### -->
+X keyboard configuration registry
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT XklConfigRegistryPrivate ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT XklConfigRegistry ##### -->
+<para>
+
+</para>
+
+@parent: 
+@priv: 
+
+<!-- ##### FUNCTION xkl_config_registry_load ##### -->
+<para>
+
+</para>
+
+@config: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_foreach_model ##### -->
+<para>
+
+</para>
+
+@config: 
+@Param2: 
+@data: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_foreach_layout ##### -->
+<para>
+
+</para>
+
+@config: 
+@Param2: 
+@data: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_foreach_layout_variant ##### -->
+<para>
+
+</para>
+
+@config: 
+@layout_name: 
+@Param3: 
+@data: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_foreach_option_group ##### -->
+<para>
+
+</para>
+
+@config: 
+@Param2: 
+@data: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_foreach_option ##### -->
+<para>
+
+</para>
+
+@config: 
+@option_group_name: 
+@Param3: 
+@data: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_find_model ##### -->
+<para>
+
+</para>
+
+@config: 
+@item: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_find_layout ##### -->
+<para>
+
+</para>
+
+@config: 
+@item: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_find_variant ##### -->
+<para>
+
+</para>
+
+@config: 
+@layout_name: 
+@item: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_find_option_group ##### -->
+<para>
+
+</para>
+
+@config: 
+@item: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_config_registry_find_option ##### -->
+<para>
+
+</para>
+
+@config: 
+@option_group_name: 
+@item: 
+@Returns: 
+
+
diff --git a/doc/reference/tmpl/xkl_engine.sgml b/doc/reference/tmpl/xkl_engine.sgml
new file mode 100644
index 0000000..b46a768
--- /dev/null
+++ b/doc/reference/tmpl/xkl_engine.sgml
@@ -0,0 +1,389 @@
+<!-- ##### SECTION Title ##### -->
+XklEngine
+
+<!-- ##### SECTION Short_Description ##### -->
+Base X keyboard configuration and access engine
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT XklEnginePrivate ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ENUM XklEngineStateChange ##### -->
+<para>
+
+</para>
+
+@GROUP_CHANGED: 
+@INDICATORS_CHANGED: 
+
+<!-- ##### ENUM XklEngineFeatures ##### -->
+<para>
+
+</para>
+
+@XKLF_CAN_TOGGLE_INDICATORS: 
+@XKLF_CAN_OUTPUT_CONFIG_AS_ASCII: 
+@XKLF_CAN_OUTPUT_CONFIG_AS_BINARY: 
+@XKLF_MULTIPLE_LAYOUTS_SUPPORTED: 
+@XKLF_REQUIRES_MANUAL_LAYOUT_MANAGEMENT: 
+
+<!-- ##### STRUCT XklState ##### -->
+<para>
+
+</para>
+
+@group: 
+@indicators: 
+
+<!-- ##### STRUCT XklEngine ##### -->
+<para>
+
+</para>
+
+@parent: 
+@priv: 
+
+<!-- ##### FUNCTION xkl_engine_get_instance ##### -->
+<para>
+
+</para>
+
+@display: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_backend_name ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_features ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_max_num_groups ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### ENUM XklEngineListenModes ##### -->
+<para>
+
+</para>
+
+@XKLL_MANAGE_WINDOW_STATES: 
+@XKLL_TRACK_KEYBOARD_STATE: 
+@XKLL_MANAGE_LAYOUTS: 
+
+<!-- ##### FUNCTION xkl_engine_start_listen ##### -->
+<para>
+
+</para>
+
+@engine: 
+@flags: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_stop_listen ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_pause_listen ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_resume_listen ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_grab_key ##### -->
+<para>
+
+</para>
+
+@engine: 
+@keycode: 
+@modifiers: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_ungrab_key ##### -->
+<para>
+
+</para>
+
+@engine: 
+@keycode: 
+@modifiers: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_filter_events ##### -->
+<para>
+
+</para>
+
+@engine: 
+@evt: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_allow_one_switch_to_secondary_group ##### -->
+<para>
+
+</para>
+
+@engine: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_current_window ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_current_state ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_window_title ##### -->
+<para>
+
+</para>
+
+@engine: 
+@win: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_state ##### -->
+<para>
+
+</para>
+
+@engine: 
+@win: 
+@state_out: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_delete_state ##### -->
+<para>
+
+</para>
+
+@engine: 
+@win: 
+
+
+<!-- ##### FUNCTION xkl_engine_save_state ##### -->
+<para>
+
+</para>
+
+@engine: 
+@win: 
+@state: 
+
+
+<!-- ##### FUNCTION xkl_engine_set_window_transparent ##### -->
+<para>
+
+</para>
+
+@engine: 
+@win: 
+@Param3: 
+
+
+<!-- ##### FUNCTION xkl_engine_is_window_transparent ##### -->
+<para>
+
+</para>
+
+@engine: 
+@win: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_is_window_from_same_toplevel_window ##### -->
+<para>
+
+</para>
+
+@engine: 
+@win1: 
+@win2: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_num_groups ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_groups_names ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_indicators_names ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_next_group ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_prev_group ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_current_window_group ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_lock_group ##### -->
+<para>
+
+</para>
+
+@engine: 
+@group: 
+
+
+<!-- ##### FUNCTION xkl_engine_set_group_per_toplevel_window ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Param2: 
+
+
+<!-- ##### FUNCTION xkl_engine_is_group_per_toplevel_window ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_set_indicators_handling ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Param2: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_indicators_handling ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
+<!-- ##### FUNCTION xkl_engine_set_secondary_groups_mask ##### -->
+<para>
+
+</para>
+
+@engine: 
+@mask: 
+
+
+<!-- ##### FUNCTION xkl_engine_get_secondary_groups_mask ##### -->
+<para>
+
+</para>
+
+@engine: 
+@Returns: 
+
+
diff --git a/doc/reference/tmpl/xklavier.sgml b/doc/reference/tmpl/xklavier.sgml
new file mode 100644
index 0000000..0a06691
--- /dev/null
+++ b/doc/reference/tmpl/xklavier.sgml
@@ -0,0 +1,94 @@
+<!-- ##### SECTION Title ##### -->
+xklavier
+
+<!-- ##### SECTION Short_Description ##### -->
+Utility functions
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### FUNCTION xkl_get_last_error ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION XklLogAppender ##### -->
+<para>
+
+</para>
+
+@file: 
+@function: 
+@level: 
+@format: 
+@args: 
+
+
+<!-- ##### FUNCTION xkl_default_log_appender ##### -->
+<para>
+
+</para>
+
+@file: 
+@function: 
+@level: 
+@format: 
+@args: 
+
+
+<!-- ##### FUNCTION xkl_set_log_appender ##### -->
+<para>
+
+</para>
+
+@fun: 
+
+
+<!-- ##### FUNCTION xkl_set_debug_level ##### -->
+<para>
+
+</para>
+
+@level: 
+
+
+<!-- ##### MACRO xkl_debug ##### -->
+<para>
+
+</para>
+
+@level: 
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...:
+@...: 
+
+