diff -r 000000000000 -r 2e8eeb919028 configurationengine/doc/plugins/genconfml-plugin/genconfmlplugin.rst --- /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) `_ style sheet for generating a file for selected settings. +Support for other style sheet or transformation mechanisms than +`XSLT `_ could be added later. + +GenConfML files are executed by default in **normal** :ref:`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 `. + +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 ` . + + 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 + + + ... + + + + 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 + + + + + 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 ` + + +FAQ +''''''''' + +This will be updated based on the questions. +