--- /dev/null
+.. _mapping-label:
+
+..
+ Le TEST_ROOT n'est pas évalué dans le literalinclude
+.. |TEST_ROOT| replace:: ../Tests/MappingAccasXsd/
+.. |cata_1.py| replace:: :download:`cata_1.py <../Tests/MappingAccasXsd/cata_1.py>`
+.. |cata_1_genere.xsd| replace:: :download:`cata_1_genere.xsd <../Tests/MappingAccasXsd/cata_1_genere.xsd>`
+.. |cata_1_test1.xml| replace:: :download:`cata_1_test_1.xml <../Tests/MappingAccasXsd/cata_1_test_1.xml>`
+
+Generating the XSD file from the catalog file
+=============================================
+
+generateXSD command
+____________________
+
+To obtain the |cata_1_genere.xsd| file corresponding to the |cata_1.py| file just enter ::
+
+ python ./generateXSD.py -c ./cata_1.py
+
+
+Here is the interesting part of |cata_1.py| content.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-after: beginJdC
+ :end-before: endJdC
+
+
+The generateXSD command has created the |cata_1_genere.xsd| file.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+
+You may check it with xmllint command.
+You may visualize it with xsddiagram command.
+
+Using PyXB to generate drivers
+______________________________
+
+Using the XSD model file to get an XML generated driver is as simple as typing ::
+
+ pyxbgen -m cata_1_genere -u cata_1_genere.xsd --write-for-customization
+
+It will create an raw/ directory containing various classes imported from the ./cata_1_genere.py file.
+
+
+Using PyXB generated drivers
+_____________________________
+
+You can use the driver to load an xml file like |cata_1_test1.xml| conforming to the |cata_1_genere.xsd| file.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_test_1.py
+ :end-before: CONFIGURATION
+
+Once the .xml file is loaded you can display it in a prety xml format.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_test_1.py
+ :start-after: _setOrphanElementInContent
+
+Understanding the XSD mapping for SIMP
+______________________________________
+
+SIMP for type simple type {'I','R', bool, 'TXM'}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Declaring an SIMP with a *type* attribute
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *SIMP* is mapped to an xsd global type and an xsd element.
+The xsd element is locally defined and may appears multiple times depending on the use the catalog does of it.
+
+If we look at the test_simp_2 in |cata_1.py| content, we get an example of an *SIMP* of *type* 'I' (int type).
+
+.. todo::
+ Give the possibility of customizing the xsd type used by an eficas type
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2
+ :end-at: test_simp_2
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2"
+ :end-at: /xs:simpleType
+
+An XSD element local declaration using this type is obviously defined since we declare it in the catalog :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_2"
+ :end-at: name="test_simp_2"
+
+You may notice that the XSD elements attributes **minOccurs** and **maxOccurs** are defined by default to 1 since the *statut* attribute is obligatory *'o'*.
+The XSD attribute **default** value is set to 2 conforming to the catalog *defaut* attribute.
+
+.. note::
+ * The xsd **minOccurs** attribute value of an element declaration that comes from an *SIMP* is either 0 or 1.
+ * The xsd **maxOccurs** attribute value of an element declaration that comes from an *SIMP* will alway be 1.
+
+If we look at the test_simp_4 in |cata_1.py| content, we get an example of an *SIMP* of *type* bool (boolean type).
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_4
+ :end-at: test_simp_4
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_4"
+ :end-at: /xs:simpleType
+
+And the XSD element local declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_4"
+ :end-at: name="test_simp_4"
+
+.. note:: Notice that the eficas *defaut* attribute is set to the python value True and the **default** xsd attribute is set to the xsd value true
+
+.. note:: If two *SIMP* have the same name (so, not sibling *SIMP* ) and different *type* attributes, there will be two local element declarations with the same name and two global xsd **type** with two different typenames
+
+
+Defining how many times a *SIMP* may appears
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If we look at the test_simp_2_3 in |cata_1.py| content, we get an example of an *SIMP* of type 'I' using *min* and *max* attributes.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_3
+ :end-at: test_simp_2_3
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_3"
+ :end-before: T_test_simp_2_4
+
+..
+ ATTENTION, JE N'AI PAS TROUVE UNE MEILLEURE BALISE DE FIN que le nom du test suivant : T_test_simp_2_4.
+
+You may notice that the XSD type is very different from the **T_test_simp_2** one.
+This is because the XSD list type is used for multiple occurrences of a *SIMP* and the XSD list must be derived by restriction to get our own list type.
+
+An XSD element declaration using this type is also defined as for test_simp2 :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_2_3"
+ :end-at: name="test_simp_2_3"
+
+You may notice that the minimum and maximum sizes of an XSD list are defined in the type definition thanks to a facet :
+
+.. code-block:: xml
+
+ <xs:minLength value = "3"/>
+
+
+Remind that in XSD, if there is no **maxLength** facet definition, the size of the list is considered unlimited.
+If a *max* eficas attribute is set to a number instead of '**' you get a additional **maxLength** xsd attribute as for type *test_simp_2_4* :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_4
+ :end-at: test_simp_2_4
+
+Here is the corresponding mapped XSD type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_4"
+ :end-before: T_test_simp_2_5
+
+The XSD elements attributes **minOccurs** and **maxOccurs** are also defined to 1 conforming to the *statut* value *'o'*.
+
+Defining an *SIMP* default value
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *defaut* eficas attribute provide a way to give a default value to an *SIMP* if it isn't defined by the user :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_5
+ :end-at: test_simp_2_5
+
+The *defaut* eficas attribute take into account the *min* and *max* eficas attribute. The number of values given in the *defaut* must be in the inclusive [ *min*, *max* ] range.
+
+If we look at the XSD element declaration, you can see the **default** xsd attribute which is set to a list of 4 numbers.
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_2_5"
+ :end-at: name="test_simp_2_5"
+
+..
+ ATTENTION, si un type T_test_simp_2_6 est défini, il faut modifier la balise de fin à cette valeur
+
+We observe that :
+ * the value of the XSD attribute **default** is set to a list conforming to the catalog *defaut* attribute
+ * the XSD elements attributes **minOccurs** is set to 0 conforming to the *statut* value *'f'*.
+
+.. note:: As you may have already noticed, some eficas *attribute* may be mapped to the **xsd type** and others to the **element declaration**.
+
+Constraining the range of possible values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Thanks to *val_min*, *val_max*, and *into* eficas attributes you may constraint the range of values allowed for the elements.
+Here is an example of produced **xsd type** for *val_min*, *val_max* usage :
+
+When we define the fololwing eficas keyword with *val_min*, *val_max* attributes
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_1
+ :end-at: test_simp_2_1
+
+The corresponding generated XSD type is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_1"
+ :end-before: T_test_simp_2_2
+
+When we define the following eficas keyword with *into* attribute :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_2_2
+ :end-at: test_simp_2_2
+
+The corresponding mapped XSD type is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_2_2"
+ :end-before: T_test_simp_2_3
+
+The use of the *into* attribute implies a xsd type definition using **xsd enumeration**.
+
+.. note:: Hence it's possible to define an *into* attribute with an *SIMP* of *type* 'R', it is generaly not very useful
+
+Declaring an SIMP with a *type* 'TXM' with an occurence of 1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The use of 'TXM' type is quite the same as 'I' or 'R' types.
+Here is an example for a SIMP with type 'TXM' :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_1_1
+ :end-at: test_simp_1_1
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_1_1"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_1_1"
+ :end-at: name="test_simp_1_1"
+
+
+Declaring an SIMP with a *type* 'TXM' with an occurence > 1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Here is an example for a SIMP with type 'TXM' with multiple ocurrences :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_1_3
+ :end-before: test_simp_2
+..
+ ATTENTION, si un type T_test_simp_1_4 est défini, il faut modifier la balise de fin à cette valeur
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_1_3"
+ :end-before: T_test_simp_2
+..
+ ATTENTION, si un type T_test_simp_1_4 est défini, il faut modifier la balise de fin à cette valeur
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_1_3"
+ :end-at: name="test_simp_1_3"
+
+.. note::
+ * The use of eficas *attributes* *val_min* and *val_max* for *type* == 'TXM' may be used to enforce values to be between the *val_min* , *val_max* strings in alphabetical order. The use of eficas *validator* keyword is a better way to check regexp for string values
+ * The use of eficas *attributes* *into* is often very convenient to enforce the only predefined possible strings
+
+.. note::
+ * Since the xsd type used to map the eficas attribute *max* when it is >1 is a **list** and since the xsd **list** separator is a space character then you can't use a space character in your strings
+ * The xsd type **list** used to map eficas attribute *max* when it is >1 is a choice of mapping which avoid the use of an xml element for each value in the .xml dataset file. Even if you can't express the direct access to an element of the list in the xpath language, it's not an issue in the PyxB generated driver because you get a Python list with its classic acessors
+
+SIMP with type { 'Fichier', 'Repertoire', 'FichierOuRepertoire', 'FichierNoAbs' }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Whatever the *typ* is for managing file or directory, by now the xsd mapping is a simple string.
+There are possible improvements such as managing xsd regexp expression.
+
+Here is an example for a SIMP with type 'Fichier' with a filename filter :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_7_4
+ :end-at: test_simp_7_4
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_7_4"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_7_4"
+ :end-at: name="test_simp_7_4"
+
+.. note:: It could be useful to define a specic xsd type for using a well-known type for managing files and directories.
+
+
+SIMP for UserASSD type
+~~~~~~~~~~~~~~~~~~~~~~
+An SIMP may be type with a user defined type. Depending on the way you defined the SIMP you can either create it or refer to it. This is the same notion as :ref:`Defining a concept type <Defining-a-concept-type-user>` for an OPER but defined an used where ever you like.
+
+
+Here is an example for a SIMP with user type *User_Data* :
+
+The *SIMP* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: class User_Data
+ :end-at: class User_Data
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_8_1
+ :end-at: test_simp_8_1
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_8_1"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_8_1"
+ :end-at: name="test_simp_8_1"
+
+The *SIMP* reference is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :dedent: 8
+ :start-at: test_simp_8_2
+ :end-at: test_simp_8_2
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_test_simp_8_2"
+ :end-at: /xs:simpleType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="test_simp_8_2"
+ :end-at: name="test_simp_8_2"
+
+.. note:: Modifier la génération pour s'adapter à celle de l'OPER.
+
+SIMP for complex type {'C'}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not yet implemented !
+
+SIMP for type {Tuple}
+~~~~~~~~~~~~~~~~~~~~~
+
+Not yet implemented !
+
+
+Understanding the XSD mapping for JdC, OPER and PROC
+____________________________________________________
+
+The JdC root level
+~~~~~~~~~~~~~~~~~~
+
+As explained in section :ref:`Defining steps in a catalog<Defining-steps-in-a-catalog>` OPER and PROC commands are the very first keywords that appears under the root node. They both provide a way to agregate data.
+
+
+The *OPER* command returns a user type while a *PROC* doesn't and just agregate a first level coherent set of data.
+
+If we have a look to a JdC definition :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: JDC_CATA
+ :end-at: JDC_CATA
+
+We notice that the *code* parameter declares the name of the code for which the catalog is written.
+The xsd mapping is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_Test1"
+ :end-at: /xs:complexType
+
+The **xsd:choice** with a **maxOccurs=unbounded** is used because the user may choose how many *PROC* / *OPER* he/she wants and in the order he/she decided.
+
+The root element declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="Test1"
+ :end-at: name="Test1"
+
+The name of the element comes from the *code* parameter previously defined.
+You find all the element declarations that come from all the *PROC* / *OPER* declared in the catalog.
+
+The OPER command
+~~~~~~~~~~~~~~~~
+
+
+The *OPER* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: class User_Data
+ :end-at: class User_Data
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: Test_oper_1
+ :end-at: Test_oper_1
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_Test_oper_1"
+ :end-at: /xs:complexType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="Test_oper_1"
+ :end-at: name="Test_oper_1"
+
+
+
+The PROC command
+~~~~~~~~~~~~~~~~
+
+The *PROC* declaration is :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py
+ :language: python
+ :start-at: Test_proc_2
+ :end-at: Test_proc_2
+
+You get the xsd type :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :start-at: name="T_Test_proc_2"
+ :end-at: /xs:complexType
+
+And the element declaration :
+
+.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd
+ :language: xml
+ :dedent: 2
+ :start-at: name="Test_proc_2"
+ :end-at: name="Test_proc_2"
+
+
+
+Understanding the XSD mapping for FACT and BLOCK
+________________________________________________
+
+
+
+Understanding the XSD mapping for RULES
+_______________________________________
+
