RE: Proposed W3C Spec Conventions

Hi Doug,

Thanks for this great doc!

Some comments:
Could we agree on some conventions regarding the naming of the WebIDL declarations?
I mean here a specific patterns/rules for referring to attributes, methods, interfaces and maybe modules.
At present the spec-conventions use the following style:

interface <a href="#style-BaseInterface">BaseInterface</a> : <a href="#style-DerivedInterface">DerivedInterface</a> {
  // ConstCode
  const unsigned long                <a href="#style-UNICORN">UNICORN</a>     = 0x00;
...
  readonly attribute boolean         <a href="#style-invisible">isInvisible</a>;
...
  boolean                            <a href="#style-method1">methodName</a>(in DOMString string);
...
};

So I assume that:
a) the individual declarations use the fragment identifier prefixed with "style-"
b) the attributes' names are coded freely (e.g. isInvisible is represented as "style-invisible")

In BONDI specs I used the following convention (just as example):
http://bondi01.obe.access-company.com/1_1_4845_145/messaging.html#ifMessagingError_cstOUT_OF_COVERAGE_ERROR

http://bondi01.obe.access-company.com/1_1_4845_145/messaging.html#ifMessagingManager_mthsendSMS

http://bondi01.obe.access-company.com/1_1_4845_145/messaging.html#ifMMSSlide_attduration


i.e.
- the module is "messaging" (we agreed that there will be one module per HTML file, this would probably need adjustments),
- the "MessagingError" interface (actually all interfaces) name is prefixed with "if",
- the "OUT_OF_COVERAGE_ERROR" constant (actually all constants) name is prefixed with "cst",
- the "sendSMS" method (actually all methods) name is prefixed with "mth",
- the "duration" attribute (actually all attributes) name is prefixed with "att",
- the "OUT_OF_COVERAGE_ERROR" constant is a member of "MessagingError" interface, both are concatenated with underscore "_" to highlight their relationship
- similarly the relationships of other declarations are highlighted in the identifier' name.

BTW: the "style-"identifiers seem not to be declared in the spec-conventions. This could be fixed for consistency of the whole document.

What would probably also be helpful for the spec editors, is the short index of all the CSS classes used/agreed upon. E.g. for those who have read the document and know it almost by heart, the index would be a fast reference when writing the actual specification.

I hope this helps.

Thanks,
Marcin

Marcin Hanclik
ACCESS Systems Germany GmbH
Tel: +49-208-8290-6452  |  Fax: +49-208-8290-6465
Mobile: +49-163-8290-646
E-Mail: marcin.hanclik@access-company.com

-----Original Message-----
From: spec-prod-request@w3.org [mailto:spec-prod-request@w3.org] On Behalf Of Doug Schepers
Sent: Friday, February 12, 2010 12:52 AM
To: Spec Prod
Subject: Proposed W3C Spec Conventions

Hi, folks-

I have updated the specification conventions based on some more
feedback, and I'm currently using these conventions in DOM3 Events, and
the SVG WG will be using them in all the SVG specs (note, it's still not
official, but it has to start somewhere).

However, I'd also like to get someone with a decent design sensibility
to work on the appearance/presentation.  Can anyone suggest a designer
who'd be willing to do so?

The new home of the Proposed Spec Conventions is here:
  http://www.w3.org/StyleSheets/spec-conventions.html


Regards-
-Doug Schepers
W3C Team Contact, SVG and WebApps WGs


________________________________________

Access Systems Germany GmbH
Essener Strasse 5  |  D-46047 Oberhausen
HRB 13548 Amtsgericht Duisburg
Geschaeftsfuehrer: Michel Piquemal, Tomonori Watanabe, Yusuke Kanda

www.access-company.com

CONFIDENTIALITY NOTICE
This e-mail and any attachments hereto may contain information that is privileged or confidential, and is intended for use only by the
individual or entity to which it is addressed. Any disclosure, copying or distribution of the information by anyone else is strictly prohibited.
If you have received this document in error, please notify us promptly by responding to this e-mail. Thank you.

Received on Wednesday, 17 February 2010 09:32:58 UTC