Re: [xsl] xsl/xslt coding standard

[Larry Garfield <lgarfiel at students dot depaul dot edu>]

James Fuller wrote:

> I generally agree, though I would like to see something centric around
> XHTML, I think its important now to reinforce the usage of XHTML.

Perhaps there is some level of XHTML philosophy that I'm not getting. 
As far as I know, XHTML is HTML turned XML, modularized so that it can
be supported piecemeal by systems that can't afford to support the full
spec or wouldn't know what to do with it anyway, like cell phones.  Is
there a broader philosophical attitude that I'm not aware of?

> > Of course, before we do that, I have to ask, exactly what are we
> > commenting?  We already have a system for unstructured comments, <!--
> > -->.  If we're talking about structured, parsable documentation, the
> 
> but its not xml and not part of our data model....which frankly leaves it
> for human consumption

And an author-specific XML-structured system is really no better in that
respect.  

> > first question to ask is what exactly we're documenting.  With JavaDoc,
> > it was fairly easy.  Methods and classes had been around long enough
> > that figuring out what to document about them was fairly
> > straight-forward.  With XSLT or other XML technologies, what exactly are
> > we commenting?  That's a question we have to ask before we figure out
> > how to comment it.  Otherwise, we're just reinventing <!-- -->, which
> > has already been done.
> 
> reinventing ? I seriousely don't think that <!-- --> serve any good whats so
> ever when it comes to automated processing of documents.

It serves just as much and as little use as /* and */ did for JavaDoc. 
You could build a JavaDoc-esque documentation system that uses
text-structured information inside <!-- --> tags, and it could be quite
useful.  I'd rather see an XML-based one, too, though.  My point is that
not having a standard vocabulary for it, such as just adding a
documentation-prefix="doc" attribute to the root element and leaving the
internals of such elements to the author's preference as was suggested,
doesn't buy you all that much, because then to make sense of it you
would need a different extraction script for each author's tastes.  OK,
there would probably be a few big ones (XHTML, DocBook, RDF), but it's
still only slightly more universal than /* */ and <!-- -->.  

Which still leaves my initial question, what exactly is it that we want
to document?  Honest question, I've not been documenting my XSLT that
much because I'm not sure what I want to say. :-)

-- 
Larry Garfield			AIM: LOLG42
lgarfiel@students.depaul.edu	ICQ: 6817012

-- "If at first you don't succeed, skydiving isn't for you." :-)

 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list