[ xframe-Feature Requests-1610648 ] Refine rule for formatting of doc text

Feature Requests item #1610648, was opened at 2006-12-07 03:09
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=454394&aid=1610648&group_id=48863

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: layout
Group: xsddoc-1.0
Status: Open
Priority: 5
Private: No
Submitted By: Jay Dunning (jaydunning)
Assigned to: Nobody/Anonymous (nobody)
Summary: Refine rule for  formatting of doc text

Initial Comment:
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.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=454394&aid=1610648&group_id=48863

-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV