Rails - Nov 2005 - Re: Rannotate v2 - Annotated Rails API documentation withsearch

> One point to mention is I would like to see a convergence of both Rails and
> Ruby (Core and Standard Library) documentation in one site...
Adding the Ruby core library should be simple I believe. It has RDoc
documentation available and as soon as I figure out how to generate
that rdoc I will add it to my site. Anyone know what packages RDoc
needs to be pointed at?
> One key point for a usability standpoint would be that of removing the
> frames (I am sure you are already on this), and providing the same
> method/function per page that PHP has.
I like the single frame myself, but I''ll put a button in there to have
a frame/no frame switch for you :) Each method has it''s own [notes]
link now. So I was thinking that would be good enough. Not only that,
but every section of a class/file/module has it''s own notes.
> Another point of recommendation is that of the URL search, whereby I can
> type www.php.net/date and it will bring me up to the date functionality
page
> with comments.
The search functionality you are asking for exists in two ways:
http://rails.outertrack.com/doc/link/classes/ActionController::Base
will bring you directly to the ActionController::Base class, or,
http://rails.outertrack.com/doc/search/ActionController::Base will
search for it.

I take your suggestion though and this will be improved using routes
(it''s a one line code change) so that it is even simpler:
http://rails.outertrack.com/ActionController::Base will bring you
directly to the page for that class if there is only one match for the
search, otherwise it will show you the search results.

Thanks for the feedback Nathan!

--
Conor

> > One point to mention is I would like to see a convergence of both 
> > Rails and Ruby (Core and Standard Library) documentation in 
> one site...
> 
> Adding the Ruby core library should be simple I believe. It 
> has RDoc documentation available and as soon as I figure out 
> how to generate that RDoc I will add it to my site. Anyone 
> know what packages RDoc needs to be pointed at?
> 
Here is a list of the two URL''s, not sure where RDoc would need to be
pointed at though:
http://www.ruby-doc.org/core/
http://www.ruby-doc.org/stdlib/
> > One key point for a usability standpoint would be that of 
> removing the 
> > frames (I am sure you are already on this), and providing the same 
> > method/function per page that PHP has.
> 
> I like the single frame myself, but I''ll put a button in 
> there to have a frame/no frame switch for you :) Each method 
> has it''s own [notes] link now. So I was thinking that would 
> be good enough. Not only that, but every section of a 
> class/file/module has it''s own notes.
> 
One of the primary reasons I have for having a specific page for each of the
methods is that when people see an empty comment box, thy are almost
possessed to put something in it :) So having a whole bunch of empty comment
boxes below the method description with source code example would encourage
more comments.
> > Another point of recommendation is that of the URL search, 
> whereby I 
> > can type www.php.net/date and it will bring me up to the date 
> > functionality page with comments.
> 
> The search functionality you are asking for exists in two ways:
> http://rails.outertrack.com/doc/link/classes/ActionController::Base
> will bring you directly to the ActionController::Base class, 
> or, 
> http://rails.outertrack.com/doc/search/ActionController::Base 
> will search for it.
> 
> I take your suggestion though and this will be improved using 
> routes (it''s a one line code change) so that it is even simpler:
> http://rails.outertrack.com/ActionController::Base will bring 
> you directly to the page for that class if there is only one 
> match for the search, otherwise it will show you the search results.
This would work, but even simpler would be
http://rails.outertrack.com/actioncontroller and it me a list of all the sub
modules below it, and if I went for something like
http://rails.outertrack.com/actioncontroller_base it would understand that
the _ is a logical separator for the sub-module.

Not sure about this is, but I don''t think the :''s themselves
untranslated
are URI compliant based on the spec, so abstracting them out would be better
for search engines and such who will likely be eager to index the comments.

Another thing that gets me is the overview pages, how the method list is
horizontal instead of vertical like the PHP docs. I find it very difficult
to read through the RDoc''s method lists as they are only space
separated.
Having an overview page of the entire modules methods in vertical list form
would be most useful as far as readability goes.

Warmest regards,
Nathan.

--------------------------------------------------------------
Nathaniel S. H. Brown                 Toll Free 1.877.4.INIMIT
Inimit Innovations                        Phone   604.724.6624
www.inimit.com                              Fax   604.444.9942

This URL contains the core libraries API for 1.8.3 in rannotate format.

http://ruby.outertrack.com/

I generated it by running rdoc in the ruby directory. There were
.documentation RDoc files already there, I modified them a bit so that
more extensive documentation is generated.
> This would work, but even simpler would be
> http://rails.outertrack.com/actioncontroller and it me a list of all the
sub
> modules below it, and if I went for something like
> http://rails.outertrack.com/actioncontroller_base it would understand that
> the _ is a logical separator for the sub-module.
I''ll have a look at this. I might just stick with the way I have
because searching for actioncontroller will return all the submodules
right now, and going to /actioncontroller::base will work too (it
might not be URI compliant but the browsers translate it fine.)
> Not sure about this is, but I don''t think the :''s
themselves untranslated
> are URI compliant based on the spec, so abstracting them out would be
better
> for search engines and such who will likely be eager to index the comments.
No idea how search engines handle it. Browsers handle it fine by doing
the translation themselves. Do search engines do the same thing?
> Another thing that gets me is the overview pages, how the method list is
> horizontal instead of vertical like the PHP docs. I find it very difficult
> to read through the RDoc''s method lists as they are only space
separated.
> Having an overview page of the entire modules methods in vertical list form
> would be most useful as far as readability goes.
Can you show me an example of this?

