Re: [RT] Moving towards a new documentation system

[Stefano Mazzocchi]

On Sunday, Oct 19, 2003, at 22:32 Europe/Rome, Joerg Heinicke wrote:

On 19.10.2003 21:07, Stefano Mazzocchi wrote:

Remain the "everlasting semantically meaningful names". Of course  
the URL should match the content. But if the content changes, so  
that it no longer matches, what's the sense of having still this  
page? Even if you use IDs and change the content later, the user  
linked from outside to this page gets other content than he wants  
to have. So there must be available an "outdating mechanism".  
Let's say there is a page  
http://cocoon.apache.org/documentation/tutorial/xmlforms.html,  
which is linked often from outside, because it was the one and  
only form handling in Cocoon. Now in Cocoon 2.2 or 3.0 XML Forms  
are removed completely, but we don't want to give the user a  
simple 404 page. We have to point out that he can "use Woody or  
Cocoon forms which is by far better than XML Forms" with a link to  
the correct page  
http://cocoon.apache.org/documentation/tutorial/cocoonforms.html.  
You have to do exactly the same for the number URLs. So I think  
there is no problem with "everlasting semantically meaningful >>>  
names".
you have a point there, that's for sure.
I'll think about this some more.... do you have any suggestion?


I read today "Cool URIs don't change" [1] for preparing the  
answering of your mail. And there are not many options left after  
reading it: The URLs of a learning object need an ID and a  
modification date, not more, not less.
hmmm, well, it depends.
The URI (we are talking about URIs here, not URLs, careful)
Hmm, but if you want to make the linking from outside also consistent,  
why inventing another scheme?
True. Consistency is one thing, but remember that is entirely possible  
that several URLs can point to the same object identified by even a  
different URI!

The URI can be used as a URL, but the "meaning" of this use is not so  
explicit as it seems at first sight. (read below for more)

of a LO will need an ID that identifies the object, then might  
(optionally) have another ID that identifies the version.
So, I would do
 http://host/path/ID
to identify the object in general
This can also be seen as "latest version" of an LO, can't it?
Exactly, but it could also get you a list of possible versions from  
where you can choose from.

As you see, the URI->URL mapping is not so obvious: even when the  
string translation is one to one, the meaning might not be.

In Subversion, for example, the URI used as a URL references the latest  
version of the file and to get a specific version you have to do

 http://host/repo/file!version=3

[or equivalent, don't remember the exact syntax]

I still don't know what is the best URI->URL translation strategy, but  
for subversion it makes sense so that I can have a subversion  
repository act as a regular web server with very little effort

[I'm thinking about using subversion of the repository for our learning  
objects!]

and
 http://host/path/ID/version
to indicate the object version
The IDs would allow to change the content without a latter mismatch  
between URI and content.
Exactly.
The date assures that a later access to a linked page has the  
content it should have, it can not have been changed in the >>> meantime.
This is a little bit more tricky. If you choose to use a timestamp  
for the version ID, then you have to make sure that you have enough  
granularity to take into account the minimum potential time in  
between two different changes might happen, or, again, you get a  
collision.
This is why I generally dislike the use of dates in URIs, version  
numbers are *abstract*, so
http://cocoon.apache.org/lo/39484/342
indicate revisions 342 of learning object 39484 and this does not  
change over time.
The user would always access a page where the content is appropriate  
to a certain date, similar to "cvs co -r 20030303 >>> lo/1234567890.xml".
That means that you get a collision if you have more than one version  
of the documents per a given date, and this is very likely to happen.
Ah, ok. Our documentation changes so rarely that I didn't thought  
about this ;-)
LOL

Yes, a version is also ok. Though a timestamp must not end with the  
day, there are also milliseconds.
But of course collision is still not impossible. OTOH how strong might  
documents change on one day?
that's the problem: how do you know? with an incremental versionID you  
don't have collision issues anyway

In general a commit short after another one fixes almost only typos or  
similar. Maybe the last version of a day might be sufficient?

I only would like to have date metadata before clicking on a link.
sorry, I'm not sure I follow you here.

But also note that we are still talking about URIs not URLs. Using  
the LO URI as a URL might not be the only way to access the object.
Maybe the date to version mapping is one thing, that can be handled  
when mapping URLs to URIs. So as said above the last version of a day  
is *the* version of that day. Then we have versioned URIs and dated  
URLs.

Could it be, that you already came to the same conclusion in other  
parts of this thread? I appologize for that. Sometimes it takes a bit  
longer ...
I don't remember if I made it explicit already, but I'm glad you came  
to the same conclusion. Yes, the "date -> version" can be part of the  
URL->URI translation procedure.

So, asking for

 http://host/path/id/date

could yield the last revision for that particular date (if any), or  
could give a list of revisions that were done on that date.

but at this point, we had to differentiate between version and date...  
so, another option, following subversion's approach is to use something  
like

 http://host/path/id!date=20031015

or

 http://host/path/id!version=343

or even

 http://host/path/id!branch='cocoon-2.1'

or, even wilder, following Kimbro Stalken's (of Xindice fame) approach  
at Syncato (http://www.syncato.org/)

  
http://host/path/!branch='cocoon-2.1'?// 
author[contains(@name,'Stefano')]

that would yield a list of objects in the "cocoon-2.1" branch that  
include at least one element named <author> that contain the string  
'stefano' in their name attribute.

This example shows pretty evidently how URL->URI traslation is not such  
an automatic and easy thing to describe and to design.

Also shows that using URI as URLs is not transparent as well and  
requires some implicit contract.

--
Stefano.