Embedded docs

ruby-talk
21

Is Esperanto or another auxiliary language practical? You would basically

There seem to be many users of Esperanto, and they have a conference
each year. There is some literature written in it, and some
esperanto-centric newspapers or journals, but I expect other
auxilliary langauges could claim the same, as could Klingon and
Tolkien Elvish enthusiasts, perhaps. Esperanto has been criticised
as being too European in flavour. Lojban is supposed to have a
grammar which YACC can handle. Ido is descended from Esperanto but
has fewer users, but is supposed to be more regular. I don’t know
the current state of Volapuk. People use these languages, so there
is some practicality.

need one person (or team) in each language to learn Esperanto. Is that

I know some on this list already do, but that is why I emphaise
automatic translation. This (machine translation) is still difficult.

better than choosing some other language as the “central” language to

But which language? Knowing how my language is so irregular
(“Power mowers are thoroughly tough, though”,
“It’s it's when it is it is, and its otherwise”), could I really ask
someone to learn that? :slight_smile: OK, we don’t really have cases, or
accented characters, but even so.

translate to and from? Can you point us to other projects that have chosen

No, I can’t point you to any, except the EU that I mentioned, and
I’m not sure about that.

this path? Mind you, they don’t have to be limited to programming. Any sort
of large-scale documentation project would be valid.

Okay, no more “doubting mode”. I’m going to go look up some Esperanto
resources for the heck of it :slight_smile:

If you find any good automatic translators, let me know. :slight_smile:

-Brian W

–
brian at coolnamehere dot com
http://coolnamehere.com

    Hugh
···

On Mon, 24 Feb 2003, Brian Wisti wrote:

22

“Seth Kurtzberg” seth@cql.com wrote in message
news:200302231530.57692.seth@cql.com…

All the Ruby documentation should be available in both English and
Japanese.
This will probably put more of a burdon on Japanese developers, as few
English speakers will be able to put anything on paper in Japanese, while
most Japanese developers have some English.

I consider documentation a very important part of developing software.
Software without documentation is like a house without a door. I mostly
avoid software where the author can’t be bothered to document the material
or only runs it through a doc tool without any further explanation.

But the above claim is unreasonable. I’m more likely to look at software
documented in Japanese than undocumented software, because at least the
author cares about the users. But even if I avoid software documented in
Japanese, there are still a lot of people that would benefit from the
software - and in the standard installation this software could still be a
dependency to other software documented in english.
Likewise, I could imagine people from Japan avoiding software only
documented in english. It happens, but I doubt you find many volunteers to
translate english to japanese, except for major books and software modules.

This shouldn’t stop the software from spreading. On the other hand, software
that is not documented, can’t be translated so documentation in any major
language could well be a requirement.

Mikkel

23

Esperanto has been touted as a common language for over 100 years, but it has
never really been a serious alternative. If you want a good way to kill Ruby

The internet may be changing that, as it makes people more aware of
other peoples. There’s a lot of Esperanto stuff out there.

entirely, put all the documentation into a language spoken by absolutely
nobody.

http://www.esperanto.net/veb/faq-5.html
2 million people > nobody.

It was not suggested that an auxilliary language prevent docs being
supplied in a native language as well. Having Japanese + Esperanto
will reach a much wider audience than just Japanese alone, and gives
me two versions of the text to look at if I want to check the
meaning.

All the Ruby documentation should be available in both English and Japanese.

Do you mean docs for all projects? How do the French speakers on
this list feel about this proposal :wink: ?

This will probably put more of a burdon on Japanese developers, as few
English speakers will be able to put anything on paper in Japanese, while
most Japanese developers have some English.

But both these could put something in Esperanto even if they
translate by machine.

    Hugh
···

On Mon, 24 Feb 2003, Seth Kurtzberg wrote:

24

Thank you very much, Josef! I am interested in learning Japanese for
its own sake, but this program will definitely help with the more
immediate concerns of reading documentation.

So the next question: anyone know of a Romaji to English converter? :wink:

-Brian W

Josef ‘Jupp’ Schugt wrote:

···

If your goal is not to learn Japanese but only to be able to
understand documentation written in Japanese, KAKASI may help you:

KAKASI - Kanji Kana Simple Inverter Version 2.3.4
Copyright (C) 1992-1999 Hironobu Takahashi. All rights reserved.

25

I’ve worked briefly at a company that prepared tools for translators. My time
there was short (several months of contract work), but long enough to get the
idea that automated translation was not to be trusted. For a real
translation of ideas and idioms, a human brain was needed. A human brain
aided by their tools, of course :wink:

I looked quickly at Lojban and Esperanto sites. Esperanto seems easier to
learn from first glance. You mentioned that people on this list were
familiar with some of the artificial languages. If they notice this
exchange, I would love to hear from them about which might make the easiest
to translate documentation to and from.

-Brian W

···

On Sunday 23 February 2003 12:15 pm, Hugh Sasse Staff Elec Eng wrote:

On Mon, 24 Feb 2003, Brian Wisti wrote:

Is Esperanto or another auxiliary language practical? You would
basically

There seem to be many users of Esperanto, and they have a conference
each year. There is some literature written in it, and some
esperanto-centric newspapers or journals, but I expect other
auxilliary langauges could claim the same, as could Klingon and
Tolkien Elvish enthusiasts, perhaps. Esperanto has been criticised
as being too European in flavour. Lojban is supposed to have a
grammar which YACC can handle. Ido is descended from Esperanto but
has fewer users, but is supposed to be more regular. I don’t know
the current state of Volapuk. People use these languages, so there
is some practicality.

need one person (or team) in each language to learn Esperanto. Is that

I know some on this list already do, but that is why I emphaise
automatic translation. This (machine translation) is still difficult.

–
brian at coolnamehere dot com
http://coolnamehere.com

26

Even if it is not 100% achievable, having the docs in both languages is a
worthwhile goal.

···

On Sunday 23 February 2003 04:48 pm, MikkelFJ wrote:

“Seth Kurtzberg” seth@cql.com wrote in message
news:200302231530.57692.seth@cql.com…

All the Ruby documentation should be available in both English and

Japanese.

This will probably put more of a burdon on Japanese developers, as few
English speakers will be able to put anything on paper in Japanese, while
most Japanese developers have some English.

I consider documentation a very important part of developing software.
Software without documentation is like a house without a door. I mostly
avoid software where the author can’t be bothered to document the material
or only runs it through a doc tool without any further explanation.

But the above claim is unreasonable. I’m more likely to look at software
documented in Japanese than undocumented software, because at least the
author cares about the users. But even if I avoid software documented in
Japanese, there are still a lot of people that would benefit from the
software - and in the standard installation this software could still be a
dependency to other software documented in english.
Likewise, I could imagine people from Japan avoiding software only
documented in english. It happens, but I doubt you find many volunteers to
translate english to japanese, except for major books and software modules.

This shouldn’t stop the software from spreading. On the other hand,
software that is not documented, can’t be translated so documentation in
any major language could well be a requirement.

Mikkel

–
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com

27

I don’t believe that there are 2 million people who know esperanto. You have
to look at the history of this thing. Every few years these claims are made,
and they never amount to anything.

I just don’t want people diluting useful efforts with something that is in
fact a joke, although you may not believe yet that it is a joke (but it most
certainly is).

Esperanto has been touted as a common language for over 100 years, but it
has never really been a serious alternative. If you want a good way to
kill Ruby

The internet may be changing that, as it makes people more aware of
other peoples. There’s a lot of Esperanto stuff out there.

entirely, put all the documentation into a language spoken by absolutely
nobody.

http://www.esperanto.net/veb/faq-5.html
2 million people > nobody.

It was not suggested that an auxilliary language prevent docs being
supplied in a native language as well. Having Japanese + Esperanto
will reach a much wider audience than just Japanese alone, and gives
me two versions of the text to look at if I want to check the
meaning.

All the Ruby documentation should be available in both English and
Japanese.

Do you mean docs for all projects? How do the French speakers on
this list feel about this proposal :wink: ?

I have no objection of course to documentation in as many languages as
possible. However, the French speakers I’ve dealt with are quite proficient
in English, so you get a larger effect by providing docs in English first.

···

On Sunday 23 February 2003 05:28 pm, Hugh Sasse Staff Elec Eng wrote:

On Mon, 24 Feb 2003, Seth Kurtzberg wrote:

This will probably put more of a burdon on Japanese developers, as few
English speakers will be able to put anything on paper in Japanese, while
most Japanese developers have some English.

But both these could put something in Esperanto even if they
translate by machine.

    Hugh

–
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com

28

Do you mean docs for all projects? How do the French speakers on
this list feel about this proposal :wink: ?

One of these french speakers understand Ruby and C better than English and
Japanese and don't care about documentation.

Guy Decoux

29

Kind of…

www.jisyo.org
www.rikai.com

···

On Thu, Feb 27, 2003 at 10:31:57AM +0900, Brian Wisti wrote:

Thank you very much, Josef! I am interested in learning Japanese for
its own sake, but this program will definitely help with the more
immediate concerns of reading documentation.

So the next question: anyone know of a Romaji to English converter? :wink:

–
_ _

__ __ | | ___ _ __ ___ __ _ _ __
'_ \ / | __/ __| '_ _ \ / ` | ’ \
) | (| | |__ \ | | | | | (| | | | |
.__/ _,|_|/| || ||_,|| |_|
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com

Sic transit discus mundi
– From the System Administrator’s Guide, by Lars Wirzenius

30

You would be far better off to look for a native character set to
English converter … much of the meaning of a Japanese sentence is
lost or becomes somewhat ambiguous when the kanji are removed.
Remember that Chinese characters are ideologic, not phonetic – the
shape of the character bears the meaning, and it happens to be bound
to a particular sound when spoken.

If you know any Japanese, there are quite a few good on-line
dictionaries around, as well as rikai.com (which someone else posted
here). There are also PC-based dictionaries using various free dict
files – I use gjiten, a Gtk+ (X11/Unix) based frontend to the popular
‘edict’.

As far as automated Japanese-to-English conversion, I’ve not seen a
free tool that does a good job. I’d be thrilled if someone would
correct me here. :wink:

Ethan

···

On Thu, 27 Feb 2003 10:31:57 +0900, Brian Wisti wrote:

Thank you very much, Josef! I am interested in learning Japanese for
its own sake, but this program will definitely help with the more
immediate concerns of reading documentation.

So the next question: anyone know of a Romaji to English converter? :wink:

–
Happiness is a belt-fed weapon.

31

automatic translation. This (machine translation) is still difficult.

I’ve worked briefly at a company that prepared tools for translators. My time
there was short (several months of contract work), but long enough to get the
idea that automated translation was not to be trusted. For a real

Agreed. That’s why I suggested using two engines, and translating
back to be sure. Even that won’t be perfect. I think distributing
the documentation in an auxilliary language alone would be a
weakness, but if distributed with the original language there is
scope for people to improve the translation. Also, with ruby code
(rather than binary applications) there is another source of
semantic information to support the translation. This solution is
sub-optimal, but it will help others to some extent greater than
having no translation.

translation of ideas and idioms, a human brain was needed. A human brain
aided by their tools, of course :wink:

I looked quickly at Lojban and Esperanto sites. Esperanto seems easier to
learn from first glance. You mentioned that people on this list were

Yes, I think so, too. Having very regular verbs is a great help.
I’m finding that keeping track of the suffices difficult, though.
But I’ve not been able to put much time in to this.

familiar with some of the artificial languages. If they notice this
exchange, I would love to hear from them about which might make the easiest
to translate documentation to and from.

-Brian W

    Hugh
···

On Mon, 24 Feb 2003, Brian Wisti wrote:

On Sunday 23 February 2003 12:15 pm, Hugh Sasse Staff Elec Eng wrote:

32

Esperanto easier to learn than Lojban… I think you said
a mouthful there. :wink:

Lojban is great in that it is wonderfully exact and there
are intricate mechanisms for gradations of meaning and
mechanisms for disambiguation. Yes, it’s machine parseable.
However, it’s not the syntax that makes it difficult. It’s
how all the little pieces relate and interact. Remember
your ninth grade biology? Lojban is a little more complex
than photosynthesis. :slight_smile: Just my opinion. I can never
remember what bridi and gismu (etc.) are and how they work.

As for Esperanto: It was designed more to be useful and
easily learned than to be scientifically exact and
unambiguous. It’s pretty easy to learn (from what I’ve
seen – I don’t really know it) and it’s been around for
120 years or so. Of all the conlangs ever made (and there
are probably more than you think), this is the most
practical, useful, and widespread of them all. Yes, it
does have its faults – it probably is too eurocentric
and it does have its irregularities despite efforts to
avoid them.

As for the practicality of writing docs in Esperanto…
it seems a little problematic to me. Most programmers
can hardly be bothered to write docs in their own
native language. :slight_smile: :slight_smile:

Yet if someone wanted to take steps in this direction, I’d
go along just for the sheer novelty of it.

We’d probably have to come up with some neologisms (or
maybe compounds, if they are allowed). What Esperanto word
would we use for “closure”? What about these terms: Memory
location, garbage collection, iterator, object-oriented,
method, class, definition, dynamic, variable, constant,
module? What about names for punctuation like braces,
brackets, parentheses, and so on? (Even English speakers
can’t agree on these. One man’s bracket is another man’s
parenthesis. And never mind the numerous names for #, such
as pound, number, sharp, octothorpe, …)

The more I think about it, the less practical it seems. :slight_smile:

Cheers,
Hal

···

----- Original Message -----
From: “Brian Wisti” brian@coolnamehere.com
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Sent: Sunday, February 23, 2003 3:07 PM
Subject: Re: Internationalization

I looked quickly at Lojban and Esperanto sites. Esperanto seems
easier to
learn from first glance. You mentioned that people on this list were
familiar with some of the artificial languages. If they notice this
exchange, I would love to hear from them about which might make the
easiest
to translate documentation to and from.

33

Do you mean docs for all projects? How do the French speakers on
this list feel about this proposal :wink: ?

One of these french speakers understand Ruby and C better than English and
Japanese and don’t care about documentation.

Yes, certainly. :slight_smile: My point was linguistic equality.

Guy Decoux

    Hugh
···

On Mon, 24 Feb 2003, ts wrote:

34

Do you mean docs for all projects? How do the French speakers on
this list feel about this proposal :wink: ?

One of these french speakers understand Ruby and C better than English
and
Japanese and don’t care about documentation.

Yes, certainly… sometimes I think you are not really
French but are a native of Rubyland, wherever that
may be… for you the code is the documentation. And
as Matz has said: It even documents the bugs… :slight_smile:

Hal

···

----- Original Message -----
From: “ts” decoux@moulon.inra.fr
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Cc: ruby-talk@ruby-lang.org
Sent: Monday, February 24, 2003 5:30 AM
Subject: Re: Internationalization (Re: embedded docs)

35

Incidentally there is a wonderful "I-Spy" photograph in the current edition
of Private Eye, a UK satirical magazine:

http://www.private-eye.co.uk/ispy.htm

(For the benefit of the archives, because this page will change: it's a
dual-language sign photographed in Chengda, China. On the top line are a
series of Chinese ideograms, and underneath the translation:
  "People railway for dumb millions")

···

On Mon, Feb 24, 2003 at 06:07:35AM +0900, Brian Wisti wrote:

I've worked briefly at a company that prepared tools for translators. My time
there was short (several months of contract work), but long enough to get the
idea that automated translation was not to be trusted. For a real
translation of ideas and idioms, a human brain was needed. A human brain
aided by their tools, of course :wink:

36

You would be far better off to look for a native character set to
English converter … much of the meaning of a Japanese sentence is
lost or becomes somewhat ambiguous when the kanji are removed.

I only did suggest the program because it takes lot of training to
read Kanji so it can be helpful to read the text in a simpler writing
and only take a look at the original text if the meaning is unclear.

As far as automated Japanese-to-English conversion, I’ve not seen a
free tool that does a good job. I’d be thrilled if someone would
correct me here. :wink:

Translations are even a problem in one of the easiest cases:
German → Dutch. From a linguistic point of view Dutch and German are
one language (from a practical point of view they are two).
Nevertheless it is not very easy to translate Dutch to German or
German to Dutch. If this is already a problem, there is little chance
that a good free automatic translation software from Japanese to
English is feasible without spending lots of time and money.

I recently saw “Hotaru no Haka” in Japanese with German subtitles.
One time ‘kamikaze’ was left as ‘Kamikaze’ whereas in another
situation it was translated as ‘der goettliche Wind’ (the devine
wind). If one would exchange these two translations they would be
inappropriate because in the first case there were kamikaze up in the
sky whereas in the second case a man did say “Now not even a devine
wind will help us any more”.

Josef ‘Jupp’ Schugt

···

On Fri, 28 Feb 2003 04:38:45 +0000 (UTC), Ethan Blanton eblanton+news@cs.purdue.edu wrote:

37

Hmmm. I think I have to agree with you there. Learning an invented
language is one thing, but adding words to it is another.

Back to the drawing board …

-Brian W

Brian Wisti
brian@coolnamehere.com
http://coolnamehere.com/

···

At 10:42 AM 2/24/2003 +0900, you wrote:

The more I think about it, the less practical it seems. :slight_smile:
Cheers,
Hal

38

We’d probably have to come up with some neologisms (or
maybe compounds, if they are allowed). What Esperanto word

These are fair questions, so I took the time to find out, with help,
what the answers might be. They seem to live at:
http://purl.org/net/kameleono/KompLeks/UTF8/
then select the initial letter from the English alphabet.

would we use for “closure”? What about these terms: Memory

closure: fermo

location, garbage collection, iterator, object-oriented,

Memory location – memora pozicio
(combining refs to location search and memory)
garbage collection: makulaturtraktado, senrubigo
iterator: iteraciilo
bject-oriented programming: objektema programado
object-oriented programming language: . objektema programlingvo

method, class, definition, dynamic, variable, constant,
method: metodo
class: klaso
definition – defino (combining refs to defining occurrence
and efinition module)
dynamic – dinamika (There are other possibilities as well)
variable: variablo
constant: konstanto
module? What about names for punctuation like braces,
module: modulo
brace: vinkulo
brackets, parentheses, and so on? (Even English speakers
bracket: krampo
parentheses: krampo
(Hmmm, same problem as English then :-))
can’t agree on these. One man’s bracket is another man’s
parenthesis. And never mind the numerous names for #, such
hash: dieso, krado
(as destinct from hash function haketfunkcio…)
as pound, number, sharp, octothorpe, …)

The more I think about it, the less practical it seems. :slight_smile:

Cheers,
Hal

    Hugh
···

On Mon, 24 Feb 2003, Hal E. Fulton wrote:

39

Wow. So we could do it if we really wanted to. But do enough people
really want to? I mean, I would like to learn Esperanto, but there is
a pretty long list of things I would like to learn. It’s food for
thought, though.

-Brian W

Brian Wisti (brian@coolnamehere.com)

···

On Monday, March 3, 2003, at 10:34 AM, Hugh Sasse Staff Elec Eng wrote:

[ An impressive conversion of English → Esperanto technical terms ]

40

If there’s already not enough time in a day to write docs in English or
to translate them from Japanese, why should there be to

  1. learn Esperanto
  2. write documentation
    ???

Obviously we cannot supply user documentation in Esperanto (people would
simply stay away from our apps), so, as we’re considering something
developer-centric, we could just get by with some standard way of
furnishing examples and pre/post conditions of the methods. The
semantics should be obvious from context.

Plus it’d be unfair for all the Japanese developers to have to learn
Esperanto as it’s mostly a mix of European languages…

···

On Tue, Mar 04, 2003 at 05:22:51AM +0900, Brian Wisti wrote:

On Monday, March 3, 2003, at 10:34 AM, Hugh Sasse Staff Elec Eng wrote:

[ An impressive conversion of English → Esperanto technical terms ]

Wow. So we could do it if we really wanted to. But do enough people
really want to? I mean, I would like to learn Esperanto, but there is
a pretty long list of things I would like to learn. It’s food for
thought, though.

–
_ _

__ __ | | ___ _ __ ___ __ _ _ __
'_ \ / | __/ __| '_ _ \ / ` | ’ \
) | (| | |__ \ | | | | | (| | | | |
.__/ _,|_|/| || ||_,|| |_|
Running Debian GNU/Linux Sid (unstable)
batsman dot geo at yahoo dot com

martin@bdsi.com (no longer valid - where are you now, Martin?)
– from /usr/src/linux/drivers/cdrom/mcd.c