XQDoc doesn't support invalid XML entities

[Paul J. Lucas]

Given the following HTML as part of an XQDoc comment:

<table>
  <tr><td>foo&nbsp;bar</td></tr>
</table>

one gets the error:

can not parse as XML for xqdoc: loader parsing error: Entity 'nbsp' not defined; raised at /Users/pjl/src/flwor/zorba/repo/feature-ft_module/zorba/src/compiler/parsetree/parsenode_print_xqdoc_visitor.cpp:433

The parser needs to accept &nbsp; so a non-breaking space can be included in the HTML.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

&nbsp; is not a valid XML entity. It is a valid XHTML entity.

Try using a single space.

Marking the bug as invalid.

[Paul J. Lucas (paul-lucas)]

You'd be right except for the fact that we're writing the documentation in XHTML, not XML.

Obviously I want a NON-BREAKING space. If I used a single space, that would be a BREAKING space.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

Paul, here is what we do with XQDoc generation:

- from the module we generate a XQDoc XML
- from the XQDoc XML we generate XHTML

In the XQuery code of the module that generates the XQDoc XML I can not state something like this:

fn:replace($XQDoc_content_as_string, "&nbsp;", codepoints-to-string(160))

because "&nbsp;" is not a valid XML entity.

So, you are right, the bug should not be marked "Invalid", it should be marked "Known limitation"/"Won't fix"

[Paul J. Lucas (paul-lucas)]

Except you could wrap unrecognized entity references like this:

<![CDATA[&nbsp;]]>

before XML processing then, before final XHTML generation, strip the CDATA.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

Paul, all XQDoc XHTML generation is done in XQuery.
As explained I can not handle XML entities in XQuery 'as is'.

I will therefore reassign this issue to Chris because he implemented the fetch module functions used to retrieve the library modules.

Also please explain why you have set the priority to this issue to HIGH.

[Paul J. Lucas (paul-lucas)]

And I explained how you *can* handle XHTML entities using CDATA.

The priority is HIGH because if a developer tool is broken (such as XQDoc), it prevents developers from doing their job (in this case, me). Plus documentation is seen by the *customer* and so it has to be *readable* and, in this particular case, using &nbsp; helps with readability.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

Paul I see your point.
thing is that you, as always, see only your point :). Nothing new under the Sun :)

So, thanks for reporting this issue and for the proposed fix: I will look into it.

As for the comment that XQDoc is *broken* I would say that XQDoc does not support invalid XML entities in comments.
It's a known issue and please stop treating it as a *show stopper*.

[Sorin Marian Nasoi (sorin.marian.nasoi)]

FYI: for a better understanding of the issue I have corrected the description of the bug.

[Paul J. Lucas (paul-lucas)]

The documentation I'm writing is slated for the 2.5 release, i.e., the next release. Dana has been insisting that the documentation is good. The documentation can't be completed without a fix for this. Hence, it *is* a show-stopper.