Bibliography recommendations

[Jeff Hodges <jhodges@oblix.com>]

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. 

> 
> - 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). 

> 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

> - 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.