Re: [sca-bindings] Suggested documentation standards for SCA specificationdocuments

[Anish Karmarkar <Anish.Karmarkar@oracle.com>]

Simon Holdsworth wrote:
> 
> Folks, following some review comments from the bindings specs, I'd like 
> to propose some high-level standard formatting that all our SCA specs 
> follow - we're not currently very consistent across or within documents. 
>  There would be more details if we want complete consistency, but the 
> following is a start to test people's reactions, and consistency on 
> these would go a long way to a common look and feel.  Copying to 
> bindings and assembly for initial reactions, and those are the specs 
> I've looked at in this regard.
> 
> If this is something we should not be worrying about until later in the 
> publication cycle, feel free to ignore for now...
> 
> Normal text ("Normal")
> 
> Arial 10pt, align left, before 4pt after 4pt, line spacing single, 
> indentation 0
> 

There has been a lot of cut-and-paste from various places that has 
resulted in "contamination". I would like to suggest that for this and 
some of the other problem areas we go back to the OASIS template and use 
  the recommended style/font/indentation/etc and apply it consistently.

> Currently used by JMS and JCA and Assembly up to section 3 and section 
> 12 onwards;  WS and Assembly section 3 to section 11 use:  Verdana, 
> align left, before 0pt after 6pt, line spacing single, indentation 0.63. 
>  Exceptions within Assembly (Section 10.4 uses Arial, not Verdana, 
> Section 11 varies per paragraph)
> Assembly also inconsistent in indent (section 7.6, WSDL Interface Type, 
> section 10.4  has no indent, most other text is 0.63 indent)
> 
> XML, code examples ("Code"):
> 
> Courier New 9pt, align left, before 0pt after 0pt, line spacing single, 
> indentation 0.76 right and left, grey background; attributes names in 
> purple (127,0,127), constants in blue (42,0,255), /<, > and /> in 
> green,/ other text in black.   Indentation using 3 spaces per level, no 
> tabs
> 
> Currently used by JMS and JCA;  WS uses:  indentation 0.63 left, 0.76 
> right; Assembly uses Courier New 10pt, white background
> 
> External references use full reference name plus tag:
> 
> name of external reference [tag]   for example SCA Assembly 
> Specification [SCA-Assembly].  The name and tag should both be 
> hyperlinked to the appropriate line in the reference section
> 
> Reference to elements and attributes in a schema or instance use Courier 
> New 10pt, and include "attribute" or "element":
> 
> the service* *element;   the @uri attribute;   the 
> inboundConnection/resourceAdapter element
> 

+1
I would also suggest that for literals we also use the same font, but 
use double quotes around the values.

> Where references are to the runtime implementation these should not be 
> highlighted, e.g.  "For an SCA service with JMS binding, the SCA 
> runtime...."
> 
> This formatting not currently used anywhere, but my feeling is this 
> makes it consistent with the presentation of the attributes/elements in 
> the Code sections.
> 
> Regards, Simon
> 
> Simon Holdsworth
> STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair
> MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
> Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
> Internet - Simon_Holdsworth@uk.ibm.com
> 
> 
> 
> ------------------------------------------------------------------------
> 
> /
> /
> 
> /Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with number 
> 741598.
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU/
> 
> 
> 
> 
> 
>