cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Re: [proposal] Cocoon documentation system
Date Mon, 17 Jan 2005 10:49:03 GMT
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.

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

Then I thought how e.g. Google can index both languages? 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.

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.

-- 
Reinhard

Mime
View raw message