--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/configurationengine/doc/plugins/genconfml-plugin/genconfmlplugin.rst Thu Mar 11 17:04:37 2010 +0200
@@ -0,0 +1,156 @@
+User guide for Generic Configuration File Markup Language (GenConfML) Plugin
+----------------------------------------------------------------------------
+
+Introduction
+'''''''''''''
+This page describes how to use and configure Generic Configuration File Markup Language
+(GenConfML) plugin fo ConE. GenConfML is one of the implementation mapping languages for
+Configuration Markup Language (ConfML). This plugin is used to generate arbitrary text file
+formats. Currently this language uses a `eXtensible Stylesheet Language Transformations
+(XSLT) <http://www.w3.org/TR/xslt>`_ style sheet for generating a file for selected settings.
+Support for other style sheet or transformation mechanisms than
+`XSLT <http://www.w3.org/TR/xslt>`_ could be added later.
+
+GenConfML files are executed by default in **normal** :ref:`invocation phase <implml-common-invocation-phase>`.
+
+GenConfML
+'''''''''
+
+The GenConfML (Generic Configuration File ML) syntax is a extension of Configuration markup
+language (confml). The term in confml for this extension is implementation method language
+(implml), which in GenConfML case is a xml file.
+
+ * Namespace: ``http://www.s60.com/xml/genconfml/1``
+ * File extension: ``gcfml``
+
+.. note::
+
+ More information about :ref:`file extensions <implml-file-extensions>`.
+
+GenConfML Elements
+..................
+
+The GenConfML model is drawn out as a uml model in below picture.
+
+ .. image:: gcfml.jpg
+
+.. note::
+
+ GenConfML supports also common ImplML elements. More information about :ref:`ImplML elements <implml-common-elements>` .
+
+<file> Element
+**************
+
+The ``file`` element is the root element of the configuration, and acts as a container to the rest of the elements. Each
+generated file must be defined in its own Generic Configuration File XML file. The input file for XSLT processor is
+the Configuration ML file including only the data element containing values for all selected settings. Following XSLT
+output types are supported: XML, HTML, and text.
+
+Attributes
+++++++++++
+
+==================== ====================== ===============================================================================
+Attribute Required Description
+==================== ====================== ===============================================================================
+name Yes Defines a name of the output file. Can contain path that is used to create
+ subfolders under output directory.
+target No Defines a Symbian specific attribute for additional path information. Final
+ target path is a combination of target and name. The combined path is used in
+ output directory and in IBY file. If target attribute is not supported full
+ path can be defined also as a value of name attribute.
+==================== ====================== ===============================================================================
+
+
+Child Elements
+++++++++++++++
+
+==================== ====================== ===============================================================================
+Element Cardinality Description
+==================== ====================== ===============================================================================
+setting 0 .. * Defines a configuration setting reference that is used as an input in XSLT
+ prosessing.
+xsl:stylesheet 1 Defines stylesheet for XSLT processor.
+==================== ====================== ===============================================================================
+
+Example
++++++++
+
+.. code-block:: xml
+
+ <file xmlns="http://www.s60.com/xml/genconfml/1" name="myname.txt" target="">
+ ...
+ </file>
+
+
+<setting> Element
+*****************
+
+Setting element is mandatory element containing the settings used in this transformation.
+
+
+Attributes
+++++++++++
+
+==================== ====================== ===============================================================================
+Attribute Required Description
+==================== ====================== ===============================================================================
+ref Yes Defines a Feature/setting reference pair. All settings inside one feature
+ can be selected by using Feature/*.
+==================== ====================== ===============================================================================
+
+Example
++++++++
+
+.. code-block:: xml
+
+ <setting ref="MyFeature/Setting1"/>
+
+
+<xsl:stylesheet> Element
+************************
+
+Xsl:stylesheet element defines the XSLT [3] stylesheet used to transform input data from ConfML to output file.
+
+The style sheet can be defined inside file element or in external file identified using stylesheet attribute.
+If style sheet is completely omitted then input file is to be used as such as the configuration file without any transformation.
+The MIME type for XML files of Generic Configuration File ML is ``text/application+xml``.
+
+
+Full example files
+''''''''''''''''''
+
+Example Generic Configuration File ML file:
+
+.. literalinclude:: genconfml_example1.txt
+ :language: xml
+
+Example file that is passed to the included XSLT processor contains only selected data elements:
+
+.. literalinclude:: genconfml_example2.txt
+ :language: xml
+
+Example output file that is generated by XSLT processor:
+
+.. literalinclude:: genconfml_example3.txt
+ :language: xml
+
+The output file will be located under the output folder in a sub-folder determined based on the
+name and target attributes of the file element. E.g., in this case the output file's path is
+``output_dir/private/2000BEE5/CamcorderData.xml``.
+
+Notice that same result is obtained by having the following line in the GenConfML file:
+
+.. literalinclude:: genconfml_example5.txt
+ :language: xml
+
+XSD
+'''''''''
+
+Download: :download:`gcfml.xsd </xsd/gcfml.xsd>`
+
+
+FAQ
+'''''''''
+
+This will be updated based on the questions.
+