[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

Re: Common documentation standard across multiple XML schemas

  • From: George Cristian Bina <george@oxygenxml.com>
  • To: Lech Rzedzicki <xchaotic@gmail.com>
  • Date: Thu, 16 May 2013 14:22:43 +0300

Re:  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:
*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
>


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


PURCHASE STYLUS STUDIO ONLINE TODAY!

Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced!

Buy Stylus Studio Now

Download The World's Best XML IDE!

Accelerate XML development with our award-winning XML IDE - Download a free trial today!

Don't miss another message! Subscribe to this list today.
Email
First Name
Last Name
Company
Subscribe in XML format
RSS 2.0
Atom 0.3
 

Stylus Studio has published XML-DEV in RSS and ATOM formats, enabling users to easily subcribe to the list from their preferred news reader application.


Stylus Studio Sponsored Links are added links designed to provide related and additional information to the visitors of this website. they were not included by the author in the initial post. To view the content without the Sponsor Links please click here.

Site Map | Privacy Policy | Terms of Use | Trademarks
Free Stylus Studio XML Training:
W3C Member
Stylus Studio® and DataDirect XQuery ™are products from DataDirect Technologies, is a registered trademark of Progress Software Corporation, in the U.S. and other countries. © 2004-2013 All Rights Reserved.