Re: [xsl] xsl/xslt coding standard

[Francis Norton <francis@xxxxxxxxxxx>]

May I suggest John Cowan's IBTWHS 
(http://www.xmlhack.com/read.php?item=585) which is the DTD for an XHTML 
subset intended for embedded documentation?

Francis.

Larry Garfield wrote:

> James Fuller wrote:
>
>  
>
> > - XHTML is a native format one can use for documentation, so there is a
> > standard native option that is close enough to the HTML we all know and love
> > ( instead of XSLT or XML schema specific, niether of who's core requirement
> > is to be a language for documentation or meta data )
> >    
>
> XHTML is not a language whose core requirement is to be a language for
> documentation, either.  In that sense, DocBook is more "naturally
> targeted" at documentation than XHTML is.  If we're going to say that
> XSLT and XML Schema are not designed for documenting code so we
> shouldn't use it for documenting code, then by extension we need to
> find/develop some system that is specifically designed and optimized for
> commenting code.
>
> Personally, I'd be in favor of going as far as a W3C-standardized
> XML-documentation format beyond normal <!-- comment --> tags.  That way,
> just as with JavaDoc, you could easily parse it into a separate document
> to serve as documentation.  The SVG folks are using RDF as a
> documentation format, which has its ups and downs.  
>
> 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
> 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.
>
>  

--
"Never mind manoeuvre, go straight at 'em." - Admiral Horatio Nelson




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