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


Help: OASIS Mailing Lists Help | MarkMail Help

oasis-member-discuss message

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

Subject: Re: [oasis-member-discuss] Re: Review of AIR = ASIS, possibly mandatorypolicy?

G. Ken Holman wrote:

> At 2006-02-22 17:01 -0800, jon.bosak@sun.com wrote:
>> UBL TC,
>> Forwarded as requested.
>> Jon
>> ------- Start of forwarded message -------
>> Date: Fri, 17 Feb 2006 16:11:17 -0800
>> From: James Bryce Clark <jamie.clark@oasis-open.org>
>> Subject: [chairs] Draft ASIS under review:  mandatory policy?  Please 
>> review
>>  and  comment by 1 March
>> To: chairs@lists.oasis-open.org
> Regarding:
> http://www.oasis-open.org/committees/download.php/16546/ArtifactStandardIdentificationSchemeForMetadata-1.0.1.pdf 
> Line 352 - this is an action item for OASIS staff, not an aspect of 
> this standard ... the "SHALL" in this jumps out at me as totally 
> unnecessary.  By the time most people have read this document, this 
> action item should have long been acted on.  Unless, of course, I'm 
> misunderstanding the sentence in which case it should be rewritten.  
> But, if this updating is a one-time action, is it on the part of those 
> who maintain the The OASIS Document Templates?  When will the 
> decisions be incorporated into the templates (note in my postscript 
> below that I've been working on the DocBook XML templates)?  A lot of 
> UBL 2.0 is already in development ... will a change in the templates 
> while writing a new specification mean that work in progress would 
> become non-conforming? 

The templates were updated to (largely) reflect these guidelines quite a 
while back. And you're right that this is a requirement on OASIS staff 
that they maintain the templates. Doesn't belong, I think.

> Lines 354-386 - I'm not sure what is meant by "consistent tabular 
> form", especially since it looks like the RFC822-styled prompts and 
> values (which is distinctly not "tabular" (I interpret this as 
> systematic aligned rows and columns; the columns are not aligned in 
> RFC822-styled mail headers).  I don't see guidelines as to how this 
> "consistent tabular form" is to be rendered in various renditions?  
> Should it be an HTML table?  If in a PDF table, with visible cell 
> borders (perhaps, somewhere in the front matter)?  Should it be also 
> in HTML <meta> elements (I think so; though I don't know how I'll do 
> this in DocBook)? 

This should be spelled out in the templates for various forms.

> Line 408 - I think ECMA-6 is a poor choice for a 128-byte character 
> set because of the two ambiguous "alternative graphic character 
> allocations" (6.4.2) ... I suppose this is covered because the 
> exclusive list is indicated, so I guess this isn't a problem.  Why use 
> ECMA and not, say, ISO-646?  Actually, I guess it has the same issue.  
> Therefore, why bother citing anything and not just list the characters 
> ... would this in fact cause problems with a mainframe tool that 
> happens to be using EBCDIC?  The fact that it is the correct ECMA/ISO 
> characters when it is being mounted in the repository is fine 
> regardless of how it was written, but given that this is a *naming* 
> standard and not an *encoding* standard, then just listing the 
> characters should be sufficient and any mention of character set is 
> probably unnecessary embellishment. 

Norm beat this pretty well :-). You're both right.  The ECMA names for 
code points were used (started from the ISO/ASCII spec in conception - 

> Oh, I just found the reference to <meta> in HTML in section 6.4.1 ... 
> though it isn't an exhaustive list of the metadata.  If ASIS is going 
> to the trouble of listing all of the metadata components, then perhaps 
> these should be mandatory XHTML metadata entries as well.  Actually, 
> not *just* XHTML, but for every rendition an example is needed of what 
> it is to look like ... otherwise, how would I be able to modify the 
> DocBook XML templates in a conformant fashion? 

Hmm. Fleshing out the XHTML/etc lists would be an improvement. 
Personally I'd defer to the template gods, of which you seem to sorta be 
one.  (<--- VERY weak attempt at humor. Sorry, it's late)

> Line 532 - Absent here are ZIP and TAR/GZ files (though I don't know 
> what to do about them) ... I think they should be recognized ... 
> perhaps have a companion ".txt" file (though I hate the idea of having 
> information in more than one file)?  Though perhaps having a companion 
> ".txt" file for all binary file types will be both sufficient and 
> consistent, but line 350 provides a list of required metadata elements 
> "The following metadata MUST be associated with each Artifact...", so 
> it would have to be documented that for every binary file (or file 
> without a human-readable rendition) that one can expect to find a .txt 
> file with the meta data.  That could add a lot of files! 

Maybe that's justification for not considering archives as artifacts 
(here we go down a rathole)...metadata needs to be associated for 
document management and sorting and searching, but I confess that I 
prefer thinking of them as containers, not as artifacts in their own 
right. Other comments?

> Line 596 - Shouldn't this be a reference to Section 7.1? 


> I think it is going to be difficult to get Joe and Jane 
> StandardsWriter to accurately divine what values for properties in 
> these guidelines apply to documents they create for their committee 
> ... could the guidelines require each TC to publish somewhere visibly 
> in their work pages what the choices are for metadata properties 
> related to all documents for that particular committee?  That way two 
> people in one TC don't end up making different decisions based on 
> their respective interpretations of these guidelines.  I'm learning 
> that one really has to spoon feed stuff like this to people who are 
> made responsible for creating things ... they won't take the energy to 
> have to interpret administrivia and distract them from their technical 
> writing.
> So, I then took a look overall at ASIS and I realized that I really 
> couldn't effectively distill what the important guidelines would be 
> for, say, the UBL TC or my HISC subcommittee of UBL.
> Consider for example the tree of file with the following directory at 
> the apex:
>   http://docs.oasis-open.org/ubl/cd-UBL-1.0/
> ... the artifact in that directory has to be named "index.html" in 
> order to be properly displayed by the server when the directory is 
> referenced.  Does this mean that the directory has the artifact name?  
> Probably, but there are 244 files in that tree.  Are *all* of them 
> (except the necessary exceptions for the directory "index.html" files) 
> to be named with these ASIS guidelines?  If none of them are used 
> outside of the context of UBL 1.0, why would the artifact naming 
> guidelines apply?  I can see them applying to the apex directory and 
> to any ZIP file that would be used out of context of the directory.  
> That's it!  The difference is, when is a committee artifact found 
> *only* in a given context and when is a committee artifact allowed to 
> live outside of that context?  The apex directory can be found in any 
> context, so its name follows the artifact naming guidelines.  The ZIP 
> or TAR/GZ packages of the directory can be found in any context, so 
> its name would also follow the guidelines.  And, as above, I suppose 
> also an associated text file with the metadata for those compressed 
> packages.
> This would greatly simplify a committee's work.  I had the 
> responsibility for creating the directory at the apex:
>   http://docs.oasis-open.org/ubl/cd-UBL-1.0/fs/
> There are 99 files just in my subtree.  BUT my subtree isn't ever 
> found outside of the context of the UBL 1.0 deliverable, so none of 
> the artifacts in that subtree would be out of context (or should be 
> out of context, of course they might be if someone made copies them 
> without copying the other files, but when they are in context on the 
> UBL web site inside of the UBL 1.0 deliverable, they are correct).  
> The burden of going through all 99 files of my subtree and renaming 
> each and every file to follow the artifact naming guidelines 
> (examples, graphics, linked specifications, etc.) would deter me from 
> going through the effort to produce everything that is needed by the 
> readers.  I ended up with 99 files because that tree of hyperlinked 
> documents and examples is what I felt the reader needed.  If I had to 
> go to so much effort for all 99 files, I would have produced fewer 
> files without as much information and the reader wouldn't have been as 
> well served. 

Let's talk offline. The approach I think you're describing is one that 
motivated some of the decisions in the guidelines. Groups of help files 
also take this kind of container arguement.

> I believe OASIS has to make the process of writing specifications 
> *easier* in order to help people with limited time involved in the 
> already lengthy process of writing to produce something that can be 
> used.  Therefore, the burden should be focused to accomplish the goal 
> and not so broad as to deter contributions.  As I said above, I think 
> it is sufficient that the burden of identifying artifacts at the apex 
> directory and any files that might be found outside of the context of 
> the apex directory.
> Perhaps it is easier than I thought and I was just confused by the 
> lack of examples.  In particular, since I chair two subcommittees and 
> one task group below the UBL umbrella, are these distinctions 
> irrelevant?  Are my work products just considered UBL work products? 

The lack of examples was/is a chicken-egg type of problem. Sorry about 
the current lack; I think that your notion of the context of an 
identifier is a useful one that might simplify the guidelines.

Thanks for your thoughtful comments!

bill cox

> . . . . . . . . . . Ken
> p.s. regarding the templates, I put 33 hours into modifying Norm's 
> former DocBook guidelines for OASIS standards into a new set of 
> guidelines to try and help writers using XML, by including all the 
> sections matching the Word and OOo templates found in:
>    http://docs.oasis-open.org/templates
> You can find these new stylesheets and complete publishing package 
> details in:
> http://docs.oasis-open.org/templates/DocBook/spec-0.4/oasis-specification-0.4.html 
> In order to try and get my UBL colleagues to use XML to create the 
> standards documents, I tried to make this environment as turnkey as 
> possible with detailed examples of what to do.  Hopefully by doing so, 
> members would be more encouraged about writing specification documents 
> since the environment would produce the desired presentation without 
> the writer having to think about it.  To prove to myself the 
> environment is functional, I've since used the environment to create 
> the two work products announced in:
>    http://lists.oasis-open.org/archives/ubl/200602/msg00062.html
>    http://lists.oasis-open.org/archives/ubl/200602/msg00069.html
> So, your decisions impact on me by bringing my latest work to the new 
> ASIS standard, and I don't see enough information in there to do a 
> complete job.
> -- 
> Upcoming XSLT/XSL-FO hands-on courses: Washington,DC 2006-03-13/17
> World-wide on-site corporate, govt. & user group XML/XSL training.
> G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
> Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/o/
> Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
> Male Cancer Awareness Aug'05  http://www.CraneSoftwrights.com/o/bc
> Legal business disclaimers:  http://www.CraneSoftwrights.com/legal
> ---------------------------------------------------------------------
> 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 
> 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]