DSSSL Documentation Project?

[Tony Graham <tgraham@xxxxxxxxxxxxxxxx>]

Several things have caught my attention over the last several weeks:

 - Earl Hood's assertion during the "DSSSL WWW Enhancements"
   discussion (and the agreement that followed) that "what would help
   more than anything else is good tutorials and examples of using
   DSSSL. Since good learning material on DSSSL is still scarce,
   people will be less likely to adopt it." [1]

 - More recently, Stephen Tinney provided "for the archives" a
   step-by-step procedure for separating and including library
   routines [2]

 - At the time I asked, no-one had volunteered to "write some more
   documentation", which is one of the ways to contribute to Jade
   listed at the end of the "jade.htm" file in the Jade
   distribution. [3]

 - There have been more than 2,700 requests for files in the DSSSList
   archive in the 2.5 (2½) months the DSSSList has been in
   existence [4]

The way I put these together is that there is a perceived need for
more DSSSL documentation, many people are actively looking for help,
but while many of us are capable of writing some documentation, the
lack of a framework for an individual's effort hasn't brought out all
the people who can contribute to a documentation effort.

There are several excellent tutorials on DSSSL and other information
available on the Web [4], but I am proposing that we, the DSSSList
subscribers, start an organized project to write and disseminate
documentation on all aspects of DSSSL -- including the flow objects,
style language, transformation language, expression language, and
query language -- using lots of examples, plus make a "DSSSL Cookbook"
of tips and techniques for using DSSSL.  We are, of course, well able
to produce documentation in a variety of forms using the tools
conforming to the very standard we are documenting.  And, in turn, the
stylesheets for the documentation can serve as further examples of
DSSSL usage.

I hope I'm not being presumptuous, but having comprehensive, freely
distributable and accessible DSSSL documentation may also aid in the
acceptance and use of xml-style the way, from my perception, that
documentation from the Linux Documentation Project aided the spread of
Linux.

It is more than premature to say what form the output of this
documentation project would take, but there are many instances of what
could be "real" documentation in people's mail to the DSSSList (some
examples are [2] and [6], finding more is left as an exercise for the
reader), there is a rudimentary DSSSL Cookbook at [7], and I have
hastily thrown together a page on simple-page-sequence [8] by adding a
graphic to the characteristics table from the current XS spec (and
suggestions for what else it requires are welcome).

Should this project take off, I am pleased to be able to offer the
Mulberry web site for the home page of the project.

Regards,


Tony Graham
=======================================================================
Tony Graham, Consultant
Mulberry Technologies, Inc.                         Phone: 301-231-6931
6010 Executive Blvd., Suite 608                     Fax:   301-231-6935
Rockville, MD USA 20852                 email: tgraham@xxxxxxxxxxxxxxxx
=======================================================================

1. http://www.mulberrytech.com/dsssl/dssslist/archive/0293.html
2. http://www.mulberrytech.com/dsssl/dssslist/archive/0450.html
3. http://www.jclark.com/jade/
4. Mulberry web site statistics
5. http://www.sil.org/sgml/related.html#dsssl
6. http://www.mulberrytech.com/dsssl/dssslist/archive/0049.html
7. http://www.mulberrytech.com/dsssl/cookbook
8. http://www.mulberrytech.com/dsssl/cookbook/simple-page-sequence.html


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist