RE: Editing specifications with ReSpec.js

Hi Robin,

>>> Specs being self-contained (e.g. the editing format is the rendering
>>> format, or with internal JS) may result in consistency-verification
>>> issues.
>>
>>I'm sorry but I don't understand what you mean. Do you have a specific
>>example?
I meant here the fact that one spec is collecting knowledge from potentially a few domains, e.g. Web IDL, algorithms, markup etc. all intermingled together in one document.
Those domains are linked together usually by prose that is not verifiable and it may result in consistency issues.
>From another pov having the "domains" clearly marked, we could easier develop tools for them.
I am thinking about putting each part of the spec into separate <div> and mark the classes as it is done e.g. in HTML5 for Web IDL.

>>Honestly, I don't want a specification building system
OK.
Would marking the parts with <div>'s work for you?
Then each domain expert could concentrate on her/his domain e.g. by extracting the relevant part with some XSLT.

>>Check. We simply use nest <ol> with <var>.
>>Check. That's supported with <dl> and some microparsing. It is easily
>>extensible to match changes in WebIDL.
Could this be formally documented somewhere? .txt file would suffice, I think.

>>But why bother editing multiple source documents when one suffices?
As above, one document would be ok.
Initially I thought that the initial "editors'" document would be processed by a set of XSLT or other tools to produce readable version, but having your comments I assume that we just may need to mark the different parts of the specs so that relevant checkers could be applied to them. Once some issues are identified, they would be fed back by hand into the original spec. This is how it works with widls and my checkers.

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: Robin Berjon [mailto:robin@robineko.com]
Sent: Thursday, August 06, 2009 5:26 PM
To: Marcin Hanclik
Cc: Anselm R Garbe; JOSE MANUEL CANTERA FONSECA; public-device-apis@w3.org; Marcos Caceres
Subject: Re: Editing specifications with ReSpec.js

On Aug 6, 2009, at 13:41 , Marcin Hanclik wrote:
> Probably we will want to verify Web IDL fragments, we may want to
> check some semantics or dependencies between various parts of
> various specs.

That should be part of PubRules checking (so that a spec cannot be
released without the checks), and available as a separate tool. The
toolset of the editor should be fast (hence the idea of not having any
processor outside of the browser) and therefore do as little as
possible outside making sure the specification can be edited swiftly.

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

I'm sorry but I don't understand what you mean. Do you have a specific
example?

> On the other hand probably we do not want to "specification-building-
> system" to be over-engineered.

Honestly, I don't want a specification building system - I just want
to edit a document, and for that to be simple, straightforward, and
most important of all vernacular. I've built specification building
systems before and they are always over-engineered because writing a
specification should be nothing more than just writing a document,
with repeated things automatic, common things short, and hard things
possible.

> 1. algorithms - they could be presented in some agreed pseudo-code
> (e.g. as in P&C or HTML5, or something else)

Check. We simply use nest <ol> with <var>.

> 2. APIs in Web IDL

Check. That's supported with <dl> and some microparsing. It is easily
extensible to match changes in WebIDL.

> 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

But why bother editing multiple source documents when one suffices?

--
Robin Berjon
   robineko - setting new standards
   http://robineko.com/




________________________________________

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, 13 August 2009 11:33:23 UTC