Update biblio.js

[g13e]

added few dated references

[marcoscaceres]

@gps-git why are you pointing to dated items instead of latest ones?

[g13e]

@marcoscaceres I think you know the answer ;) (see discussion on spec-prod). I need them for a spec I'm editing. As they have a date in the name they don't disrupt the biblio file, so should be harmless for people not using them

[g13e]

btw on this subject: there are a lot of references in the spec that do not have a date (in the name) but point to dated version (i.e. dated url that needs to be updated manually). Those are a problem IMO, but of course I can see that there isn't really time for someone to seat and clean all of them.

[marcoscaceres]

@gps-git I'm wondering if for dated one, you can just add them to your custom bilbio? I see from the Respec documentation that you can easily have a localBiblio:

localBiblio:  {
                  "MEMES":  "<a href='http://w3cmemes.tumblr.com/'>W3C Memes</a>"
              ,   "REX":    "<strong>Overridden!</strong>"
              }

[marcoscaceres]

@gps-git I'm happy to collaborate on cleanup. I guess I would want to get agreement from @darobin @tobie on the cleanup rules, then I'd be happy to help with that.

[g13e]

Sure I can,and I already do. what I'm doing here is to share with the community. But if you don't want my dated references just say and I'll stop submitting these patches ( but please keep the old ones as I don't want to redit existing documents)

[g13e]

about the cleanup and rules: @darobin already confirmed to me a while ago that the agreed rules are the ones I'm using. On the other end, changing existing references (names) is not nice to people using them. All we could do is to remove dated reference when the name doesn't contain a date itself.

[marcoscaceres]

I personally think dated references are harmful in the main biblio. It may confuse editors and cause them to point to dated versions when they should be pointing to latest and greatest version. As @darobin already said, the only use case for the dated references was "in [[some-dated-version]] we did X, but we have since fixed that." That's very specification specific which is why I think a localBiblio is a better place for them.

[g13e]

up to you, I'm not going to push things if you don't want them. I'll wait for @darobin last word.

Anyway I don't share your fear: if editors get confused so easily I think you have a bigger problem. References should be done knowing what you are referencing, so I would assume you triple check what you are actually pointing to before adding a reference

[tobie]

@marcoscaceres do you make a distinction between specs which are recommendations and others? How do you suggest handling /tr/foo pointing to "foo, version 4" when publishing you references and to "foo, version 5" two years later, without any changes on your side?

[marcoscaceres]

@tobie can you provide a real example of that? (thinking of XML 1-5 edition). What I mean, why would one want to point at an outdated version, apart from the case where you want to warn implementers that a mistake was made (which is specification specific - hence covered by localBiblio). The only other case I can think of is if the future version is harmful (like with XML1.1)... but even then, the URL for XML 1.1 was different from XML (http://www.w3.org/TR/xml11/).

[g13e]

IMO the convention should be pretty easy:
FOO: should point to the latest and greatest version of FOO, regardless of version and status. This will be achieved by either using a url that is always pointing to the latest version (when available) or via manual updates
FOO-: should point exactly at the version of the given date and shall not be changed. This is used if I want a reference to a specific document and I don't want it to change.

@marcoscaceres there are other use cases but as you don't like them you pretend they don't exist ;)

[g13e]

@marcoscaceres a less controversial example: I'm an implementer documenting which version of a given spec I'm using. I need a dated reference for that as I want to point to exactly the document I used when implementing.

[marcoscaceres]

@gps-git That still very specific to a particular document and not to the benefits to the community at large (i.e., "we implemented [dated-version]"). That also feels to me like localBiblio.

[tobie]

@marcoscaceres I was thinking about /tr/html which now point to XHTML 1.0 and which we'd like to see point to HTML5 instead.

[tobie]

The thing is we have two moving targets: 1) until you print out and save a copy of the doc created with respec, all refs can change under you at any time, 2) pointing to /tr/foo from within the doc can change the meaning of your reference years after the fact (that seems kind of wrong to me). It's also unclear when you link to [[FOO]] whether you're effectively linking to /tr/FOO/ or to /tr/CR-FOO-20120223.html. I find that to be particularly confusing.

[fhirsch]

not everyone agrees that all references should point to the latest - there are also arguments for pointing to a dated version. Thus I would expect it premature to clean up references for which you don't know who is using them and how...

