Currently xml2html generates xsd:documentation content as pre-formatted text, unless it contains an element, in which case it is copied as-is.
Generation as pre-formatted text is a nice feature, even though it is inconsistent with JavaDoc, because it allows the schema to be documented in a human-readable form without HTML formatting elements.
However, there are times when a little HTML formatting is useful. For example, the addition of emphasis or a link to some other document.
The current documentation behavior does not allow graceful stepwise evolution of documentation. If one HTML formatting element is added to a documentation element that contains more than a simple paragraph, the entire documentation element needs to be updated to use HTML formatting.
I would like to see the rule refined so that pre-formatted text is generated unless the documentation element contains a block content element. The elements 'p', 'pre', 'table', 'ol', and 'ul' are probably all that need to be tested for. So, instead of 'test="*"', 'test="p|pre|table|ol|li"'.
An alternative would be to support some sort of wiki-text, but that would be a lot more complicated.
I believe the only impact this change would make to existing documentation would be to cause any single paragraph documentation elements with in-line elements to be output as pre-formatted text instead of formatted text.
Log in to post a comment.