OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index]
Re: [xml-dev] Common documentation standard across multiple XML schemas

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:
DocBook to XHTML: 

*XML Schema*
HTML sample: 
PDF sample: 

Hope this helps!

Best Regards,
George Cristian Bina
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index]

News | XML in Industry | Calendar | XML Registry
Marketplace | Resources | MyXML.org | Sponsors | Privacy Statement

Copyright 1993-2007 XML.org. This site is hosted by OASIS