--
Conor

> This URL contains the core libraries API for 1.8.3 in 
> rannotate format.
> 
> http://ruby.outertrack.com/
> 
> I generated it by running rdoc in the ruby directory. There 
> were .documentation RDoc files already there, I modified them 
> a bit so that more extensive documentation is generated.
> 
This is excellent. I was more referring to have a
rubyandrails.outertrack.com that combines both ruby.outertrack.com and
rails.outertrack.com into one single resource so I don''t need to switch
between the two.
> > This would work, but even simpler would be 
> > http://rails.outertrack.com/actioncontroller and it me a 
> list of all 
> > the sub modules below it, and if I went for something like 
> > http://rails.outertrack.com/actioncontroller_base it would 
> understand 
> > that the _ is a logical separator for the sub-module.
> 
> I''ll have a look at this. I might just stick with the way I 
> have because searching for actioncontroller will return all 
> the submodules right now, and going to 
> /actioncontroller::base will work too (it might not be URI 
> compliant but the browsers translate it fine.)
> 
> > Not sure about this is, but I don''t think the :''s
themselves
> > untranslated are URI compliant based on the spec, so 
> abstracting them 
> > out would be better for search engines and such who will 
> likely be eager to index the comments.
> 
> No idea how search engines handle it. Browsers handle it fine 
> by doing the translation themselves. Do search engines do the 
> same thing?
> 
I am not an expert at the internals of search engines, but when I look at
the URL:
http://rails.outertrack.com/doc/modules/ActionController%3A%3ACaching%3A%3AF
ragments
http://api.rubyonrails.com/classes/ActionController/Caching/Fragments.html

The second is a lot more likely to be index more effectively by search
engines as it doesn''t contain any special characters. As you probably
know,
XSS uses such tactics as encoding the <script> tag into the URL for
variables to parse and insert into the page, where people can grab the
cookies from unsuspecting users. So based on that, I would have to go with
the fact that without it, would be much better.

Removing the frames will also greatly increase the search engine
optimization. In addition to using a .html extension (even if its dynamic)
as search engines prefer to index static pages.
> > Another thing that gets me is the overview pages, how the 
> method list 
> > is horizontal instead of vertical like the PHP docs. I find it very 
> > difficult to read through the RDoc''s method lists as they 
> are only space separated.
> > Having an overview page of the entire modules methods in 
> vertical list 
> > form would be most useful as far as readability goes.
> 
> Can you show me an example of this?
The guys working on RDoc must have known I didn''t like it horizontal
list :)
The latest version is fixed now and has a vertical list style. Just checked
it not even two days ago and it was horizontal, so this is a mute point now.

Also, any word on getting this into the api.rubyonrails.com ? Have a hard
time remembering your outertrack.com domain ;)

Warmest regards,
Nathan.

--------------------------------------------------------------
Nathaniel S. H. Brown                 Toll Free 1.877.4.INIMIT
Inimit Innovations                        Phone   604.724.6624
www.inimit.com                              Fax   604.444.9942

I like the other ideas, but I would suggest not combining rails and
ruby into one huge annotated API--Or at least make it very clear what
the dividing line between the two areas is, perhaps with a different
background color or something.  I think it''s important for people who
are new to know what functionality is rails-specific and what is
general to all ruby.

Carl

On 11/17/05, Nathaniel S. H. Brown
<nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org>
wrote:
> This is excellent. I was more referring to have a
> rubyandrails.outertrack.com that combines both ruby.outertrack.com and
> rails.outertrack.com into one single resource so I don''t need to
switch
> between the two.

1 (one) vote from me for it to replace http://api.rubyonrails.org/ when
tested as stable...

On 11/17/05, Carl Youngblood
<carl-MJzSGySFh6ZUfOvSQQQpYw@public.gmane.org>
wrote:
>
> I like the other ideas, but I would suggest not combining rails and
> ruby into one huge annotated API--Or at least make it very clear what
> the dividing line between the two areas is, perhaps with a different
> background color or something. I think it''s important for people
who
> are new to know what functionality is rails-specific and what is
> general to all ruby.
>
> Carl
>
> On 11/17/05, Nathaniel S. H. Brown
<nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org> wrote:
> > This is excellent. I was more referring to have a
> > rubyandrails.outertrack.com <http://rubyandrails.outertrack.com>
that
> combines both ruby.outertrack.com <http://ruby.outertrack.com> and
> > rails.outertrack.com <http://rails.outertrack.com> into one
single
> resource so I don''t need to switch
> > between the two.
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>


--
First they laugh at you, then they ignore you, then they fight you.
Then you win.
-- Mahatma Karamchand Gandhi


_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

Thanks Leon, I''ve sent an email to David Hansson, so we''ll see
what he
has to say.

I need lots of bug testing on different platforms, so if you have some
time please add notes, browse around, try the search and see what bugs
you can find.

