On Tue, Jun 23, 2009 at 11:30 PM, Robert
Klemme<shortcutter / googlemail.com> wrote:
> On 23.06.2009 01:20, Robert Dober wrote:
>>
>> On Mon, Jun 22, 2009 at 6:50 PM, Joel VanderWerf<vjoel / path.berkeley.edu>
>> wrote:
>>>
>>> James Gray wrote:
>>>>
>>>> On Jun 22, 2009, at 7:10 AM, Roger Pack wrote:
>>
>>> To expand on James's proposal a bit... what about defining a module
>>> called,
>>> for example, Socket::Tutorial, and putting the material in the comment
>>> block
>>> of that module, for rdoc to find? Then:
>>>
>>>   콽  󨪩
>>>
>>>  
>>>
>>>      
>>>
>>> (*) actually, I'm not sure current ri performs a search for x::Tutorial,
>>> but
>>> why shouldn't it?
>
>> Honestly that sounds brilliant. I am just a little bit confused about
>> the x::Tutorial, should that not be Tutorial::X
>> for X in { Array, Module, Class, Exception, Enumerator, You::Name::It } ?
>>
>> And Tutorial would be a module in the standard lib?
>
> I do not like the idea.     > of carrying documentation.        > functionality and not serve as a text skeleton.
And what if documentation were the functionality of this code?
IMHO it is completely open if there would be code or only rdoc
documentation, but nicely included into the class hierarchy. Jo has
probably an idea about that.
>
> The second reason is, that documentation derived from code typically has a
> different structure than "hand crafted" tutorials. his documentation is
> structured around source code artifacts such as classes and modules. 
> written tutorial focuses on tasks and usually has a structure so that you
> can more easily learn when reading from beginning to end.
You are absolutely correct, but please see above, no code as far as I
am concerned.
>
> Having said that it is probably a good idea to include tutorials in the
> standard distribution. ut IMHO they should be written as tutorials,
> probably using Textile markup or something similar.
Not a bad idea at all. I would prefer to write it in textile rather
than in rdoc.
However I still feel it would be great if we could incorporate Jo's
idea of linking it into the "right" place.
What'u think?

R.