add complete example of usage

README.md

@@ -95,9 +95,146 @@ In addition, it uses the contents of `$VISUAL` or `$EDITOR`
 when needing to launch a text editor, or `ed` as default.
 *(Yay, ed !)*
 
-## Examples
+## Example
 
-*Work In Progress*
+We assume a first start with no environment variables set.
+
+    $ ./clikan.sh
+     no config found, generating default config file /home/username/.clikanconf
+     and default kanban file /home/username/clikanban.md
+     (this should happen only once at first use)
+
+       doing
+    1: learn to use clikan
+
+Default config and kanban files have been generated.
+Let's see the waiting, the archived/done, and again the "doing" cards:
+
+    |< w
+
+       waiting/todo/backlog
+    1: improve clikan
+    |< a
+
+       archived/done
+    1: install clikan
+    |< d
+
+       doing
+    1: learn to use clikan
+
+Now let's assume we know everything, so card 1 is done:
+
+    |< done 1
+
+       doing
+    |< w
+
+       waiting/todo/backlog
+    1: improve clikan
+
+We've seen there is waiting work, so let's do it:
+
+    |< do 1
+
+       doing
+    1: improve clikan
+
+Now we check for the target kanban ...
+
+    |< k
+    1: /home/username/clikanban.md
+    choice? (default: /home/username/clikanban.md)
+
+
+       doing
+    1: improve clikan
+
+... do a manual editing session on it ...
+
+    |< ek
+    calling /bin/ed /home/username/clikanban.md ...
+    158
+    1z
+    # my kanban file
+
+    + learn to use clikan
+    * improve clikan
+    + install clikan
+
+    ### titles work as comments
+    # might be a future card you don't yet want in waiting
+
+... change one entry ...
+
+    ?improve
+    * improve clikan
+    s/improve/test/p
+    * test clikan
+
+... and save it, quit, and we're back at our script:
+
+    w
+    155
+    q
+    welcome back
+
+Verifying the entry indeed has been changed:
+
+    |< d
+
+       doing
+    1: test clikan
+
+Now let's add a new card:
+
+    |< n
+    enter new card for target /home/username/clikanban.md :
+    give feedback to clikan developer
+
+       doing
+    1: test clikan
+
+The new card has been added to the waiting/backlog list:
+
+    |< w
+
+       waiting/todo/backlog
+    1: give feedback to clikan developer
+
+Just hitting RETURN at the prompt shows the help/usage page:
+
+    |<
+    ./clikan.sh : command line kanban
+      (2017-06-22 Y.Bonetti)
+    configuration file: /home/username/.clikanconf
+    for help about commands, just hit RETURN
+    to show configuration, enter 'c'
+
+We want to see the configuration, then quit:
+
+    c
+     CLIKANCONF=
+     configfile=/home/username/.clikanconf
+     editor=/bin/ed
+     maxshow=15
+     configfile contents:
+        # configuration file for ./clikan.sh
+        # (autogenerated at Don Jun 22 17:18:26 CEST 2017)
+        # file name can be defined by env.var CLIKANCONF
+        #
+        #  prompt is displayed when waiting for command
+        prompt |<
+        #  maxshow defines the maximum number of cards/lines to be displayed
+        maxshow 15
+        #  kanban defines a kanban file, may be given several times
+        # kanban /some/path/to/jobkanban.txt
+        # kanban /another/path/to/privatekanban.md
+        kanban /home/username/clikanban.md
+
+       doing
+    1: test clikan
+    |< q
 
 ---