cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Collen <colle...@umn.edu>
Subject Re: [RT] Moving towards a new documentation system
Date Mon, 20 Oct 2003 04:56:32 GMT
Replies inline, I may have missed something important, so please pardon 
anything obvious that was commented on that I may have missed :)

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".

Hmm, well, then we need to look and plan ahead a little:

http://cocoon.apache.org/documentation/X.X/tutorial/whatever.html

This way we version the whole branch of the docs tree based on version 
-- sort of how we already have separate sections of the site for 1.x, 
2.0, 2.1, etc.

.. And, perhaps something like 
http://cocoon.apache.org/documentation/foo/bar.html would take you to 
the appropriate document for the most current version of Cocoon.  My 
only concern is how this could possibly interact with the versioning 
scheme that is being planned for the individual documents.. perhaps it 
will work perfectly fine.

Joerg Wrote:

>>> 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.

Ughh... the thought of having a large string of numbers (even if it is a 
date) in order to know what a document is, leaves a bad feeling in the 
pit of my stomach.

Then again, Stefano wrote:

>> hmmm, well, it depends.
>>
>> The URI (we are talking about URIs here, not URLs, careful)

Which puts the hole in my gut at ease, at least for now :)

<snip what="discussion about versioning"/>

>> 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.

This is a good idea, it's easy enough to increment the number.  Getting 
back to the idea of using the date,  this convention is used in setting 
the "Serial" in a DNS server, which lets the server know when the record 
has been updated:

YYYYMMDDNN

YYYY = year
MM = month
DD = day

And NN where NN = 00 to 99 (I think it will accept more).  The idea is 
when you make a change to a zone file, you update the date, and possibly 
  increment NN, if the date is already "up to date". But I think the 
revision idea above is simple enough.


Stefano wrote:

>> 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.

(and then Joerg wrote):

> Ah, ok. Our documentation changes so rarely that I didn't thought about 
> this ;-) 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? In 
> general a commit short after another one fixes almost only typos or 
> similar. Maybe the last version of a day might be sufficient?

If a document changes more than 100 times in a day, (at least in my 
proposed idea) we might want to think about using the wiki more before a 
commit is made :)

> 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.

I would still like to voice my distaste over having a numerical system 
to access a document, at least for the "current" version of a document. 
  For accessing a historical version of a document, I think it's fine, 
but like I said above, having to remember numbers for a URL really 
really scares me.

> 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 ...

(Ditto) :)

> 
> Joerg
> 


Regards,

Tony


Mime
View raw message