RE: Editing specifications with ReSpec.js

Hi,

IMHO the security policy specification will define some syntax for the policy interchange format (e.g. in XML).
So we have here another building blocks:
7. XML elements with related content model etc
8. XML attributes

Thanks.

Kind regards,
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: public-device-apis-request@w3.org [mailto:public-device-apis-request@w3.org] On Behalf Of Marcin Hanclik
Sent: Thursday, August 06, 2009 1:41 PM
To: Anselm R Garbe; JOSE MANUEL CANTERA FONSECA
Cc: Robin Berjon; public-device-apis@w3.org; Marcos Caceres
Subject: RE: Editing specifications with ReSpec.js

Hi,

I think we could agree on some tool/format chain.
Probably we will want to verify Web IDL fragments, we may want to check some semantics or dependencies between various parts of various specs.
In BONDI we use widls: Web IDL + doxygen.
Widls have some problems and are not ideal, but their idea have already helped to find and fix many bugs.

Specs being self-contained (e.g. the editing format is the rendering format, or with internal JS) may result in consistency-verification issues.

So maybe we could elaborate first on what the target specs should contain and we could then find the building blocks.
On the other hand probably we do not want to "specification-building-system" to be over-engineered.

Each current related spec seems to contain at least the following building blocks:
1. algorithms - they could be presented in some agreed pseudo-code (e.g. as in P&C or HTML5, or something else)
2. APIs in Web IDL - here we could adjust the specification text to Web IDL syntax (if it is stable enough). Each attribute, constant, method, interface, module may need its own description with code samples etc. The BONDI syntax as pseudo-specified here: http://bondi.omtp.org/1.01/apis/BONDI_Interface_Patterns_v1.0.html#widls could be improved, moved to another syntax or so, but the principle could remain.
3. definitions - dfn in markup would be ok as it is used now
4. acknowledgements - just text
5. references - any
6. descriptions with links to algorithm and Web IDL fragments in the same final document

I think that spec-internal links would direct us to HTML format and clarity of the specification production could require some stepwise processing of that HTML. We could e.g. have chain of XSLT(s) that - when applied sequentially to the "editors' HTML" - would generate another HTML with some aspects clarified or fixed. At the end of that chain we would have the spec as it should be rendered to the potential readers.

Thanks.

Kind regards,
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: public-device-apis-request@w3.org [mailto:public-device-apis-request@w3.org] On Behalf Of Anselm R Garbe
Sent: Thursday, August 06, 2009 1:08 PM
To: JOSE MANUEL CANTERA FONSECA
Cc: Robin Berjon; public-device-apis@w3.org; Marcos Caceres
Subject: Re: Editing specifications with ReSpec.js

2009/8/6 JOSE MANUEL CANTERA FONSECA <jmcf@tid.es>:
> I would prefer not to use wiki evil formats. Markup is a better solution

Well, markdown is still markup, even if its name is telling the opposite ;)

Kind regards,
Anselm


________________________________________

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.

________________________________________

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 Thursday, 6 August 2009 11:46:40 UTC