Re: [xml-dev] Common documentation standard across multiple XML schemas

[George Cristian Bina <george@oxygenxml.com>]

Hi Lech,

oXygen XML Editor provides support for generating documentation for XSLT 
and XSD - not yet for RNG I am afraid.
However, for XSLT the main idea was to document the structure itself and 
the user documentation can be written in different annotation formats: 
we define also an oXygen specific format that provides highlighting and 
links but we support also other languages including XSLStyle, a DocBook 
subset, a DITA subset, etc.
 From our experience with generating documentation the user 
documentation is a secondary concern and that can easily take different 
languages - the more difficult part is getting the 
schema/stylesheet/etc. structure and split that, generate diagrams where 
needed, link between different components, etc.

Here you can find additional information and some examples of how the 
generated documentation looks like:
*XSLT*
http://www.oxygenxml.com/xml_editor/xslt_documentation.html
DocBook to XHTML: 
http://www.oxygenxml.com/samples/xslt-documentation/docbook/docbook.html
DITA to XHTML: 
http://www.oxygenxml.com/samples/xslt-documentation/dita/map2xhtmall.html

*XML Schema*
http://www.oxygenxml.com/xml_editor/xml_schema_documentation.html
HTML sample: 
http://www.oxygenxml.com/samples/xml-schema-documentation/personal/personal.html
PDF sample: 
http://www.oxygenxml.com/samples/xml-schema-documentation/personal/personal.pdf

Hope this helps!

Best Regards,
George
--
George Cristian Bina
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com

On 5/15/13 9:59 PM, Lech Rzedzicki wrote:
> We're considering developing in-house markup standard or a best practice
> for inline XML documentation.
> This would be used on XSL, RNG and XML instance documents in various
> proprietary schemas.
> Do you see an advantage in developing markup that would be consistent
> across multiple XML schemas?
> It would mean writing just one XSL to say produce HTML output of that
> documentation, but as schema and stylesheets need to document different
> things, I wonder how it might work in practice?
> Has anyone taken on a similar initiative in the past?
> What do you use to document your XML, do you just use XML comments?
> If so do you follow some convention inside a'la javadoc?
>
> If you were to recommend different documentation markup per schema - one
> for RNG/RNC, one for XSL etc, what would you recommend?
>
> Lech
>