OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

sca-assembly message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [sca-assembly] Re: [sca-bindings] Interesting PR comment


Wow. So what would it take to hire you to do this for the Policy FW spec? I'm sure Ashok will go halves with me on whatever your price is.

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:booz@us.ibm.com

Inactive hide details for Bryan Aupperle---08/26/2009 02:24:08 PM---Here is a version of CD03 Rev2 with captions added for all Bryan Aupperle---08/26/2009 02:24:08 PM---Here is a version of CD03 Rev2 with captions added for all snippets, figures, and tables that are n


From:

Bryan Aupperle/Raleigh/IBM@IBMUS

To:

sca-assembly@lists.oasis-open.org

Date:

08/26/2009 02:24 PM

Subject:

Re: [sca-assembly] Re: [sca-bindings] Interesting PR comment






Here is a version of CD03 Rev2 with captions added for all snippets, figures, and tables that are not in an appendix (getting the numbering right for captions in appendices is tricky and I do not want to undertake that until I get some feedback on this draft) and explicit references to them instead of phrases like "The following snippet..."

I have removed blank lines that otherwise get removed during the conversion to PDF in the publishing process.

In addition I have updated paragraph styles to match the current template (http://docs.oasis-open.org/templates/OASISSpecificationTemplateGuidelines.html) Sections 7.4, 7.5 and 7.8

I did not touch section 1.2, but I would note there are several formatting problems there:
- Inconsistent reference tag format
- Incorrect format for OASIS document references
- Blank lines between items.
- I believe some of the references should be moved to section 1.3

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

From: David Booz/Poughkeepsie/IBM@IBMUS
To: sca-assembly@lists.oasis-open.org, sca-bindings@lists.oasis-open.org, sca-j@lists.oasis-open.org, sca-policy@lists.oasis-open.org
Date: 07/15/2009 03:16 PM
Subject: [sca-assembly] 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:booz@us.ibm.com

Inactive hide details for Bryan Aupperle---07/15/2009 03:08:33 PM---One of the PR comments (editorial) against the C++ spec (maBryan 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:

sca-assembly@lists.oasis-open.org, sca-bindings@lists.oasis-open.org, sca-j@lists.oasis-open.org

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: aupperle@us.ibm.com





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]