DI

Tim Berners-Lee
Date: 2016-12-01, last change: $Date: 2017/12/10 18:42:36 $
Status: personal view only. Editing status: good enough for government work

Up to Design Issues


Icing on the cake


There are two competing patterns in the way the URIs of a source code control system and those of the web site are related.

Version Control System-Centric

In a web-based interface to a Version Control System, like Github, there are a bunch of similar URIs for things like repositories, branches, folders within the source, particular commits, particular files at a particular commit, and raw versions of those files. Of these, one file, say

     <https://github.com/acmedata/myproject/blob/master/index.html>
     
is a "landing page" sanitized editable view of an actual file which will be n the website. The actual raw file itself is at
     https://raw.githubusercontent.com/acmedata/myproject/master/index.html
    
and the raw file of a specific file is
      https://raw.githubusercontent.com/acmedata/myproject/ac05c1f01cbd911f35202fb327a2687e979d4c4a/package.json
     

But of course of these files are web pages in a web site (or anything with links) you need to have them all served up at their appropriate URLs, at least as far as the end of the path so that relative URLs work. This includes scripts and stylesheets too, of course not just hypertext links. SO github offers a separate service where the file above is served at

    https://acmedata.github.io/myproject/index.html
    

Here, the source code system rules, and the actual live system gets less attention. Clearly this is designed for people who will test their stuff out on github.io and then copy everything to the destination server of their choice, say

    https://acmedata.com/myproject/index.html
    

One disadvantage of this pattern is that when you are in the project github web pages, it it is not at all obvious how to construct the URL above for the live site, and the project folks he to make an explicit link to it in their documentation. Another disadvantage is that when you are on the live site, either the acmedata.github.io site or the acmedata.com site, their is no obvious way of knowing that the github site exists or of finding its URI. A node module will, on a good day, explicitly include that information in package.json, but in general there is no way for a HTTP client to discover the link by fetching the HTML page.

Live-site-centric

If you look be contrast at the w3.org site, things are flipped. The live data is the center. This is the cake - this is the main purpose of the site: serving the web pages. That is the cake, and everything else is icing on the cake. The URL of the work is the basic clean thing, and the URLs of the many things related to it are made by adding a little extra to to the URL. Icing on the cake. In the case of w3.org, you can just add a comma ",". So for example, if the URL is

https://www.w3.org/Payments/WG/
Then by adding "," you get a page with an index of many tools
https://www.w3.org/Payments/WG/,
you get a page with an index of many tools.
https://www.w3.org/Payments/WG/,tools
Many of those tools have comma shortcuts. We are not talking only about version control, but also access control, and lots handy tools like validation, link checking, different formats of the same thing, spell checking and so on. An advantage of the "icing on he cake" model is that because the tools are all available from the actual page itself, they can scale to more an more tools as no one tool forces the whole URL into its own strange shape.

In fact, in the case of w3.org, once you follow the link into the CVS system, it looks pretty much like th git system above, so you can't find your way immediately back. It would certainly be interesting for someone to make a web interface for a version control system which is all icing on the original cake, where at any point you can strip off the ,stuff and get back to the original file live on the web site)

Machine-readable icing

It helps the user of existing browsers to use icing on the cake if they are provided witha human-readable index, and to make the URI suffixes used short, simple ane memorable.

Also think though of duture more powerful tools, or browser extensions,

The Memento protocol is a good example of a machine-readable icing on the cake. It adds HTTP headers to allow older versions of a web page to be found, allowing a momento-equipped browser to explore the timeline of a web page's histroy.'

The solid system does provide, for example, meta links to access contol pages, in this spirit. Future versions of solid may do well to think about including icing along the lines of the hashes of subtrees, and other parts of a version control system.

Conclusion

The "icing on the cake" pattern, in which all services around a live web page are available at URIs make by adding smll strings to the same URI, ha many nice properties. It is easy to use, and scales well as new facilities are added. Future systems, especially version control systems, but also access control systems, should be desigend with that in mind. Not only should one make the facilities available to a human user by adding (say) the comma by hand, but also make the facilities visible to software by adding a link of some sort.

Appendix: Example of actual icing on one cake

This is a subset of all the facilities available, a snapshot on 2017-12-10.


The following W3C administrative information is available about "http://www.w3.org/Payments/WG/". Some of these pages can also be accessed by adding the comma prefix shown to the document Web address — these so called "comma-tools" work on any www.w3.org or dev.w3.org page.

For this page General tool ,shortcut Access control
A plain text version of the page, handy for pasting into email. HTML to Text converter ,text Same as the document
List of bad links in the page Link Checker ,checklink Same as the document
Bad links in a page and in pages linked from it Link Checker ,rchecklink Same as the document
List of HTML markup errors. HTML Validator ,validate Same as the document
List of spelling errors. W3C Spellchecker ,spell Same as the document
List of style CSS errors. CSS Validator ,cssvalidate Works only on public pages.
Log of changes to the document CVS Log ,cvslog Public on dev.w3.org, Team-only on www.w3.org
HTTP headers sent by the server Headers ,headers Same as the document
Check the compliance of this document to the W3C publication rules the pubrules checker ,pubrules Same as the document
Check the compliance of this document to the W3C publication rules, only displaying errors the pubrules checker ,pubruleserrors Same as the document

The following services have shortcuts available only on www.w3.org:

For this page General tool ,shortcut Access control
List of translations for the current document. Translations ,translations Public
List of translations for the current document in the specified language (where XX stands for: fr, it, nl, ja...). Translations ,translations-XX Public
Generate formatted minutes of a meeting IRC log Online Minutes Generator ,minutes Same as the document
Tidied version of the page HTML Tidy ,tidy Same as the document
Access control for file or directory Access Control .../file,access or .../dir/*,access Per document/directory dependent
List all templates in this directory Simple templating system ,new Public

References

Memento
HTTP Framework for Time-Based Access to Resource States -- Memento
WAC
Web Acess control (WAC) specification: ACL Resource Location Discovery
Comma
W3C comma tools
pattern
Christopher Alexander, "A Pattern Language"

Up to Design Issues

Tim BL