Thanks.

--
Conor

On 11/17/05, Leon Leslie
<leonleslie-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> 1 (one) vote from me for it to replace http://api.rubyonrails.org/ when
> tested as stable...
>
>
> On 11/17/05, Carl Youngblood
<carl-MJzSGySFh6ZUfOvSQQQpYw@public.gmane.org> wrote:
> > I like the other ideas, but I would suggest not combining rails and
> > ruby into one huge annotated API--Or at least make it very clear what
> > the dividing line between the two areas is, perhaps with a different
> > background color or something.  I think it''s important for
people who
> > are new to know what functionality is rails-specific and what is
> > general to all ruby.
> >
> > Carl
> >
> > On 11/17/05, Nathaniel S. H. Brown
<nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org> wrote:
> > > This is excellent. I was more referring to have a
> > > rubyandrails.outertrack.com that combines both
ruby.outertrack.com and
> > > rails.outertrack.com into one single resource so I don''t
need to switch
> > > between the two.
> > _______________________________________________
> > Rails mailing list
> > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > http://lists.rubyonrails.org/mailman/listinfo/rails
> >
>
>
>
> --
> First they laugh at you, then they ignore you, then they fight you.
> Then you win.
> -- Mahatma Karamchand Gandhi
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>
>
>

I agree.  I think this is a great tool.  I do agree that it would be
cool to offer a non-frames version as well, but all in good time. 
Thanks for all your efforts with this Conor.  It is very useful.  The
search feature is really cool and quite snappy.

On 11/17/05, Leon Leslie
<leonleslie-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> 1 (one) vote from me for it to replace http://api.rubyonrails.org/ when
tested as stable...

>>One key point for a usability standpoint would be that of removing the
>>frames (I am sure you are already on this), and providing the same
>>method/function per page that PHP has.
> I like the single frame myself, but I''ll put a button in there to
have
> a frame/no frame switch for you :) Each method has it''s own
[notes]
> link now. So I was thinking that would be good enough. Not only that,
> but every section of a class/file/module has it''s own notes.
Just like the other posters, I like your annotated documentation system
a lot. As a point of feedback, navigation could use a little more care.
Maybe tinkering with the CSS would make the pages look and feel less
rough (e.g. heading font sizes appear too big, to my eye at least).
Php''s documentaton site could act as a role model here. The search
facility will be the most-used function of the site, so that needs extra
attention - it''s quite nice already though.

Please consider also: Having a framed version, even conditionally, will
result in isolated content frames (without the corresponding menu)
ending up in google. Even though frames make some thing easier, they''re
mostly harmful.

Thanks!
Paulus

Probably you are using it under a platform that I have not tested yet.
Unfortunately I''m not a designer (at all). I''ll do the best I
can in
the next release to make the CSS look similar under different
platforms though.

If anyone out there is a designer and has some CSS skills it would be
great if you had a few hours and could take a look at the site and
improve the CSS.

Isolated content frames are a problem, although there can easily be a
link to show the index frame if it is missing. I''m not sure if it is a
good idea to display the huge list of files, classes or methods for
each page. I think without frames I''d probably only show
classes/modules in a collapsable hierarchy and allow you to search the
other types.

--
Conor

On 11/17/05, Paulus Esterhazy <pesterhazy-hi6Y0CQ0nG0@public.gmane.org>
wrote:
> >>One key point for a usability standpoint would be that of removing
the
> >>frames (I am sure you are already on this), and providing the same
> >>method/function per page that PHP has.
> > I like the single frame myself, but I''ll put a button in
there to have
> > a frame/no frame switch for you :) Each method has it''s own
[notes]
> > link now. So I was thinking that would be good enough. Not only that,
> > but every section of a class/file/module has it''s own notes.
>
> Just like the other posters, I like your annotated documentation system
> a lot. As a point of feedback, navigation could use a little more care.
> Maybe tinkering with the CSS would make the pages look and feel less
> rough (e.g. heading font sizes appear too big, to my eye at least).
> Php''s documentaton site could act as a role model here. The search
> facility will be the most-used function of the site, so that needs extra
> attention - it''s quite nice already though.
>
> Please consider also: Having a framed version, even conditionally, will
> result in isolated content frames (without the corresponding menu)
> ending up in google. Even though frames make some thing easier,
they''re
> mostly harmful.
>
> Thanks!
> Paulus
>
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>

Hey Conor,

When you get the no-frames version up, I will take a peek and come up with a
cool interface for the doc system. Be happy to help make it look a little
more appealing and user friendly :)

Warmest regards,
Nathan.

--------------------------------------------------------------
Nathaniel S. H. Brown                 Toll Free 1.877.4.INIMIT
Inimit Innovations                        Phone   604.724.6624
www.inimit.com                              Fax   604.444.9942
 
