This is the mail archive of the
xsl-list@mulberrytech.com
mailing list .
Re: Re: xsl/xslt coding standard
- From: Mulberry Technologies List Owner<xsl-list-owner at lists dot mulberrytech dot com>
- To: xsl-list <xsl-list at lists dot mulberrytech dot com>
- Date: Mon, 19 Aug 2002 18:08:16 -0400
- Subject: Re: [xsl] Re: xsl/xslt coding standard
- Reply-to: xsl-list at lists dot mulberrytech dot com
>Date: Mon, 19 Aug 2002 09:51:12 -0600
>From: "Edward L. Knoll" <ed.knoll@cosd.fedex.com>
>To: XSL-List@lists.mulberrytech.com
>Subject: Re: [xsl] Re: xsl/xslt coding standard
>
>I only subscribe to the digest which makes replying to individual
>messages a chore. This is general response to several of the more
>recent threads.
>
>I certainly agree with the assessment that inline documentation is
>meta-data associated with the stylesheet. Of coarse we'd never be able
>to agree on what that set of meta-data should be; out of the proposed
>set there were only a couple I use routinely. However, the meta-data
>should be a superset of what people routinely use; this would provide
>some consistency. No one has to use all predefined documentation
>elements. If we articulate the meta-data as XML elements, users can
>always add their own.
>
>I believe Javadoc helps Java overcome one of it's major deficiencies:
>programming in the large. For a class, all content has to be in the
>same file. You can not separate the specification/description of a
>class from it's implementation. In order to get a sense of what a class
>does, you have to consume the entire implementation description. A good
>set of Javadoc overcomes this problem.
>
>XSL is going to suffer from the same problem. There is no separate
>specification and implementation. To get a sense of what a set of XSL
>is doing, you have to consume the entire implementation. Ideally, the
>author provides an overview. But with no documentation conventions,
>this will not be consistent. And face it, with no established
>conventions, normally well intentioned developers will not bother to
>document if there are no guidelines suggesting what to document.
>Additionally, just the mechanics of scanning a file for the bits and
>bobs of overview makes it difficult to develop an understanding of that
>overview; extracting all of the documentation pieces out into a
>single/coherent document makes it much easier to consume.
>
>I'm not sure that we have to focus on a particular presentation format
>(e.g. (X)HTML). Our goal is to identify and extract meta-data;
>different (meta) stylesheets can be used to extract different elements
>and format them appropriately.
>
>A consistent and general namespace for identifying inline documentation
>elements seems like a good idea. If part of the XSL 2.0 standard, the
>default templates could be defined to ignore all components within this
>namespace. Having a predefined set of meta-data means that implementors
>can supply predefined extraction mechanisms with a reasonable
>probability that they will generate something useful. The XSL
>processors would then have some incentive for providing builtin
>documentation generation capability.
>
>With regards to the argument of documentation overwhelming code: (a) I
>think all of us, if we were honest, would agree that our industry
>typically suffers from the opposite problem, (b) you only have to supply
>as much as you feel is useful, so it doesn't have to overwhelm the
>code. However, I would also have to confess that to generate "good"
>Javadoc for a simple class seems to explode the amount of source
>significantly. Unfortunately, sometimes that's the cost to promote
>maintainable components.
>
>Documentation is one of the keys/costs for successful reuse. Do we
>wantpromote reuse of XSL components (beyond individuals and small
>groups)? If we seriously do, then we need to build in consistent
>documentation mechanisms into XSL.
>
>Regards,
>Ed Knoll
>
>--
>Edward L. Knoll Phone (work) : (719)484-2717
> e-mail (work) : ed.knoll@cosd.fedex.com
> e-mail (business): eknoll@sf-inc.com
> e-mail (personal): edward@elknoll.com
XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list