How to refer to issues on the tracker from the Use Case doc

Hi-

At last week's meeting I suggested how one could use the `issue` class
within a W3C html / respec document to refer to resources managed in
external systems.

Within the CSVW wg, we use this to refer to issues our Github repository.

For example ... see the CSVW metadata vocabulary document, section 5.2
Columns [1]. Here you will see an ISSUE in a pink box stating:

"""We invite comment on whether virtual columns
<http://w3c.github.io/csvw/syntax/#dfn-virtual-column> are useful enough to
include in the final recommendation in spite of the added complexity."""

You can see the it is linked to `ISSUE 179` [2]

(for reference, this ISSUE is resolved in favour, but we're yet to update
the document)

So how do we do this?

Looking at the source of the metadata vocab document [3] you will see we
have added to the respec config: `issueBase` ...

[line 10]    <script class="remove">
[line 11]    var respecConfig = {
                ...
[line 82]    issueBase: "https://github.com/w3c/csvw/issues/",
                ...
[line 85]    };
[line 86]    </script>

Then in the body of the document we use the `issue` CSS class with an
additional attribute: `data-number` ...

[line 1102]    <p class="issue" data-number="179">We invite comment ... </p>

As far as I am aware, this is standard respec [4][5] functionality.

So for the SDW Use Case document to refer to refer to, say, "
ISSUE-15: Time req. not clear - represent past, present and future
" [5], we would specify the following ...

- in the <head>

var respecConfig = { issueBase: "
http://www.w3.org/2015/spatial/track/issues/" };

- and in the <body>

<p class="issue" data-number="15"> ... </p>

This closes ACTION-47.

Jeremy

PS: as an aside, I notice that the SDW Use Case doc is referring to the
respec script using HTTP whilst CSVW uses HTTPS. I am unaware of any policy
on this, but noticed the discrepancy.

[1]: http://w3c.github.io/csvw/metadata/index.html#columns
[2]: https://github.com/w3c/csvw/issues/179
[3]: https://github.com/w3c/csvw/blob/gh-pages/metadata/index.html
[4]: https://www.w3.org/respec/
[5]: https://www.w3.org/Tools/respec/respec-w3c-common
[6]: http://www.w3.org/2015/spatial/track/issues/15

Received on Tuesday, 2 June 2015 10:00:31 UTC