Update 'docs/commands.md'

docs/commands.md

@@ -1,19 +1,5 @@
 # Commands
 
-```shell
-kiwimix 
-  generate --....         # generate X calendar in memory & push the result
-  @ load alice.ics        # push alice's calendar on stack 
-  @ filter --merge        # pop alice's calendar, filter & push the result
-  @ filter --anonymize    # pop alice's calendar, filter & push the result
-  @ read bob.ics          # push bob's calendar on stack 
-  @ filter --merge        # pop bob's calendar, filter & push the result
-  @ filter --anonymize    # pop bob's calendar, filter & push the result
-  @ union --ranges        # pop bob's calendar, pop alice's calendar, compute (alice + bob) on time ranges, push the result
-  @ substract --ranges    # pop bob, pop alice, compute (alice - bob) on time ranges, push the result
-                          # (we just computed the time slots where alice & bob are both free)
-  @ save remaining      
-```
 
 ## Create & destroy
 
@@ -54,6 +40,26 @@ Cette commande inverse l'élément du haut de la pile avec l'élement juste en d
 
 Cette commande retire les deux fichiers .ics du dessus de la pile, construit la différence entre les deux (c'est-à-dire retire du calendrier du bas de la pile les éléments qui sont dans celui du haut de la pile), puis ajoute le résultat à la pile.
 
+## Exemple
+
+
+```shell
+kiwimix 
+  generate --....         # generate X calendar in memory & push the result
+                          # (we build a calendar from 9:00 to 18:00 for the ... period )
+  @ load alice.ics        # push alice's meetings calendar on stack 
+  @ filter --merge        # pop alice's meetings calendar, filter & push the result
+  @ filter --anonymize    # pop alice's meetings calendar, filter & push the result
+  @ read bob.ics          # push bob's meetings calendar on stack 
+  @ filter --merge        # pop bob's meetings calendar, filter & push the result
+  @ filter --anonymize    # pop bob's meetings calendar, filter & push the result
+  @ union --ranges        # pop bob's meetings calendar, pop alice's calendar, 
+                          # compute (alice + bob) on time ranges, push the result
+                          # (we just build an calendar with events where either alice or bob are occupied by meetings)
+  @ substract --ranges    # pop bob, pop alice, compute (alice - bob) on time ranges, push the result
+                          # (we just computed a calendar with all time slots where alice & bob are both free from meetings)
+  @ save free-time.ics    # pop the resulting calendar, save to a file
+```
 * --events : supprime les evements qui sont dans le calendrier en haut de pile
 * --ranges : supprime les intervales de temps des évenements qui sont dans le cadrier en haut de pile