> -----Original Message-----
> From: rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org 
> [mailto:rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org] On
Behalf Of Conor Hunt
> Sent: November 17, 2005 3:30 PM
> To: rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> Subject: Re: [Rails] Re: [ANN] Rannotate v2 - Annotated Rails 
> APIdocumentation withsearch
> 
> Probably you are using it under a platform that I have not tested yet.
> Unfortunately I''m not a designer (at all). I''ll do the
best I
> can in the next release to make the CSS look similar under 
> different platforms though.
> 
> If anyone out there is a designer and has some CSS skills it 
> would be great if you had a few hours and could take a look 
> at the site and improve the CSS.
> 
> Isolated content frames are a problem, although there can 
> easily be a link to show the index frame if it is missing. 
> I''m not sure if it is a good idea to display the huge list of 
> files, classes or methods for each page. I think without 
> frames I''d probably only show classes/modules in a 
> collapsable hierarchy and allow you to search the other types.
> 
> --
> Conor
> 
> On 11/17/05, Paulus Esterhazy
<pesterhazy-hi6Y0CQ0nG0@public.gmane.org> wrote:
> > >>One key point for a usability standpoint would be that of 
> removing 
> > >>the frames (I am sure you are already on this), and providing
the
> > >>same method/function per page that PHP has.
> > > I like the single frame myself, but I''ll put a button in
there to
> > > have a frame/no frame switch for you :) Each method has
it''s own
> > > [notes] link now. So I was thinking that would be good 
> enough. Not 
> > > only that, but every section of a class/file/module has 
> it''s own notes.
> >
> > Just like the other posters, I like your annotated documentation 
> > system a lot. As a point of feedback, navigation could use 
> a little more care.
> > Maybe tinkering with the CSS would make the pages look and 
> feel less 
> > rough (e.g. heading font sizes appear too big, to my eye at least).
> > Php''s documentaton site could act as a role model here. The
search
> > facility will be the most-used function of the site, so that needs 
> > extra attention - it''s quite nice already though.
> >
> > Please consider also: Having a framed version, even conditionally, 
> > will result in isolated content frames (without the corresponding 
> > menu) ending up in google. Even though frames make some 
> thing easier, 
> > they''re mostly harmful.
> >
> > Thanks!
> > Paulus
> >
> > _______________________________________________
> > Rails mailing list
> > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > http://lists.rubyonrails.org/mailman/listinfo/rails
> >
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>

A nice alternative to frames would be to use a scrollable DIV. The problem
with that and the main reason I think frames were used is because that long
list has to be reloaded on every page request, making the page size much
larger than it needs to be. I don''t mind the frames, as long as each
individual page can still be indexed and searched by google easily. If a
user happens to come upon the page outside of frames, the page could detect
this and refresh the page inside frames again. I think this is what the MSDN
site does.

Just curious, is all that information stored in a database somewhere? If so,
why not make the search fields into an auto-complete text field using the
javascript helpers in rails. I think its a one liner.

Great resource nonetheless.. I use this as a replacement to the regular
Rails/Ruby API sites now.


On 11/18/05, Nathaniel S. H. Brown
<nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org>
wrote:
>
> Hey Conor,
>
> When you get the no-frames version up, I will take a peek and come up with
> a
> cool interface for the doc system. Be happy to help make it look a little
> more appealing and user friendly :)
>
> Warmest regards,
> Nathan.
>
> --------------------------------------------------------------
> Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT
> Inimit Innovations Phone 604.724.6624
> www.inimit.com <http://www.inimit.com> Fax 604.444.9942
>
>
> > -----Original Message-----
> > From: rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> >
[mailto:rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org] On
Behalf Of Conor Hunt
> > Sent: November 17, 2005 3:30 PM
> > To: rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > Subject: Re: [Rails] Re: [ANN] Rannotate v2 - Annotated Rails
> > APIdocumentation withsearch
> >
> > Probably you are using it under a platform that I have not tested yet.
> > Unfortunately I''m not a designer (at all). I''ll do
the best I
> > can in the next release to make the CSS look similar under
> > different platforms though.
> >
> > If anyone out there is a designer and has some CSS skills it
> > would be great if you had a few hours and could take a look
> > at the site and improve the CSS.
> >
> > Isolated content frames are a problem, although there can
> > easily be a link to show the index frame if it is missing.
> > I''m not sure if it is a good idea to display the huge list of
> > files, classes or methods for each page. I think without
> > frames I''d probably only show classes/modules in a
> > collapsable hierarchy and allow you to search the other types.
> >
> > --
> > Conor
> >
> > On 11/17/05, Paulus Esterhazy
<pesterhazy-hi6Y0CQ0nG0@public.gmane.org> wrote:
> > > >>One key point for a usability standpoint would be that of
> > removing
> > > >>the frames (I am sure you are already on this), and
providing the
> > > >>same method/function per page that PHP has.
> > > > I like the single frame myself, but I''ll put a
button in there to
> > > > have a frame/no frame switch for you :) Each method has
it''s own
> > > > [notes] link now. So I was thinking that would be good
> > enough. Not
> > > > only that, but every section of a class/file/module has
> > it''s own notes.
> > >
> > > Just like the other posters, I like your annotated documentation
> > > system a lot. As a point of feedback, navigation could use
> > a little more care.
> > > Maybe tinkering with the CSS would make the pages look and
> > feel less
> > > rough (e.g. heading font sizes appear too big, to my eye at
least).
> > > Php''s documentaton site could act as a role model here.
The search
> > > facility will be the most-used function of the site, so that
needs
> > > extra attention - it''s quite nice already though.
> > >
> > > Please consider also: Having a framed version, even
conditionally,
> > > will result in isolated content frames (without the corresponding
> > > menu) ending up in google. Even though frames make some
> > thing easier,
> > > they''re mostly harmful.
> > >
> > > Thanks!
> > > Paulus
> > >
> > > _______________________________________________
> > > Rails mailing list
> > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > >
> > _______________________________________________
> > Rails mailing list
> > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > http://lists.rubyonrails.org/mailman/listinfo/rails
> >
>
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>


