The great ri conversion... :)

ruby-talk
1

We’re in the middle of integrating RDoc/ri-style comments into the main
interpreter sources (we being Michael Granger and me, with help from Ed
Sinjiashvili). So far we’re maybe 60% complete, and it’s starting to
look pretty good. You can check our progress at

http://www.rubygarden.org/ruby?StillToDo

If you want to play with the results (and you’re on a Unix-based box)(*)

  • check out a copy of the latest Ruby from CVS.

  • build and install

  • in the main Ruby directory (the one containing object.c etc), type

    rdoc --ri *.c

  • then use ‘ri’ to browse the results

    ri Array
    ri Array.push

  • You can get prettier output by enabling formatting

    ri -f bs Array.select
    ri -f ansi MatchData

“-f bs” does formatting using overstrikes, and works with pagers such
as “more” and “less.” The “-f ansi” option uses ANSI escape sequences.
To make these work with the “less” pager, you need to tell it to allow
raw escape codes through. I run my version of less with the LESS
environment variable set as follows:

export LESS="-REX"

You can use RDoc as before to extract documentation from your own
classes (and from library classes). If you use the --ri option, this
documentation will then be accessible via ‘ri’.

Right now there are some holes, and I’ll be adding features and fixing
bugs over the next couple of weeks. I’m announcing this now to
encourage people to play, find issues, and come up with things to
improve. However, I’m not yet at the stage where I can deal with bugs
reports and the like. Please play with all this stuff, and in a week or
so I’ll announce a release candidate, at which point I’ll be soliciting
as much feedback as I can get.

Cheers

Dave

(*) Why Unix only? Because I haven’t even tried it on a Windows box
yet. It might work, but then again… I will try it at some point.

2

“Dave Thomas” dave@pragprog.com wrote in message

Cheers

Dave

(*) Why Unix only? Because I haven’t even tried it on a Windows box
yet. It might work, but then again… I will try it at some point.

