I just launched the all new Ruby Manual for 1.8.4 at:
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
String is missing quite a few methods:
http://www.rubymanual.org/class/String
Where is rjust() for example?
James Edward Gray II
On May 31, 2006, at 8:22 AM, Nathaniel Brown wrote:
I just launched the all new Ruby Manual for 1.8.4 at:
This is a fully searchable Ruby Manual providing the ability to add comments
using the Rannotate system.
Looks cool!
Not sure if it is only me, but it looks very slow in my case.
./alex
--
.w( the_mindstorm )p.
On 5/31/06, Nathaniel Brown <nshb@inimit.com> wrote:
I just launched the all new Ruby Manual for 1.8.4 at:
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
<title>Action Controller: Exception caught</title>
regards.
-a
On Wed, 31 May 2006, Nathaniel Brown wrote:
I just launched the all new Ruby Manual for 1.8.4 at:
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
be kind whenever possible... it is always possible.
- h.h. the 14th dali lama
What is the difference between this and http://ruby.outertrack.com/? I
think we should consolidate
dominic
On 5/31/06, Nathaniel Brown <nshb@inimit.com> wrote:
I just launched the all new Ruby Manual for 1.8.4 at:
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
-----Original Message-----
From: James Edward Gray II [mailto:james@grayproductions.net]
Sent: Wednesday, May 31, 2006 3:35 PM
To: ruby-talk ML
Subject: Re: [ANN] Ruby ManualOn May 31, 2006, at 8:22 AM, Nathaniel Brown 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 Gray II
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 Brown 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.030salso 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
<title>Action Controller: Exception caught</title>regards.
-a
--
Posted via http://www.ruby-forum.com/\.
Dominic Sisneros wrote:
What is the difference between this and http://ruby.outertrack.com/? I
think we should consolidatedominic
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 Hunt wrote:
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/
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
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?
On Fri, 2006-06-02 at 02:59 +0900, Conor Hunt wrote:
Dominic Sisneros wrote:
> What is the difference between this and http://ruby.outertrack.com/? I
> think we should consolidate
>
> dominicThere 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
--
Ross Bamford - rosco@roscopeco.REMOVE.co.uk
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...
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.
On 6/1/06, Conor Hunt <conor.hunt+rails@gmail.com> wrote:
--
Conor - http://www.conorhunt.com/techblog/
--
thanks,
-pate
-------------------------
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! 
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.
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.
> Dominic Sisneros 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=8I 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.
On 6/1/06, Ross Bamford <rossrt@roscopeco.co.uk> wrote:
On Fri, 2006-06-02 at 02:59 +0900, Conor Hunt wrote:
Nathaniel: Would you elaborate on why you started this project, and why
you feel it's needed?--
Ross Bamford - rosco@roscopeco.REMOVE.co.uk
--
Bill Guindon (aka aGorilla)
The best answer to most questions is "it depends".
(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 Kramer
On 6/1/06, Conor Hunt <conor.hunt+rails@gmail.com> 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.
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
On Jun 1, 2006, at 2:53 PM, Conor Hunt 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 toI 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.
On Fri, 2006-06-02 at 03:53 +0900, Conor Hunt 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 toI 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)
--
Ross Bamford - rosco@roscopeco.REMOVE.co.uk