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

[Krishna Sankar <ksankar@cisco.com>]

Eve,

	I think it would be easier if we could change the format of all
the Section 7.x "URI: ..." to the "code" format (Courier New 9 with the
gray background). 7.1.4, 7.1.6, 7.1.7, 7.18. & 7.1.9 have the extra
spaces before the am, after the 1.0:.

	Format of the 7.1.3 and 7.1.4 are different from other section
numbers.

cheers

|  -----Original Message-----
|  From: Eve L. Maler [mailto:eve.maler@sun.com] 
|  Sent: Friday, May 31, 2002 7:24 AM
|  To: Philpott, Robert
|  Cc: security-services@lists.oasis-open.org
|  Subject: Re: [security-services] Drafts of core Committee 
|  Spec and schemas
|  
|  
|  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
|  
|  
|  ----------------------------------------------------------------
|  To subscribe or unsubscribe from this elist use the subscription
|  manager: <http://lists.oasis-open.org/ob/adm.pl>
|