--
- Ramin
http://www.getintothis.com/blog


_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

I''m not familiar with scrollable DIVs, but I''ll have a look. I
used a
frame because I didn''t want to load all that data multiple times, a
non framed version would have to have some type of collapsed hierarchy
at the side.

All the information is stored in a database, but we didn''t want to
make the search field auto-complete because we were worried about the
number of database queries it would generate.

--
Conor

On 11/18/05, Ramin <i8ramin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> A nice alternative to frames would be to use a scrollable DIV. The problem
> with that and the main reason I think frames were used is because that long
> list has to be reloaded on every page request, making the page size much
> larger than it needs to be. I don''t mind the frames, as long as
each
> individual page can still be indexed and searched by google easily. If a
> user happens to come upon the page outside of frames, the page could detect
> this and refresh the page inside frames again. I think this is what the
MSDN
> site does.
>
>  Just curious, is all that information stored in a database somewhere? If
> so, why not make the search fields into an auto-complete text field using
> the javascript helpers in rails. I think its a one liner.
>
>  Great resource nonetheless.. I use this as a replacement to the regular
> Rails/Ruby API sites now.
>
>
>
> On 11/18/05, Nathaniel S. H. Brown
<nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org> wrote:
> > Hey Conor,
> >
> > When you get the no-frames version up, I will take a peek and come up
with
> a
> > cool interface for the doc system. Be happy to help make it look a
little
> > more appealing and user friendly :)
> >
> > Warmest regards,
> > Nathan.
> >
> >
> --------------------------------------------------------------
> > Nathaniel S. H. Brown                 Toll Free 1.877.4.INIMIT
> > Inimit Innovations                        Phone
> 604.724.6624
> > www.inimit.com                              Fax
> 604.444.9942
> >
> >
> > > -----Original Message-----
> > > From:
rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > [mailto:
rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org] On Behalf
> Of Conor Hunt
> > > Sent: November 17, 2005 3:30 PM
> > > To: rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > Subject: Re: [Rails] Re: [ANN] Rannotate v2 - Annotated Rails
> > > APIdocumentation withsearch
> > >
> > > Probably you are using it under a platform that I have not tested
yet.
> > > Unfortunately I''m not a designer (at all). I''ll
do the best I
> > > can in the next release to make the CSS look similar under
> > > different platforms though.
> > >
> > > If anyone out there is a designer and has some CSS skills it
> > > would be great if you had a few hours and could take a look
> > > at the site and improve the CSS.
> > >
> > > Isolated content frames are a problem, although there can
> > > easily be a link to show the index frame if it is missing.
> > > I''m not sure if it is a good idea to display the huge
list of
> > > files, classes or methods for each page. I think without
> > > frames I''d probably only show classes/modules in a
> > > collapsable hierarchy and allow you to search the other types.
> > >
> > > --
> > > Conor
> > >
> > > On 11/17/05, Paulus Esterhazy <
pesterhazy-hi6Y0CQ0nG0@public.gmane.org> wrote:
> > > > >>One key point for a usability standpoint would be
that of
> > > removing
> > > > >>the frames (I am sure you are already on this), and
providing the
> > > > >>same method/function per page that PHP has.
> > > > > I like the single frame myself, but I''ll put a
button in there to
> > > > > have a frame/no frame switch for you :) Each method has
it''s own
> > > > > [notes] link now. So I was thinking that would be good
> > > enough. Not
> > > > > only that, but every section of a class/file/module has
> > > it''s own notes.
> > > >
> > > > Just like the other posters, I like your annotated
documentation
> > > > system a lot. As a point of feedback, navigation could use
> > > a little more care.
> > > > Maybe tinkering with the CSS would make the pages look and
> > > feel less
> > > > rough (e.g. heading font sizes appear too big, to my eye at
least).
> > > > Php''s documentaton site could act as a role model
here. The search
> > > > facility will be the most-used function of the site, so that
needs
> > > > extra attention - it''s quite nice already though.
> > > >
> > > > Please consider also: Having a framed version, even
conditionally,
> > > > will result in isolated content frames (without the
corresponding
> > > > menu) ending up in google. Even though frames make some
> > > thing easier,
> > > > they''re mostly harmful.
> > > >
> > > > Thanks!
> > > > Paulus
> > > >
> > > > _______________________________________________
> > > > Rails mailing list
> > > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > > >
> > > _______________________________________________
> > > Rails mailing list
> > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > >
> >
> > _______________________________________________
> > Rails mailing list
> > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > http://lists.rubyonrails.org/mailman/listinfo/rails
> >
>
>
>
> --
> - Ramin
> http://www.getintothis.com/blog
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>
>
>

