RE: [security-services] Drafts of core Committee Spec and schemas

Hi Eve - nice work.

With respect to the current revisions:

1. I do like the new formatting style for the document. However, I really don't like the indentation used for the code/schema snippets. The narrower margins result in a lot more line wrapping making the code snippets considerably less readable. It's just the indenting and margins that are a problem. If the margins can't be changed, I recommend indenting the wrapped text within the snippets to be to the right of the previous line indentation wherever feasible.

2. Personally, I would prefer that level 5 headers continue to be bolded as well as italicized. It makes them easier to pick out when scanning pages for a section. As I said, it's a personal preference.

3. Call me anal, but I also don't like the extra spacing that got introduced between the header level 4 and 5 section numbers and the section head label.

4. When reformatting line 595, some extra spaces got introduced: "defined in [RFC 2822] §3.4.1 ." - there's an extra space before the bolded reference and before the final period.

5. Line 1347: "number" should be "numbers" since we're speaking about the individual major and minor version numbers.

6. In section 7, spaces somehow appear to have been introduced into some of the identifiers. For example, in 7.1.6 X.509 Public Key, the identifier now has a space between "SAML:1.0:" and "am:X509-PKI". These weren't there in the previous version of core-00. I also now see spaces in 7.1.7, .8, and .9.

7. There are now also spaces between "SAML:1.0:" and "action:..." in sections 7.2.1 through 7.2.4.

Each time we read these things we'll probably find more little nits... Here are some nits for the next release...

1. Line 182: "[XML 1.0 Sec. 2.3]" - Shouldn't "XML 1.0" just be a bolded "XML" as a reference to the doc listed in the back?

2. The doc isn't always consistent in using references. For example:

a. Line 595: "defined in [RFC 2822] §3.4.1"

b. Lines 601-602: "rules given in RFC2253 [RFC 2253]"

Either a) should say "defined in RFC 2822 [RFC 2822] §3.4.1" or b) should remove the first RFC2253. Both styles are regularly used throughout the document.

3. Specifying sections within references is not done consistently. For example, Line 595 now uses "§3.4.1". Lines 205-206 say "in Section 2.11 of the XML Recommendation [XML]" Both styles are regularly used throughout the document.

Rob Philpott

RSA Security Inc.

The Most Trusted Name in e-Security

Tel: 781-515-7115

Mobile: 617-510-0893

Fax: 781-515-7020

mailto:rphilpott@rsasecurity.com

> -----Original Message-----

> From: Eve L. Maler [mailto:eve.maler@sun.com]

> Sent: Thursday, May 30, 2002 5:48 PM

> To: security-services@lists.oasis-open.org

> Subject: [security-services] Drafts of core Committee Spec and schemas

> Prateek, Krishna, and others--

> Attached are unofficial *drafts* of the revised cs-sstc-core spec and

> the two schema modules. PLEASE DO NOT take these as final; normally we

> wouldn't distribute these to the whole TC list for review, but we need

> to get as many eyeballs checking this as possible before tomorrow's

> final versions. The files have a letter after the rev number to

> indicate that they're unofficial. I will publish final drafts tomorrow,

> May 31, by COB (but hopefully way before).

> Things to note about this core draft: While I did do a Track Changes

> version for my own (and Prateek's and Krishna's) sanity checking, I

> turned it off before applying the new OASIS template. I didn't want to

> take a chance on change bars screwing up the formatting changes. The

> formatting is not all that different from before, but you will notice a

> few horizontal rules and some color, and the code examples are done in a

> slightly different way.

> All errata and known formatting issues have been corrected in these

> drafts. If you see anything amiss, please let me know ASAP. I will

> send out drafts of the other four specs, and hopefully also a revised

> errata document, tonight.

> Thanks,

> Eve

> --

> Eve Maler +1 781 442 3190

> Sun Microsystems XML Technology Center eve.maler @ sun.com

security-services message