[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: Lech Rzedzicki <xchaotic@gmail.com>
  • To: "xml-dev@lists.xml.org" <xml-dev@lists.xml.org>
  • Date: Thu, 16 May 2013 10:36:17 +0100

Re:  Common documentation standard across multiple XML schemas
Thank you Ken - this is looking really good and not sure how how I missed it - I will definitely give it a go.
May I suggest that you rephrase some of your description on http://cranesoftwrights.com/resources/#xslstyle so that search engines pick up on "XSL documentation" keywords - in spite of being very relevant, your page doesn't show up in top Google results.
Just curious, have you used this markup for anything other than XSL?
In general do you think that this is a good idea? Like I said I have some reservations due to the fact that you're documenting different concepts in Schemas and in XSL...

Lech


On 15 May 2013 20:13, G. Ken Holman <gkholman@cranesoftwrights.com> wrote:
At 2013-05-15 19:59 +0100, 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?

In my XSLStyle approach for documenting XSLT stylesheets I standardized scaffolding and then offer the user to plug in under the scaffolding one of three vocabularies for the actual documentation:  DocBook, DITA or XHTML.

  http://CraneSoftwrights.com/resources/#xslstyle

I then have three XSLStyle stylesheets that have a common fragment to handle the scaffolding and tailored fragments for each of the three documentation vocabularies.  This produces a JavaDoc-like result.  One of my clients posted the stylesheet documentation of a system I wrote here:

  http://sportsmlt.svn.sourceforge.net/viewvc/sportsmlt/2.0/sportsmlt2.html

The XSLT with the embedded constructs is here:

http://sportsmlt.svn.sourceforge.net/viewvc/sportsmlt/2.0/sportsmlt2.xsl?view=markup

XSLT allows non-XSLT elements as children of the document element, and so the XSLStyle scaffolding lives there quite innocuously.  The scaffolding provides structure and section titling and business rules for validating properly-written documentation.  It is agnostic to the content below the scaffolding and allows the user to put in anything at all.  The business rules are validated at the time the documentation is generated.

If you were to use something like XSLStyle in an XML vocabulary where the presence of the scaffolding markup is not innocuous, you would need a filter of some kind to take it away and leave the transient undocumented result for processing.  You wouldn't have to worry about taking away the descendent documentation constructs below the top-level scaffolding elements.

I hope this helps you with some ideas.

. . . . . . . . Ken


--
Contact us for world-wide XML consulting and instructor-led training |
Free 5-hour lecture: http://www.CraneSoftwrights.com/links/udemy.htm |
Crane Softwrights Ltd.            http://www.CraneSoftwrights.com/x/ |
G. Ken Holman                   mailto:gkholman@CraneSoftwrights.com |
Google+ profile: https://plus.google.com/116832879756988317389/about |
Legal business disclaimers:    http://www.CraneSoftwrights.com/legal |


_______________________________________________________________________

XML-DEV is a publicly archived, unmoderated list hosted by OASIS
to support XML implementation and development. To minimize
spam in the archives, you must subscribe before posting.

[Un]Subscribe/change address: http://www.oasis-open.org/mlmanage/
Or unsubscribe: xml-dev-unsubscribe@l....org
subscribe: xml-dev-subscribe@l....org
List archive: http://lists.xml.org/archives/xml-dev/
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php




[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.