just saying..

On Apr 29, 2013, at 7:11 AM, Marcos Caceres wrote:

@gps-git I'm happy to collaborate on cleanup. I guess I would want to get agreement from @darobin @tobie on the cleanup rules, then I'd be happy to help with that.

—
Reply to this email directly or view it on GitHub.

[marcoscaceres]

@fhirsch, that's not what I mean. Cleanup would mean updating dates where latest versions are out of date. Here we are discussing using dates on keys (eg. FOO-20091201).

[marcoscaceres]

@tobie, that's a tricky one. HTML5 defines XHTML, but I can see that one could be a problem. However, such clashes are really rare, no?

[g13e]

@marcoscaceres if my use case is NOT beneficial to the community is arguable. Once again it seems you are taking a position here and try to enforce it as a general principle. I see your PoV and I partially agree with you (I have been doing my battles on this) but I don't think this is relevant from this discussion. This is just a tool, not a spec, and AFAIK is not intended to be a "W3C" tool, but a generic tool.

So my strong recommendation is to support this format (dated references) whether you agree with the intended use or not.

[fhirsch]

marcos, thanks for the clarification, that helps!

On Apr 29, 2013, at 7:52 AM, Marcos Caceres wrote:

@fhirsch, that's not what I mean. Cleanup would mean updating dates where latest versions are out of date. Here we are discussing using dates on keys (eg. FOO-20091201).

—
Reply to this email directly or view it on GitHub.

[marcoscaceres]

Right, but remember lots of us maintain and use this stuff, so the more one off references we have in there, the more difficult this bibliography is to maintain. The bibliography has already become nearly impossible to edit in the browser through github's text editor interface. Finding references is also annoying in text editors because you have scroll a kilometer to find the right place to slot in the references, etc. Adding the same reference over an over and over again just to change the date seems very broken. Perhaps there is another solution to the problem, like adding a previousVersions, which contains the URLs to previous versions.

previousVersions: [{datekey: "20121213",  url: "http://w3/TR/"}] 

Then, in HTMLs:

<p>Avoid the [[FOO-20121213]], it's so badly broken it will break your mama's back!</p>

That gets rid of the redundancy and allows you to key the actual spec you want.

[marcoscaceres]

The above would also maintain backwards compatibility and meet everyone's use cases, AFACT.

[g13e]

sure, an alternative that help "compressing" the biblio file is welcome. My use case is being able to reference a specific version, I don't have a strong preference about how this is achieved.

BTW I was under the impression that @darobin had a plan to implement something a bit more efficient for handling biblio references, but I can't remember what that was (or am I making this up?)

[marcoscaceres]

Had not heard either. Be great if we could come up with a clean solution to this. @darobin, if there is not already a bug, can you file one so we can continue discussion there?

@tobie, I don't want to block on this bug. If you are happy to merge, please merge.

@gps-git, thanks for the fruitful discussion. I think we are making progress towards having something that can work for everyone.

[marcoscaceres]

On Monday, April 29, 2013 at 12:43 PM, Tobie Langel wrote:

The thing is we have two moving targets: 1) until you print out and save a copy of the doc created with respec, all refs can change under you at any time, 2) pointing to /tr/foo from within the doc can change the meaning of your reference years after the fact (that seems kind of wrong to me).
WRT, the thing I proposed solves the problem. Also, with regards to the TR/html/ example, I would object to that pointing to HTML5. XHTML stole that one fair and square and I don't think we should steal it back from them.
It's also unclear when you link to [[FOO]] whether you're effectively linking to /tr/FOO/ or to/tr/CR-FOO-20120223.html. I find that to be particularly confusing.

Can't we solve this by making sure we keep good track of the data that is coming into the bib through pull requests - and by using my proposed solution? If we go through the current biblio file, we can basically fix most of those issues without breaking existing specs.

Marcos Caceres

[tobie]

status should be "WD"

[tobie]

OK to pull this in once the required changes have been addressed.

Still worth having a longer term conversation on these issues.

[g13e]

changes done. Should be ok to merge. For the follow-up discussion maybe better use spec-prod list?

[tobie]

For the follow-up discussion maybe better use spec-prod list?

WFM.