Over the years the old documentation has outgrown its initial design and finally failed to satisfy the needs of beginning and advanced programmers alike. Moreover, its html-code had become quite - umm - untidy over the years. Therefore: Both, form and content needed a rewrite.
Well the new documentation (which has become the current documentation by now) should be an improvement in both respects. The new docu is written in xml with docbook as a dtd.
The new documentation is distributed as a html-document, which is generated by xsltproc with a html-stylesheet from the xml-source yabasic.xml.
Docbook can be easily transformed into really nice html; However I have problems to transform it into nroff, the format which is used for Unix man-pages. Of course there are numerous tools (e.g. docbook-to-man, sgmltools or sgmltools-lite), which claim to do just that; but unfortunately they either produce ill-formatted garbage (at least, when I used them) or they only transform the refentry-elements of yabasic.xml.
Currently, I have chosen to transform yabasic.xml into pure ascii-text and to embed this text as-is within the unix man-page. However, the result is weak (although much better than the old documentation). Therefore I would really appreciate any hint, on how to transform all of yabasic.xml into a single nroff-document; please mail me, if you have any suggestions or hints.