[Nitro] A Request for Help

James Britt james_b at neurogami.com
Wed Sep 21 11:37:52 EDT 2005

Michael Fellinger wrote:

> I guess you know the examples spark and flare already... they are not 
> exactly what one would call complex, but they are very good to study and 
> learn (almost, one can't get everything on one page i guess) everything 
> about nitro and a few things about og as well.

Yes, but I think something a bit more complex would be good, as well as 
the visibility of having a popular Ruby community site powered by Og/Nitro.


> Your idea sounds interesting, and i wondered already how that page works :)
> However, i saw a website with all kinds of categorized rss-feeds about 
> ruby some time ago.... i just can't remember it anymore, but it looked 
> good for further collection.

I gave  presentation on this last year, and had a beta version of 
ruby-doc up for a while.  Its down now, mostly due to a sudden need to 
move servers and reinstall everything.

> But there are two ways you could go - a bit manually or automagically.
> So, getting a community to serve news is one thing, wich has happened 
> now - i can't even read or track everything of it (i read Technorati 
> with everything related to ruby and the ML), that is something i really 
> miss from the beginning... (wasn't that long before).
> Well, one could just collect everything about ruby from blogs, news and 
> so on, get it into a queue and some moderators check it if they like it. 
> this would be the manually process - the automagically will have to 
> unite some very very good ideas about information-relevance and like... 
> you don't want information that is important to be filtered, i guess 
> this could be solved by using a bayesian filtering, wich we would have 
> to watch, but that does most of the work on its own.

Two goals here would be: no manual labor on my part; instead, periodic 
and minimal labor in the part of users.  This is one reason I like the 
idea of leeching off of del.icio.us: people are already doing it, and 
are doing it out self-interest.  So there is no need to ask folks to do 
anything extra.

The other goal is that it not be complicated.  Simple is better, even if 
the results are less than ideal.  I'd rather try to work out a fairly 
simple plan fr collecting, filtering, and rendering lists of resources, 
even it includes some cruft.  It will still be better than what is there 
now, and is more  likely to get finished in my lifetime.

> http://en.wikipedia.org/wiki/Bayesian_filtering
> There are very good spam-filters out there, and i think we could 
> implement one in ruby too, based on something like spamassassin.
> The only problem i see with this is that ruby may be widespread over too 
> many topics already, i guess we just have to try that one.

I was thinking about a statisical analysis is tags applied (or not) to 
posts entered on del.icio.us.  Basically, count stuff.
>>The other main change is how to display the RDocs for the core and 
>>standard libs.  Problem one is simply the layout, and I think the RDog 
>>project shows a much better approach.  Problem two is that the site does 
>>not offer a way for a reader to add annotations, such as with the docs 
>>at http://www.php.net/docs.php (often cited as a model of good on-line 
>>docs presentation).
> Well, the way to add annotations should be the wiki. it was planned to 
> add the article of the wiki, or maybe an extract between special 
> [doc]tags[/doc] on the page of the doc.
> it is not implemented yet and there are some (good) reasons for that.
> First of all, the DocController is not merged with the WikiController, 
> so they have no common database and don't share anything (except the skin)
> This is because the DocController has nothing to do with Og, it is base 
> on yamls instead - this will change as soon as the problem with the 
> inheritance in og is solved (giving george a broad hint ;)
> next thing is that i'm not sure how to merge them later and if it would 
> be better to split the whole thing (possibly not) into smaller parts 
> like 'nitro/og', 'glue', 'core/stdlib' - you get the idea...
>>My plan for this was to change the default rdoc template to include a 
>>javascript call that would make an XmlHttpRequest (AKA AJAX) fetch from 
>>a docs wiki page,  and dynamically insert the content of the 
>>corresponding page into the rdoc display.  Those without javascript 
>>would simply see a link to the wiki.
> i like XmlHttpRequest... but this happens not only to everyone without 
> javascript, but also to every lucky IE-surfer who has ActiveX off (about 
> 99% of them - the others don't survive)
> well, and doing this the normal way is no problem either, so why bother 
> with ajax?

Because it is easy and will work for most of the target audience, who I 
expect are using Mozilla/Firefox/not-IE.  Lots of people using IE also 
use Gmail and Google maps, both which require ActiveX to drive the AJAX 
stuff.   And even if JavaScript is turned off, the user will at least 
see a link tot he wiki.  It's a fairly simple, low-tech way to solve a 
problem and get something running.  Improvements can come later

>>A decent, simple search engine would be quite nice, too.
> It is planned and will get implemented ASAP, but searching through yamls 
> is a pain, you know? :)

Yeah, I was looking at Lucence or whatever it is; basically, have a 
local spider crawl through the local docs, index words, and offer a 
searchable index.


> Hey, i would love to help you indeed, i want ruby-doc.org to become the 
> new standard in documentation (leaving php.net behind) :)
> But i guess we have to wait for the next version of nitro/og.

Maybe not.  I think there is enough there to get the basic stuff 
working.  I just do not have the wherewithal to keep trying to do it by 

> Another thing i have stumbled upon is something much more trivial but 
> really important.
> The standard-stuff, like if/else, loops, iterators and like, it is 
> described in the book, but there is no unified documentation on them 
> (found some tables comparing the syntax to other languages, but that is 
> not what i want)
> I know this is not php (and that's good), but i like the idea to give 
> comments on these topics as well.

Yes,  it would be nice if ri/rodc and so on also offered help on 
keywords and language constructs.  I *think* stuff like that is on the 
To Do list of whoever has taken over ri/rdoc development.

If not, adding it by hand to ruby-doc is probably easy enough; it tends 
not to change a whole lot.



http://www.ruby-doc.org - The Ruby Documentation Site
http://www.rubyxml.com  - News, Articles, and Listings for Ruby & XML
http://www.rubystuff.com - The Ruby Store for Ruby Stuff
http://www.jamesbritt.com  - Playing with Better Toys

More information about the Nitro-general mailing list