Ruby Manual


#1

I just launched the all new Ruby Manual for 1.8.4 at:

www.rubymanual.org

This is a fully searchable Ruby Manual providing the ability to add
comments
using the Rannotate system.

-Nb

Nathaniel S. H. Brown                        http://nshb.net

#2

On May 31, 2006, at 8:22 AM, Nathaniel B. wrote:

I just launched the all new Ruby Manual for 1.8.4 at:

www.rubymanual.org

This is a fully searchable Ruby Manual providing the ability to add
comments
using the Rannotate system.

String is missing quite a few methods:

http://www.rubymanual.org/class/String

Where is rjust() for example?

James Edward G. II


#3

Looks cool!

Not sure if it is only me, but it looks very slow in my case.

./alex

.w( the_mindstorm )p.


#4

just a wild guess: only the .rb files are parsed.


Class String:

Files this class is defined in

File: src/ruby-1.8.4/bigdecimal/util.rb
File: src/ruby-1.8.4/jcode.rb
File: src/ruby-1.8.4/kconv.rb
File: src/ruby-1.8.4/mkmf.rb
File: src/ruby-1.8.4/yaml/rubytypes.rb

cheers

Simon


#5

On Wed, 31 May 2006, Nathaniel B. wrote:

Nathaniel S. H. Brown http://nshb.net

is it running in testing mode?

harp:~ > time curl
http://www.rubymanual.org/list/methods/ruby/1.8.4’ >/dev/null 2>&1
real 0m13.765s
user 0m0.020s
sys 0m0.030s

also the methods are throwing errors for me

harp:~ > curl
http://www.rubymanual.org/class/URI%3A%3AGeneric/%2B/1.8.4
2>/dev/null|grep title
Action Controller: Exception caught

regards.

-a


#6

Conor H. wrote:

I have implemented some RDoc patches and major code changes to Rannotate
to fix the various issues and I will be releasing this soon to
http://ruby.outertrack.com.


Conor - http://www.conorhunt.com/techblog/

The idea here is cool, even if there are still some kinks to work out.
I have a few questions/ideas for you though.

It would be helpful it rubymanual.org had a link to rannotate on the
page. As people start to use the site they will probably be interested
in the system as well…

It looks like in the rannotated ruby documentation on outertrack.com
there is a lot more info for the classes implemented in C. What’s the
current support for doing this?

How does an admin use the notes? It would be great if the tool could
output a patch or a series of patches that could easily be read &
applied in an editor (i.e. vim :-). With that in mind, it could be
helpful to use rannotate with logins so notes from developers can be
automatically applied, while notes from the world could be looked at
first.

I’m going to try to get it setup in the next few days. Thanks for the
great stuff.

-Jeff


#7

It would be helpful it rubymanual.org had a link to rannotate on the
page. As people start to use the site they will probably be interested
in the system as well…

I don’t have any access to railsmanual, that is something that Nathaniel
setup on his own. I found out through someone else about his setup. I
asked him to put back the link to Rannotate, but I haven’t got a reply
on that.

It looks like in the rannotated ruby documentation on outertrack.com
there is a lot more info for the classes implemented in C. What’s the
current support for doing this?

RDoc can index these classes like anything else.

How does an admin use the notes? It would be great if the tool could
output a patch or a series of patches that could easily be read &
applied in an editor (i.e. vim :-). With that in mind, it could be
helpful to use rannotate with logins so notes from developers can be
automatically applied, while notes from the world could be looked at
first.

That is exactly my goal! :slight_smile: I’m working towards allowing moderators to
edit the documentation directly on the site and produce an diff file
that can be submitted to the code repository.

cheers.


Conor


#8

What is the difference between this and http://ruby.outertrack.com/? I
think we should consolidate

dominic


#9

