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

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

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 |