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 Tue, 18 Jan 2005 07:54:36 GMT
Stefano Mazzocchi wrote:
> 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.

ok. I will adapt my proposal

> 
>>> 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 :-)

... what shall I say ... sometimes the solution is soooo close and I don't see 
it ;-)

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

point taken :-)

here my next steps:
  - adapt the proposal so that it reflects the results of the discussion
  - same for the two demo repositories
  - implement the web application

-- 
Reinhard

Mime
View raw message