I''m not familiar with scrollable DIVs, but I''ll have a look,
thanks. I used a
frame because I didn''t want to load all that data multiple times, a
non framed version would have to have some type of collapsed hierarchy
at the side.

All the information is stored in a database, but we didn''t want to
make the search field auto-complete because we were worried about the
number of database queries it would generate.

--
Conor

On 11/18/05, Ramin <i8ramin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> A nice alternative to frames would be to use a scrollable DIV. The problem
> with that and the main reason I think frames were used is because that long
> list has to be reloaded on every page request, making the page size much
> larger than it needs to be. I don''t mind the frames, as long as
each
> individual page can still be indexed and searched by google easily. If a
> user happens to come upon the page outside of frames, the page could detect
> this and refresh the page inside frames again. I think this is what the
MSDN
> site does.
>
>  Just curious, is all that information stored in a database somewhere? If
> so, why not make the search fields into an auto-complete text field using
> the javascript helpers in rails. I think its a one liner.
>
>  Great resource nonetheless.. I use this as a replacement to the regular
> Rails/Ruby API sites now.
>
>
>
> On 11/18/05, Nathaniel S. H. Brown
<nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org> wrote:
> > Hey Conor,
> >
> > When you get the no-frames version up, I will take a peek and come up
with
> a
> > cool interface for the doc system. Be happy to help make it look a
little
> > more appealing and user friendly :)
> >
> > Warmest regards,
> > Nathan.
> >
> >
> --------------------------------------------------------------
> > Nathaniel S. H. Brown                 Toll Free 1.877.4.INIMIT
> > Inimit Innovations                        Phone
> 604.724.6624
> > www.inimit.com                              Fax
> 604.444.9942
> >
> >
> > > -----Original Message-----
> > > From:
rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > [mailto:
rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org] On Behalf
> Of Conor Hunt
> > > Sent: November 17, 2005 3:30 PM
> > > To: rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > Subject: Re: [Rails] Re: [ANN] Rannotate v2 - Annotated Rails
> > > APIdocumentation withsearch
> > >
> > > Probably you are using it under a platform that I have not tested
yet.
> > > Unfortunately I''m not a designer (at all). I''ll
do the best I
> > > can in the next release to make the CSS look similar under
> > > different platforms though.
> > >
> > > If anyone out there is a designer and has some CSS skills it
> > > would be great if you had a few hours and could take a look
> > > at the site and improve the CSS.
> > >
> > > Isolated content frames are a problem, although there can
> > > easily be a link to show the index frame if it is missing.
> > > I''m not sure if it is a good idea to display the huge
list of
> > > files, classes or methods for each page. I think without
> > > frames I''d probably only show classes/modules in a
> > > collapsable hierarchy and allow you to search the other types.
> > >
> > > --
> > > Conor
> > >
> > > On 11/17/05, Paulus Esterhazy <
pesterhazy-hi6Y0CQ0nG0@public.gmane.org> wrote:
> > > > >>One key point for a usability standpoint would be
that of
> > > removing
> > > > >>the frames (I am sure you are already on this), and
providing the
> > > > >>same method/function per page that PHP has.
> > > > > I like the single frame myself, but I''ll put a
button in there to
> > > > > have a frame/no frame switch for you :) Each method has
it''s own
> > > > > [notes] link now. So I was thinking that would be good
> > > enough. Not
> > > > > only that, but every section of a class/file/module has
> > > it''s own notes.
> > > >
> > > > Just like the other posters, I like your annotated
documentation
> > > > system a lot. As a point of feedback, navigation could use
> > > a little more care.
> > > > Maybe tinkering with the CSS would make the pages look and
> > > feel less
> > > > rough (e.g. heading font sizes appear too big, to my eye at
least).
> > > > Php''s documentaton site could act as a role model
here. The search
> > > > facility will be the most-used function of the site, so that
needs
> > > > extra attention - it''s quite nice already though.
> > > >
> > > > Please consider also: Having a framed version, even
conditionally,
> > > > will result in isolated content frames (without the
corresponding
> > > > menu) ending up in google. Even though frames make some
> > > thing easier,
> > > > they''re mostly harmful.
> > > >
> > > > Thanks!
> > > > Paulus
> > > >
> > > > _______________________________________________
> > > > Rails mailing list
> > > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > > >
> > > _______________________________________________
> > > Rails mailing list
> > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > >
> >
> > _______________________________________________
> > Rails mailing list
> > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > http://lists.rubyonrails.org/mailman/listinfo/rails
> >
>
>
>
> --
> - Ramin
> http://www.getintothis.com/blog
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>
>
>

Regarding the autocomplete feature. Makes sense, but I''m wondering if
there
is a way to "cache" the list of classes/methods/filenames locally with
javascript and have the autocomplete query that instead of hitting the db.
I''m pretty sure its doable, just not sure if its worth the trouble of
coding
it up :-)

To make a DIV scrollable, all you gotta do is give it a fixed height and
then set overflow: auto; for example:

<div style="height: 500px; overflow: auto"> .. long list ..
</div>

The only caveat to this approach is you have to set the heigt of the DIV
manually. A work around would be to determine the height of the browser
window (using javascript) and dynamically set the height of the DIV to
correspond to that calculated height. This way the DIV will always be the
same height as the browser window. OR just use frames ;-)



