RE: [sca-c-cpp] ISSUE 87: Imprecise language

[Bryan Aupperle <aupperle@us.ibm.com>]

I've looked at the other SCA spec drafts.
 The term "snippet" is used fairly consistently (but not
exclusively).  There has not been any discussion in any of the other
TC I that I am aware of about referencing snippets.

In any event, here is a draft addressing
the concerns raised in issue 87.  I have added captions to any figure,
table or snippet that is referenced in running text and made the reference
explicit via a cross reference to the caption.  There are snippets
that are not referenced by the running text (notably the examples in the
appendices) and tables (notably the ones providing member function details).
 I did not add captions for these. 


Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect

Research Triangle Park,  NC 
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com

"David Haney" <haney@roguewave.com>

07/08/2009 06:49 PM

To	Bryan Aupperle/Raleigh/IBM@IBMUS, <sca-c-cpp@lists.oasis-open.org>
cc
Subject	RE: [sca-c-cpp] ISSUE 87:

I like the idea of being able
to explicitly reference a particular code sample, and the updates you’ve
made look good to me.  It seems like this is something that would
be an issue for the other TC’s specifications as well, has there been
any discussion to standardize conventions for referencing code samples?
 In particular, I’m curious if these should be called snippets, samples,
or something else.
 
Thanks.

David.

---

From: Bryan Aupperle [mailto:aupperle@us.ibm.com]
Sent: Tuesday, June 30, 2009 1:29 PM
To: sca-c-cpp@lists.oasis-open.org
Subject: [sca-c-cpp] ISSUE 87: 
 

One of the comments in Issue 87 is that our rather liberal use of phrases
like "The following snippet..." is not very precise and that
numbering and explicitly referencing snippets would be better.  I
have done this for section 2 of the attached draft (along with addressing
the other comments in Issue 87).  I would be interested in your reaction
to the changes before embark on this work for the remainder of the specification.



Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect

Research Triangle Park,  NC 
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com

sca-cppcni-1.1-spec-cd03-rev2+Issue 87.doc