Hi all,
This is a summary of ruby-dev ML in these days.
-------- #17696-17713 (2002-07-12 … 2002-07-19) --------
[ruby-dev:17703] Re: Getting CGI argument as scalars
In this thread, Nobuyoshi Nakada has noted that he had imported
OptionParser (optparse.rb) to the CVS repository. This is the
preparation to bundle RDtool into the standard package.
[ruby-dev:17706] self in block
Isao Masaki has posted original article, and many interesting
responses are given on this idea.
Matz has noted that he is examining to introduce “real” function
object. Details has not been given yet.
Takaaki Tateishi has proposed a new method `call_current_block’,
which calls the current block itself (It achieves recursive
block call). e.g.
fact = lambda {|n|
if n == 0
1
else
n * call_current_block(n-1)
end
}
p fact[1] # 1
p fact[5] # 120
This idea has been rejected.
– Minero Aoki
Minero Aoki aamine@mx.edit.ne.jp writes:
In this thread, Nobuyoshi Nakada has noted that he had imported
OptionParser (optparse.rb) to the CVS repository. This is the
preparation to bundle RDtool into the standard package.
At this risk of sounding biased… 
I’m wondering if any consideration was given to including RDoc in the
base distribution?
I think RDTool is a wonderful utility for creating general purpose
documentation: if I were writing a manual I’d seriously consider using
it. However, I personally find it quite cumbersome when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the information that’s
in the source itself. That’s why I wrote RDoc. Because it understands
the syntax of the languages it’s documenting (Ruby, C extensions, and
Fortran currently) , it can produce meaningful output even if the
input file contains no documentation whatsoever. If also has output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation, automatic
hyperlinks, and pop-up source code for method (just click on the
method name).
I’ve put up a small compare-and-contrast page at
http://rdoc.sourceforge.net/rd/
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.
For this to be useful, we’d need to bundle RDoc with Ruby.
Cheers
Dave
I think this is an intriguing idea.
How does RDoc handle multiple languages, though? I think for your
suggestion to work, it would have to make sure that there are at least
english and japanese docs. As Ruby grows, documenation in more and more
languages would be wanted. If you stick with inline documentation, then
eventually you will end up with more documentation than code.
Does RDoc have a mechanism for dealing with this?
Paul
···
On Tue, Jul 23, 2002 at 12:28:23AM +0900, Dave Thomas wrote:
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.
If it helps, I think that rdoc should be part of the standard distribution.
It is a great resource for us and it is part of our spec to have rdoc
pages for released code. The only way it could be improved
is if could add to the ri database.
···
On Tue, Jul 23, 2002 at 12:28:23AM +0900, Dave Thomas wrote:
At this risk of sounding biased…
I’m wondering if any consideration was given to including RDoc in the
base distribution?
–
Jim Freeze
If only I had something clever to say for my comment…
~
As we say over here, `I’m falling off from clouds’. I thought RDoc
was already scheduled for inclusion in the base distribution. Have I
been daydreaming again?
Personally I don’t generate docs from my classes, but the fact that
with RDoc I can write comments in a way that is 99.9% transparent to
me, and still let who wants HTML docs easily generate them, is great.
If raised hands matter, count mine for RDoc.
Massimiliano
···
On Tue, Jul 23, 2002 at 12:28:23AM +0900, Dave Thomas wrote:
I’m wondering if any consideration was given to including RDoc in the
base distribution?
my votes for RDoc as well. i started by using RDTool, but was floored
when i found RDoc. --there’s room for improvement, but its quite the
bomb. i wonder if RDoc could be modified to understand RD markup as
well?
concerning transalation between japanese and english, is it possible to
add an option to RDoc for passing the output through babelfish? then we
could have both english and japanese for all RDocs! someone just
mentioned interfacing a ruby script with babelfish recently, so that
sparked the notion.
by the way, you can print a single frame (or save it to a file) just as
easily as you can print a whole page. the frames do not interfere with
that kind of document usage at all.
oh, one last thing: can we move the the three frames from the top to the
left hand side. i’d prefer more vertical viewing space for the
docuementation itself. (probably and easy hack, but i thought you might
want to consider it)
code safe,
~transami
···
On Mon, 2002-07-22 at 09:28, Dave Thomas wrote:
Minero Aoki aamine@mx.edit.ne.jp writes:
In this thread, Nobuyoshi Nakada has noted that he had imported
OptionParser (optparse.rb) to the CVS repository. This is the
preparation to bundle RDtool into the standard package.
At this risk of sounding biased…
I’m wondering if any consideration was given to including RDoc in the
base distribution?
I think RDTool is a wonderful utility for creating general purpose
documentation: if I were writing a manual I’d seriously consider using
it. However, I personally find it quite cumbersome when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the information that’s
in the source itself. That’s why I wrote RDoc. Because it understands
the syntax of the languages it’s documenting (Ruby, C extensions, and
Fortran currently) , it can produce meaningful output even if the
input file contains no documentation whatsoever. If also has output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation, automatic
hyperlinks, and pop-up source code for method (just click on the
method name).
I’ve put up a small compare-and-contrast page at
http://rdoc.sourceforge.net/rd/
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.
For this to be useful, we’d need to bundle RDoc with Ruby.
Cheers
Dave
–
~transami
Hi,
I’m wondering if any consideration was given to including RDoc in the
base distribution?
While it is not clearly defined how to bundle non-interpreter tools
in the standard distribution (irb is bundled in a bad manner), I’m not
against about putting RDoc in the distribution.
So I’d say “go ahead”. I’d like to see both RDtool and RDoc in the
distribution. In fact, they are for different purpose.
Will somebody volunteer to
(a) put RDoc in the distribution
(b) put RDoc comments to the sourcefile (as baseline)
? Will you, Dave? Let us discuss on the ruby-core list.
matz.
···
In message “rdtool and rdoc” on 02/07/23, Dave Thomas Dave@PragmaticProgrammer.com writes:
While I don’t comment my code too extensively, I do find RDoc is a nice
unobtrusive way to present code level documentation. A professional tool like
this is also essential for me to persuade work that Ruby is ready for prime
time. My collegues drolled over RDoc as I showed them the beauty of it
compared to javadoc.
I would like to see the Ruby API available in RDoc format, and being able to
add to ri would be fantastic!
Signed,
Holden Glova
···
On Tue, 23 Jul 2002 03:28, Dave Thomas wrote:
Minero Aoki aamine@mx.edit.ne.jp writes:
In this thread, Nobuyoshi Nakada has noted that he had imported
OptionParser (optparse.rb) to the CVS repository. This is the
preparation to bundle RDtool into the standard package.
At this risk of sounding biased…
I’m wondering if any consideration was given to including RDoc in the
base distribution?
I think RDTool is a wonderful utility for creating general purpose
documentation: if I were writing a manual I’d seriously consider using
it. However, I personally find it quite cumbersome when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the information that’s
in the source itself. That’s why I wrote RDoc. Because it understands
the syntax of the languages it’s documenting (Ruby, C extensions, and
Fortran currently) , it can produce meaningful output even if the
input file contains no documentation whatsoever. If also has output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation, automatic
hyperlinks, and pop-up source code for method (just click on the
method name).
I’ve put up a small compare-and-contrast page at
http://rdoc.sourceforge.net/rd/
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.
For this to be useful, we’d need to bundle RDoc with Ruby.
Cheers
Dave
Dave Thomas wrote:
Minero Aoki aamine@mx.edit.ne.jp writes:
In this thread, Nobuyoshi Nakada has noted that he had imported
OptionParser (optparse.rb) to the CVS repository. This is the
preparation to bundle RDtool into the standard package.
At this risk of sounding biased…
I’m wondering if any consideration was given to including RDoc in the
base distribution?
I think RDTool is a wonderful utility for creating general purpose
documentation: if I were writing a manual I’d seriously consider using
it. However, I personally find it quite cumbersome when using it to
document source files: the documentation breaks up the source, and the
documentation writer is forced to repeat much of the information that’s
in the source itself. That’s why I wrote RDoc. Because it understands
the syntax of the languages it’s documenting (Ruby, C extensions, and
Fortran currently) , it can produce meaningful output even if the
input file contains no documentation whatsoever. If also has output
options that are useful when working with source code (such as the
pseudo file/module/method browser bar for quick navigation, automatic
hyperlinks, and pop-up source code for method (just click on the
method name).
I’ve put up a small compare-and-contrast page at
RDtool or RDoc?
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
the text from the PickAxe for the interpreter documentation and for
many of the libraries, and the others could be added as we go along.
For this to be useful, we’d need to bundle RDoc with Ruby.
Cheers
Dave
rdoc looks nice, and it works well for small pieces of code. But when
you use it for a large piece of code you run into problems, because the
methods listed are not separated by the class they are a member of. (I
tried to use it that way a couple of weeks ago when the PickAxe book was
offline.) I don’t know how well RDTool would have worked for that, it
seems more aimed at printouts, but doesn’t itself produce any search
capability at all.
As far as the source code goes (from you examples), I find the rdoc code
to be much more readable. Also, the rdoc comments look much more likely
to get done, and definitely more likely to be kept current.
···
–
– Charles Hixson
Gnu software that is free,
The best is yet to be.
ts decoux@moulon.inra.fr writes:
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself.
^^^^^^^^^^^^^^^^
Not a good idea, for me.
Could you elaborate?
Cheers
Dave
Paul Brannan pbrannan@atdesk.com writes:
How does RDoc handle multiple languages, though? I think for your
suggestion to work, it would have to make sure that there are at
least english and japanese docs. As Ruby grows, documenation in
more and more languages would be wanted. If you stick with inline
documentation, then eventually you will end up with more
documentation than code.
True enough. There’s been some talk about having a --lang switch that
would select from available languages in the documentation, but as you
say that ends up making the files pretty messy.
I’d suggest that in any scheme there’d be a compromise: the in-source
documentation would be in a single language. hen there’s be narrative
files in different languages: README.en, README.jp, etc. Both RDTool
and RDoc can do this well (although I believe RDoc to have the
advantage in inline documentation). Also, not being able to write
Japanese, I’ve never had RDoc processing a multi-byte character set
file, so there may well be things that need looking at.
Cheers
Dave
Why not?
I have never tried rdtool, but using RDoc has been a breeze exactly
because it produces useful output even if there is no inline
documentation at all (as stated somewhere else in this thread, by the
author). I have later added some inline documentation where it is most
needed in my own modules, but not many places. Without a dought (imho)
RDoc’s strongest feature is that it really helps reduce the amount of
duplicated knowledge in the documentation.
Cheers,
Thomas
···
On Mon, 2002-07-22 at 17:33, ts wrote:
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself.
^^^^^^^^^^^^^^^^
Not a good idea, for me.
In mail “Re: rdtool and rdoc”
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself. We could use
I think this is an intriguing idea.
How does RDoc handle multiple languages, though? I think for your
suggestion to work, it would have to make sure that there are at least
english and japanese docs. As Ruby grows, documenation in more and more
languages would be wanted. If you stick with inline documentation, then
eventually you will end up with more documentation than code.
Matz is requiring standard library must contains English document,
and must contains only English document. (I had been opposed to it
strongly, but was rejected.) So we need not to worry about it.
Privately saying, net/*.rb might not use rdoc, just because the
current management system of Japanese documents requires RD format.
But if I write the new system, I’ll select rdoc. Maintaining embedded
RD is too hard.
– Minero Aoki
···
Paul Brannan pbrannan@atdesk.com wrote:
Massimiliano Mirra list@NOSPAMchromatic-harp.com writes:
If raised hands matter, count mine for RDoc.
Mine, as well.
Jim
···
–
Jim Menard, jimm@io.com, http://www.io.com/~jimm/
“Rumor has it the internet is out of money. Pack your stuff and go home.”
– “Pud”, www.f***edcompany.com
Tom Sawyer transami@transami.net writes:
oh, one last thing: can we move the the three frames from the top to
the left hand side. i’d prefer more vertical viewing space for the
docuementation itself. (probably and easy hack, but i thought you
might want to consider it)
Try
rdoc -T kilmer …
(an example of a pluggable template)
Cheers
Dave
matz@ruby-lang.org (Yukihiro Matsumoto) writes:
Will somebody volunteer to
(a) put RDoc in the distribution
(b) put RDoc comments to the sourcefile (as baseline)
? Will you, Dave? Let us discuss on the ruby-core list.
Yes - I’ll do it, although I have to clear a few things off my plate
first.
Thank you for considering it.
Cheers
Dave
How does RDoc handle multiple languages, though? I think for your
suggestion to work, it would have to make sure that there are at least
english and japanese docs. As Ruby grows, documenation in more and more
languages would be wanted. If you stick with inline documentation, then
eventually you will end up with more documentation than code.
Does RDoc have a mechanism for dealing with this?
I’d like to see a solution to this. Given the collaboration between
speakers of Japanese and speakers of English within the Ruby community,
I suppose people would expect us to be further ahead on this than
others.
Is it worth doing something like GNU’s gettext, though I’m pretty
ignorant of that? I know gettext is geared up for error messages etc
from programs, so the problem domain is different. Anyway, in the hope
that this might spark a useful association in someone…
Paul
Hugh
···
On Tue, 23 Jul 2002, Paul Brannan wrote:
Charles Hixson charleshixsn@earthlink.net writes:
rdoc looks nice, and it works well for small pieces of code. But when
you use it for a large piece of code you run into problems, because
the methods listed are not separated by the class they are a member
of. (I tried to use it that way a couple of weeks ago when the
PickAxe book was offline.) I don’t know how well RDTool would have
worked for that, it seems more aimed at printouts, but doesn’t itself
produce any search capability at all.
If you click on the class name in the center pane you get a list of
all the methods in that class at the top of the main pane. Also, I
suspect the eventual integration of ri and rdoc would help you here.
Dave