Nathaniel is using my software Rannotate
(http://rubyforge.rannotate.org) to run the site. I had previously
released the same documentation at http://ruby.outertrack.com.

There are unfortunately a few major issues with documenting Ruby using
Rannotate right now. One issue is mixins. For example with String you
will see a to_yaml() method even though that method is only available if
you do “require ‘yaml’”. This is a major issue because you will also
find that mixins that override String methods (jcode etc.) will wipe out
the String RDoc with their RDoc.

I have implemented some RDoc patches and major code changes to Rannotate
to fix the various issues and I will be releasing this soon to
http://ruby.outertrack.com.


Conor - http://www.conorhunt.com/techblog/

unknown wrote:

On Wed, 31 May 2006, Nathaniel B. wrote:

Nathaniel S. H. Brown� � �� ��� �� �� �� �� �http://nshb.net

is it running in testing mode?

harp:~ > time curl
http://www.rubymanual.org/list/methods/ruby/1.8.4’ >/dev/null 2>&1
real 0m13.765s
user 0m0.020s
sys 0m0.030s

also the methods are throwing errors for me

harp:~ > curl
http://www.rubymanual.org/class/URI%3A%3AGeneric/%2B/1.8.4
2>/dev/null|grep title
Action Controller: Exception caught

regards.

-a


#10

Dominic S. wrote:

What is the difference between this and http://ruby.outertrack.com/? I
think we should consolidate

dominic

There is no differece and this is something that Nathaniel and I had a
back and forth over via email. I disagree with it strongly. I’ve posted
about it on my blog at http://www.conorhunt.com/techblog/?p=8

Unfortunately Nathaniel is not willing to give access to his site and
seems to want to own it. Which I disagree with for a collaberative
documentation site. I believe the site should be community owned and
managed. Otherwise one person can decide what links to put in the
sidebar, what comments are ok, should there be advertising etc. Also for
me I would like access to the logs and performance data so I can use
that information to improve Rannotate.

I’m trying to figure out what to do about the situation, any opinions
welcomed…


Conor - http://www.conorhunt.com/techblog/


#11

On Fri, 2006-06-02 at 02:59 +0900, Conor H. wrote:

Dominic S. wrote:

What is the difference between this and http://ruby.outertrack.com/? I
think we should consolidate

dominic

There is no differece and this is something that Nathaniel and I had a
back and forth over via email. I disagree with it strongly. I’ve posted
about it on my blog at http://www.conorhunt.com/techblog/?p=8

I also strongly disagree with this kind of fragmentation - it’s just not
what we need. It may be my ignorance (Not up on rannotate yet) but I
can’t see why we need either, given that ruby-doc.org is strong, getting
stronger, and has a wiki for comments and so forth. Surely it’s best to
have a single documentation place, and the curmudgeon in me is always
more comfortable with an org domain…

Nathaniel: Would you elaborate on why you started this project, and why
you feel it’s needed?


#12

On 6/1/06, Ross B. removed_email_address@domain.invalid wrote:

I also strongly disagree with this kind of fragmentation - it’s just not
what we need. It may be my ignorance (Not up on rannotate yet) but I
can’t see why we need either, given that ruby-doc.org is strong, getting
stronger, and has a wiki for comments and so forth. Surely it’s best to
have a single documentation place, and the curmudgeon in me is always
more comfortable with an org domain…

+1
Conor mentions in his blog post…
“The permanent documentation sites should be community controlled, not
owned by one person.
Theoretically this home should be api.rubyonrails.org and ruby-doc, I
have been working hard (many many hours) to make the software
acceptable to the maintainers of those sites.”

I couldn’t agree more. I think you (Conor) should keep working
towards that goal. Once it’s achieved, Nathaniel’s sites will fade
off into obscurity.


#13

On Jun 1, 2006, at 2:53 PM, Conor H. wrote:

documentation in a database (in a very flexible format)

Just to offer my $.02 as someone who came from PHP to Ruby about 2
months ago.
ruby-doc.org is a nice site with good content, but the organization
is a bit tricky for beginners. I feel the same holds true for other
ruby sites that rely heavily on rdoc.

The PHP documentation is great for two reasons:

  1. Organization by logical topic that don’t directly correlate to a
    class (e.g., Database Security)
  2. User comments on all pages

If we could have both of those things and house them at ruby-doc.org
I think we’d lower the barrier to entry considerably. Building this
as a scripted solution would be tricky though. A really good
documentation system would have to incorporate both the “Why Ruby”
and “Core API” sections or ruby-doc.org into one searchable content
base.

-Mat


#14

On 6/1/06, Conor H. removed_email_address@domain.invalid wrote:

welcomed…
Sadly, this is not the first time there have been conflicts with
Nathaniel
over this kind of thing. They’ve been brought to my attention before.
In
this case, I’d already blogged about his site when I saw this thread –
I’ve now updated that post to point to http://ruby.outertrack.com/ as
well.

Conor, I wish you the best in resolving this. I’m not sure I have any
specific advice for you though.


#15

On Fri, 2006-06-02 at 03:53 +0900, Conor H. wrote:

I also strongly disagree with this kind of fragmentation - it’s just not
what we need. It may be my ignorance (Not up on rannotate yet) but I
can’t see why we need either, given that ruby-doc.org is strong, getting
stronger, and has a wiki for comments and so forth. Surely it’s best to

I can offer an opinion on why I think Rannotate helps improve things,
but generally they all because Rannotate has put all of the
documentation in a database (in a very flexible format)

I had a better look, and I agree that Rannotate has some promising
features, and I’m pretty impressed by the way it works too - I think it
could have a lot to offer as part of ruby-doc.org. I’m still opposed to
having multiple sites purporting to be The ruby manual /
documentation, as with the new site.


#16

I also strongly disagree with this kind of fragmentation - it’s just not
what we need. It may be my ignorance (Not up on rannotate yet) but I
can’t see why we need either, given that ruby-doc.org is strong, getting
stronger, and has a wiki for comments and so forth. Surely it’s best to

I can offer an opinion on why I think Rannotate helps improve things,
but generally they all because Rannotate has put all of the
documentation in a database (in a very flexible format)

  1. Searching:
    Rannotate can search at a very detailed level because everything is in
    the database. Try it out. The search can be also be very easily made
    more comprehensive.

  2. Inline Annotations:
    The annotations are inline with the documentation, you don’t have to go
    to a separate page. You can see at a single class which methods have
    annotations.

  3. Getting documentation back into the core:
    Maintainers will be able to click on the documentation on the site, edit
    the RDoc (perhaps incorporating user comments) and then generate a diff
    that can be directly applied to the source code repository.

  4. Multiple versions of libraries:
    You can host multiple versions of a library. Perhaps some people are
    working with Ruby 1.8.4 and some with Ruby 1.8.3. It doesn’t matter,
    Rannotate will store both versions of the library, let you view either,
    and can even show you the differences between the two. Check this out on
    the rails site. Shows you what changed between versions of Rails for a
    single class:
    http://rails.outertrack.com/history/RaClass/ActionController::Base

  5. CSS.
    Easy to create user selectable themes for the site because everything is
    database driven.


Conor


#17

On 6/1/06, Conor H. removed_email_address@domain.invalid wrote:

Unfortunately Nathaniel is not willing to give access to his site and
seems to want to own it. Which I disagree with for a collaberative
documentation site. I believe the site should be community owned and
managed. Otherwise one person can decide what links to put in the
sidebar, what comments are ok, should there be advertising etc. Also for
me I would like access to the logs and performance data so I can use
that information to improve Rannotate.

(Aside: Sorry–I think I have the attribution right, but the threading
may be
off as I’m actually replying to a later post than I meant to.)

I’m confused, is Rannotate a program/application or data (text).

If a program/application, and assuming the license allows it, anyone
should be
able to use it for any web site.

If concerned about the data (and especially contributions by other than
the
“owner” of the website), what is the site policy on such contributions.

On WikiLearn (at least for the present), all such contributions are
owned by
the contributor. If there is no policy stated, I’m not 100% sure, but
I
think
copyrights (etc.) would still belong to the contributing author.

Randy K.