RE: [chairs] Unique OASIS document identifiers

[Rex Brooks <rexb@starbourne.com>]

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