[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-bindings] Suggested documentation standards for SCA specificationdocuments
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/ > > > > > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]