Marking issues resolved

In the past, the way we've marked that issues in the specifications are resolved, is by adding the "resolved" class to the issue. For example, in the 20120930 version of json-ld-syntax/index.html, we had issues 114 and 133 marked resolved:

<p class="issue resolved" data-number="114">This section is an attempt to formalize
a normative grammar for JSON-LD.</p>

These were apparently dropped sometime after that, which is somewhat unfortunate, but hardly a problem.

We also had the following CSS:

.issue.resolved { display: none; }

but, that's also been removed from the latest versions of the specs.

I also see that we stopped using issue numbers to actually reference the GitHub issues, which we should do. Ideally, we would put back removed issues and reference the appropriate GitHub issue. For example, the previously mentioned issue would actually reference <https://github.com/json-ld/json-ld.org/issues/114>. Issues currently in the json-ld spec are just numbered 1-4, and result in URLs which don't reference the appropriate issue.

ReSpec doesn't yet have specific support for noting these as issues (open or resolved) in RDFa. Shane did this manually in the RDFa Core 1.1 spec, as follows using bibo [1]:

        <p rel="bibo:issue" typeof="bibo:Issue">
	  <span resource="http://www.w3.org/2010/02/rdfa/meetings/2010-05-20#resolution_1" rel="bibo:affirmedBy">
	    When  attributes accept a white space separated list of tokens, an RDFa
            Processor MUST ignore any leading or trailing white space.
	  </span>
	</p>

Now that ReSpec has better issue support, I think we can update ReSpec to generate better markup. However, I think that bibo:affirmedBy is being misused, as it relates to legal decisions. For that matter, a bibo:Issue is not like a GitHub issue, but relates to an issued document: "something that is printed or published and distributed, esp. a given number of a periodical".

The closest to what we want is probably [2]. Looking at a current atrisk definition, this might be rendered described as follows:

  <div class="issue atrisk" data-number="223" title="@base keyword">
    <p class="atrisk-head">Note: This feature is
      <a href="http://www.w3.org/2005/10/Process-20051014/tr#cfi">"at risk"</a> and may
      be removed from this specification based on feedback. Please send feedback to
      <a href="mailto:public-rdf-comments@w3.org">public-rdf-comments@w3.org</a>.
      For the current status see
      <a href="http://www.w3.org/2011/rdf-wg/wiki/JSON-LD_Features_at_Risk">features "at risk" in JSON-LD 1.0</a></p>
    <p>Support for the <code>@base</code> keyword might be removed from JSON-LD 1.0 if
      implementation experience reveals that the fact that a document may have multiple
      base IRIs is confusing for developers. It is also being discussed whether relative
      IRIs are allowed as values of <code>@base</code> or whether the empty string should
      be used to explicitly specify that there isn't a base IRI, which could be used to
      ensure that relative IRIs remain relative when expanding.</p>
  </div>

Note that data-number is changed from the current "1" to "223", which matches the issue on GitHub. This might generate the following markup:

<div class="issue atrisk resolved" property="bom:issue" typeof="bom:Issue" prefix="bom: http://www.ifi.uzh.ch/ddis/evoont/2008/11/bom#">
  <div class="issue-title" role="heading" aria-level="5">
    <a href="https://github.com/json-ld/json-ld.org/issues/223" property="bom:bugURL"><span>Feature at Risk 223</span>: @base keyword</a>
    <meta property="bom:name" content="@base keyword"/>
    <meta property="bom:number" datatype="xsd:int" content="223"/>
    <link rel="bom:hasResolution" resource="bom:Resolved"/>
  </div>
  <div class="atrisk">
    <p class="atrisk-head">Note: This feature is
      <a href="http://www.w3.org/2005/10/Process-20051014/tr#cfi">"at risk"</a> and may
      be removed from this specification based on feedback. Please send feedback to
      <a href="mailto:public-rdf-comments@w3.org">public-rdf-comments@w3.org</a>.
      For the current status see
      <a href="http://www.w3.org/2011/rdf-wg/wiki/JSON-LD_Features_at_Risk">features "at risk" in JSON-LD 1.0</a></p>
      <p property="bom:description">Support for the <code>@base</code> keyword might be removed from JSON-LD 1.0 if
        implementation experience reveals that the fact that a document may have multiple
        base IRIs is confusing for developers. It is also being discussed whether relative
        IRIs are allowed as values of <code>@base</code> or whether the empty string should
        be used to explicitly specify that there isn't a base <abbr title="Internationalized Resource Identifier">IRI</abbr>, which could be used to
        ensure that relative IRIs remain relative when expanding.
      </p>
    </div>
</div>

Gregg Kellogg
gregg@greggkellogg.net

[1] http://bibotools.googlecode.com/svn/bibo-ontology/trunk/doc/index.html
[2] https://files.ifi.uzh.ch/ddis/ontologies/evoont/2008/11/bom/