On 11/18/05, Conor Hunt
<conor.hunt+rails-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
>
> I''m not familiar with scrollable DIVs, but I''ll have a
look, thanks. I
> used a
> frame because I didn''t want to load all that data multiple times,
a
> non framed version would have to have some type of collapsed hierarchy
> at the side.
>
> All the information is stored in a database, but we didn''t want to
> make the search field auto-complete because we were worried about the
> number of database queries it would generate.
>
> --
> Conor
>
> On 11/18/05, Ramin <i8ramin-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> > A nice alternative to frames would be to use a scrollable DIV. The
> problem
> > with that and the main reason I think frames were used is because that
> long
> > list has to be reloaded on every page request, making the page size
much
> > larger than it needs to be. I don''t mind the frames, as long
as each
> > individual page can still be indexed and searched by google easily. If
a
> > user happens to come upon the page outside of frames, the page could
> detect
> > this and refresh the page inside frames again. I think this is what
the
> MSDN
> > site does.
> >
> > Just curious, is all that information stored in a database somewhere?
If
> > so, why not make the search fields into an auto-complete text field
> using
> > the javascript helpers in rails. I think its a one liner.
> >
> > Great resource nonetheless.. I use this as a replacement to the
regular
> > Rails/Ruby API sites now.
> >
> >
> >
> > On 11/18/05, Nathaniel S. H. Brown
<nshb-wgYSSEAWXinQT0dZR+AlfA@public.gmane.org> wrote:
> > > Hey Conor,
> > >
> > > When you get the no-frames version up, I will take a peek and
come up
> with
> > a
> > > cool interface for the doc system. Be happy to help make it look
a
> little
> > > more appealing and user friendly :)
> > >
> > > Warmest regards,
> > > Nathan.
> > >
> > >
> > --------------------------------------------------------------
> > > Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT
> > > Inimit Innovations Phone
> > 604.724.6624
> > > www.inimit.com <http://www.inimit.com> Fax
> > 604.444.9942
> > >
> > >
> > > > -----Original Message-----
> > > > From:
rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > > [mailto:
rails-bounces-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org] On Behalf
> > Of Conor Hunt
> > > > Sent: November 17, 2005 3:30 PM
> > > > To: rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > > Subject: Re: [Rails] Re: [ANN] Rannotate v2 - Annotated
Rails
> > > > APIdocumentation withsearch
> > > >
> > > > Probably you are using it under a platform that I have not
tested
> yet.
> > > > Unfortunately I''m not a designer (at all).
I''ll do the best I
> > > > can in the next release to make the CSS look similar under
> > > > different platforms though.
> > > >
> > > > If anyone out there is a designer and has some CSS skills it
> > > > would be great if you had a few hours and could take a look
> > > > at the site and improve the CSS.
> > > >
> > > > Isolated content frames are a problem, although there can
> > > > easily be a link to show the index frame if it is missing.
> > > > I''m not sure if it is a good idea to display the
huge list of
> > > > files, classes or methods for each page. I think without
> > > > frames I''d probably only show classes/modules in a
> > > > collapsable hierarchy and allow you to search the other
types.
> > > >
> > > > --
> > > > Conor
> > > >
> > > > On 11/17/05, Paulus Esterhazy <
pesterhazy-hi6Y0CQ0nG0@public.gmane.org> wrote:
> > > > > >>One key point for a usability standpoint would
be that of
> > > > removing
> > > > > >>the frames (I am sure you are already on this),
and providing
> the
> > > > > >>same method/function per page that PHP has.
> > > > > > I like the single frame myself, but I''ll
put a button in there
> to
> > > > > > have a frame/no frame switch for you :) Each
method has it''s own
> > > > > > [notes] link now. So I was thinking that would be
good
> > > > enough. Not
> > > > > > only that, but every section of a
class/file/module has
> > > > it''s own notes.
> > > > >
> > > > > Just like the other posters, I like your annotated
documentation
> > > > > system a lot. As a point of feedback, navigation could
use
> > > > a little more care.
> > > > > Maybe tinkering with the CSS would make the pages look
and
> > > > feel less
> > > > > rough (e.g. heading font sizes appear too big, to my
eye at
> least).
> > > > > Php''s documentaton site could act as a role
model here. The search
> > > > > facility will be the most-used function of the site, so
that needs
> > > > > extra attention - it''s quite nice already
though.
> > > > >
> > > > > Please consider also: Having a framed version, even
conditionally,
> > > > > will result in isolated content frames (without the
corresponding
> > > > > menu) ending up in google. Even though frames make some
> > > > thing easier,
> > > > > they''re mostly harmful.
> > > > >
> > > > > Thanks!
> > > > > Paulus
> > > > >
> > > > > _______________________________________________
> > > > > Rails mailing list
> > > > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > > > >
> > > > _______________________________________________
> > > > Rails mailing list
> > > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > > >
> > >
> > > _______________________________________________
> > > Rails mailing list
> > > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > > http://lists.rubyonrails.org/mailman/listinfo/rails
> > >
> >
> >
> >
> > --
> > - Ramin
> > http://www.getintothis.com/blog
> > _______________________________________________
> > Rails mailing list
> > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > http://lists.rubyonrails.org/mailman/listinfo/rails
> >
> >
> >
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>


