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

Re: XSL - Documentation

Subject: Re: XSL - Documentation
From: "G. Ken Holman" <gkholman@xxxxxxxxxxxxxxxxxxxx>
Date: Wed, 13 May 2009 08:09:56 -0400
Re:  XSL - Documentation
At 2009-05-13 11:57 +0200, Michael Schdfer wrote:
I've given this subject some thoughts I'd like to share. They centre on two
central aspects: a possible requirement for a
general approach to standardising
XML documentation and simple XML comments vs. structured, namespace-based
comments.
...
 * XSLStyle supports DITA and DocBook. I have practically no experience
   with these document types, but from the little I know I'd say that
   in the vast majority of cases they go far beyond the requirements for
   documenting XSLT, XSD and so on.

   When generating documentation from an XSL document, one gets most of the
   information by analysing the code, so in a
comment one would add maybe some
   descriptive text, change and state information and a hyperlink here and
   there, or an image. The same probably applies to XSD.

   So I think that allowing the full set of DITA and DocBook features for
   use in comments may introduce unnecessary complexity.

Interestingly I saw the choice of DITA and DocBook as introducing simplicity because in both cases I use off-the-shelf stylesheets (included in the package) that render these vocabularies to HTML. No need to write one's own documentation vocabulary and then stylesheets for that vocabulary.

And I have a number of customers' stylesheets
documented with lists, graphics, tables, program
listings and other constructs that are all
sitting there ready to use in the off-the-shelf vocabularies.

   If one looks at Wiki text formatting like it's supported in Trac, one
   can do impressively much with little effort and complexity, including
   tables, images and hyperlinks, and the learning curve is flat. If more
   was needed, one could mix in XML islands as one does with HTML in Java
   comments.

The modular design of the stylesheets should allow anyone to plug in their own documentation vocabulary in place of DITA or DocBook. You are welcome to find or devise your own XML model for documentation and integrate it into XSLStyle. The design should allow you to do this without touching the XSLStyle fragments as I believe those fragments have zero dependencies on either DITA or DocBook.

But you may find value in learning the basics of
these two vocabularies, but you can do a lot
knowing only that DocBook <para> and DITA <p>
allow you to document every aspect of the stylesheet with paragraphs of
prose.

Forgive my delay (because of OASIS deadlines in
two committees) in incorporating stylistic layers
in between XSLStyle and either DocBook or DITA
that have been requested by two active
users.  These changes will give a much flashier
presentation of the content that looks far more
visually attractive than just using the
off-the-shelf stylesheets.  Again, as I said
above, both any new vocabulary and its
stylesheets should be able to be incorporated
with zero changes to the base XSLStyle stylesheet
fragments.  I hope it won't be long before my committee work abates.

. . . . . . . . . . . . . Ken

--
XSLT/XSL-FO/XQuery hands-on training - Los Angeles, USA 2009-06-08
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/s/
Training tools: Comprehensive interactive XSLT/XPath 1.0/2.0 video
Video lesson:    http://www.youtube.com/watch?v=PrNjJCh7Ppg&fmt=18
Video overview:  http://www.youtube.com/watch?v=VTiodiij6gE&fmt=18
G. Ken Holman                 mailto:gkholman@xxxxxxxxxxxxxxxxxxxx
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/s/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal

Current Thread

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