Re: [sca-bindings] Conformace point highlight color

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

Doing a bit of digging, I found this
in the OASIS Specification Template Usage Guide (http://docs.oasis-open.org/templates/OASISSpecificationTemplateGuidelines.html)

This template defines several character styles for general
text use:

.attribute

.codetemp

.datatype

.element

.emphasis

.keyword

.refterm

.variable

Attribute, element, codetemp, datatype and keyword all resolve to Courier.   Variable (and emphasis for that matter) are italic.

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

Anish Karmarkar <Anish.Karmarkar@oracle.com>

07/08/2009 07:32 PM

To	Bryan Aupperle/Raleigh/IBM@IBMUS
cc	sca-assembly@lists.oasis-open.org, sca-bindings@lists.oasis-open.org, sca-c-cpp@lists.oasis-open.org
Subject	Re: [sca-bindings] Conformace point highlight color

Bryan Aupperle wrote:
>
> I have added two shades of grey (10% and 20%) to the samples.  I agree
> with your point about grey working well with color-challenged technology
> and people.  My only concern about that approach is that this does not
> provide any real visual distinction from samples.

If we make the two grey different (10% v. 20%) and put a box around the
examples that may do the trick.

>
> In the C++ and C specs we use italics for text literals and courier for
> language constructs (keywords/identifiers), so I would not be thrilled
> with the font changes you suggested.
>

Don't have a strong opinion on this, but I have a mild preference to use
courier for both language constructs and literals with quotes around
literals.

> 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
>
>
> *Anish Karmarkar <Anish.Karmarkar@oracle.com>*
>
> 06/26/2009 06:47 PM
>
>                  
> To
>                  Bryan Aupperle/Raleigh/IBM@IBMUS
> cc
>                  sca-assembly@lists.oasis-open.org, sca-bindings@lists.oasis-open.org,
> sca-c-cpp@lists.oasis-open.org
> Subject
>                  Re: [sca-bindings] Conformace point highlight color
>
>
>                  
>
>
>
>
>
> Bryan,
>
> Thanks for starting the thread and providing alternatives.
> I actually prefer a shade of grey. Is there a good reason not to use
> grey? Works well with color-challenged technology and people. We could
> even use italics in addition to the grey color. I know in some SCA specs
> we have used italics (although not consistently) for attribute/element
> names/values, but I would suggest changing that and using courier new
> font for those.
>
> I would also like to start a discussion on the suggestion that Eric had
> made: to use a superscript instead of running text for the conformance
> item number. It does enhance the readability.
>
> -Anish
> --
>
> Bryan Aupperle wrote:
>  >
>  > There has been some discussion over the past few weeks about the color
>  > highlighting of the conformance points in several of the TCs.  To
>  > summarize the key points of the discussion:
>  >
>  > - Without the highlighting, it is not clear in the PDF version of
>  > document what the extent of the conformance point text is (it shows up
>  > with grey shading in Word but this is not carried over to the generated
>  > PDF).  One of the TAB members remarked favorably on the highlighting of
>  > the Assembly spec in his review of the C++ spec.
>  > - The current highlight color can make the text  hard to read in some
>  > environments, especially when the highlighted content includes added
>  > text that is displayed in a different color.  This will not be as big a
>  > concern when we are done working on the documents, but is a problem for
>  > us in the mean time.
>  > - The current color is rather intense.
>  >
>  > I have prepared a test version of the C spec, which currently does not
>  > have the highlighting, showing 6 different highlight color options (the
>  > original yellow, plus 5 others)  The best place to look at the samples
>  > is Appendix F (pages 109-112).  Here you can see the colors with and
>  > without added text in them.  I have also converted the sample to PDF to
>  > show what that would look like (links do not work).
>  >
>  >  
>  >
>  > I offer this up to start an e-mail discussion about what highlighting
>  > color people prefer.  My preference is the light yellow used for C20006
>  > and C20014.  It shows well but does not seem to clash as badly with red
>  > marking for added text.
>  >
>  > 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
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  > ---------------------------------------------------------------------
>  > To unsubscribe from this mail list, you must leave the OASIS TC that
>  > generates this mail.  Follow this link to all your TCs in OASIS at:
>  > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>