[OpenSER-Docs] migrating sgml to xml

[Henning Westerholt]

On Monday 03 March 2008, Daniel-Constantin Mierla wrote:
> [..]
> - 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

Hi Daniel,

strange command, indeed. ;-)

> 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).

I think this table of contents is generated from the <toc> tag in the 
$name.sgml file. It would make sense to switch this of, if we generate a 
document holding all module docs.

> 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.

I think also that it makes no sense to have this mixed generation, its ok to 
break the docs generation for a few days..

Cheers,

Henning