Improve documentation

Improve documentation. Find a bug in converting markdown to html: the
parsing step must be refactored for safe conversione.