#19 Refine rule for formatting of doc text

xsddoc-1.0
open
nobody
layout (4)
5
2006-12-07
2006-12-07
Jay Dunning
No

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.

Discussion