From: James Britt <jamesUNDERBARb@...>
Date: 2004-10-14T16:17:49+09:00
Subject: Internationalizing ri (was Re: documentation as source )

> On Tue, 2004-10-12 at 00:44, Niklas Frykholm wrote:
>
>>I've toyed a bit with literate programming, but I'm not really sold on
>>the idea. I guess my problem with "documentation as source" (or even
>>with "source as documentation", but that is a smaller gripe) is the
>>notion that a program only has one "story". Usually, I find that in my
>>programs there are many different stories: a story for a beginner user,
>>a story for an expert user, a story for someone who wants to extend the
>>module, a story for someone who wants to hack it, a story for someone
>>who wants to understand and study the technology behind it. And of

>>course, there can be stories can be in different languages.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

>> Trying to put all these stories as well as the source code in
>> the same document tends to be confusing, at least for me.


(Emphasis mine.)

Right now, one can get API help at the command line using ri.  The data
come from the source + source code comments, which tend to be in English.

Suppose one wanted to make ri data available in other languages?  How
might one go about this?

I'm thinking that one could write additional yaml files that would act
as overlays on the base documentation, such that, for example,
   % ri String -DE
would instruct ri to load the default docs for String from the file
cdesc-String.yaml, and then overlay any content from an additional file,
cdesc-String.de.yaml, which would contain the German translations.

Basically, passing a language switch to ri would tell it to look for and
load any translation overlays for the given language.  Loading an 
overlay would simply replace any data in the default set if there is 
something defined in the translation file.  For example, much of 
cdesc-String.yaml is a list of methods; cdesc-String.de.yaml could omit 
these as they do not need translations, and just provide the comment: 
section.

Comments?

Are there any plans to internationalize ri?

On a related note, how stable are the RI and and RDoc APIs, and the YAML 
file formats used to feed ri?

Being an early registrant for RubyConf2004, I managed to get a copy of 
the pickaxe II before leaving for Germany, but I did not see 
documentation for the RI classes themselves (e.g., RiWriter, RiCache); 
they do not seem to be listed as either part of the core classes or the 
standard library.  Is there a recommended way to read or manipulate ri data?

Thanks,

James