Re: [sca-bindings] Interesting PR comment

+1

Dave Booz

STSM, BPM and SCA Architecture

Co-Chair OASIS SCA-Policy TC and SCA-J TC

"Distributed objects first, then world hunger"

Poughkeepsie, NY (845)-435-6093  or  8-295-6093

e-mail:

Bryan Aupperle---07/15/2009 03:08:33 PM---One of the PR comments (editorial) against the C++ spec (made by a TAB  member) was:

From:

Bryan Aupperle/Raleigh/IBM@IBMUS

To:

, , 

Date:

07/15/2009 03:08 PM

Subject:

[sca-bindings] Interesting PR comment

One of the PR comments (editorial) against the C++ spec (made by a TAB member) was: 

Moreover, the use of "following," or "above," or "below," creates 

ambiguity about which "snippet" or "code extract" is being described. 

The better practice would be to number all of them and then make 

specific reference to those numbered (suggest) "code examples".

Note that the use of indirect and ambiguous references limits the 

utility of the final version as others cannot make clear references to 

the "code examples" either in texts, tutorials, manuals or other materials.

One could argue that the use of line numbers makes precise citation 

possible, if awkward, but the ambiguity of internal referencing remains. 

This same comment could be made for a number of other SCA specs. So I thought I would pass it along. 

The C/C++ TC is taking the approach of captioning snippets, tables, and figures and using explicit cross-references in the running text. 

Bryan Aupperle, Ph.D.

STSM, WebSphere Enterprise Platform Software Solution Architect

Master Inventor

Research Triangle Park,  NC 

+1 919-254-7508 (T/L 444-7508)

Internet Address: