From 6f2278ff9bda7c978f8f3cdae08f2fbd254b545a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Daoust?= Date: Thu, 21 Jun 2018 13:56:05 +0200 Subject: [PATCH] [Framework] Custom maturity icons for evergreen/informative specs Features initially proposed in https://github.com/w3c/web-roadmaps/issues/90. W3C specs are automatically flagged as informative when they contain only informative content or when they will be (or have been) published as a Note. Specs can also be flagged as "evergreen", which means that, regardless of their exact status on the Rec-track (or elsewhere), they can be considered fit for reference. This is roughly equivalent to the notion of a Living Standard in WHATWG. These settings are used to adjust the maturity icon being rendered. Notably: - regardless of their exact maturity status, evergreen specs use a green "REF" (for "Reference") icon. - informative icons are in dark grey to convey the fact that the spec does not define normative content. Note these colors do not match those proposed in the initial issue. This can be adjusted later on if needed. --- README.md | 2 ++ js/generate-utils.js | 25 +++++++++++++++++++------ js/translations.json | 11 +++++++++++ tools/extract-spec-data.js | 6 ++++-- tools/spec.jsons | 8 ++++++++ tools/tr.jsons | 8 ++++++++ 6 files changed, 52 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0c215b58..c88777a1 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,8 @@ Depending on the advancement of the underlying specification, the JSON object ca * `edDraft`: when the specification is unknown to the [W3C API](https://w3c.github.io/w3c-api/) and to [Specref](https://www.specref.org/), or when these APIs do not know the URL of the Editor's Draft for the specification, the `edDraft` property should contain the URL of the Editor's Draft of the specification. * `wgs`: when the specification is unknown to the [W3C API](https://w3c.github.io/w3c-api/) and to [Specref](https://www.specref.org/), the `wgs` property should be an array of objects describing the groups that are producing the spec; each such object should have a `url` property with a link to the group's home page, and a `label` property with the name of the group. * `publisher`: the organization that published the specification. The framework automatically computes the publisher for W3C, WHATWG, and IETF specifications. +* `informative`: when the specification is unknown to the [W3C API](https://w3c.github.io/w3c-api/), set the `informative` property to `true` to tell the framework that it only contains informative content or that it will be (or has been) published as a Group Note and not as a Recommendation. +* `evergreen`: from time to time, specifications remain as drafts indefinitely but are continuously updated and can be considered stable whenever a new version is published. Set the `evergreen` property to `true` when the specification can always be used as a reference, no matter where it is on the Recommendation track. Here is an example of a JSON file that describes the "Intersection Observer" specification: ```json diff --git a/js/generate-utils.js b/js/generate-utils.js index 42d070bd..66b238c3 100644 --- a/js/generate-utils.js +++ b/js/generate-utils.js @@ -301,7 +301,7 @@ const createSpecCell = function (column, featureId, featureName, specInfo, implI const createMaturityCell = function (column, featureId, featureName, specInfo, implInfo, translate, lang, pos) { // Render maturity info let cell = document.createElement('td'); - let maturityInfo = maturityData(specInfo); + let maturityInfo = maturityData(specInfo, translate); fillCell(cell, maturityInfo.maturity, maturityInfo.maturityIcon); cell.classList.add('maturity'); return cell; @@ -388,16 +388,29 @@ const fillCell = function (el, data, image) { }; -const maturityData = function (spec) { +const maturityData = function (spec, translate) { + let iconSrc = + 'https://www.w3.org/2013/09/wpd-rectrack-icons/' + + (spec.evergreen ? 'REF' : spec.status).toLowerCase() + + (spec.informative ? '-informative' : '') + + '.svg'; + let label = + (spec.evergreen ? 'REF' : spec.status) + + (spec.informative ? ' - informative' : ''); + let localizedLabel = + translate('maturity', spec.evergreen ? 'REF' : spec.status) + + (spec.informative ? + translate('maturity', ' - ') + translate('maturity', 'informative') : + ''); return { maturity: { - label: spec.status, + label: label, + localizedLabel: localizedLabel, level: maturityLevels[spec.status] || 'low' }, maturityIcon: !spec.status ? null : { - src: 'https://www.w3.org/2013/09/wpd-rectrack-icons/' + - spec.status.toLowerCase() + '.svg', - alt: spec.status, + src: iconSrc, + alt: localizedLabel, width: 50, height: 50 } diff --git a/js/translations.json b/js/translations.json index c76c6860..0ecbbf5d 100644 --- a/js/translations.json +++ b/js/translations.json @@ -32,5 +32,16 @@ "qq": "QQ Browser", "samsunginternet": "Samsung Internet", "uc": "UC Browser" + }, + "maturity": { + "ED": "Editor's Draft", + "WD": "Working Draft", + "LS": "Living Standard", + "CR": "Candidate Recommendation", + "PR": "Proposed Recommendation", + "REC": "Recommendation", + "Retired": "Retired", + "NOTE": "Group Note", + "REF": "Reference" } } \ No newline at end of file diff --git a/tools/extract-spec-data.js b/tools/extract-spec-data.js index a76da1fa..8d1a03de 100644 --- a/tools/extract-spec-data.js +++ b/tools/extract-spec-data.js @@ -262,7 +262,8 @@ async function extractSpecData(files, config) { edDraft: latestInfo['editor-draft'], title: latestInfo.title, status: latestInfo.status, - publisher: 'W3C' + publisher: 'W3C', + informative: latestInfo.informative || !latestInfo['rec-track'] }; let deliverersJson = await fetchJson( latestInfo._links.deliverers.href + `?embed=1`, @@ -283,7 +284,8 @@ async function extractSpecData(files, config) { title: spec.data.title || trInfo.title || lookupInfo.title, status: spec.data.status || trInfo.status || lookupInfo.status || 'ED', deliveredBy: spec.data.wgs || trInfo.deliveredBy || lookupInfo.deliveredBy || [], - publisher: spec.data.publisher || trInfo.publisher || lookupInfo.publisher + publisher: spec.data.publisher || trInfo.publisher || lookupInfo.publisher, + informative: spec.data.informative || trInfo.informative }; // Spec must have a title, either retrieved from Specref or defined in diff --git a/tools/spec.jsons b/tools/spec.jsons index 493eeb19..5cbab811 100644 --- a/tools/spec.jsons +++ b/tools/spec.jsons @@ -141,6 +141,14 @@ "description": "The URL of the Living Standard. Deprecated. Use `url` instead.", "type": "string", "format": "uri" + }, + "evergreen": { + "description": "The spec may be a draft but is continuously updated and suitable for use as reference.", + "type": "boolean" + }, + "informative": { + "description": "The spec contains only informative content or is/will be published as a Note.", + "type": "boolean" } } } diff --git a/tools/tr.jsons b/tools/tr.jsons index 63120da7..3dff4ab4 100644 --- a/tools/tr.jsons +++ b/tools/tr.jsons @@ -63,6 +63,14 @@ "description": "The organization that published the specification.", "type": "string", "minLength": 1 + }, + "evergreen": { + "description": "The spec may be a draft but is continuously updated and suitable for use as reference.", + "type": "boolean" + }, + "informative": { + "description": "The spec contains only informative content or is/will be published as a Note.", + "type": "boolean" } } }