sca-bindings message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Interesting PR comment
- From: Bryan Aupperle <aupperle@us.ibm.com>
- To: sca-assembly@lists.oasis-open.org, sca-bindings@lists.oasis-open.org, sca-j@lists.oasis-open.org
- Date: Wed, 15 Jul 2009 15:08:02 -0400
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: aupperle@us.ibm.com
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]