Subject: RE: [xsl] Should You Comment XSLT And If So, How? From: Ryan Gallagher <binerman@xxxxxxxxxxxxxxxxxxxxx> Date: Tue, 18 Feb 2003 22:25:57 -0600 |
> -----Original Message----- > From: Ted Stresen-Reuter [mailto:tedmasterweb@xxxxxxx] > Sent: Wednesday, 19 February 2003 12:51 PM > To: XSL-List@xxxxxxxxxxxxxxxxxxxxxx > Subject: [xsl] Should You Comment XSLT And If So, How? > > > Hi, > > I joined this list what seems like several weeks ago now, at the outset > of a project I am working on (http://www.tedmasterweb.com/htdig/). I've > seen several fascinating conversations taking place here, in addition > to getting several truly excellent answers to what must have seemed > like incredibly dumb questions. In short, I'm fairly wowed and realize > I'm surrounded by rather enlightened beings. > > Thank you all for your time, effort, and sense of humor. > > As you can see by the Subject line, I'd like to know if you think you > should comment XSTL. And if so, How? > > I'd like to say "here's what I do" but what provoked me to ask this > question was a realization that although XML can be commented, I don't > really find myself needing it or making much use of it when writing > XSLT (which is XML). The problem is, I've never seen an XML > application, just sample code. So, I was wondering, should you comment > XSLT and if so, How? > > I sincerely look forward to your answers. > > Peace. > > Ted Stresen-Reuter Hi ted... I am just getting settled with XSLT myself but the few books i've read on the subject, and my fondness of source generated documentation... leads me to the approach that follows: Use XML TAGS in your xsl... <doc type="variable"> <desc>This variable is for X</desc> </doc> <xsl:variable name="foobar" select="Hello World!"/> <doc type="template"> <desc type="short">This template does foo.</desc> <desc type="long">I'm the verbose desc...</desc> </doc> <xsl:template match="foo"> ... </xsl:template> Granted normal comments will still have their place. But anything that you would specifically like to be able to parse out into "pretty documentation" to go alongside your API docs or whatever, could be created from these tags using XSLT itself to do the parsing. Gotta love internal solutions! If you like you can even give your comments a namespace and DTD, but from what i've read/understand anything not in the xsl namespace will be safely ignored outside of templates. Inside templates i'm not positive, but namespaces would certainly resolve the conflicts. Aside: I use normal <!-- --> comments to cause my editor (vim) to fold up blocks of code by default. With foldmethod set to marker you can do the following. <!-- Template: foo {{{ --> <xsl: template name="foo" match="example"> ... </xsl:template <!-- }}} --> Would result in a collapsed object: # Template: foo -->-----------------------------------------------------# This is all probably overkill for small projects (cept maybe the folding) but if you undertake a large xslt project, source generated documentation is very handy. -- Ryan Gallagher (binerman) binerman@xxxxxxxxxxxxxxxxxxxxx The Parchive Project http://parchive.sourceforge.net http://sourceforge.net/projects/parchive XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
RE: [xsl] Should You Comment XSLT A, Ross Ken | Thread | Re: [xsl] Should You Comment XSLT A, Ted Stresen-Reuter |
RE: [xsl] Should You Comment XSLT A, Ross Ken | Date | Re: [xsl] Should You Comment XSLT A, Ted Stresen-Reuter |
Month |