[ xframe-Feature Requests-853750 ] documentation elements should not be in <pre> environment

Feature Requests item #853750, was opened at 2003-12-04 02:31
Message generated for change (Comment added) made by kriede
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=454394&aid=853750&group_id=48863

Category: layout
Group: xsddoc-0.3-alpha
Status: Open
Priority: 5
Submitted By: Malcolm Jones (malbj)
Assigned to: Kurt Riede (kriede)
Summary: documentation elements should not be in <pre> environment

Initial Comment:
I want to be able to include arbitrary XHTML in my
schema documentation annotations.  Perhaps I do not
know html and there is a way to do this already, but It
would be good if there was at least an option to
control what element the documentation elements are
included within.


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

>Comment By: Kurt Riede (kriede)
Date: 2003-12-05 10:31

Message:
Logged In: YES 
user_id=484961

Documentation:
I gues there will always be a type of documentation that will 
not be nicely formatted, but the three steps should fit a lot.
Could you provide us some schema fragments with 
documentation samples to be added to our stress tests?

XML:
You can use the -xml option to generate XML instead of 
HTML. The generated XML follows the xsddoc schema (see 
http://xframe.sourceforge.net/xsddoc/samples/xsddoc/html/in
dex.html), but unfortunately in release 0.3 only the 
component pages are XML; all the others (e.g. summary 
pages) are not yet, but they will be in future.

forrest:
As soon as all pages are XML, you could either declare the 
xsddoc XML as valid input to forrest (you will need a DTD of 
xsddoc) or you could transform tje xsddoc XML with a XSLT 
stylesheet to any format yet known by forrest.

Ant:
set the xml attribute to "true" and all component pages will be 
output as XML instead of html (see also Usage as an Apache 
Ant task: http://xframe.sourceforge.net/xsddoc.html#N1011A)
Hope this helps. If not, feel free to post a bug report.


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

Comment By: Malcolm Jones (malbj)
Date: 2003-12-05 03:55

Message:
Logged In: YES 
user_id=908874

What you suggest sounds great.

I understand how ugly 'preformated' text looks without the
<pre>, as I tried a couple of hacks and found the same - my
solution was to include the <pre></pre> tags in the (my
schema only needed a small number of these) schema
documentation as this seemed a more 'morally' correct
solution - if the comment is meant to be viewed preformatted
it is good to have that specified explicitly (form a
puritanical point of view), however I am not really a
pedant, so I don't I intend that comment to be taken as a
suggestion, particularly, as it would require changing any
existing schema to get decent output from xsddoc, which
would, I imagine, reduce it's usefullness significantly.

The optional external XSLT file idea is a really good one.

Just as further info, in case it helps, at some (future)
stage I hope to be able to integrate the xsddoc output into
our intranet which uses the 'forrest' tool - I don't know
yet whether this goal is realistic (I am still novice with
forrest tool and also XSLT in general) but I thought xsddoc
developers might be intrested to consider this possibility.

Thanks for the speedy feed-back, and just to express my
appreciation, even your alpha release output has been very
useable to me, so well done on a solid and useful tool.

One final point - somewhere something I read suggested that
XML output was an option - I haven't been able to figure out
how to use this with the xsddoc ant task, don't know whether
this is a documentation issue or user failure :-).


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

Comment By: Kurt Riede (kriede)
Date: 2003-12-04 12:07

Message:
Logged In: YES 
user_id=484961

That's an interesting point!
We started with the 'XML Schema for XML Schema" where 
documentation is preformatted text and looked ugly while it 
was not in a pre-tag.
On the other side I agree documentation should follow XML 
conevntions, but it could not only by xhtml, but also a custom 
gramar having e.g. author- description- and other tags.
So what could be a generic solution?

So far we are following this approach for a future release:

1. If there are only text nodes within the documentation 
node: assume it is preformatted text, so use pre-tag

2. path-thru all xhtml node unchanged

3. non-xhtml-nodes: allow optional external XSLT file to 
format those nodes. By default (if no external stylesheet 
provided) they will be rendered as XML, simillar to the source 
section.

If you have any suggestions on this, please feel free to 
contribute here.


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

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


-------------------------------------------------------
This SF.net email is sponsored by: SF.net Giveback Program.
Does SourceForge.net help you be more productive?  Does it
help you create better code?  SHARE THE LOVE, and help us help
YOU!  Click Here: http://sourceforge.net/donate/