Forum: Ruby Ruby Manual

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
00e3a96684ab390a350b0271e98741d3?d=identicon&s=25 Nshbrown Nshbrown (nshb)
on 2006-05-31 15:22
(Received via mailing list)
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4299e35bacef054df40583da2d51edea?d=identicon&s=25 James Gray (bbazzarrakk)
on 2006-05-31 15:35
(Received via mailing list)
On 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
5c4e57ad9f066e56297a60b4a1daa1d3?d=identicon&s=25 Alexandru Popescu (Guest)
on 2006-05-31 15:44
(Received via mailing list)
Looks cool!

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

./alex
--
.w( the_mindstorm )p.
87e9a89c53ccf984db792113471c2171?d=identicon&s=25 Kroeger, Simon (ext) (Guest)
on 2006-05-31 16:15
(Received via mailing list)
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
Cb48ca5059faf7409a5ab3745a964696?d=identicon&s=25 unknown (Guest)
on 2006-05-31 16:15
(Received via mailing list)
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.030s

also the methods are throwing errors for me

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


regards.



-a
30e1c25a554f4af3d4d07127db13ffc8?d=identicon&s=25 Conor Hunt (conorh)
on 2006-06-01 06:14
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.030s
>
> also the methods are throwing errors for me
>
>    harp:~ > curl
> 'http://www.rubymanual.org/class/URI%3A%3AGeneric/%...
> 2>/dev/null|grep title
>      <title>Action Controller: Exception caught</title>
>
>
> regards.
>
>
>
> -a
567898c496278341be69087507d5ed24?d=identicon&s=25 Jeff Rose (Guest)
on 2006-06-01 13:27
(Received via mailing list)
Conor Hunt 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
30e1c25a554f4af3d4d07127db13ffc8?d=identicon&s=25 Conor Hunt (conorh)
on 2006-06-01 15:30
> 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
6ff7cc79a09836e7930763a9d8b6ba9a?d=identicon&s=25 Dominic Sisneros (Guest)
on 2006-06-01 19:48
(Received via mailing list)
What is the difference between this and http://ruby.outertrack.com/?  I
think we should consolidate

dominic
30e1c25a554f4af3d4d07127db13ffc8?d=identicon&s=25 Conor Hunt (conorh)
on 2006-06-01 19:59
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=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/
A9b6a93b860020caf9d2d1d58c32478f?d=identicon&s=25 Ross Bamford (Guest)
on 2006-06-01 20:39
(Received via mailing list)
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
> >
> > 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?
30e1c25a554f4af3d4d07127db13ffc8?d=identicon&s=25 Conor Hunt (conorh)
on 2006-06-01 20:53
> 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/Action...

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

--
Conor
Ff63c03fd68754adbadd2c6314646bef?d=identicon&s=25 Bill Guindon (agorilla)
on 2006-06-01 20:55
(Received via mailing list)
On 6/1/06, Ross Bamford <rossrt@roscopeco.co.uk> 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.
Fc784eadb3b54531fdc3d2053db6f83f?d=identicon&s=25 Mat Schaffer (Guest)
on 2006-06-01 21:28
(Received via mailing list)
On Jun 1, 2006, at 2:53 PM, Conor Hunt 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
Bb6ecee0238ef2461bef3416722b35c5?d=identicon&s=25 pat eyler (Guest)
on 2006-06-01 21:57
(Received via mailing list)
On 6/1/06, Conor Hunt <conor.hunt+rails@gmail.com> 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.
A9b6a93b860020caf9d2d1d58c32478f?d=identicon&s=25 Ross Bamford (Guest)
on 2006-06-02 02:19
(Received via mailing list)
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 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.
F5b3c1ebfb2e9fc5f67bb48b119f6054?d=identicon&s=25 Randy Kramer (Guest)
on 2006-06-02 20:56
(Received via mailing list)
> 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.

(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
This topic is locked and can not be replied to.