Re: Editing specifications with ReSpec.js

I think it is important to avoid needless manual editing time on  
boilerplate, reference sorting, maintaining table of contents,  
formatting   styles etc. For this reason I dislike plain HTML editing  
and have preferred XMLspec that automates some of this, but dealing  
with the build environment has been somewhat difficult (probably an  
understatement)

ReSpec looks like it solves this problem in an elegant manner -  I  
need to try it out, but it looks good. It looks like it handles  
references and document status and boilerplate, etc.

Seems like a good approach, and allows use of HTML as needed, I agree  
with Robin's remarks on those benefits.

I've found it useful to be able to generate redlines for review, it  
looks like we can use htmldiff for this with output of ReSpec, if we  
can get htmldiff to work correctly and not truncate.

regards, Frederick

Frederick Hirsch
Nokia



On Aug 6, 2009, at 7:41 AM, ext Marcin Hanclik wrote:

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

Received on Monday, 10 August 2009 16:26:59 UTC