Re: [docbook] more than validating

[Frans Englich <frans dot englich at telia dot com>]

On Monday 24 January 2005 00:51, Marco Correia wrote:
> hi,
>
> I was wondering if there is a tool that given an invalid docbook document
> (but still valid xml) and the docbook dtd, could remove all tag blocks that
> makes it invalid. For example, if my docbook document is
>
> <book><chapter><book> ... </book></chapter></book>
>
> it would produce
>
> <book><chapter></chapter></book>
>
> I need something like this to help me translate doxygen xml output to
> docbook. It would make the process much more easier if I could produce an
> "almost-valid" docbook document and then remove all invalid blocks. I know
> that it would miss some parts of the document but I could live with that.

I don't know of any software which has that particularly functionality, but 
given a validation API which is aware of what is wrong, it would be possible 
to program.. If it's not too much markup and you can intervene manually, you 
could simply look up the line number from a validator and manually delete. It 
amazes me that you can live with such loss of data.

To me, it sounds like you're trying to make the wrong solution work.

Regarding converting Doxygen output to Docbook; I was investigating that issue 
for KDE. I mailed Dimitre(the author) about this issue. I've taken the 
liberty to quote parts from our discussion.

<quote>
[...]
> Is there anything which XML output currently 
> doesn't support? If so, what are the time frames of when it will be 
> corrected/extended?

I think the XML output is quite good and stable as it is. I believe there
is not much missing with respect to features (although occasionally some minor
omissions are found). The output does reflect the way things are stored in
doxygen internally, so this may not be ideal in all cases, but if you do not
want to generate a completely different type of documentation it is 
probably fine. 

[...]
> I know nothing about Doxygen's XML output format, but what are your 
> estimations on how difficult/feasible it would be to write XSLTs converting 
> XML output to Docbook, assuming one is "reasonable" comfortable with XSLT? 
> Would there be capabilities one would have to let go, and if so, which ones? 
> If not transforming XML to Docbook is the proper way, how should it be done 
> then?

Going from XML to Docbook is a good approach (though I do not know XSLT that
well so I never designed the XML output to be easy to use for XSLT, any
improvement suggestions in this respect are welcomed though).

Have a look at boost's documentation system:
http://www.boost.org/doc/html/boostbook.html
Apparently they use tools to convert doxygen's XML into Docbook already!

</quote>

So, perhaps you should go for Boost Book which I will try to do when having a 
look, instead of what I had in plans and what you do know: starting at the 
XML output.

If you do anything Doxygen->Docbook, feel free to do a small write-up on the 
docbook-apps list. People are struggling with this issue, and I think shared 
experience would be appreciated.


Perhaps useful,

		Frans