[OpenSER-Docs] migrating sgml to xml

[Daniel-Constantin Mierla]

Hello,

thinking about migrating to xml from the sgml, I found a good tutorial:
http://www.sagehill.net/docbookxsl/index.html

Following some guidelines there, I was able to migrate the doc for 
dispatcher in just few steps:
- renamed extension from sgml to xml
- changed the header of disptacher.xml to conform xml structure and link 
to dtd
- fixed some bogus entities defined in doc/entities.sgml (I made a local 
copy to entities.xml)
- fixed some unclosed <para> tags in disptacher_user.xml
- run this futuristic command (in modules/dispatcher/doc/):
 xsltproc --stringparam html.stylesheet ../../../doc/docbook.css 
--stringparam section.autolabel 1 --stringparam 
section.label.includes.component.label 1 -o dispatcher.html 
/usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl dispatcher.xml
- to get the readme txt format:
 lynx -force_html -dump -nolist -width=72 dispatcher.html >dispatcher.txt

I downloaded http://www.openser.org/css/docbook.css in openser/doc/ 
folder, so I got the same look on my local generated html files as for 
the ones on the openser.org. The extra option now is that each chapter 
has its own table of content (can be removed via some option, but I 
didn't dig in more).

It was not that painful, but will require some work, when coming to all 
modules. I propose to add the docbook.css in the openser SVN under doc 
folder, maybe renamed as "openser-docbook.css". Also, a copy of 
entities.sgml as entities.xml with the required fixes (the sgml version 
will be removed once migration is complete).

I believe makes no sense to add support for mixed doc sources -- meaning 
here that some modules have sgml and some xml. If we can sync 3-4 
people, and split the modules among, we can get the work done in few 
days. In this case, we will go directly in replacing the generation of 
html from sgml to xml. Will be useless work to add intermediary support 
in Makefile and try to detect whether is sgml or xml.

Any comment?

Cheers,
Daniel