Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: neutral (hermes.apache.org: local policy)
Message-ID: <41ECC0BC.4000101@apache.org>
Date: Tue, 18 Jan 2005 08:54:36 +0100
From: Reinhard Poetz <reinhard@apache.org>
User-Agent: Mozilla Thunderbird 0.9 (Windows/20041103)
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [proposal] Cocoon documentation system
References: <41E772B7.8010207@apache.org>
 <6E0707BF-6606-11D9-B7AF-000A95AF004E@apache.org>
 <41E82E41.6010701@apache.org> <20050115005102.GA10528@igg.indexgeo.com.au>
 <41E88852.9010204@apache.org> <41E8DBF1.20900@apache.org>
 <41E96E9F.6000508@apache.org> <41EB981F.5020404@apache.org>
 <41EC1544.9000003@apache.org>
In-Reply-To: <41EC1544.9000003@apache.org>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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