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/

Received on Thursday, 6 August 2009 15:27:14 UTC