docs/sphinx/source/format/conventions.rst

+====================
+ Naming Conventions
+====================
+

docs/sphinx/source/format/example.rst

+.. highlight:: yaml
+
+=====================
+ An Example: Bonjour
+=====================
+
+You will see here how to define step-by-step the sign ``bonjour``. You can find
+a video of the sign ``bonjour`` on the online dictionary `Elix
+<https://www.elix-lsf.fr/spip.php?page=signes&id_article=137586>`_.
+
+Bonjour::
+
+    Names: [Bonjour]
+        
+    States:
+        - NDH: ~
+          DH:
+              shape: B
+              Orient: [90, 90, 0]
+              Locate:
+                  refPoint: fingertips
+                  place: chin
+                  dist: 0
+                
+        - NDH: ~
+          DH:
+              shape: ~
+              Orient: [0, 90, 0]
+              Locate:
+                  refPoint: ~
+                  place: chest
+                  dist: 1
+                    
+    Moves:
+        - ~
+        
+    Face:
+        look: ~
+        expression: happy
+        lips: ~
+        
+    shoulders: ~
+
+
+We first define the name of the sign. As one sign can have many names, we are
+giving a list of names::
+
+  Name: [Bonjour]
+
+Then we define the *states*, which are the configurations of the
+hands at the beginning and at the end of the movement::
+
+      States:
+        - NDH: ~
+          DH:
+              shape: B
+              Orient: [90, 90, 0]
+              Locate:
+                  refPoint: fingertips
+                  place: chin
+                  dist: 0
+                
+        - NDH: ~
+          DH:
+              shape: ~
+              Orient: [0, 90, 0]
+              Locate:
+                  refPoint: ~
+                  place: chest
+                  dist: 1
+
+
+The first state has two components: the non-dominating hand (NDH), usually the
+left hand (for the right-handed persons) and the dominating hand (DH). As the
+sign ``bonjour`` is done with one hand, the non-dominating hand has a null
+value::
+
+  NDH: ~
+
+The dominating hand is more interesting. It has a shape (the letter B from the
+French Sign Language alphabet), an orientation, which is given as a 3D vector,
+and a location, which can be read as : the fingertips touches the chin. ::
+
+  DH:
+      shape: B
+      Orient: [90, 90, 0]
+      Locate:
+          refPoint: fingertips
+          place: chin
+          dist: 0
+
+We then have another state, the final one. As the shape and the point of
+reference of the hand did not change, we left these fields empty. ::
+  
+  - NDH: ~                 
+    DH:                    
+        shape: ~           
+        Orient: [0, 90, 0] 
+        Locate:            
+            refPoint: ~    
+            place: chest   
+            dist: 1        
+
+We now must define the transitions between the states, or *movement*. As there
+are two states, there is only one move. It is here a simple straight move (the
+default move), so we can leave it empty. ::
+
+  Moves:
+    - ~
+
+We eventually describe the face and the shoulders::
+
+    Face:
+        look: ~
+        expression: happy
+        lips: ~
+        
+    shoulders: ~

docs/sphinx/source/format/index.rst

@@ -4,3 +4,14 @@
 
 Avatar ENSignes uses its own format to represent and manipulate signs, written
 in the YaML markup langage.
+
+The main idea of this format is to divide a sign into fixed *states*
+(configurations of the hands at a given time) and to describe the sign as
+transitions between these states. Atop of that, one can describe the face and
+the shoulders.
+
+.. toctree::
+   :maxdepth: 1
+			  
+   example
+   conventions