From: Clemens Hintze <c.hintze@...>
Date: 1999-08-22T22:37:27+02:00
Subject: [ruby-talk:00742] Re: RD with multi charset

On 22 Aug, Minero Aoki wrote:
> Hi, I'm Minero Aoki. This is my first mail in this mailling list.

Welcome you :-) I am happy you use this mailing list to speak about Ruby
:-))) We need more traffic here, I think!

> I propose new feature for RD.
> 
> Now RD can contain only the one 
> If there is only Japanese document in ruby source code, it will
> cause trouble in non-Japanese environment. But, we (Japanese user)
> strongly want to use Japanese in documents.

[good proposal deleted... ;-)]

> How do you think this?

Erhm.. Few days before, I would had said, that this is a good idea,
indeed. But now, after some discussion with Tosh, I have adopted his
meaning, that RD should be used to simply comment a source file, and
produce documentation with that comments.

That all should be simple and readable for the reader of the plain
source as well. Now after some thinking, I find that Tosh's thoughts are
very true. 

So I think, it would be too complicate. A user would perhaps doesn't see
the code among all these comments. I think, that you are very right,
that to produce language dependend documentation is a very important
issue. But I feel, that this would be the wrong way to go.

I mean, that we should use the RD format to comment modules and classes,
that we would like to distribute for others usage. So we get both source
comments and documentation. But we should made such descriptions not
language dependend in the source.

I feel that way... If I produce a very cool class, that I want to share
with you or others, I cannot write German documentation. Ok! I could
write it in German, but then I couldn't expect, that anybody would take
my code, if s/he couldn't find out, how to use it. ;-)))

So after some thinking, I hope, we don't go that way. I hope further,
modules and classes in Ruby will be documented in English. So that I am
also able to read, understand and use them.

Think about Perl! How many peoples are using Perl? How many would it be,
if the documentation of the most modules in Perl were written in e.g.
Arab? ;-)

> -------------------------------------------------------------------
> Minero Aoki

\cle