search

json-ld / json-ld.org

JSON for Linked Data's documentation and playground site
https://json-ld.org/
Other
857 stars 152 forks source link

Keeping https://json-ld.org/spec/ updated #671

Closed BigBlueHat closed 6 years ago

BigBlueHat commented 6 years ago

Currently the "Latest" links on https://json-ld.org/spec/ (and in the header menu) are incorrect--as they point to the last draft from the CG and not the current in-progress WG specs.

Consequently, I'd like to fix that. 😄

@gkellogg I've noticed that the past pattern seems to be to persist the "published" copies of specs to this repo and those copies (as copies) contain their "this version" URLs pointing to their actual published location (sadly lacking all semblance of linked data...or even basic link relationships......which I'd also love to change/fix/improve 😜).

Should we continue the above pattern with the current Working Drafts from the WG? or (more simply) just change the "Latest" links to point to the W3C URLs?

Right now, I'm thinking just change the "latest" URLs...but figured asking would be best. 😄

gkellogg commented 6 years ago

Previously, this was done with an HTTP redirect, so that all of the latest links would redirect to the /TR versions of the documents. Personally, I found this confusing, as you would need to look at the .htaccess file to figure this out.

I think a better solution would be to update the drafts with some header which redirects users to either the current WG drafts, or published working drafts when available. W3C manages to do this automatically for documents in /TR which are not the latest versions (see, for example RDF Semantics. It would be great if we can do something like that.

I've noticed that the past pattern seems to be to persist the "published" copies of specs

Such versions are referenced at https://json-ld.org/spec/, and appear in navigational drop-downs on https://json-ld.org. Those are really all that need to be accessed now, but a search for "JSON-LD 1.1 API" will reference https://json-ld.org/spec/latest/json-ld-api/, so that should either redirect or bring up the notice as I suggested above.

BigBlueHat commented 6 years ago

@gkellogg I like the "leading note" approach stating that things have moved. However, I've not been able to get one (without CSS or JS) to appear above the version links. Respec doesn't seem to have that capability natively, and the note on RDF Semantics seems to have been added by hand (judging by all the inline styles).

I can get a note added above the abstract...but I'd prefer something higher up...

Thoughts?

gkellogg commented 6 years ago

It seems that the annoying-warning class was added just for this purpose. From https://www.w3.org/StyleSheets/TR/2016/base.css you can see that annoying-warning is intended for this:

 * Special Sections
 *   - .note       for informative notes             (div, p, span, aside, details)
 *   - .example    for informative examples          (div, p, pre, span)
 *   - .issue      for issues                        (div, p, span)
 *   - .advisement for loud normative statements     (div, p, strong)
 *   - .annoying-warning for spec obsoletion notices (div, aside, details)

Given that it comes up as a banner that does not scroll, that would seem to be adequate.

W3C seem to automatically update obsolete TRs, such as RDF Concepts with code such as the following just above "This Version":

<div id="rdf_1_1_notice" style="border: solid black 1px; padding: 0.5em; background: #FFB;">
  <p style="margin-top: 0; font-weight: bold;">New Version
        Available: "RDF 1.1 Concepts and Abstract Syntax"<span style="padding-left: 2em;"></span>
        (Document Status Update, 25 February 2014)</p>

  <p style="margin-bottom: 0;">The RDF Working Group has produced
  a W3C Recommendation for a new version of RDF which adds
  features to this 2004 version, while remaining compatible.
  Please see <a href="http://www.w3.org/TR/rdf11-concepts">"RDF 1.1
  Concepts and Abstract Syntax"</a> for a new version of this document, and the
  <a href="http://www.w3.org/TR/rdf11-new">"What's New in RDF 1.1"</a> document for the differences between this 
  version of RDF and RDF 1.1.</p>
</div>

This may be automatically done, but it rewrite the static HTML, not the ReSpec source, as you say.

Unless you want to get into ReSpec hacking, what we have in place will probably need to do.

BigBlueHat commented 6 years ago

What you added in 0f4546484b6394837f19f887b08f5b40d316a954 looks great!

Thanks, @gkellogg!