[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: RE: [chairs] Unique OASIS document identifiers
We also used the spectools templates for our HumanMarkup spec,too, and I made certain that the WSIA TC also knew about it, (whether the editors needed reminding or not, I don't recall). It has long since been adopted there. I agree that support documents should also be standardized, and a schema template would probably be a good idea, too. Ciao, Rex At 5:31 PM -0500 11/15/02, William Z Pope wrote: >I like what Jeff is proposing. Only addition would be to provide >a name form for non-normative output, an accepted version of an overview >document, a primer, etc. This would never be considered a cmtee spec >or an oasis standard but exists as 'official' supporting documentation. > >=bill > >-----Original Message----- >From: Jeff Hodges [mailto:Jeff.Hodges@sun.com] >Sent: Friday, November 15, 2002 5:24 PM >To: chairs@lists.oasis-open.org >Subject: Re: [chairs] Unique OASIS document identifiers > > >"Eve L. Maler" wrote: >> >> Hello folks, >> >> Karl Best has suggested that I use this list to open up a quick >> discussion on ways that all the OASIS TCs can get some consistency out >> of the ways they identify their specs. >> >> There is a set of OASIS specification template instructions here, which >> Norm Walsh and I put together a little while ago: >> >> http://www.oasis-open.org/spectools/docs/wd-spectools-instructions-01.html >> >> We were guessing a little bit on some of the guidelines therein, and >> we're also not sure who exactly is following them. Though it would be >> great to get input on that document as a whole, the matter of most >> importance right now is the piece of metadata called the "document >> identifier". It is discussed in this section: >> >> >http://www.oasis-open.org/spectools/docs/wd-spectools-instructions-01.html#s >..metadata >> >> A scheme is proposed for assigning document identifiers (which are >> intended to be used as the root of a filename, with the extension >> reflecting the format used in the file). The SAML TC and the UBL Naming >> and Design Rules subcommittee have been trying to apply this scheme as >> best they can, but experience has shown that it needs some tweaking. >> I'm hoping you all can help in this endeavor. > >in the SSTC/SAML comm. we've also been using these guidelines.. > >http://www.oasis-open.org/committees/security/docs/draft-sstc-doc-guidelines >-02.txt > >...just fyi. > > >> >> I'd like to propose the following scheme instead, and suggest that we >> conduct an email discussion on this topic until December 2. At that >> time, I'll summarize and try to propose a revision of the specification >> template instructions. >> >> Eve >> >> * * * >> >> - For contributions and proposals that are outputs of one or >> more individuals/organizations but are not an output of the >> TC in question: >> >> p-{name_of_proposer}-{description}-nn >> >> Where: >> >> name_of_proposer >> Is typically the last name of the main individual making >> the proposal. >> >> description >> Is some descriptive text, possibly with embedded hyphens, >> that identifies the proposal. >> >> nn >> Is a monotonically increasing number starting from 00 >> representing the revision of the document. >> >> - For outputs of a TC: >> >> {type}-{name_of_TC}-{description}-nn >> >> Where: >> >> type >> wp=white paper >> wd=working draft (may not have reached consensus, is in progress) >> cs=committee spec (has had 2/3 positive vote) >> This list is not closed, but new type keywords should be added >> only advisedly, and hopefully only after consultation with the >> chairs list. >> >> name_of_TC >> Is some canonical shorthand for the TC name, or possibly one >> of its subcommittees (though this may make the name too long). > > >I think the above is kinda mixing some things together, such as notions of >maturity level and doc track. > >The way I'd do it is like this.. > > draft -- for proposals and working drafts and committee drafts. I > don't think we really need the fine distinction between them. > > this designation is used in conjunction with the next "term" in > the filename, which is either an individual's name, or an > acronym representing a committee. Often, "proposals" will be > from individuals... > > cs -- committee spec > > oasis -- oasis standard > > >so the above two doc types (indiv proposer, vs a committee working draft) >would >be.. > > draft-{name_of_proposer}-{description}-nn > >...or.. > > draft-{name_of_TC}-{description}-nn > > >The only "official" output of a committee is (to me) a "committee >specification" maturity-level doc. Now, that doc may or may not be >"standards >track", ie it might be what you're thinking of tagging as "info" (aside: I'd >merge the notions of "info" and "white paper"). > >we may or may not want to denote the doc track in the filename, I'm >conflicted >on this. > > > >> - For OASIS Standards: >> >> {name_of_TC}-{description}-Vnn >> >> Where: >> >> Vnn >> Is a representation of the version of the Standard, however the >> TC wants to reflect that. > > > >couple of things here. I'd start the filename of an oasis std with "oasis". >I >wouldn't put the committee name in the filename cuz in an efficient the docs >will last longer than the committee. Plus I wouldn't have a Vnn version >designator in the filename. I'd have an oasis-wide monotonically increasing >doc >number. the info about whether a spec is updated or obsoleted (and doc track >and maturity level) is maintained in the document index (which might just be >output from a spreadsheet for the time being). > >this gives something like.. > > oasis-####-{description} > >where #### is the oasis doc number. > > >examples.. > > oasis-0011-docbook-whatever > oasis-0029-saml-core > oasis-0030-saml-bindings > > > >hope this helps, > >JeffH > >---------------------------------------------------------------- >To subscribe or unsubscribe from this elist use the subscription >manager: <http://lists.oasis-open.org/ob/adm.pl> > > > >---------------------------------------------------------------- >To subscribe or unsubscribe from this elist use the subscription >manager: <http://lists.oasis-open.org/ob/adm.pl> -- Rex Brooks Starbourne Communications Design 1361-A Addison, Berkeley, CA 94702 *510-849-2309 http://www.starbourne.com * rexb@starbourne.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC