[mapserver-dev] documentation localization and svn structure

[Howard Butler]

On May 9, 2009, at 10:45 AM, Lars Lingner wrote:
>
> I was playing around with Sphinx, but couldn't get the language  
> suffixes
> to work. Instead I found a way to handle the docs as follow:
>
> #some "global" files and directories
> ...trunk/docs/_static
> ...trunk/docs/_templates
> ...trunk/docs/{conf.py,labels.py,Makefile)
> #and the documentation separated in <language>-directories
> ...trunk/docs/en/{cgi,community,development,...)
> ...trunk/docs/de/{cgi,community,development,...)
>
> I modified the Makefile, so that for every language the html/latex/etc
> code output is generated.
> The output will be placed in ../build/en/{html, latex, labels,...} the
> german output goes in ../build/de/{html, latex, labels,...}. Other
> languages will be handled the same way.

Excellent.  I'm glad you found a workable solution that you seem  
reasonably happy with.  It was mod_negotiation that I was thinking  
about.  http://httpd.apache.org/docs/2.0/mod/mod_negotiation.html   
This way should be just as useful and easy to maintain.
>
>
> The generated code can be served by the webserver. Wouldn't it be
> possible to use mod_rewrite to keep the current urls but get the  
> content
> from an <lang>-subdirectory?
>

Yes, we can do that.  We'll just need to cook up some permanent  
redirects and a few rewrites.

>
> With this way, its not possible to auto deliver browser requested
> languages. Instead the user has to choose his favorite language. But
> IMHO this should not be a problem. The English doc will be the  
> preferred
> language. Every other language would be optional with no guarantee.
>

We may need to make it a bit more prominent to show the user what  
language they're looking at.  We could use flag icons too I suppose.


> Some further conditions apply:
> - all documents need to have the same file name in every language
> subdirectory
>
> - if there is no translation for a particular file, there is no  
> warning
> message (see [1], I just removed the unix installation file), the text
> is just missing
> - if there is an directory missing, the corresponding toc entry will  
> not
> be a link (see [2], I removed the 'input' directory), also no warning
>
> Maybe it is possible to implement some kind of default error page  
> which
> gets shown when an particularly translation is not available (with  
> link
> to default English docu).
>
> The latex/pdf generation is also working [3], but I didn't changed the
> code yet to copy the file to the right destination.
>
>
>>>
>>> Third question is how to maintain the translations. I volunteer  
>>> for the
>>> German part. But how would I (or others) get notified when the  
>>> English
>>> docs get updated? I would like to keep the translation synchron  
>>> with the
>>> English one.
>>
>> This is a hard problem.  We have finally made it easy enough for  
>> people
>> just go edit the docs as they need to.  If we were to require a  
>> ticket
>> or something for each edit, it would greatly slow this process down
>> again and kill off any (limited) enthusiasm we have for doc writing.
>> About the only reasonable option would be to follow the Trac's RSS  
>> feed
>> of /trunk/docs/
>>
>> http://trac.osgeo.org/mapserver/log/trunk/docs?limit=100&mode=stop_on_copy&format=rss
>>
>>
>> but that puts a lot of burden on you to integrate changes into
>> translations.
>>
>
> With the above solution the synchronization of translations will not  
> get
> easier but also not more difficult. If it would be possible to build  
> an
> status page so its easy to visualize the difference in translations,
> that would be nice. But I have no clue how to do it... yet :)

Georg on the Sphinx list has been very helpful with questions if you  
want to do something interesting.  The "labels" target was the result  
of a question I had asked about determining link target names.

>
>
> I wouldn't mind to follow an rss feed. But then only the translators
> would have an overview, the website visitor wouldn't know if or what  
> is
> missing.
>
>
> Lars
>
>
> [1] http://www.lingner.eu/docs/umn/build/en/html/installation/index.html
> [2] http://www.lingner.eu/docs/umn/build/de/html/documentation.html
> [3] http://www.lingner.eu/docs/umn/build/de/latex/MapServer.pdf

This looks great, and I'm glad you've been working hard to get a  
workable solution.  I would be interested in hearing from Jeff and  
Perry, but I think we should implement this as soon as possible,  
including backporting it to the 5.4 docs.  Others may have different  
ideas though.  It will be nice to finally have a workable multilingual  
solution to MapServer's documentation -- especially one that isn't too  
restrictive.

Howard