W3C home > Mailing lists > Public > public-device-apis@w3.org > August 2009

Re: Editing specifications with ReSpec.js

From: Anselm R Garbe <anselm@aplixcorp.com>
Date: Thu, 6 Aug 2009 16:27:44 +0100
Message-ID: <89d1e7b80908060827v5eaa8cfav2b06353f80fe9ca0@mail.gmail.com>
To: Robin Berjon <robin@robineko.com>
Cc: public-device-apis@w3.org, Marcos Caceres <marcosc@opera.com>
2009/8/6 Robin Berjon <robin@robineko.com>:
> On Aug 6, 2009, at 12:41 , Anselm R Garbe wrote:
>> Why editing HTML at all?
>
> I can think of many good reasons:
>
>  - because it's the output format, and therefore there's a 1-1 mapping
> between what we can do in the source and what we can do in the target,
> without the need for extensions
>  - because it runs in the browser, avoiding having to run some tool
>  - because some people use WYSIWYG tools
>  - because it's our dogfood
>  - because it's nice to edit, simple, and readable
>  - because anyone who plans on editing a W3C specification has to know it
> already, whereas other options need be learnt
>  - because it has well-defined interactions with CSS so that it is trivial
> to produce good-looking documents
>  - because it can be scripted
>  - because it is minimally whitespace sensitive
>  - because its syntax is clear, a link is just <a href='foo'>bar</a>, I
> don't have to wonder whether this time of year it might be [foo | bar], [bar
> | foo] [foo bar] [foo](bar) or maybe some mix, match, and reverse of those
>
>> I'd propose to write specs in plain
>> markdown[1] and add some additional pre- or post-filters to it, in
>> order to generate PubRules compliant HTML. In contrast to HTML,
>> markdown aims at being readable in source and gives an idea about
>> WYSIWYM -- it can be extended with rfc2119 style keywords -- and even
>> your ReSpec.js could be integrated during the generator run.
>
> Yes, the common feature of all wiki markup is that they can eventually be
> extended to the point where they come close to HTML's power and flexibility
> :)
>
> Seriously though, I've edited specifications before based on variants on
> wiki-like languages, and at the end of the day it's always hell. Given a
> choice I'd rather use Word, and that's saying a lot!

Ok understood. [Though bare in mind that markdown is not specifically
a wiki language, it's simply ascii with some semantics for HTML
conversion, and as a counter example IETF specs are written in plain
text for a good reason: you don't need to update them when your
presentation format (HTML) changes over time, they can be fixed for
decades. The same applies in theory to markdown documents.]

Kind regards,
Anselm
Received on Thursday, 6 August 2009 15:28:26 UTC

This archive was generated by hypermail 2.3.1 : Monday, 23 October 2017 14:53:38 UTC