RE: [xsl] xsl/xslt coding standard

[DPawson@xxxxxxxxxxx]

Jim wrote:
> 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'

+ parameters (for usage details)

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

With the simplest one being the 'default' ? For those just
starting?




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

For the lack of another, how about using something from exslt as the
namespace?
<doc:xxx xmlns:doc='http:exslt.org/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"/>t
> his 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...

Like it Jim.
Until one of the working group comes up with support for that, 
use the exslt ns?


> 
> and using the XHTML module for Metainformation
> http://www.w3.org/TR/xhtml-modularization/abstract_modules.htm
l#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.

Hang on Jim, you were suggesting above, to allow one of many documentation
formats? XHTML as the default perhaps?

that makes me think that we'd need at least two additional ns additions.
1. for the wrapper documentation.
2. For the actual elements in use?

OK, that's not too hard.


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 ?

Good point. Highly likely too with xhtml. Suggestions to get round this?
I'd (fairly naturally) put the ns in the stylesheet element.


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

Yep, I don't think its flexible enough either.

Regards DaveP.


**** snip here ********

- 

NOTICE: The information contained in this email and any attachments is 
confidential and may be legally privileged. If you are not the 
intended recipient you are hereby notified that you must not use, 
disclose, distribute, copy, print or rely on this email's content. If 
you are not the intended recipient, please notify the sender 
immediately and then delete the email and any attachments from your 
system.

RNIB has made strenuous efforts to ensure that emails and any 
attachments generated by its staff are free from viruses. However, it 
cannot accept any responsibility for any viruses which are 
transmitted. We therefore recommend you scan all attachments.

Please note that the statements and views expressed in this email 
and any attachments are those of the author and do not necessarily 
represent those of RNIB.

RNIB Registered Charity Number: 226227

Website: http://www.rnib.org.uk 

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