#19 Refine rule for formatting of doc text

layout (4)
Jay Dunning

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.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks