Yep...

But, while we wait, I'll prepare some script to change, at least, the parts that You pointed... then I'll send the list a copy so it is available to everybody to start tweak as soon SVN is updated...

Edson

-----Original Message----- From: Daniel-Constantin Mierla [mailto:miconda@gmail.com] Sent: segunda-feira, 3 de março de 2008 17:46 To: Edson Cc: openser-docs@lists.openser.org Subject: Re: [OpenSER-Docs] migrating sgml to xml

Hello,

On 03/03/08 22:28, Edson wrote:

...

Hi, Dan..

If the steps that You follow could be applied to all SGML DOC files, then what about a script to do the job? I can handle this script, but need detailed instructions to follow...

I think the only steps that can be automatized is the removal of the sgml header and adding the xml one and changing the extension from sgml to xml (there are entities referenced to user, devel and faq files).

For sgml the header was:

<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ Now for xml should be: <?xml version="1.0" encoding='ISO-8859-1'?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ In sgml was: <!ENTITY user SYSTEM "dispatcher_user.sgml">

<!ENTITY faq SYSTEM "dispatcher_faq.sgml">

In xml should be:

<!ENTITY user SYSTEM "dispatcher_user.xml">

<!ENTITY faq SYSTEM "dispatcher_faq.xml">

The rest I did were errors and had to be fixed by hand.

However, first we have to wait for Henning to commit the updated version following the latest patch you sent. The we can work, having a working sgml version.

Cheers, Daniel

...

Edson

...

-----Original Message----- From: openser-docs-bounces@lists.openser.org [mailto:openser-docs- bounces@lists.openser.org] On Behalf Of Daniel-Constantin Mierla Sent: segunda-feira, 3 de março de 2008 17:21 To: openser-docs@lists.openser.org Subject: [OpenSER-Docs] migrating sgml to xml

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

---

Openser-docs mailing list Openser-docs@lists.openser.org http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs

---

Openser-docs mailing list Openser-docs@lists.openser.org http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs

Hello,

On 03/04/08 15:35, Henning Westerholt wrote:

On Monday 03 March 2008, Daniel-Constantin Mierla wrote:

...

Now for xml should be:

<?xml version="1.0" encoding='ISO-8859-1'?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

Hi Daniel, hi Edson,

i think we should go for the 4.4 version of docbook-xml, this is in debian stable, so it should be safe to use this. Perhaps there are some bugfixes and extensions that are useful for us..

4.4 is ok, I used 4.2 as the sgml files were having that version.

...

In sgml was:

<!ENTITY user SYSTEM "dispatcher_user.sgml">

<!ENTITY faq SYSTEM "dispatcher_faq.sgml">

In xml should be:

<!ENTITY user SYSTEM "dispatcher_user.xml">

<!ENTITY faq SYSTEM "dispatcher_faq.xml">

This is good for now, but in the future it would probably make sense to use xincludes here instead of the old entities method, like with the database scheme stuff.

xinclude is good -- I haven't used it at all so far. I just did the minimal steps to migrate sgml to xml -- this will be the big step, further optimizations will be done afterwards.

Cheers, Daniel

Cheers,

Henning

Hello Henning,

On 03/04/08 15:42, Henning Westerholt wrote:

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

strange, but it is more flexible than generating from sgml -- the sgml tools looked very heavy for me, with no much options (e.g., to enforce the link to css file, I had to change the content of some files, which sometime get overwritten by updates).

...

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.

Might be as you say, I will try to see if we can control it with some command line parameter, will be easier to deal with.

...

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

OK,

Cheers, Daniel

Cheers,

Henning