RE: [xsl] xsl/xslt coding standard

["James Fuller" <james dot fuller at o-idev dot com>]

> [mailto:owner-xsl-list@lists.mulberrytech.com]On Behalf Of Jeni Tennison

> > If you take the idea of using document-element-prefixes to mark
> certain namespaces as being for documentation, people who wanted to
> could bring across that pattern of documentation if they wanted.

I see the need to have a common set of conventions for meta data within a
stylesheet...not just that of satisfying  doc requirements, inevitably
people will want to include;

- versioning and authoring meta data
- generic doc
- code doc
- change log
- compatibility issues
- licensing
- usage details
- and whatever else, that is actually meta data which also happens to be
'documentation'

I think that developers should have a choice of which markup to use within
their documentation....Docbook, XHTML, HTML, voiceml, dublin core, whatever
etc.....

So, I think that we need a recognized doc idiom.....but possibly expand the
idea that doc is a subset of a general requirement of metadata within an xsl
stylesheet ( or any markup for that matter ! ) .

I was surprised to see the lack of a specific documentation namespace
...e.g. that xs:documentation is using xs defined as
xmlns:xs="http://www.w3.org/2001/XMLSchema".....would it not make sense to
have a standard unique namespace that can be used across every markup, not
just xsl....

Scenario 1: add an xsl specific element <xsl:doc/> which of course binds it
to the xsl namespace....but why ? This seems silly when we have a doc
requirement in every markup.

Scenario 2: <xs:documentation/> which binds it to XML schema.....but why ?
same problem as S1 in addition, that some people will not a binding to XML
schema  because it is not a native markup for writing documentation.

Scenario 3: add a new namespace to XMLSchema which then segregates the doc
from schema...yet keeps it under Schema <meta:doc
xmlns:meta="http://www.w3.org/2001/XMLSchema/Documentation"/>this may keep
everyone happy.

Scenario 4: <meta:doc
xmlns:meta="http://www.w3.org/2002/someDocumentation"/>this takes it 'out'
of schema and xsl namespaces...

so I suggest Scenario 4...

and using the XHTML module for Metainformation
http://www.w3.org/TR/xhtml-modularization/abstract_modules.html#s_metamodule

which  means we have a unique namespace
http://www.w3.org/TR/xhtml-modularization/DTD/xhtml-meta-1.mod that is a
subset of xhtml, itself a language to be used for documentation.

as we can extend it as time goes on; not to mention use it whithin any
context, in addition to using any markup you would like within those meta
elements.

I think Jeni's suggestion of adding to xsl:stylesheet doesnt make any
sense...for example if your document is HTML format; what happens if you
also use HTML namespace in a literal result element...as part of your result
tree ? Also meta data, such as doc, should be able to live on its on, after
any kind of extraction or transform process (....something like Xinclude or
even non-xml processing )...which means that putting this data in the
enclosing stylesheet element as an attribute is not a precise enough
resolution....though admittedly it would be a pain to have to explicitly add
namespace declaration to each <meta:doc/> tag.


cheers ,jim fuller


ps: the words xs:annotation and xs:documentation are wayyyy to long also !


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