From: Roger Pack <rogerpack2005@...>
Date: 2009-07-01T21:07:20+09:00
Subject: Re: ruby suggestion: officially sanctioned tutorials/howto's

> One way to attempt to not "mix them in together" might be to create the 
> tutorials are in a sub folder, i.e. trunk/doc/tutorials, then one can 
> generate "tutorial only" rdocs by running rdoc from within that 
> subfolder.  It wouldn't (easily) contain backlinks to the class 
> description themselves, but it would give you all the tutorials in a 
> single rdoc.  Would that help?
> 
> 
> The other thought is "if it's not a wiki, it's not user editable".
> I'm not sure of an easy way around that one...maybe have a "staging 
> wiki" for the tutorials that people can edit, that has a maintainer who 
> tracks changes and submits "good ones" to core?


My latest thought is to "adopt" some wiki or other, and use that wiki 
for staging, then use mechanize to "scrape" it into rdoc style syntax 
which can be rolled into a file to complement the existing rdocs.

like

http://www.meshplex.org/wiki/Ruby/Basic_GUI
or
http://en.wikibooks.org/wiki/Ruby_programming_language
and
http://pleac.sourceforge.net/pleac_ruby/index.html

Thoughts?  I was thinking it might be good to leverage some existing 
tutorials rather than copy and paste them a lot.

Another option would be to create a single rdoc "wiki" page that is user 
editable.

i.e. when you click "edit" you are presented something like ruby source 
[1]

class Socket
 module Tutorial
=begin rdoc
  some rocking tutorial
=end
  def go
  end
 end
end

and are expected to edit it in rdoc style syntax.

I think I may end up doing both, just for fun.  And probably end up 
gemifying it so that I can push out more rapid release/response cycles.

Thoughts?

=r

[1] shameless self-promotion: discovered this syntax via rdoc's rdocs: 
http://allgems.faithpromotingstories.org/gems/doc/rdoc/2.3.0/classes/RDoc.html
-- 
Posted via http://www.ruby-forum.com/.