At 2009-05-13 11:57 +0200, Michael Schäfer 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@C...
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/s/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal


--~------------------------------------------------------------------
XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list
To unsubscribe, go to: http://lists.mulberrytech.com/xsl-list/
or e-mail: <mailto:xsl-list-unsubscribe@l...>
--~--