I tried it on Windows ! It worked !! Well, almost (see below :wink:

DISCLAIMER: I am just a user of “benchtimer.rb”, not the author
I have attached the ruby source of that file for reference only.

···

C:>ruby -v
ruby 1.8.1 (2003-12-25) [i386-mswin32]

C:>rdoc -v
RDoc V1.0pr1: 2003/12/01 07:12:48 (1.1)

C:> cd RubyConf*

C:\RubyConf2003>rdoc --ri LegoTowerServer.rb

             LegoTowerServer.rb: c..........

Generating RI…

C:\RubyConf2003>ri LegoTowerServer
------------------------------------------------ Module: LegoTowerServer
DRb Server to talk to the LegoUSB port

Constants:

 SCREEN: 0
 FILE:   1

Class methods:

 new

Instance methods:

 bye, close_usb, log_start, log_stop, old_send_msg, open_usb,
 recv_msg, send_msg, sender

C:\RubyConf2003> cd \atest
C:\atest>rdoc --ri benchtimer.rb

                  benchtimer.rb: c.....

Generating RI…
C:/RUBY/lib/ruby/1.8/rdoc/markup/simple_markup/to_flow.rb:92:in
accept_rule': undefined local variable or method size’ for
#SM::ToFlow:0x2c24c80 (NameError)
from
C:/RUBY/lib/ruby/1.8/rdoc/markup/simple_markup/fragments.rb:170:in accept' from C:/RUBY/lib/ruby/1.8/rdoc/markup/simple_markup/fragments.rb:165:in each’
from
C:/RUBY/lib/ruby/1.8/rdoc/markup/simple_markup/fragments.rb:165:in accept' from C:/RUBY/lib/ruby/1.8/rdoc/markup/simple_markup.rb:259:in convert’
from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:224:in
markup' from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:153:in generate_method_info’
from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:137:in
generate_class_info' from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:136:in each’
from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:136:in
generate_class_info' from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:90:in process_class’
from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:85:in
generate' from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:84:in each’
from C:/RUBY/lib/ruby/1.8/rdoc/generators/ri_generator.rb:84:in
generate' from C:/RUBY/lib/ruby/1.8/rdoc/rdoc.rb:210:in document’
from C:/RUBY/bin/rdoc.bat:70

C:\atest>

begin 666 benchtimer.rb
M(R ]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]
M/3T]/3T]/3T]/3T]/3T-“B,@(” @(" @(“!”(&4@;B!C(&@@5"!I(&T@92!R
M(“X@<B!B#0HC(#T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]
M/3T]/3T]/3T]/3T]/3T]/3T]/3T]/0T*(PT*(R!0<F]J96-T.B!L:6)R87)Y
M(”@=71I;&ET>0T*(R!697)S:6]N.B D4F5V:7-I;VXZ(“,R(“0-“B,@075T
M:&]R.B @)$%U=&AO<CH@<')O8F5R=&T@) T*(R!$871E.B @(” D1&%T93H@
M,C P,R\P,2\P,B D#0HC#0HC(#T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]
M/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/0T*(PT*(R!#;W!Y<FEG
M:‘0@&,I(#(P,#(L($UA<FL@4’)O8F5R=" H<‘)O8F5R=&U 86-M+F]R9RD-
M"B,@(" @(" @(" @(" @($%L;"!2:6=H=’,@4F5S97)V960-"B,-"B,@/3T]
M/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]
M/3T]/3T]/3T]#0HC($%B;W5T.@T(PT*(R!!(’-I;7!L92!T:6UE<B!F;W(@
M9&]I;F<@8F5N8VAM87)K(&-O;7!A<FES;VYS+@T*(PT*(R!%>&%M<&QE.@T*
M(PT*(R @8G0@/2!“96YC:%1I;65R+FYE=PT*(R @8G0N=&5S=%]B96=I;B@B
M8F]B(#$B0T(R @(R!D;R!B;V(@,2!S='5F9B N+BX-“B,@(&)T+G1E<W1?
M96YD*”)B;V(@,2(I#0HC(”!B=“YR97!O<G0@(R!P<FEN=”!T:&4@<F5P;W)T
M(“XN+@T*(PT*(R!296QE87-E9”!U;F1E<B!-250@3&EC96YS92 H<V5E($Q)
M0T5.4T4N='AT0T(PT*(R ]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]
M/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]/3T]#0H-“F-L87-S($)E;F-H5&EM
M97(-”@T*(”! 0’1I;65R(#T@2&%S:“YN97<-”@T*(”!D968@:6YI=&EA;&EZ
M90T*(" @($!L87-T7VQA8F5L(#T@;FEL(" @(" @(" @(" C(‘)E8V]R9"!F
M;W(@96%S>2!A8V-E<W,-“B @(”! <F5S=6QT<R @(" ]($AA<V@N;F5W(" @
M(" @(R!U<V5D(&EN(’!R;V-E<W-I;F<@<F5S=6QT<PT*#0H@(" @0$!T:6UE
M<BYC;&5A<B @(" @(" @(" @(" @(“,@;6%K92!S=7)E(&ET(&ES(&5M<'1Y
M#0H@(&5N9 T*#0H-“B @(R M+2TM+0T*(” C(&1O:70@+2T@<W1A<G0@=&AE
M('1I;65R(&9O<B!T:&4@<G5N#0H@(”,-“B @9&5F(&1O:70@&QA8F5L/6YI
M;“D-“B @(”!R86ES92 B>6]U(&YE960@82!L86)E;”$B(&EF(&QA8F5L+FYI
M;#-"@T(” @($! =&EM97);;&%B96Q=(#T@(B-[5&EM92YN;W<N=&]?9GTB
M#0H@(" @0&QA<W1?;&%B96P@/2!L86)E; T*#0H@(" @<F5T=7)N(‘1R=64-
M"B @96YD#0H-“B @(R M+2TM+0T*(” C(&1O;F4@+2T@<W1O<“!T:&4@=&EM
M97(@9F]R('1H92!R=6X-“B @(PT*(”!D968@9&]N92 H;&%B96P]0&QA<W1?
M;&%B96PI#0H@(” @<F%I<V4@(GEO=2!N965D(&$@;&%B96PA(B!I9B!L86)E
M;“YN:6P_#0H@(” @<F%I<V4@(F)A9"!L86)E;“$@“-[;&%B96Q]2(@:68@
M0$!T:6UE<EML86)E;%TN;FEL/PT#0H@(” @0$!T:6UE<EML86)E;%T@/#P@
M(CHC>U1I;64N;F]W+G1O7V9](@T(” @(’)E=‘5R;B!T<G5E#0H@(&5N9 T*
M#0H-“B @(R M+2TM+0T*(” C(’!R;V-E<W,@+2T@9V@=&AR;W5G:“!T:&4@
M=&EM97(@87)R87D@86YD(&9I;F0@=&AE(&1E;'1A<PT*(” C#0H@(&1E9B!P
M<F]C97-S#0H@(" @0’)E<W5L=‘,N8VQE87(-“@T*(” @($! =&EM97(N96%C
M:“![('QI=&5M? T*(” @(" @;&%B96P@/2!I=&5M6S!=#0H@(" @(“!T<W1A
M<G0L('1S=&]P(#T@:71E;5LQ72YS<&QI=”@O.B\I#0H@(" @(“!D96QT82 ]
M('1S=&]P+G1O7V8@+2!T<W1A<G0N=&]?9@T*#0H@(” @(“! <F5S=6QT<UML
M86)E;%T@/2!D96QT80T*(” @(‘T-“B @(”!R971U<FX@0’)E<W5L=’,-“B @
M96YD#0H-”@T*(" C(“TM+2TM#0H@(”,@<F5P;W)T(“TM('!R;V1U8V4@82!N
M:6-E;‘D@9F]R;6%T=&5D(’)E<&]R= T*(” C#0H@(&1E9B!R97!O<G0-“B @
M(”!P=71S(“)<;EQN(@T*(” @(‘!U=’,@(BTM+2TM+2TM+2TM+2TM+2TM+2TM
M+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM(@T*(" @(‘!U=’,@(D)E
M;F-H5&EM97(@4F5P;W)T.B(-“B @(”!P=71S(“(M+2TM+2TM+2TM+2TM+2TM
M+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2(-”@T*(" @(‘!R
M;V-E<W,N<V]R=“YE86-H('L@?&QA8F5L+”!D96QT87P-“B @(” @(’!R:6YT
M9B B)2TT,',@)3@N,F9S7&XB+"!L86)E;“P@9&5L=&$-“B @(”!]#0H-“B @
M(”!P=71S(”(M+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM+2TM

+2TM+2TM+2TM+2TM+2(-“B @96YD#0IE;F0-”@T*
`
end

3

When i run this in my ruby source dir I get the following error:

uehli@ueh-t ruby $ rdoc --ri *.c

                        array.c: Override []

/usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:364: warning: character
class has ]' without escape /usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:364:in find_override_comment’: premature end of regular expression:
/Document-method:\s.?\n((?>.?*/))/ (RegexpError)
from /usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:333:in
find_body' from /usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:305:in handle_method’
from /usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:256:in
do_methods' from /usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:248:in scan’
from /usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:248:in
do_methods' from /usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:142:in scan’
from /usr/local/lib/ruby/1.9/rdoc/rdoc.rb:159:in parse_files' from /usr/local/lib/ruby/1.9/rdoc/rdoc.rb:152:in each’
from /usr/local/lib/ruby/1.9/rdoc/rdoc.rb:152:in parse_files' from /usr/local/lib/ruby/1.9/rdoc/rdoc.rb:188:in document’
from /usr/local/bin/rdoc:63

···

On Sam, 2003-12-27 at 07:30, Dave Thomas wrote:

We’re in the middle of integrating RDoc/ri-style comments into the main
interpreter sources (we being Michael Granger and me, with help from Ed
Sinjiashvili). So far we’re maybe 60% complete, and it’s starting to
look pretty good. You can check our progress at

http://www.rubygarden.org/ruby?StillToDo

If you want to play with the results (and you’re on a Unix-based box)(*)

  • check out a copy of the latest Ruby from CVS.

  • build and install

  • in the main Ruby directory (the one containing object.c etc), type

    rdoc --ri *.c

uehli@ueh-t ruby $ ruby -v
ruby 1.9.0 (2003-12-27) [i686-linux]

  • then use ‘ri’ to browse the results

    ri Array
    ri Array.push

  • You can get prettier output by enabling formatting

    ri -f bs Array.select
    ri -f ansi MatchData

“-f bs” does formatting using overstrikes, and works with pagers such
as “more” and “less.” The “-f ansi” option uses ANSI escape sequences.
To make these work with the “less” pager, you need to tell it to allow
raw escape codes through. I run my version of less with the LESS
environment variable set as follows:

export LESS="-REX"

You can use RDoc as before to extract documentation from your own
classes (and from library classes). If you use the --ri option, this
documentation will then be accessible via ‘ri’.

Right now there are some holes, and I’ll be adding features and fixing
bugs over the next couple of weeks. I’m announcing this now to
encourage people to play, find issues, and come up with things to
improve. However, I’m not yet at the stage where I can deal with bugs
reports and the like. Please play with all this stuff, and in a week or
so I’ll announce a release candidate, at which point I’ll be soliciting
as much feedback as I can get.

Cheers

Dave

(*) Why Unix only? Because I haven’t even tried it on a Windows box
yet. It might work, but then again… I will try it at some point.

4

Excellent! Thanks for the report. I’d never tried running with warning
enabled (which is kinda stupid, I know). This should be fixed in the
latest CVS.

Cheers

Dave

···

On Dec 27, 2003, at 12:24, Thomas Uehlinger wrote:

When i run this in my ruby source dir I get the following error:

uehli@ueh-t ruby $ rdoc --ri *.c

                        array.c: Override []

/usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:364: warning: character
class has `]’ without escape

5

Yet another thing:
When I try to rdoc --ri the whole ruby source dir (which is probably
stupid), I get a seg fault:

Generating RI…
/usr/local/lib/ruby/1.9/yaml/rubytypes.rb:315: [BUG] Segmentation fault
ruby 1.9.0 (2003-12-28) [i686-linux]

Aborted

This would, of course, not so much be related to rdoc or ri, but to ruby
itself.
Just wanted to ask whether you can reproduce it.

···

On Sam, 2003-12-27 at 19:52, Dave Thomas wrote:

On Dec 27, 2003, at 12:24, Thomas Uehlinger wrote:

When i run this in my ruby source dir I get the following error:

uehli@ueh-t ruby $ rdoc --ri *.c

                        array.c: Override []

/usr/local/lib/ruby/1.9/rdoc/parsers/parse_c.rb:364: warning: character
class has `]’ without escape

Excellent! Thanks for the report. I’d never tried running with warning
enabled (which is kinda stupid, I know). This should be fixed in the
latest CVS.

Cheers

Dave

6

This would, of course, not so much be related to rdoc or ri, but to ruby
itself.

No, for me the problem is in syck.

Guy Decoux

7

This would, of course, not so much be related to rdoc or ri, but to ruby
itself.

No, for me the problem is in syck.

You’re right, I was just too lazy to check.
_why, are you listening?

– Thomas Uehlinger

···

On Son, 2003-12-28 at 15:34, ts wrote:

Guy Decoux