Howdy. Matz just got back to me w/ an email about
internationalization and multilingual documentation. What's become
abundantly clear is that inline documentation _only_ works well with
mono-lingual documentation.
One solution to inline multi-lingual documentation would be to
use some kind of markup language to embed the various languages inline.
While this would buy us inline documentation, I'm not convinced that
this actually gets us anywhere. The file size would grow out of
control and eventually a program would be unmaintainable. file size *
documentation size * number of languages = lots of bits changing all of
the time.
The biggest problem that I can envision would be file version
numbers. A developer could make two commits to the code, but there
could easily be 5-10 commits from the doc folks in between. And who's to
say that a doc writer didn't bork the code someplace and create a bug?
The easiest and best solution for this is to create a parallel
documentation tree. The advantages of this are plentiful, but most
notably:
1) Modules are smaller and would create faster execution times from the
parser (less work for lex/yacc).
2) Each translation of a various component of documentation would have
its own history independent of the other parts of a project.
3) If we wanted to get fancy and provide an inline documentation
system, we could by compiling external documentation into the module
itself by using a tagging/external document referencing system (could
compliment RD very well).
File system paths
There are three options as I see it:
1) %%PREFIX%%/share/doc/ruby/module/name.rd.en
%%PREFIX%%/share/doc/ruby/module/name.rd.mx
%%PREFIX%%/share/doc/ruby/module/name.rd.jp
%%PREFIX%%/share/doc/ruby/module/name.rd.no
2) %%PREFIX%%/share/doc/ruby/en/module/name.rd
%%PREFIX%%/share/doc/ruby/mx/module/name.rd
%%PREFIX%%/share/doc/ruby/jp/module/name.rd
%%PREFIX%%/share/doc/ruby/no/module/name.rd
Right now I'm leaning towards option #1 just because it
simplifies the number of file/directory operations necessary. If I
wanted to get the documentation for Module::name, I would only have to
open two directories to see if it exists as opposed to n + 1 operations
(where n is the number of languages installed on the system and + 1 is
the final lookup to make sure the file exists in the module/ directory).
Once I've cooked up some code and have ported the mod_ruby
documentation to this format I'll probably be more set in my opinion
(practical applications have a tendency to do that). -sc
--
Sean Chittenden
|
