personally I like what I see, I don't have any objection.��

My personal opinion on this is that Pharo needs a proper documentation system which what examples are part of like Java or Python doc strings. But then a doc strings system is far more complex than the GTExample and a lot more work. In the mean time GTExample looks like a good enhancement to have. I also dont see it creating any incompatibilities with the existing <example> pragma.��

On Mon, Dec 19, 2016 at 7:27 PM Tudor Girba <tudor@tudorgirba.com> wrote:
Hi,

> On Dec 19, 2016, at 5:49 PM, Ben Coman <btc@openinworld.com> wrote:
>
> On Mon, Dec 19, 2016 at 3:53 PM, Nicolai Hess <nicolaihess@gmail.com> wrote:
>>
>>
>> 2016-12-19 8:46 GMT+01:00 Tudor Girba <tudor@tudorgirba.com>:
>>>
>>> Hi,
>>>
>>> I would prefer if this thread does not transform in a terminology debate
>>> too much.
>>>
>>
>> @Doru, but you asked "What do you�� think" and I think Bens response about
>> sampleScript is valid
>>
>> @Ben Did you check Dorus blog entry
>> (http://gtoolkit.org/doc/Examples/examples.html) I think this makes
>> it more clear why gttExamples are more than just methods producsing
>> "samples"
>
>
> I hadn't seen that before.�� Thanks for the tip.
> So I cede the point the aim is something more than just a sample.

Thank you!

But, if we are at it, please let���s continue and brainstorm. The existing implementation should be taken as a first fully working version. It would be great to have people play with it and find its weaknesses.

Cheers,
Doru



> cheers -ben
>
>>
>>
>>>
>>> Example is a term that fits both the code and the returning object.
>>> <gtExample> is applied on a method and it primarily describes that method.
>>> The term ���example��� also describes the meta object that is wraps the concrete
>>> return value with the information from the method (for example, the label of
>>> the example, the link to the subject, or the dependencies to other
>>> examples). The example term is also important from the metaphor point of
>>> view: "we learn from examples���.
>>>
>>> Cheers,
>>> Doru
>>>
>>>
>>>
>>>> On Dec 19, 2016, at 3:34 AM, Ben Coman <btc@openinworld.com> wrote:
>>>>
>>>> On Mon, Dec 19, 2016 at 5:49 AM, Tudor Girba <tudor@tudorgirba.com>
>>>> wrote:
>>>>> Hi,
>>>>>
>>>>> As you might know, a while ago we created GTExamples, a framework that
>>>>> supports both example-based live documentation and testing:
>>>>> http://gtoolkit.org/doc/Examples/examples.html
>>>>>
>>>>> GTExamples was part of the GTInspector for a while, but as it evolved,
>>>>> we pulled it out in a separate project. This separate project is not in
>>>>> Pharo anymore but it is part of the full GToolkit configuration (Pharo only
>>>>> ships the core of GToolkit). The idea of taking GTExamples out was to allow
>>>>> the community to have a more elaborate discussion about the role of examples
>>>>> in our environment.
>>>>>
>>>>> I have invited you to join that conversation, but it did not take off.
>>>>> I understand that perhaps the topic does not look appealing at this moment.
>>>>>
>>>>> We will certainly continue to evolve GTExamples both on the semantics
>>>>> level of the dependency constructs and on the integration with tools. Our
>>>>> goal is to enable a new practice that I would like to call Example-Guilded
>>>>> Development (or Example-Driven Development), and position Pharo to be the
>>>>> only platform on which someone can do that. But, that is our goal, and does
>>>>> not have to be the same with other people���s goal.
>>>>>
>>>>> Right now, GTExamples relies on the <gtExample> pragma to denote a
>>>>> method that returns an object that exemplifies something.
>>>>
>>>>
>>>> I've previously not done a good job of promoting the use of <sample>
>>>> for this.�� I'll try spinning this wheel once more.
>>>>
>>>> There are two concepts to consider:
>>>> * The returned object.
>>>> * The method code that creates the returned object.
>>>>
>>>> The "returned object" is best considered a <sample>.
>>>> The "method code" is best considered an <example> that produces the
>>>> sample.
>>>>
>>>> http://www.differencebetween.com/difference-between-example-and-vs-sample/
>>>>
>>>> The term "exemplifies/exemplification" associates equally with both...
>>>> * http://www.thesaurus.com/browse/example
>>>> * http://www.thesaurus.com/browse/sample
>>>> but for example... from a draw full of cutlery you don't "take an
>>>> example spoon", you "take a sample spoon".
>>>>
>>>>
>>>> So it depends on where you want the focus to be.
>>>> * If the focus is on working with a sample object, then <sample> makes
>>>> a better pragma for the method creating it.
>>>> * If the focus is on the code producing the sample, then <example> is
>>>> a better choice.
>>>>
>>>> Maybe you are constrained by existing industry terminology,
>>>> but "Example-Driven Development" might be equally called
>>>> "Sample-Driven Development".
>>>> Without having read into the topic, intuitively the former broadly
>>>> encompasses copying static code
>>>> while the latter feels more limited to working with an object.
>>>>
>>>>
>>>> My proposal...
>>>> * <sample> provides a narrower sense of side-effect-free provision of
>>>> object to work with.�� "Samples are often tangible parts and can be
>>>> observed"
>>>> * <example> provides a broader sense of showing how things work
>>>> together, in ways that may or may-not include side effects that you
>>>> don't actually want to execute - just to refer to.�� "Examples are used
>>>> [to] illustrate something. [Its] expected that the example will be
>>>> imitated and replicated among its audience."
>>>> * <script> provides a sense of system management, of methods causing
>>>> significant side effects.�� You won't want to copy these methods, just
>>>> make use them.
>>>>
>>>> <sampleScript> feels awkward to apply to examples, since by my these
>>>> are neither samples nor scripts.
>>>>
>>>>
>>>> cheers -ben
>>>>
>>>>
>>>>> Executing this method as an example should have no side-effects (either
>>>>> because the method itself does not have a side-effect, or because the
>>>>> example method defines how the cleanup should happen using the mechanism
>>>>> provided by GTExamples).
>>>>>
>>>>> This meaning is different from the meaning of the <example> pragma used
>>>>> through Pharo.�� There are currently 55 places that use this pragma inside
>>>>> Pharo and most of them come from FastTable. As things will progress and more
>>>>> libraries might use GTExamples, the situation can become confusing.
>>>>>
>>>>> To make things less confusing in the future, I would like to define the
>>>>> meaning of the <example> to denote a method that returns an object without
>>>>> having side effects. Would you agree with this?
>>>>>
>>>>> If yes, I would suggest the name of the new pragma that would replace
>>>>> the existing one to include ���script��� in the name. For example,
>>>>> <sampleScript>.
>>>>>
>>>>> What do you think?
>>>>>
>>>>> Cheers,
>>>>> Doru
>>>>>
>>>>>
>>>>> --
>>>>> www.tudorgirba.com
>>>>> www.feenk.com
>>>>>
>>>>> "Reasonable is what we are accustomed with."
>>>
>>> --
>>> www.tudorgirba.com
>>> www.feenk.com
>>>
>>> ���Software has no shape. Actually, it has no one shape. It has many."

--
www.tudorgirba.com
www.feenk.com

"If you can't say why something is relevant,
it probably isn't."