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
On May 31, 2006, at 8:22 AM, Nathaniel B. 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.
String is missing quite a few methods:
http://www.rubymanual.org/class/String
Where is rjust() for example?
James Edward G. II
Looks cool!
Not sure if it is only me, but it looks very slow in my case.
./alex
.w( the_mindstorm )p.
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
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
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
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.
–
Conor
What is the difference between this and http://ruby.outertrack.com/? I
think we should consolidate
dominic
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.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
Action Controller: Exception caughtregards.
-a
Dominic S. 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 - http://www.conorhunt.com/techblog/
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 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
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 6/1/06, Ross B. [email protected] 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.
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:
- Organization by logical topic that don’t directly correlate to a
class (e.g., Database Security) - 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 6/1/06, Conor H. [email protected] 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.
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 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.
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)
-
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. -
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. -
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. -
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 -
CSS.
Easy to create user selectable themes for the site because everything is
database driven.
–
Conor
On 6/1/06, Conor H. [email protected] 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.