From: Robert Klemme <shortcutter@...>
Date: 2009-07-02T05:00:09+09:00
Subject: Re: ruby suggestion: officially sanctioned tutorials/howto's

On 01.07.2009 14:07, Roger Pack wrote:
>> 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.

My preference would be a web accessible solution and probably a PDF for 
printing.  Maybe we could have an editor which signs wiki changes off or 
something.

> 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.

As you know, I am not a fan of the "code" approach... :-)

Kind regards

	robert

-- 
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/