OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

sdd message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [sdd] Re: Request for Committee Specification Ballot: SDD


> can be downright brutal....

Brent, I don't necessarily disagree with you.  (Maybe) we need to provide
tools to eliminate some of the human/manual part of the task.  It does
require concentration and extreme care to get things right in the
absence of automation.

If you are in the process of editing/correcting files, here are a
couple items I omitted -- trying to focus on the more egregious
errors.

1. The RDDL documents need to follow the RDDL templates provided on
    the OASIS Library web site; the three RDDLs provided are ad hoc,
    and use nomenclature that's not current with the Naming Guidelines

2. You indicated in the instructions that the TC wanted to declare
    the Word (.doc) format files authoritative.  But the three
    RDDL documents (using the rubric "Normative") declare the
    PDF format document to be authoritative.  The RDDL docments
    should (by your verdict) be edited to indicate that the .doc
    format files are authoritative.

Let me know if I need to do anything to help.

Cheers,

Robin (in Dallas)

Robin Cover
OASIS, Chief Information Architect
Editor, Cover Pages and XML Daily Newslink
http://xml.coverpages.org/


On Tue, 29 Apr 2008, Brent Miller wrote:

> Robin,
>
> I am at the OASIS Symposium with Mary. I'll try to sit down with her and
> go through these issues.
>
> Apologies for any mismatches. As Mary, our specification editors and I
> (and I'm sure many other people) can attest, this process of just getting
> all the URIs (etc.) right can be downright brutal.
>
> I appreciate your taking the time to work on this and point out
> discrepancies. I'm sure we'll find a way to resolve the issues.
>
> Regards,
> Brent
>
> Brent A. Miller
> Senior Technical Staff Member
> Lead Architect, Autonomic Computing
> IBM Corp.
> Tel. 919-543-6959 (TIE 441)
>
> "In theory, there is no difference between theory and practice. But, in
> practice, there is."
> -- Jan L.A. van de Snepscheut
>
>
>
> Robin Cover <robin@oasis-open.org>
> 04/29/2008 03:19 PM
>
> To
> SDD TC List <sdd@lists.oasis-open.org>
> cc
> Mary McRae <mary.mcrae@oasis-open.org>, Robin Cover <robin@oasis-open.org>
> Subject
> [sdd] Re: Request for Committee Specification Ballot: SDD
>
>
>
>
>
>
>
> Owing to VPN (IP address) connection problems in Santa Clara, Mary McRae
> asked me to upload files associated with "Solution Deployment Descriptor
> Specification 1.0" (approved) Committee Draft 4, 8-April-2008, in
> preparation for a Committee Specification ballot.
>
> I cannot upload the files until I receive clarification from the
> TC and/or Mary: the upload instructions forwarded to me are ambiguous
> due to:
>
> a) discrepancies between the instructions and the implications from
>    the data themselves
> b) apparent conflicts (discrepancies) in the data
> c) incomplete instructions about desired filenames and file locations
>
> It would be hazardous for me to guess at all the correct anwers, so
> I am seeking clarification.
>
> Lots of incorrect URIs: In addition, it appears to me that the
> number of (apparent) discrepancies which could lead to errata or to a
> failed CS ballot warrant re-examination of the data and/or instructions
> made to TC Admin.  Since I do not have any official role as TC Admin,
> I am not empowered to make changes to TC requests.  Furthermore, since we
> to not "break links" (once a URI is published), there's too much risk
> in (my) uploading resources to the incorrect location(s): the URIs
> would become permanent.
>
> =====================================================================
> #1 Instructions for schema file upload implicitly contradict the
>    URIs given in the canonical schema files
> =====================================================================
>
> The instructions request that the six XML schema files be unzipped
> and installed in the /FullSchema/ and /CL1Schema/ directories. The
> schema URIs in the schema files do not reflect the directory portion
> in the paths
>
> [quote from="TC instructions"]
>
> * Full schema (set of XSD files in a ZIP) is at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27987/FullSchema.zip
>
>   and the unzipped files are to be published at
>   http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema
> * CL1 schema (published for convenience; set of XSD files in a ZIP) is at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27988/CL1Schema.zip
>
>   and the unzipped files are to be published at
>   http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema [/quote]
>
> However, the XML schema files are at variance:
>
> 3x schema files in /FullSchema/ attest:
> URL:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
> schemaLocation
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
> schemaLocation
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
> URL:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-deploymentDescriptor-1.0.xsd
>
> URL:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-packageDescriptor-1.0.xsd
>
>
> 3x schema files in /CL1Schema/ attest:
> URL:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
> schemaLocation:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
> schemaLocation:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
> URL:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-deploymentDescriptor-1.0.xsd
>
> URL:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-packageDescriptor-1.0.xsd
>
>
> Since we do not create arbitrary URI aliases, the TC needs to make a
> clear choice, and (IMO) normalize/correct the URI references in all
> specification materials.  Please confirm with Mary (that) WRT OASIS
> rules that an "approved" CS cannot be emended, even "editorially"
> for minor changes.
>
> =====================================================================
> #2  Similar to #1 above, the three RDDL (XML Namespace) documents
>     have XML schema URIs lacking the directory components in the path
> =====================================================================
>
> XSD:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-common-1.0.xsd
> XSD:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-deploymentdescriptor-1.0.xsd
>
> XSD:
> http://docs.oasis-open.org/sdd/v1.0/cd04/cd04-sdd-packagedescriptor-1.0.xsd
>
>
> Note in the "PackageDescriptor Namespace" document a typo:
> *http://docs.oasis-open.org/sdd/nsv1.0/cd04/cd04-sdd-packagedescriptor-1.0.xsd
>  (see HTML link code associated with the  display text
>  "cd04-sdd-packagedescriptor-1.0.xsd")
>
> =====================================================================
> #3  Similar to the instructions, but at variance with the Schemas and
>     RDDL document URIs, Specification Appendix A ("A. Schema File
>     List") presents URIs with 1 directory components in the path
> =====================================================================
>
> From Appendix A
>
> http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema/cd04-sdd-common-1.0.xsd
> http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema/cd04-sdd-common-1.0.xsd
>
> *http://docs.oasis-open.org/sdd/v1.0cd04/CL1Schema/cd04-sdd-deploymentDescriptor-1.0.xsd
> [typo]
> http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema/cd04-sdd-deploymentDescriptor-1.0.xsd
>
> http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema/cd04-sdd-packageDescriptor-1.0.xsd
>
> http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema/cd04-sdd-packageDescriptor-1.0.xsd
>
>
> * Note the typo in one of the URIs
>
> =====================================================================
> #4 'Previous Version: specification URIs on the cover page appear to
>     be incorrect
> =====================================================================
>
> Whereas the "Previous Version:" URIs contain a substring 'pr01-r01',
> the documents published in the OASIS Library for the preceding
> spec version are different.  The most recent published version is
> 'pr01', and the URIs are as follows:
>
> * http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.html site
> * http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.doc site
> * http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.pdf site
>
> If the 'cd04' files are uploaded, the cover page "Previous Version:"
> URIs will create status 404 errors when dereferenced:
>
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.html 12
> display
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.html link
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.doc 13
> display
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.doc link
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf 14
> display
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf link
>
> We cannot break the existing URIs, and I have no authorization to
> create (gratuitious) URI aliases, nor to seek out missing intermediate
> documents (and publish them) -- should any such documents exist.
>
>
> =====================================================================
> #5  Similar to #4, the three RDDL (XML Namespace) documents attest
>     URIs for resources that are missing (404)
> =====================================================================
>
> All three RDDL (XML Namespace) documents have:
>
> *Prev:
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf
> *Prev:
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf
> *Prev
> http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01-r01.pdf
>
> =====================================================================
> #6  URIs published in the three RDDL (XML Namespace) documents for
>     "Previous version:" [(Public Review, Revision 1)] schema files
>     do not match any existing online resources
> =====================================================================
>
> The following schema file URIs in RDDL documents are published:
>
> *Prev:
> http://docs.oasis-open.org/sdd/v1.0/pr01/pr01-r01-sdd-common-1.0.xsd
> *Prev:
> http://docs.oasis-open.org/sdd/v1.0/pr01/pr01-r01-sdd-deploymentdescriptor-1.0.xsd
>
> *Prev
> http://docs.oasis-open.org/sdd/v1.0/pr01/pr01-r01-sdd-packagedescriptor-1.0.xsd
>
>
> In fact, the most recent published schema URIs (they would be
> ("Previous version:" from the POV of CD04) are:
>
> http://docs.oasis-open.org/sdd/v1.0/pr01/FullSchema/pr01-sdd-common-1.0.xsd
>
> http://docs.oasis-open.org/sdd/v1.0/pr01/FullSchema/pr01-sdd-deploymentDescriptor-1.0.xsd
>
> http://docs.oasis-open.org/sdd/v1.0/pr01/FullSchema/pr01-sdd-packageDescriptor-1.0.xsd
>
>
> Dereferencing the URIs presented in the RDDL documents would result
> in status 404 errors.
>
> =====================================================================
> #7 Incomplete information about RDDL file locations and filenames
> =====================================================================
>
> A. No instructions are given about the TC's preference (if any) for
>    URIs to be associated with the RDDL namespace document files
>    themselves.  By convention, we do not create directories (or
>    files) corresponding to NS URIs themselves: we use URI rewrite
>    rules to present a namespace document to a user (agent/client)
>    when the NS URI is dereferenced, ensuring that the NS URI
>    is retained in the browser address window.  By this means, we
>    clearly associate the (visible) namespace URI with the namespace
>    document which documents the namespace.
>
>    Oddly, the published 'pr01' SDD specification has no namespace
>    document(s) associates with the NS URIs, so convention is
>    missing.  Absent any special request or preference from the TC,
>    I would probably store the new namespace documents in the
>    directory http://docs.oasis-open.org/sdd/v1.0/, OR create
>    an alias in /v1.0/ with the actual file in /cd04/
>    (http://docs.oasis-open.org/sdd/v1.0/cd04/) -- but the choice
>    is not consequential.
>
> B. The files embedded in the ZIP ('namespaces') are:
>
> cd04-common-rddl-1.0.html
> cd04-deploymentdescriptor-rddl-1.0.html
> cd04-packagedescriptor-rddl-1.0.html
>
> However, the upload instructions are silent about whether these
> filenames represent a specific choice on the part of the TC.
> If not, it might be clearer to follow the URI pattern used in
> the other SDD spec resources, viz., to include the 'sdd'
> naming component.  Thus:
>
> sdd-cd04-common-rddl-1.0.html
> sdd-cd04-deploymentdescriptor-rddl-1.0.html
> sdd-cd04-packagedescriptor-rddl-1.0.html
>
> Please clarify if any specific request is implied or of concern.
>
> =====================================================================
> #8 [Non-fatal] Example ZIP file missing from install list/instructions
> =====================================================================
>
> Appendix A ("A. Schema File List")
>
>   [quote]
>   "Example SDDs showing the use of the schema can be found at the
>   following address.
>   http://docs.oasis-open.org/sdd/v1.0/sdd-examples-v1.0.zip"; [/]
>
> No such file is currently installed, and is not referenced in the
> install instructions.
>
>
> =====================================================================
> #9 [Non-fatal] XML Namespaces (not a showstopper for mere upload)
> =====================================================================
>
> * Section 1.7 "XML Namespaces" fails to identify the XML Namespaces;
>   it only mentions three prefixes, but by rule, prefixes are
>   insignificant. The critical namespace declaration is the
>   HTTP scheme URI, and should be presented here.
>
> "The XML namespaces defined as part of this specification are:
>  - sdd-pd: stands for the package descriptor portion of the SDD
>    namespace.
>  - sdd-dd: stands for the deployment descriptor portion of the
>    SDD namespace.
>  - sdd-common: stands for the common (shared) types, elements
>    and groups of the SDD namespace."
>
> =====================================================================
> #10 [FYI, Non-fatal] Missing documents references
> =====================================================================
>
> * Section 1.2 references a Primer, but the Primer '[SDDP]' does not
> exist at the referenced URI(s):
>
> [SDDP]           Solution Deployment Descriptor Primer
> http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.doc
> http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.pdf
> http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.html
>
> * Section 1.2 references a Profile, but the Profile '[SDDSP]'
> does not exist at the referenced URI(s):
>
> [SDDSP]          Solution Deployment Descriptor Starter Profile
> http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.doc
> http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.pdf
> http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.html
>
>
> - Robin Cover
>   OASIS, Chief Information Architect
>
> =========== Notes and References
>
>
> [1] Sources:
>
> http://www.oasis-open.org/committees/download.php/27964/sdd-spec-v1.0-cd04.doc
>
> http://www.oasis-open.org/committees/download.php/27965/sdd-spec-v1.0-cd04.pdf
>
> http://www.oasis-open.org/committees/download.php/27966/sdd-spec-v1.0-cd04-HTML.zip
>
> http://www.oasis-open.org/committees/download.php/27987/FullSchema.zip
> http://www.oasis-open.org/committees/download.php/27988/CL1Schema.zip
> http://www.oasis-open.org/committees/download.php/28002/namespaces.zip
>
> [2] Candidate URIs:
>
> http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.doc
> http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.pdf
> http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.html
> http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema
> http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema
>
> [3] (candidate) RDDL filenames as uploaded to Kavi in ZIP:
>
> cd04-common-rddl-1.0.html
> cd04-deploymentdescriptor-rddl-1.0.html
> cd04-packagedescriptor-rddl-1.0.html
>
>
> ============= Upload request:
>
> Brent Miller/Raleigh/IBM
> 04/17/2008 07:31 AM
> To <mary.mcrae@oasis-open.org>
> cc Subject
> RE: Request for Committee Specification Ballot: SDDLink
>
> Mary,
>
> The specification has been updated to reflect its approval as CD04. Here's
> the full updated information/request for CS ballot:
>
> The OASIS SDD TC has approved moving the current CD04 specification and
> schema draft forward for a Committee Specification vote. We understand
> that you conduct this ballot.
>
> SDD Public Review was held from January 18 - March 18, 2008. Two public
> review comments were received (see the TC's "comments" e-mail archives);
> details about these comments and their disposition can be found at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27940/SDD-PRComments.doc
>
>
> The TC approved the PR01-R01 draft as CD04; this draft has no Substantive
> Changes from the PR01 draft that was approved and underwent Public Review
> (meeting minutes with the unanimous TC approval are at
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27916/Meeting%20Minutes%20OASIS%20SDD%20TC%202008.doc
>
> see the 03/27/2008 minutes).
>
> Please publish the following documents on docs.oasis-open.org, according
> to the
> URIs specified within the documents, and please initiate a ballot to
> approve
> these as Committee Specification:
>
>  *  Specification editable source (MS-Word): document is at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27964/sdd-spec-v1.0-cd04.doc
>
>     and is to be published at
>     http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.doc
>  *  Specification PDF: document is at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27965/sdd-spec-v1.0-cd04.pdf
>
>     and is to be published at
>     http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.pdf
>  *  Specification HTML: document (set of HTML files in a ZIP) is at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27966/sdd-spec-v1.0-cd04-HTML.zip
>
>     and is to be
>     published at
> http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.html
>  *  Full schema (set of XSD files in a ZIP) is at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27987/FullSchema.zip
>
>     and the unzipped files are to be
>     published at http://docs.oasis-open.org/sdd/v1.0/cd04/FullSchema
>  *  CL1 schema (published for convenience; set of XSD files in a ZIP) is
> at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/27988/CL1Schema.zip
>
>     and the unzipped files are to be
>     published at http://docs.oasis-open.org/sdd/v1.0/cd04/CL1Schema
>  *  The RDDL namespace documents are at
>
> http://www.oasis-open.org/apps/org/workgroup/sdd/download.php/28002/namespaces.zip
>
>     ** The authoritative version of the specification is the MS-Word
> editable
> source
>
>     If you need any additional information, please let me know.
>
>     Thank you!
>
> Regards,
> Brent
>
> Brent A. Miller
> Senior Technical Staff Member
> Lead Architect, Autonomic Computing
> IBM Corp.
>
> ==================================================
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  You may a link to this group and all your TCs in
> OASIS
> at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
>
>


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]