RE: Editing specifications with ReSpec.js

Hi Robin,

Thanks for your comments.
I have to study ReSpec.js deeper to be able to help you further.

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: Robin Berjon [mailto:robin@robineko.com]
Sent: Tuesday, August 25, 2009 6:23 PM
To: Marcin Hanclik
Cc: DAP
Subject: Re: Editing specifications with ReSpec.js

Hi Marcin,

On Aug 13, 2009, at 13:32 , Marcin Hanclik wrote:
>>> 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.

Ah, gotcha. Yes, that's true, though note that one way to avoid
consistency issues is to cleanly separate concerns in the prose (e.g.
having a section explaining processing rules and then simply pointing
to it from the definition of a method, so that if the method changes
nothing is broken).

>> 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.

That's already the case with ReSpec (for instance it puts all WebIDL
in a <pre class=webidl>). We can certainly add more as we spot them.

>>> Honestly, I don't want a specification building system
> OK.
> Would marking the parts with <div>'s work for you?

Yes, definitely. By system I thought you meant something more complex.
Providing enough semantics that other tools (unrelated to editing
specifications) can provide valuable services (such as validation) is
certainly a good approach.

>>> 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.

There are pieces in the ReSpec documentation:

    http://dev.w3.org/2009/dap/ReSpec.js/documentation.html

But I can certainly add more.

> 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.

Yup, agreed.

--
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 Wednesday, 26 August 2009 19:46:08 UTC