RE: [chairs] Unique OASIS document identifiers

[William Z Pope <zpope@pobox.com>]

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>