--
- Ramin
http://www.getintothis.com/blog


_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

On 11/18/05, Conor Hunt
<conor.hunt+rails-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> All the information is stored in a database, but we didn''t want to
> make the search field auto-complete because we were worried about the
> number of database queries it would generate.
That would be a real issue on a site that got a lot of traffic, which
undoubtedly this will, given its usefulness.  I think the search is
great as is.  Autocomplete IMO would mostly be a gee-whiz feature.

All,

I installed the latest version Rails in order to get the updates for the SQL
Server adaptor.  Here is the log of the update:

Successfully installed rails-0.14.3.2969
Successfully installed activesupport-1.2.3.2969
Successfully installed activerecord-1.13.0.2969
Successfully installed actionpack-1.11.0.2969
Successfully installed actionmailer-1.1.3.2969
Successfully installed actionwebservice-0.9.3.2969
Installing RDoc documentation for activesupport-1.2.3.2969...
Installing RDoc documentation for activerecord-1.13.0.2969...

lib/active_record.rb:73:64: Skipping require of dynamic string:
"active_record/c
onnection_adapters/#{adapter}_adapter"
Installing RDoc documentation for actionpack-1.11.0.2969...

lib/action_controller/assertions.rb:4:69: Skipping require of dynamic string:
"#
{File.dirname(__FILE__)}/vendor/html-scanner/html/document"
Installing RDoc documentation for actionmailer-1.1.3.2969...
Installing RDoc documentation for actionwebservice-0.9.3.2969...
Gems: [rails] updated 

When I ran it against my one table named interior_selections that has a primary
key of selection_id [below is the source for it]

class InteriorSelection < ActiveRecord::Base
  set_table_name "interior_selections" 
  set_primary_key "selection_id"
  
end


Here is the error message I get:

Execute
    OLE error code:80040E14 in Microsoft OLE DB Provider for SQL Server
      Incorrect syntax near the keyword ''TOP''.
    HRESULT error code:0x80020009
      Exception occurred.
C:/ruby/lib/ruby/site_ruby/1.8/DBD/ADO/ADO.rb:135:in `execute''
C:/ruby/lib/ruby/site_ruby/1.8/dbi/dbi.rb:1049:in `execute''
C:/ruby/lib/ruby/site_ruby/1.8/dbi/dbi.rb:640:in `execute''
C:/ruby/lib/ruby/site_ruby/1.8/dbi/dbi.rb:671:in `select_all''
C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/connection_adapters/sqlserver_adapter.rb:322:in
`add_limit_offset!''
C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/base.rb:937:in
`add_limit!''
C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/base.rb:930:in
`construct_finder_sql''
C:/ruby/lib/ruby/gems/1.8/gems/activerecord-1.13.0.2969/lib/active_record/base.rb:411:in
`find''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/pagination.rb:174:in
`find_collection_for_pagination''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/pagination.rb:192:in
`paginator_and_collection_for''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/pagination.rb:124:in
`paginate''
#{RAILS_ROOT}/app/controllers/interior_selection_controller.rb:11:in
`list''
#{RAILS_ROOT}/app/controllers/interior_selection_controller.rb:3:in
`index''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:845:in
`send''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:845:in
`perform_action_without_filters''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/filters.rb:332:in
`perform_action_without_benchmark''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/benchmarking.rb:69:in
`perform_action_without_rescue''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/benchmarking.rb:69:in
`measure''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/benchmarking.rb:69:in
`perform_action_without_rescue''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/rescue.rb:82:in
`perform_action''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:369:in
`send''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/base.rb:369:in
`process_without_session_management_support''
C:/ruby/lib/ruby/gems/1.8/gems/actionpack-1.11.0.2969/lib/action_controller/session_management.rb:116:in
`process''
C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/dispatcher.rb:38:in
`dispatch''
C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/webrick_server.rb:121:in
`handle_dispatch''
C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/webrick_server.rb:87:in
`service''
C:/ruby/lib/ruby/1.8/webrick/httpserver.rb:104:in `service''
C:/ruby/lib/ruby/1.8/webrick/httpserver.rb:65:in `run''
C:/ruby/lib/ruby/1.8/webrick/server.rb:155:in `start_thread''
C:/ruby/lib/ruby/1.8/webrick/server.rb:144:in `start''
C:/ruby/lib/ruby/1.8/webrick/server.rb:144:in `start_thread''
C:/ruby/lib/ruby/1.8/webrick/server.rb:94:in `start''
C:/ruby/lib/ruby/1.8/webrick/server.rb:89:in `each''
C:/ruby/lib/ruby/1.8/webrick/server.rb:89:in `start''
C:/ruby/lib/ruby/1.8/webrick/server.rb:79:in `start''
C:/ruby/lib/ruby/1.8/webrick/server.rb:79:in `start''
C:/ruby/lib/ruby/gems/1.8/gems/rails-0.14.3.2969/lib/webrick_server.rb:73:in
`dispatch''
Thanks in advance,
Ron


_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails