Re: Spec with issue markers [was: Re: HTML5-warnings - request to publish as next heartbeat WD]

James Graham wrote:
> Julian Reschke wrote:
>> James Graham wrote:
>>> I haven't added any ISSUEs with a status of RAISED rather than OPEN 
>>> yet. They will be added as soon as I get around to it. If anyone 
>>> would like to suggest which section(s) the RAISED issues should be 
>>> associated with that would be a considerable help.
>>> ...
>>
>> How about adding metadata to the issue page, so that information can 
>> be discovered automatically. Such as:
>>
>> APPLIES-TO-HTML5-SECTION: hyperlink-auditing
> 
> Something like that could work although it will be a bit fragile since 
> it will rely on scraping magic strings. Probably no more so than the 
> rest of the setup though.
> 
> I have experimented with ISSUE-4 adding "HTML5-SPEC-SECTIONS 
> the-doctype" at the end of the description field. The notes field seems 
> more appropriate but appears to be immutable, which I had forgotten. I 
> assume that one issue could be associated with more than one section so 
> the field would have a space-separated list of markers. The change in 
> magic marker string is entirely due to not checking what you originally 
> wrote.
> 
> Assuming there are no objections I will write some code that uses this 
> approach this evening.

This is now done; it is possible to generate the HTML5 spec with static 
inline status markers (pulled from the WHATWG annotation system) and 
ISSUE markers pulled from tracker (currently OPEN and RAISED issues; it 
should be no problem to add PENDING REVIEW if necessary). Some sample 
output is at [1]. My branch of anolis, and hence http://pimpmyspec.net, 
has gained the ability to add these annotations and pimpmyspec.net also 
gained the ability (at [2]) to generate a combined annotations/issues 
file of the type needed as input when adding issue markers to a spec.

ISSUE/section associations are picked up from tracker by looking for 
strings in the description field of the form:

HTML5-SPEC-SECTIONS [section1 section2 section3]

i.e. a magic identifier followed by a square-bracket-enclosed, 
space-separated list of ids.

I suggest that we add such status/issue markers to the W3C versions of 
the spec henceforth. This would seem to address many of the points made 
in favour of publishing the "warnings" draft in the recent poll without 
tripping over the substantial objections.

[1] http://hoppipolla.co.uk/410/spec-full.html
[2] http://pimpmyspec.net/aquarium.py/annotations

Received on Monday, 24 August 2009 08:33:17 UTC