Re: Re: xsl/xslt coding standard

>Date: Mon, 19 Aug 2002 09:51:12 -0600
>From: "Edward L. Knoll" <ed.knoll@xxxxxxxxxxxxxx>
>To: XSL-List@xxxxxxxxxxxxxxxxxxxxxx
>Subject: Re:  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@xxxxxxxxxxxxxx
>                  e-mail (business): eknoll@xxxxxxxxxx
>                  e-mail (personal): edward@xxxxxxxxxxx



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