RE: [xsl] xsl/xslt coding standard

["James Fuller" <james.fuller@xxxxxxxxxx>]

Larry Garfield wrote

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

no, u get it .....i would like to have a nice little 'piecemeal' bit that is
general enough for documentation, similar to John Cowan's IBTWHS ( from
Francis ) but able to deal with a slightly expanded scope...I had suggested
reusing the meta data module...but I can see something that is a mixture of
a reduced IBTWHS and meta module.

I feel quite confident that XHTML is the place for this, as it imparts the
native ability to document ( though as u pointed out is not necc core for
this type of thing ) instead of asking XSLT or XML Schema to go outside of
their problem domain and specify ( as done with xs:documentation or some
sort of proposed xsl:doc does ) specific elements that would be strange to
use across all markup. As stated it would be strange to be using an xsl:doc
in the middle of a VOICEML document.

I am quite amazed at the slow burn that XHTML is, with respect to taking
over HTML especially...as I mentioned before I think that we need to promote
its usage, and reduce the many headed hydra that XML is today...to something
that was 'pre browser war HTML useful'.

> 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

I agree, but if we are talking about a XML wide, instead of just XSL,
requirement for documentation then we should probably use markup for this, I
think that all I am reaching for is part 'Lingua Franca' pattern, nothing so
overarching.....

The difference between using <!-- --> or /* */ is trivial in implementation
be it this syntax or another xml specific one. And if purely constrained to
the world of markup, then I don't have an issue doing this, I can see where
having snippets of xml within C code would be interesting...but possibly
counterintuitive; though I do it all the time.

Javadoc is useful, but would it not more useful for Javadoc to directly
publish in xml form. Various transforms could produce the human
documentation we love, the WSDL-like file for describing methods, possibly
the UML diagrams in SVG, and a variety of fun things....which of course is
the Java Doclet technology from SUN.

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

I see what where you are getting at.

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

naughty, naughty...but honestly I don't want to get into that line of
reasoning, its not rare that I will perform the following when dealing with
any markup in my daily life;

- general documentation
- code level annotation
- meta data along the lines of versioning and author
- the ability to specify a generic container, by just using meta:doc or
doc:doc; ...in other words I may want to pop in a bit of Docbook, Dublin
Core or whatever else might come done the pipe

we had a similar discussion, when doing the EXSLT effort....and to a certain
degree we went a little overblown....so I think that I will knock up
something that is simple and fulfills the requirements of the lowly
programmer just wanting to document their code.

will look forward to your comments.

cheers, jim fuller


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