[xquery-talk] XQuery Style Conventions

[McBeath, Darin W (ELS-AMS)]

I apologize in advance for always beginning a new thread, but my current
email reader is stripping out certain headers required by mailman.

 

Anyway, thanks for all of the feedback to date on the xqDoc Style
Conventions. Below, I have captured some of the comments/suggestions from
the past week and have included some thoughts.  We plan on incorporating the
feedback that we have received over the next several weeks and will
disseminate a version 0.2 document by the end of November 2005.  In the
meantime, please keep the suggestions coming and we will do our best to
integrate the feedback into the next version of the document.  In
particular, we are really interested in hearing more about your adopted best
practices.

 

Thanks.

 

Darin.

 

 

1.  XQuery embedded within XML

 

<div>{
  $content-generated-elsewere 
}</div>
 
over
 
<div>
  { $content-generated-elsewere }
</div>

 

I agree (with the reasoning listed by Michael Kay and Michael Rys) that the
first option would be preferable.

 

 

2. Default Function Namespace

 

* Never use a default function namespace other than the F+O namespace, it
will only confuse your readers (and never use the fn: prefix either)

 

I agree with the Michael Kay on this best practice.  Personally, I never set
the default function namespace.    Would it be a best practice to
specifically set the default function namespace or should one be reliant
upon the XQuery engine implementation?  Unfortunately, the Working Draft
states that an implementation 'can' override the default function namespace
if one is not specified.  What are your thoughts on this matter?

 

 

3.  Module URI and Location URI

 

I would agree with Micheal that the Module URI should be used in situations
where there is some form of URI Resolver mechanism.  Unfortunately, there is
currently no 'standard' in this area for XQuery Module URI resolution.  In
my opinion, this would be the best method for handling versioning of
modules, debug versions of modules, etc.  But, in the interim, our approach
of:

 

Module URI:

 
http://xquery. <http://xquery.%3c%3cdomain-name>
<<domain-name>>/<<some-optional-path-info>>/<<file-name-withou
t-suffix>>

 

http://xquery.elsevier.com/fabrication/utilities
<http://xquery.elsevier.com/fabrication/utilities> 

 

Location URI:

 

/<<some-optional-path-info>>/<<file-name-with-suffix>>

 

/fabrication/utilities.xqy

 

 

works under most situations.  It has worked fine for us whether we store our
XQuery modules in a file system or on a webdav server (using the location
URI) or in a database (using the module URI).  Until the April 2005 Working
Draft, there was an indirect requirement that every module namespace URI had
to be unique.   In the February 2005 Working Draft, there was the following
text:

 

It is a static error [err:XQ0047] if more than one module import in a Prolog
specifies the same target namespace. It is a static error [err:XQ0056] if
the target namespace of the modules to be imported is the same as the target
namespace of the importing module

 

 However, this 'requirement' was removed in the April 2005 Working Draft.
So, this would introduce issues with the approach that we have proposed.
Internally, we have avoided this by mandating that all module namespace URIs
must be unique.  But, I'm sure not everyone will agree with this approach
and some will likely have valid reasons for multiple library modules with
the same module uri.  I would be interested in other opinions on this
matter.  For example, would people agree that it's a best practice to have
unique module URIs for every library module?

 

 

4.  Spaces or Tabs

 

I would be ok with specifying only spaces, but I doubt we could reach a
consensus on the matter.  Are they any strong feelings one way or another on
this topic?  I notice that there were no responses to Ron's post on the
subject.

 

I agree with Liam when he states the following (in terms of what really
matters on this topic):

 

(1) clear indication of nesting using space

 (2) being consistent

 

 

5.  PDF version of the document

 

A PDF version is now available here

 

 

http://xqdoc.org/xquery-style.pdf <http://xqdoc.org/xquery-style.pdf> 

 

In the future, we will always publish a PDF version (and likely an XHTML
version).  I believe Frank has offered to help with constructing an XHTML
version.

 

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://xquery.com/pipermail/talk/attachments/20051026/51622cc2/attachment.htm