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/

Received on Tuesday, 25 August 2009 16:23:56 UTC