cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [proposal] Cocoon documentation system
Date Mon, 17 Jan 2005 19:43:00 GMT
Reinhard Poetz wrote:
> Stefano Mazzocchi wrote:
> 
>> Sun did this with the Java API did this and created a mess, people 
>> linked to java/1.4.2/ and then 1.4.3 was created and all links broke 
>> down.
>>
>> If a document shipped in 2.1.3 has a bug and was fixed in 2.1.4, why 
>> would anybody want to see it? and if 2.1.4 removed something useful 
>> for 2.1.3, that's a bug and we should fix it in the doc, rather than 
>> make everything available on the web.
>>
>> So I'm -1 on this.
> 
> 
> Makes sense, especially that all links to our docs may become out of 
> date if the person linking to us doesn't use the dynamic version.
> 
> The reason for publishing docs of patch versions is, that not everybody 
> uses the latest Cocoon version. I know a company that uses 2.1.5 and 
> every now and then I came across the problem that I'm not sure if a 
> feature is already available. But maybe notes within the document are 
> good enough here. And when setting up a new repository for a new minor 
> Cocoon version all notes _can_ be skipped.

cool.

>> As for french docs, I *strongly* think that we should do this thru 
>> content-negotiation rather than URL design. A person accessing the 
>> page with a french browser will get the page in french, that's all 
>> they have to know (and the page will have a series of flags that will 
>> trigger an overload in locale, but that's going to be a parameter of 
>> the URL, not part of it).
>>
>> The language a page is written, just like the data-type of the page, 
>> should not belong in the URL.
>>
>> This makes the URL space way more "solid" overtime: I can link to
>>
>>  http://cocoon.apache.org/2.2/3984948
>>
>> and *be sure* that it will be there a few years from now and, by then, 
>> maybe a translation in my native language would have poped up!
>>
>> let's be brave!
> 
> 
> :-)
> 
> For my new website (hopefully it goes online very soon ;-) ) I provide 
> the most docs in German and in English. The URL is the same and as you 
> describe, based on the browsers language either the one or the other 
> content is displayed. Additionally the user has the possibility to switch.

Right, having a list of small flags in the page somewhere is a must... 
it gives the user the ability to know how many translations of that page 
exist... and, also, provide a *stub* for others to start attacking the 
problem.

> Then I thought how e.g. Google can index both languages? 

following those links above :-)

> It can follow 
> the switching link but then it doesn't know that it should follow all 
> links again. The result was the introdution of another transformer step 
> in my pipeline that appends "l=en" or "l=de" (depending of the current 
> language) to all links that makes all links unique and indexable.

yep, correct. the parameter overloads the facility. also easy to 
implement with request parameter matching ;-)

> I think something similar can work for the published Cocoon docs maybe 
> using some mod_rewrite tricks but it may become difficult when providing 
> static docs. This probably needs some Forrest tweaks for generating the 
> "downloadable" docs.

tell you what. forget about it for now. Think about going dynamic and 
later we'll find a way to make a persistent copy of that (either via 
forrest or simply by wget or something)

-- 
Stefano.


Mime
View raw message