Is ruby going to have (in a reasonably predictable future 
embedded
docs available via some attributes, in a similar way as it is done in
python?
···
–
Cthulhu cultists will be given the following priveleges:
They will die last.
I don't know about python, but there already is a mechanism like perl's pod:
See http://www.rubycentral.com/book/rdtool.html
http://raa.ruby-lang.org/list.rhtml?name=rdtool
Regards,
Brian.
···
On Sun, Feb 23, 2003 at 02:05:36AM +0900, Wojciech Kaczmarek wrote:
Is ruby going to have (in a reasonably predictable future
embedded
docs available via some attributes, in a similar way as it is done in
python?
if you’re talking about doc
Well, matz answered me on this topic telling that no, thiw won’t ever
appear, cause it makes the interpreter bigger.
Anyway, in near future all the stdlib would incorporate rdoc
documentation, and the whole thing would be integrated with ri.
It seems reasonable to me having documentation separated from running
code.
···
il 22 Feb 2003 17:03:50 GMT, Wojciech Kaczmarek schatten@nospam.transilvania.eu.org ha scritto::
Is ruby going to have (in a reasonably predictable future
docs available via some attributes, in a similar way as it is done in
python?
gabriele renzi wrote:
Is ruby going to have (in a reasonably predictable future
docs available via some attributes, in a similar way as it is done in
python?if you’re talking about doc
Well, matz answered me on this topic telling that no, thiw won’t ever
appear, cause it makes the interpreter bigger.Anyway, in near future all the stdlib would incorporate rdoc
documentation, and the whole thing would be integrated with ri.It seems reasonable to me having documentation separated from running
code.
Will ri (or some other doc browser) be available as part of the standard
distribution? I really miss perldoc and was looking for a similar
utility for Ruby. Something that could search for the appropriate
documentation bundle, module, class, or method and display available
documentation. If documentation was unavailable, it could at least
describe the interface by listing methods (or arguments for a method).
Here are a few ideas of how such a browser could be invoked:
rubydoc ruby
rubydoc rubyfaq
rubydoc Kernel
rubydoc Kernel.putc
rubydoc -f eval
(These examples use the notation from “Programming Ruby”, page xxxi)
rubydoc Fred
rubydoc Fred#doit
rubydoc Fred.new
rubydoc Fred::EOF
This is one of those ideas that nag at me any time I use a language that
isn’t Perl 
-Brian W
···
il 22 Feb 2003 17:03:50 GMT, Wojciech Kaczmarek >schatten@nospam.transilvania.eu.org ha scritto::
Is ruby going to have (in a reasonably predictable future
docs available via some attributes, in a similar way as it is done in
python?if you’re talking about doc
Well, matz answered me on this topic telling that no, thiw won’t ever
appear, cause it makes the interpreter bigger.
Ok. I was curious about matz plans.
Anyway, in near future all the stdlib would incorporate rdoc
documentation, and the whole thing would be integrated with ri.
Btw, very interesting discussion has been started within this thread.
I’m only just discovering the Ruby Universe and I’m glad seeing many
important answers at once. It speeds up the process of minimizing lack
of my knowledge very efficiently
It seems reasonable to me having documentation separated from running
code.
Well, in my opinion: yes and no. There are the cases when availability
of docs in runtime could be a crucial thingy. Anyway, the solution
could be a wrapper/loader/whatever adding specific doc-data from
external sources. I don’t need it now, just theorizing.
···
On Sat, 22 Feb 2003 19:09:37 GMT, gabriele renzi wrote:
–
We don’t demand solid facts! What we demand
is a total absence of solid facts!
Will ri (or some other doc browser) be available as part of the standard
distribution?
I think it already is.
Actually, I’m saying that it is in the winInstaller, and I’ve got it
in my linux boxes, but dunno how I got it there
Here are a few ideas of how such a browser could be invoked:
rubydoc ruby
rubydoc rubyfaq
rubydoc Kernel
rubydoc Kernel.putc
rubydoc -f eval
I’m not really used to perldoc… but what -f does?
It seems to me that it documents basic functions which don’t fall in
external modules.
If it is so, well, the Kernel class is documented in ri, and all the
“functions” are actually methods so they’re defined too.
Anyway, I think (3.4) are already there.
I know that perldoc incorporates lots of stuff that is more about the
whole language, while the ri philosophy is to document classes/methods
that you could use.
But maybe adding references to external docs could be useful, even if
not incorporating them.
just my 2 eurocents
···
il Sun, 23 Feb 2003 05:16:36 +0900, Brian Wisti brian@coolnamehere.com ha scritto::
(These examples use the notation from “Programming Ruby”, page xxxi)
rubydoc Fred
rubydoc Fred#doit
rubydoc Fred.new
rubydoc Fred::EOFThis is one of those ideas that nag at me any time I use a language that
isn’t Perl-Brian W
Brian Wisti brian@coolnamehere.com writes:
Will ri (or some other doc browser) be available as part of the standard
distribution? I really miss perldoc and was looking for a similar
utility for Ruby.
Perhaps the best thing about perldoc is that I can install a new Perl
module and then read its documentation and work out how to use it. In
the Ruby world, I often install a module and then think “Now
what?”. If I’m very lucky, there’s some documentation buried away in the
module’s source tarball somewhere. If I’m only ordinarily lucky, there
might be an example script. Usually, there’s neither.
I don’t know a good way of fixing this that doesn’t presuppose a
documentation browser which can go and find documentation about a
specific module in a known, standard place.
···
–
I think the real problem here is that he is a university CS
professor and therefore knows very little about programming in the real
world, in any languge.
I’m not really used to perldoc… but what -f does?
It seems to me that it documents basic functions which don’t fall in
external modules.
I don’t know what -f does, but perldoc is one of the most fantastic things
about Perl, and what I miss most from it. Any and every module that has
documentation can be reached with perldoc. That definitelly includes
external modules. Information about perl in general can be obtained with
perldoc. Details of perl’s internals, object orientation, tutorials, etc
etc etc. One of the things I loved most of Perl was the massive
documentation that it came with via perldoc.
I hope to see a rubydoc some day.
What does ‘ri’ stand for? Would “rubydoc” be a better name?
I know that perldoc incorporates lots of stuff that is more about the
whole language, while the ri philosophy is to document classes/methods
that you could use.
That’s something I’d like to see either change in ‘ri’ or be incorporated
into a new ‘rubydoc’ tool.
But maybe adding references to external docs could be useful, even if
not incorporating them.just my 2 eurocents
Just my 2 pesos.
···
On Sun, Feb 23, 2003 at 06:06:03AM +0900, gabriele renzi wrote:
–
Daniel Carrera
Graduate Teaching Assistant. Math Dept.
University of Maryland. (301) 405-5137
Will ri (or some other doc browser) be available as part of the standard
distribution?I think it already is.
Actually, I’m saying that it is in the winInstaller, and I’ve got it
in my linux boxes, but dunno how I got it there
I had to download and install ri myself on my Linux machine, but I’m not
surprised that it is already included in some installations. It is a nice
tool, though.
I’m not really used to perldoc… but what -f does?
It seems to me that it documents basic functions which don’t fall in
external modules.
Yes, exactly. “perldoc -f eval” performs the same task as “ri eval”. You are
right - some of the functionality I am describing is already available.
I know that perldoc incorporates lots of stuff that is more about the
whole language, while the ri philosophy is to document classes/methods
that you could use.But maybe adding references to external docs could be useful, even if
not incorporating them.
I can accept that ri has a narrower focus, and that it might not be a good
idea to make ri do things it was not built for. I would still like to see as
much documentation as possible included with the Ruby distribution. It can
be enlightening to browse a random Perldoc item, and that sort of random
enlightenment would be nice in other languages, also
-Brian W
···
On Saturday 22 February 2003 01:06 pm, gabriele renzi wrote:
il Sun, 23 Feb 2003 05:16:36 +0900, Brian Wisti > > brian@coolnamehere.com ha scritto::
–
brian at coolnamehere dot com
http://coolnamehere.com
It’s funny how these conversations all seem to lead back to the same
things:
The Perl community has -
(1) documentation standards (pod + perldoc)
(2) distribution standards (h2xs stub builder and the like, and the
whole Makefile.PL dance)
(3) development standards (pause and the whole smokehouse concept)
(4) a decent archive (CPAN - note: I’m not saying that ruby doesnt have
an archive - just that what CPAN offers that the Ruby community doesnt
is constantly under estimated IMHO)
(5) bug tracking (rt.cpan.org)
These are all things that add up in lots of subtle, and not so subtle
ways to be a very effective Langauge support infrastructure.
The way Perl does all these things may not be the best way, but it all
adds up to being arguably the most successful Community Language of all
time (so far).
Forinstance Makefile.PL’s reliance on make is a problem for some - but
because you at least have a build, test, and install phase that is enforced
to some degree, and the automatic creation, and installation of documentation,
still makes light years ahead of extconf.rb approach.
The absence of these things that Perl programmers take for granted, is
quite possibly the stumbling block that may stop Ruby from stepping up
to the mark in the long run if there is no will to take what is good
from those that have been before.
I propose that all those that are going to OSCON (if there is still
going to be a Ruby contingent) get togther (maybe at a BOF), and have a
go at mapping this stuff out - I’ll certainly be there for it.
(sorry for the rant Simon - just taking the lead in from the thread, and
certainly not a criticism of you).
Cheers.
···
On Sun, Feb 23, 2003 at 11:47:08PM +0900, Simon Cozens wrote:
Brian Wisti brian@coolnamehere.com writes:
Will ri (or some other doc browser) be available as part of the standard
distribution? I really miss perldoc and was looking for a similar
utility for Ruby.Perhaps the best thing about perldoc is that I can install a new Perl
module and then read its documentation and work out how to use it. In
the Ruby world, I often install a module and then think “Now
what?”. If I’m very lucky, there’s some documentation buried away in the
module’s source tarball somewhere. If I’m only ordinarily lucky, there
might be an example script. Usually, there’s neither.I don’t know a good way of fixing this that doesn’t presuppose a
documentation browser which can go and find documentation about a
specific module in a known, standard place.–
I think the real problem here is that he is a university CS
professor and therefore knows very little about programming in the real
world, in any languge.
Very well put. Take whatever I said about Perldoc and put this in its place,
so I can sound much smarter
-Brian W
···
On Saturday 22 February 2003 01:28 pm, Daniel Carrera wrote:
I don’t know what -f does, but perldoc is one of the most fantastic things
about Perl, and what I miss most from it. Any and every module that has
documentation can be reached with perldoc. That definitelly includes
external modules. Information about perl in general can be obtained with
perldoc. Details of perl’s internals, object orientation, tutorials, etc
etc etc. One of the things I loved most of Perl was the massive
documentation that it came with via perldoc.
–
brian at coolnamehere dot com
http://coolnamehere.com
I agree that this is very important.
Another note: for some key modules there is documentation only in Japanese.
···
On Sunday 23 February 2003 09:55 am, Piers Harding wrote:
It’s funny how these conversations all seem to lead back to the same
things:The Perl community has -
(1) documentation standards (pod + perldoc)
(2) distribution standards (h2xs stub builder and the like, and the
whole Makefile.PL dance)
(3) development standards (pause and the whole smokehouse concept)
(4) a decent archive (CPAN - note: I’m not saying that ruby doesnt have
an archive - just that what CPAN offers that the Ruby community doesnt
is constantly under estimated IMHO)
(5) bug tracking (rt.cpan.org)These are all things that add up in lots of subtle, and not so subtle
ways to be a very effective Langauge support infrastructure.The way Perl does all these things may not be the best way, but it all
adds up to being arguably the most successful Community Language of all
time (so far).
Forinstance Makefile.PL’s reliance on make is a problem for some - but
because you at least have a build, test, and install phase that is enforced
to some degree, and the automatic creation, and installation of
documentation, still makes light years ahead of extconf.rb approach.The absence of these things that Perl programmers take for granted, is
quite possibly the stumbling block that may stop Ruby from stepping up
to the mark in the long run if there is no will to take what is good
from those that have been before.I propose that all those that are going to OSCON (if there is still
going to be a Ruby contingent) get togther (maybe at a BOF), and have a
go at mapping this stuff out - I’ll certainly be there for it.(sorry for the rant Simon - just taking the lead in from the thread, and
certainly not a criticism of you).Cheers.
On Sun, Feb 23, 2003 at 11:47:08PM +0900, Simon Cozens wrote:
Brian Wisti brian@coolnamehere.com writes:
Will ri (or some other doc browser) be available as part of the
standard distribution? I really miss perldoc and was looking for a
similar utility for Ruby.Perhaps the best thing about perldoc is that I can install a new Perl
module and then read its documentation and work out how to use it. In
the Ruby world, I often install a module and then think “Now
what?”. If I’m very lucky, there’s some documentation buried away in the
module’s source tarball somewhere. If I’m only ordinarily lucky, there
might be an example script. Usually, there’s neither.I don’t know a good way of fixing this that doesn’t presuppose a
documentation browser which can go and find documentation about a
specific module in a known, standard place.–
I think the real problem here is that he is a university CS
professor and therefore knows very little about programming in the real
world, in any languge.
–
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com
Piers Harding piers@ompa.net writes:
(sorry for the rant Simon - just taking the lead in from the thread, and
certainly not a criticism of you).
No, I think you underscored my point better than I could have done. Thanks.
···
–
dd.c: sbrk(64); /* For good measure */
- plan9 has a bad day
This little sentence speaks volumes about one of the major challenges for
Ruby. The language is an international effort, with people contributing
thoughts and ideas from all over the globe. This is wonderful because oour
enjoyment of Ruby gives us a common bond. On the other hand, it is awkward,
because the best documentation for one module is in Japanese, while another
module’s documentation is in English. How much effort is being duplicated
simply because we do not realize that somebody else already covered it in
another language?
I would like to see a documentation browser in the style of Perldoc, but now I
think that it would only address part of the issue. Perhaps we can take a
close look at how other successful projects have handled the challenges we
are facing right now. PHP and KDE are the first such projects that I think
of, but I am sure there are others.
- http://www.php.net/docs.php
- http://i18n.kde.org/
I have seen several attempts to tie all of the Ruby documentation together. I
am wondering how successful they are, and any ideas that they could
contribute to this, or any help that they need. It would be embarassing to
duplicate effort when the goal is to reduce duplication
It is time to send this off and get more coffee before I start to ramble too
much!
-Brian W
···
On Sunday 23 February 2003 09:18 am, Seth Kurtzberg wrote:
Another note: for some key modules there is documentation only in
Japanese.
–
brian at coolnamehere dot com
http://coolnamehere.com
Another note: for some key modules there is documentation only in
Japanese.This little sentence speaks volumes about one of the major challenges for
Ruby. The language is an international effort, with people contributing
thoughts and ideas from all over the globe. This is wonderful because oour
enjoyment of Ruby gives us a common bond. On the other hand, it is
awkward, because the best documentation for one module is in Japanese,
while another module’s documentation is in English. How much effort is
being duplicated simply because we do not realize that somebody else
already covered it in another language?
It is more than that. I have just written a module that already exists, and I
was always aware that Japanese documentation exists. That doesn’t help; if I
can’t find one of my Japanese speaking friends, knowing the documentation
exists in Japanese doesn’t help me. (I also rewrote it because the other
implementation is poorly designed, but that is a separate issue.)
The solution is straightforward, if perhaps annoying; simply don’t accept any
module as “official” Ruby unless the documentation is included. Having a
common format for the documentation would of course be very beneficial, but
one step at a time.
···
On Sunday 23 February 2003 10:53 am, Brian Wisti wrote:
On Sunday 23 February 2003 09:18 am, Seth Kurtzberg wrote:
I would like to see a documentation browser in the style of Perldoc, but
now I think that it would only address part of the issue. Perhaps we can
take a close look at how other successful projects have handled the
challenges we are facing right now. PHP and KDE are the first such
projects that I think of, but I am sure there are others.I have seen several attempts to tie all of the Ruby documentation together.
I am wondering how successful they are, and any ideas that they could
contribute to this, or any help that they need. It would be embarassing to
duplicate effort when the goal is to reduce duplicationIt is time to send this off and get more coffee before I start to ramble
too much!-Brian W
–
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com
Did the original module only have Japanese documentation available? It is
hard for me to guess from your first paragraph. I agree with your general
solution, but it brings us back to the question: what language should this
documentation be in? It would be unfair to make us learn Japanese in order
for us to master ruby. It would be at least as unfair to force matz and the
army of Ruby folks in Japan to do all of their documentation in English.
Of course, I’m still working on learning Japanese anyhow. It’s just so
cool-looking
-Brian W
···
On Sunday 23 February 2003 10:06 am, Seth Kurtzberg wrote:
It is more than that. I have just written a module that already exists,
and I was always aware that Japanese documentation exists. That doesn’t
help; if I can’t find one of my Japanese speaking friends, knowing the
documentation exists in Japanese doesn’t help me. (I also rewrote it
because the other implementation is poorly designed, but that is a separate
issue.)The solution is straightforward, if perhaps annoying; simply don’t accept
any module as “official” Ruby unless the documentation is included. Having
a common format for the documentation would of course be very beneficial,
but one step at a time.
–
brian at coolnamehere dot com
http://coolnamehere.com
It is more than that. I have just written a module that already exists, and I
was always aware that Japanese documentation exists. That doesn’t help; if I
[…]
The solution is straightforward, if perhaps annoying; simply don’t accept any
module as “official” Ruby unless the documentation is included. Having a
Doesn’t your example pass that test? The documentation existed.
Don’t we then need to choose a language into which documentation
must be translated, even automatically, for this to work?
This sort of thing seems to be the function of auxilliary
languages. As far as I can see the only Auxilliary Language with a
large number of users is Esperanto (though this is notoriously
difficult to determine), and I heard in the 1980’s[?] that this was
the language into which European Community activity was translated
before being translated into the destination language. Thus the
translation process was k to 1, followed by 1 to k => 2k tranlations
needed, rather than k**2 direct translations needed. I have not
seen any really good online translation engines for Esperanto. More
than one is needed so a person can translate through one, and
translate back through another, to determine if the descriptions are
clear enough to survive translation. Esperanto is relatively easy to
learn, but that would be asking all Ruby authors to put the time in
to learn it to a sufficient level to be useful for documentatio.
Hence the need for automatic translation. Also I don’t know how
computer literate the language is – i.e. how well it covers the
topics we wil need. But an auxialliary language does have the
advantage of a “level playing field”, we’d all find it equally
foreign.
To summarize (so people can trim the above :-))
If one language is to be standard for Ruby docs, it must be chosen.
Auxialliary langauges are not biased to one country/culture.
The availability of good, free automatic translators is very important.
Hugh
···
On Mon, 24 Feb 2003, Seth Kurtzberg wrote:
Dude. Esperanto? That is … that is to say … I think … I do not know if
I like it because it is a reasonable suggestion or just because it sounds
very cool. So I have to put myself into “doubter mode” just to see past my
own preferences
Is Esperanto or another auxiliary language practical? You would basically
need one person (or team) in each language to learn Esperanto. Is that
better than choosing some other language as the “central” language to
translate to and from? Can you point us to other projects that have chosen
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
-Brian W
···
On Sunday 23 February 2003 11:20 am, Hugh Sasse Staff Elec Eng wrote:
To summarize (so people can trim the above :-))
If one language is to be standard for Ruby docs, it must be chosen.
Auxialliary langauges are not biased to one country/culture.
The availability of good, free automatic translators is very important.Hugh
–
brian at coolnamehere dot com
http://coolnamehere.com
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
entirely, put all the documentation into a language spoken by absolutely
nobody.
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.
···
On Sunday 23 February 2003 11:52 am, Brian Wisti wrote:
On Sunday 23 February 2003 10:06 am, Seth Kurtzberg wrote:
It is more than that. I have just written a module that already exists,
and I was always aware that Japanese documentation exists. That doesn’t
help; if I can’t find one of my Japanese speaking friends, knowing the
documentation exists in Japanese doesn’t help me. (I also rewrote it
because the other implementation is poorly designed, but that is a
separate issue.)The solution is straightforward, if perhaps annoying; simply don’t accept
any module as “official” Ruby unless the documentation is included.
Having a common format for the documentation would of course be very
beneficial, but one step at a time.Did the original module only have Japanese documentation available? It is
hard for me to guess from your first paragraph. I agree with your general
solution, but it brings us back to the question: what language should this
documentation be in? It would be unfair to make us learn Japanese in order
for us to master ruby. It would be at least as unfair to force matz and
the army of Ruby folks in Japan to do all of their documentation in
English.Of course, I’m still working on learning Japanese anyhow. It’s just so
cool-looking-Brian W
–
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com
Of course, I’m still working on learning Japanese anyhow. It’s
just so cool-looking
And as far as reading written language is concerned, Japanese is the
most complicated language I know of. It has three alphabets: Hira-
gana, Katakana, and Kanji.
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.
Usage: kakasi -a[jE] -j[aE] -g[ajE] -k[ajKH] -E[aj] -K[ajkH] -H[ajkK]
-J[ajkKH] -i{oldjis,newjis,dec,euc,sjis}
-o{oldjis,newjis,dec,euc,sjis} -r{hepburn,kunrei} -p -s
-f -c"chars" [jisyo1, jisyo2,]
Character Sets:
g: graphic k: kana (j,k defined in jisx0201)
E: kigou K: katakana
H: hiragana J: kanji(E,K,H,J defined in jisx0208)
Options:
-i: input coding system -o: output coding system
-r: romaji conversion system
-p: list all readings (with -J option)
-s: insert separate characters (with -J option)
-f: furigana mode (with -J option)
-c: skip chars within jukugo (with -J option:
default TAB CR LF BLANK)
-C: romaji Capitalize (with -Ja or -Jj option)
-U: romaji Upcase (with -Ja or -Jj option)
-u: call fflush() after 1 character output
-w: wakatigaki mode
Kakasi relies on the libkakasi library; a libkakasi binding for Perl
does exist and IIRC I recently came across a Ruby binding.
As far as information on the web is concerned there is a
Japanese-rewriting Proxy called ‘japana’ written in Perl that makes
use of libkakasi to convert Japanese Web pages to Roma-ji (latin
transliteration). Warning: That does not solve all problems; any
graphical elements (that may show Japanese text) are of course left
untranslated.
HTH
Josef ‘Jupp’ Schugt
···
On Mon, 24 Feb 2003 03:52:43 +0900, Brian Wisti brian@coolnamehere.com wrote:
On Sunday 23 February 2003 10:06 am, Seth Kurtzberg wrote:
a: ascii j: jisroman