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

["Eve L. Maler" <eve.maler@sun.com>]

Rob-- Thanks for the awesome comments.  I will try to get as many of the 
nits fixed as possible.  A few responses below:

Philpott, Robert wrote:
> 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.

I had thought that the indenting worked out to be approximately the same 
as before; there was a lot of wrapping before too.  But I'll see if I 
can minimize it.  I've been trying to avoid going through and rewrapping 
by hand, as these snippets are already "one generation away" from the 
original schemas.

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

This is good input in general for the template (which I own anyway, 
apart from any SAML usage of it!).  Since the template is just a draft, 
I will try to play with this and improve.

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

I thought I had fixed this.  There should be only a single space here. 
Will check.

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

Will fix.

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

Will check.

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

Arrgh, this is important to fix.  This is probably because of the effect 
of updating the cross-references when I had Track Changes on earlier. 
(The URI stem was done with a bookmark cross-reference.)

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

Ditto.

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

I'll try to fix this.

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

This is one that I probably won't be able to fix this time around.  This 
drives me nuts, too...  (And by the way, "anal retentive" *does* have a 
hyphen when it's the predicate adjective. :-)

> 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]* 
> <http://www.w3.org/TR/REC-xml#sec-line-ends>" Both styles are regularly 
> used throughout the document.

I had thought that the predominant use for external section references 
was the §.  I hadn't caught the other cases, but will try to do so today.

	Eve

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