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

 


Help: OASIS Mailing Lists Help | MarkMail Help

security-services message

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


Subject: Re: Bibliography recommendations


My reactions below...

At 08:55 AM 9/25/01 -0700, Jeff Hodges wrote:
>Here's the bob recommendations Eve wrote up way back when. IIRC the suggestion
>was to include them in a revision of
>
>http://www.oasis-open.org/committees/security/docs/draft-sstc-doc-guidelines-02.txt
>
>Thanks to Eve for writing-up the below.
>
>JeffH
>
> > -------- Original Message --------
> >
> > Bibliography recommendations
> >
> > References section:
> >
> > - There will be only one References section shared by all outputs of the
> > SSTC, and it will be in the SAML specification itself.  The editor of
> > this section will be the arbiter of entry keys and will ensure that all
> > keys in text are consistent with the References section.
> >
> > - The editor of the References section will be the arbiter of the
> > spelling of entry keys.
>
>I don't think I necessarily agree with the above, especially at this time. It
>strikes me a bit too heavyweight, plus I don't think we've really come to
>agreement on the final form the SAMLv1 spec(s) will take (and I feel we should
>wait to tackle that until after we've reached the "stable spec" milestone
>(meaning "stable schema and semantics"), and we're largely working on "spec
>polishing"). So for now I think each spec should continue to have it's own 
>refs
>section and we can decide later if we want to institute something like the
>above.

I was thinking that it might make the jobs of all the editors easier, not 
harder, if one single person were to "own" the bibliography problem.  It's 
true that we don't know yet where a single bibliography should reside, but 
we could just keep it separate for now and refer to it with a URL.

I'd rather that we clean up purely editorial clashes relating to 
bibliographies soon rather than later, particularly since we're going to 
need to be clear about which references are normative.

But if no one takes on the job of "bibliography editor" (I had toyed with 
it, but now fear that I'd just hold things up), then it's moot anyway. :-)

> > - IETF-related entry keys will be in this form: [RFCnnnn],
> > [I-Dnnnn], etc.
>
>We should try hard to not ref any internet-drafts, either normatively or
>non-normatively. They are explicitly transient docs -- they eventually 
>disappear
>from the IETF and mirrored repositories. If we feel we must -- in a
>non-nomative fashion say -- then we should cache our own copy (but we should
>really try to avoid this).

Ah, good point.  W3C draft specs sometimes refer to I-Ds non-normatively, 
so I was trying to cover cases that I was familiar with.

> > W3C-related entry keys will use an uppercase version of the spec
> > "shorthand" name used in W3C URLs.
>
>A quibble is that these will get kinda long. Perhaps we should invent our own
>shorthand for these, e.g. as we're doing in core-15

This was probably overkill; I can see ditching this rule.  (But the W3C 
shorthand is sometimes shorter than you'd want it to be -- e.g., for the 
XML Namespaces spec, it's xml-names, which doesn't mean much by itself.)

> > - Normative entries will be in their own subsection and identified as
> > such.
> >
> > - Entries for resources available online will be in this form (with no
> > more than one author listed literally and with titles either italicized
> > or quoted):
> >
> >    A. Writer[, et al]. Title. Publishing source, date. (See
> >    http:///example.com/foo.htm.)
> >
> > - Entries for paper resources will use classical bibliography form, as
> > roughly exemplified by the current entry for RFC-2104.
> >
> > Entry keys in text:
> >
> > - Keys will be of the form [XXX].
> >
> > - They will be used parenthetically (that is, not as essential sentence
> > text; you should be able to remove them without ruining the current
> > reading context).
> >
> > - Only one reference to any entry will be provided in any one chapter
> > (major section), unless more are needed for editorial reasons.

         Eve
--
Eve Maler                                    +1 781 442 3190
Sun Microsystems XML Technology Center   eve.maler @ sun.com



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


Powered by eList eXpress LLC