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

James Graham wrote:
> Quoting James Graham <jgraham@opera.com>:
> 
>> Jonas Sicking wrote:
>>>> A copy of the spec with the WHATWG annotations in is at [1] (that  
>>>> URL is not
>>>> expected to be long-lasting). Note how this document makes the relative
>>>> maturity of the <iframe> ("working draft") and <video> ("last call for
>>>> comments") sections clear. I understand that some people will think 
>>>> that
>>>> reusing W3C language is inappropriate; that can be changed. Please 
>>>> bear in
>>>> mind that this document may contain errors since my  spec-processing 
>>>> pipeline
>>>> is immature; indeed I spotted some encoding issues already.
>>>
>>> Wow, this is great! I'd say I'd even prefer even more attention to the
>>> status annotations, i.e. give them a border or something else to make
>>> them stand out.
>>
>> OK I will experiment with making the markers more obvious.
>>
>> Another idea to throw into the ring is that it would be possible to add
>> information to the annotations file about whether a section has an
>> associated tracker issue. That would allow a link to the issue to be
>> automatically inserted into the status marker along with, possibly,
>> some explanatory text about the fact that the issue must be resolved
>> before the next spec phase transition. Obviously some UI to maintain
>> the list of issues in the annotations file would be needed but that is
>> a solvable problem.
> 
> I now have a version of the spec with links to open ISSUEs [1]. See [2] 
> for an example of a section where it applies. The issues are added using 
> an extra metadata file that contains a map between each issue and one or 
> more sections in the spec. The file I have created so far is at [3]; it 
> contains mappings for open issues which map well on to specific sections 
> of the spec (it is hard to see how to associate ISSUE-59 with the spec 
> since it is about the language reference; ISSUE-41 doesn't map on to a 
> particular section of the spec except maybe microdata). I also just 
> noticed that I missed ISSUE-55; that will be fixed. However this list is 
> not supposed to be definitive it is just a quickly-knocked-together 
> sample to demonstrate the approach. In particular raised issues are not 
> covered at all. Also the use of class="XXX" and the resulting appearance 
> is a result of doing the simplest thing that could possibly work rather 
> than some commitment to having that exact appearance for the markers.
> 
> Note that I have not applied any date cut-off to the issues given 
> markers; this is deliberate since the intent is to provide information 
> about all the things that must be fixed before the next spec status 
> transition not to single out "controversial" areas of the spec.
> 
> At this point it would be useful to get feedback. Is this something that 
> people believe is worth pursuing? How should the issue to section map be 
> maintained? Is there some style that would be better for the 
> status/issue markers?

1) I think this looks great!

2) Any chance you can include the short name (e.g. "table-summary") 
either inline or as a title?

3) I would suggest section 3.2.1 for issue 41.  (key being the second 
sentence of the second paragraph).

> (For the curious; this works by extending the annotation file format 
> used by WHATWG by adding an extra status attribute on the root element 
> indicating the status of the draft as a whole, and adding <issue name="" 
> url=""/> elements to each <entry> with one more associated issues. I 
> have a little bit of code that takes the file in [3] and mixes the 
> information into a copy of the WHATWG annotation file. The resulting 
> annotation file is then used with an anolis module to produce the actual 
> specification. My anolis repository is at [4]; once I have cleaned up 
> the code a bit I will talk to gsnedders about pushing this back to the 
> main repository. The code to process the issue_markers file is at [5]. I 
> also plan to add UI for the annotations feature to pimpmyspec.net.).
> 
> [1] http://hoppipolla.co.uk/410/spec-full.html
> [2] http://hoppipolla.co.uk/410/spec-full.html#video
> [3] http://hoppipolla.co.uk/410/issue_markers
> [4] http://hg.hoppipolla.co.uk/anolis/
> [5] http://hg.hoppipolla.co.uk/w3c_issues

- Sam Ruby

Received on Wednesday, 19 August 2009 00:47:42 UTC