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: Suggested documentation standards for SCA specification documents

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

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

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

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