Hi, On Wed, Mar 25, 2015 at 12:17 AM, Nicolai Hess <nicolaihess@web.de> wrote:

2015-03-24 22:48 GMT+01:00 Tudor Girba <tudor@tudorgirba.com>:

...

Hi Torsten,

Thanks for the long email. The first part summarizes the situation reasonably well, except that you are putting the same pot <example> annotated methods and methods having example* selectors. To try to clear the water I thought I would answer with an almost equally long email :).

I am not trying to redefine anything. We had the discussion about renaming the original <gtExample> into <example> some months ago and since then we only used <example> to mean what my description is: an initialized object. There are indeed many methods named example* that have a loose meaning that is different than the clearly defined <example> methods, but that does not mean that <example> was ever used for anything else than what my definition.

I must admit I misunderstood that discussion, I thought it was about a the GLMExamplesBrowser not the inspector. I thought the tag will be used to create a list of examples and selecting the method will run the method.

There was a screenshot of the inspector in it :).

...

In the Pharo image there are current 96 methods annotated with <example> or <example:>, and in fact, the only one method of these that does not preserve the meaning of <example> appeared in the recently integrated Athens version 3.1. This method executes a demo that requires a key press to end.

So, who would you say is changing the meaning of an existing state of facts? :)

I think he is talkting about the meaning of "example" in the "method name". This exists much longer than the "gtExample pragmas". We have many exampleXXX methods in the image that actually start something (the widget examples for instance). So it is a bit confusing that the <example> pragma only provides some data.

Yes, there are many example* methods, often with different interpretations. That is why, I specifically mentioned the distinction between the #example* selectors and <example> pragmas multiple times. As for Nautilus dealing with fuzzy semantics, my choice would be to only support <example>, or at least when we have <example> to inspect the result rather than just to execute it.

How about removing the <example> pragma from the runDemo method in VGTigerDemo and rename it to example

and move this discussion after the release?

Sure. Or we can have <script> which I already committed, but I am fine with the comment.

There is great value that comes from the simple and clearly defined

...

concept of <example>.

I think this discussion shows that the purpose of the <example> pragma is not "a simple and clearly defined concept" :)

I think the concept is straightforward enough that it could be nicely summarized both by you and by Torsten :). I think it's not the concept that is the problem but that we historically built tools to deal with fuzzy semantics and now it's hard to let go of them :) Cheers, Doru

Nicolai

...

Cheers, Doru

On Tue, Mar 24, 2015 at 8:56 PM, Torsten Bergmann <astares@gmx.de> wrote:

...

Hi Tudor and all,

to understand the issue one has to know:

------------------------------------------------------------------------------------------ There are two pragmas in Pharo 4 that were already introduced and integrated:

<script> / <script:> - one can use this to mark methods (of any signature) as development scripts. One can use it on instance side and an class side methods to run the method or some code while developing without having to leave the browser. After completion Nautilus shows that the method finished

Think of a class "MyKillerProjectDatabase" with a class side method "start". You can click this to run - but it does not serve as an example. A script is just "SOMETHING TO RUN". The code of the script may be too easy or to complicated to serve as an example.

See also #14647, #14747 and #14995 for details.

<example> - Nautilus in the past already honored class side exampleXXX methods to have a "play" icon to easily visually see examples and just run them.

With the <example> pragma one can explicitly mark a method as an example method and we do not have to rely on the method name. So we can use #tryThisOutForExample as selector name as well now.

It also allows to search for examples, build an example browser for newbees, ...

An example shows the usage of a class or code (usually to get an initial idea). The pragma also only works on class side methods.

Think of existing classes like EditableList or WidgetExamples that provide example methods starting with exampleXXX. The user sees in the browser directly that this is an example he can run or look at to understand the details because the author offered it as "SOMETHING TO LEARN FROM".

See also #14646 and #15225 for details

So (even only at the second look) there is a distinction between a "script" and an "example". Being a script does not automagically make a method an example. And yes: a method can also be both and both pragmas can be used.

The history of these two is explained in https://pharo.fogbugz.com/f/cases/15225/useless-play-icon-in-nautilus and I already use this in several projects.

--------------------------------------------------------------------------------------------

Now it looks like Tudor is in need of a pragma for GT tools to provide "example data".

@Tudor: I do not understand why you now abuse/try to redefine the meaning of this existing <example> pragma for your special purposes/needs or try to exchange one against the other as in new issue #15229.

According to your own comment in issue #15225 your definition of an "example" is something "to offer an initialized object that can be used for documentation or testing purposes."

I have to strongly disagree on this as this is ONLY TRUE FOR A FEW CASES. Look at our image, look at how people write example (methods):

NOT ALL class side example methods necessarily return an initialized objects but are still examples. I already explained in the above issue that there are lots of example methods that one just run (either from the comment or from Nautilus icon) like EditableListExampel(class)>>example, ... They DO NOT return an initialized instance.

Look at the "examples" in class WidgetExamples or others. None of them provide an initialized instance!

So the right definition for an "example" is: "to offer runnable code that can be used for documentation or testing purposes."

So PLEASE if you are in need of such a new thing where only initialized instances are returned from code then DO NOT REDEFINE existing and used pragmas like the integrated <example> pragma.

PLEASE use an OWN NEW PRAGMA for GT purposes like <exampleData>, <exampleInstance>, <gtExampleInstance> or whatever. I would also find an "exampleInstance" pragma name then more intention revealing.

Thanks a lot in in advance!

Bye T.

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com "Every thing has its own flow"

Hi Torsten, I think there can be some value in having example code that shows things beyond just returning an object. However, I think there is significantly more value in examples that do return objects. That is why I would want to have example for the more valuable piece, and to eliminate confusions I would not even call the others example, but another word, like script: exampleThatReturnsOneObject <example> ^ ... snippetThatDoesOrShowsSomething <script> / <exampleScript> / <exampleCode> ^ ... I still think that <script> is enough. The goal of these methods is to get the person to run them and observe the side effect, without reusing the result. That is what scripts typically do. It should be enough. As for the example* methods, most of them can be nicely decomposed into an <example> and possibly a <script>. It would be enough. Here is more reasons why I would not change <example> now. Until now, nobody is really using the <example> except the code that is packaged in GT. The only problematic part is: TigerDemo>> runDemo <example> ^ self new runDemo But this one does not even fit your definition of an example of code. It's merely a way to trigger the running of the instance. It so happens that the class is an example for something else, but this code is not an example. It's a script. So, it should be: TigerDemo>> runDemo <script> ^ self new runDemo (this solution is already committed in the Athens repo) This would not even be a new interpretation. In the image, there already exists scripts that trigger an example class: DynamicSpecExample>> openOnNil <script: '(DynamicSpecExample object: nil) open'> ... ui openWithSpecLayout: layout. Btw, the <example> check in the CompiledMethod>>isExampleMethod was added after the discussion about introducing <example> and this tended to unify the meaning with the current example* selectors. We did not catch this distinction at that time, but it is clearly a mismatch. So, the actual intention of <example> did not change at all, but isExampleMethod enforces a new contract on the original one. So, really, let's not make a larger thing than we have to out of this. We really have *one* problem that is not even a problem. The solution from Athens should be fine now, and we could remove the <example> pragma check from isExampleMethod for now. Cheers, Doru On Wed, Mar 25, 2015 at 9:57 AM, Torsten Bergmann <astares@gmx.de> wrote:

Hi Tudor,

stay serious: the methods you are talking about were introduced as GT extension following YOUR definition of an example.

We could argue what/who was first with <example>, who discussed/patented it first, who has to change the most code now ... but would it move us forward? We do not need a long discussion, we need a solution.

The situation is that we have a conflict in the usage of <example> Pragma:

We wanted a way to find out the examples given in methods (often hidden in the image and external packages) and also remove the limitation that they have to start with exampleXXX. So I took action to be able to explicitly mark methods that are intended by the author as an "example" by using the <example> pragma. This was integrated in Pharo 4 and is also in use, not in the image but in loadable packages already. My definition of an example is "a general code example".

You had another discussion in the context of GT Tools about renaming the <gtExample> into <example> and also meanwhile took action to use use <example>.

But you also put the ADDITIONAL meaning behind the pragma that methods marked with <example> should always return an initialized object.

And this last part is the only part where our point of views collide. There is no need to explain from your side that it is often valuable to have such example methods that return initialized instance. One can use them to construct other initialized instances, ...

Anything I say is that not all "examples" and "example methods" are providing such example instances. So we can not (and should not) ignore the fact that not all methods intended by the author as "examples" follow this additional definition/requirement.

So the only difference in our point of view is that you want to mark all of them equally with <example> and assume that all of them return an instance of the same class while I will not because not all examples do that. Some of them are just example methods to demonstrate how to use the class or combine objects or do some action where the return value of the method is uninteresting.

So in your definition of <example> pragma you talk about the need for marking methods with "example instances" while I talk about more general examples (examples of code) that can but do not necessarily have to provide such initialized instances.

So my proposal is simple and should satisfy both needs: =======================================================

1. The <example> Pragma can used to mark a method as an "example" method. An example is a method that is intended as an "example of code":

tryThisOut <example>

Transcript show: 'An example on how to write to the transcript'

2. The <exampleInstance> Pragma can be used to mark methods that return an an example instance:

anInstanceA <exampleInstance>

^$A

This will solve the issue easily and it will be more clear as THE INTENTION OF THE PRAGMA in both cases FITS WITH THE NAME. Also a tool can query for one or both pragmas and decide if if it wants to inspect/display the result after performing the method or just run it.

So this is my proposal to satisfy both POV's. You can argue agains it but not without making another proposal that satisfies both needs.

Thanks T.

-- www.tudorgirba.com "Every thing has its own flow"

The word example is based on previous research. For example: - Modeling Examples to Test and Understand Software, Markus Gaelli, PhD Thesis, 2006 http://scg.unibe.ch/archive/phd/gaelli-phd.pdf - JExample: Exploiting Dependencies Between Tests to Improve Defect Localization, Kuhn etal, 2008 http://scg.unibe.ch/archive/papers/Kuhn08aJExample.pdf (Phexample is also available on SmalltalkHub) The idea is that you learn from concrete (examples) to abstract, and objects are but examples of classes. I think this is a powerful concept that is underutilized and I also think that we will see more of it in the future if we support it a first class concept in our tools. Nevertheless, please, let's focus on the release that comes in a few days. Cheers, Doru On Wed, Mar 25, 2015 at 1:40 PM, Ben Coman <btc@openinworld.com> wrote:

On Wed, Mar 25, 2015 at 7:34 PM, Tudor Girba <tudor@tudorgirba.com> wrote:

...

Hi Torsten,

I think there can be some value in having example code that shows things beyond just returning an object. However, I think there is significantly more value in examples that do return objects. That is why I would want to have example for the more valuable piece, and to eliminate confusions I would not even call the others example, but another word, like script:

exampleThatReturnsOneObject <example> ^ ...

snippetThatDoesOrShowsSomething <script> / <exampleScript> / <exampleCode> ^ ...

I still think that <script> is enough. The goal of these methods is to get the person to run them and observe the side effect, without reusing the result. That is what scripts typically do. It should be enough. As for the example* methods, most of them can be nicely decomposed into an <example> and possibly a <script>. It would be enough.

I'm not sure of the correct solution, but this semantic doesn't feel right to me. I've never thought I needed to inspect the result of an example. An example "does something", like a doIt. I want it to "show" me something. If the aim of the example was to give an object to Inspect, then it should explicitly open an Inspector.

To me a script is definitely NOT an example. A script is something that provides convenience for performing system maintenance. For example, it might change system state by resetting a cache.

The word that I feel best applies to Doru's need is <sample>, to return a fully initialised sample instance that you can play with in the Inspector. When you double-click a method so tagged you can think of it as "give me a sample" of yourself.

cheers -ben

...

Here is more reasons why I would not change <example> now. Until now, nobody is really using the <example> except the code that is packaged in GT. The only problematic part is:

TigerDemo>> runDemo <example> ^ self new runDemo

But this one does not even fit your definition of an example of code. It's merely a way to trigger the running of the instance. It so happens that the class is an example for something else, but this code is not an example. It's a script. So, it should be: TigerDemo>> runDemo <script> ^ self new runDemo (this solution is already committed in the Athens repo)

This would not even be a new interpretation. In the image, there already exists scripts that trigger an example class: DynamicSpecExample>> openOnNil <script: '(DynamicSpecExample object: nil) open'> ... ui openWithSpecLayout: layout.

Btw, the <example> check in the CompiledMethod>>isExampleMethod was added after the discussion about introducing <example> and this tended to unify the meaning with the current example* selectors. We did not catch this distinction at that time, but it is clearly a mismatch. So, the actual intention of <example> did not change at all, but isExampleMethod enforces a new contract on the original one.

So, really, let's not make a larger thing than we have to out of this. We really have *one* problem that is not even a problem. The solution from Athens should be fine now, and we could remove the <example> pragma check from isExampleMethod for now.

Cheers, Doru

On Wed, Mar 25, 2015 at 9:57 AM, Torsten Bergmann <astares@gmx.de> wrote:

...

Hi Tudor,

stay serious: the methods you are talking about were introduced as GT extension following YOUR definition of an example.

We could argue what/who was first with <example>, who discussed/patented it first, who has to change the most code now ... but would it move us forward? We do not need a long discussion, we need a solution.

The situation is that we have a conflict in the usage of <example> Pragma:

We wanted a way to find out the examples given in methods (often hidden in the image and external packages) and also remove the limitation that they have to start with exampleXXX. So I took action to be able to explicitly mark methods that are intended by the author as an "example" by using the <example> pragma. This was integrated in Pharo 4 and is also in use, not in the image but in loadable packages already. My definition of an example is "a general code example".

You had another discussion in the context of GT Tools about renaming the <gtExample> into <example> and also meanwhile took action to use use <example>.

But you also put the ADDITIONAL meaning behind the pragma that methods marked with <example> should always return an initialized object.

And this last part is the only part where our point of views collide. There is no need to explain from your side that it is often valuable to have such example methods that return initialized instance. One can use them to construct other initialized instances, ...

Anything I say is that not all "examples" and "example methods" are providing such example instances. So we can not (and should not) ignore the fact that not all methods intended by the author as "examples" follow this additional definition/requirement.

So the only difference in our point of view is that you want to mark all of them equally with <example> and assume that all of them return an instance of the same class while I will not because not all examples do that. Some of them are just example methods to demonstrate how to use the class or combine objects or do some action where the return value of the method is uninteresting.

So in your definition of <example> pragma you talk about the need for marking methods with "example instances" while I talk about more general examples (examples of code) that can but do not necessarily have to provide such initialized instances.

So my proposal is simple and should satisfy both needs: =======================================================

1. The <example> Pragma can used to mark a method as an "example" method. An example is a method that is intended as an "example of code":

tryThisOut <example>

Transcript show: 'An example on how to write to the transcript'

2. The <exampleInstance> Pragma can be used to mark methods that return an an example instance:

anInstanceA <exampleInstance>

^$A

This will solve the issue easily and it will be more clear as THE INTENTION OF THE PRAGMA in both cases FITS WITH THE NAME. Also a tool can query for one or both pragmas and decide if if it wants to inspect/display the result after performing the method or just run it.

So this is my proposal to satisfy both POV's. You can argue agains it but not without making another proposal that satisfies both needs.

Thanks T.

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com "Every thing has its own flow"

On Wed, Mar 25, 2015 at 5:32 PM, Torsten Bergmann <astares@gmx.de> wrote:

I would like to see more opinions or proposals from others. ;)

I agree with Doru. Just checked the image and it seems that there is already quite a number of methods with <example> annotation that behave exactly the same behaviour described by Doru. So maybe we could continue having <example> to show how to create a valid instance of the class that have some value and can work? One benefit is that we could based on <example> show some usefull preview of the class in inspector. Assume having a MultistateButtonMorph with <example> pragma. You can inspect MultistateButtonMorph (class) and will get as preview morph instance of the button. Cheers, Alex

Alex wrote:

I agree with Doru. Just checked the image and it seems that there is already quite a number of methods with <example> annotation that behave exactly >the same behaviour described by Doru.

Yes - there are more for a simple reason: because Doru created them according to HIS OWN definition to solely return instances. And they come in as GT extension methods. Would my opinion/points are more valid if we had more examples tagged <example> tags to mark all example methods?

So maybe we could continue having <example> to show how to create a valid instance of the class that have some value and can work? One benefit is that we could based on <example> show some usefull preview of the class in inspector.

The point is that we could do this preview with <exampleInstance> or <exemplar> as well! We do not lose anything! So with two different tags: - <example> for general examples - and <exemplar> <exampleInstance> for valid instances we would catch TWO FLIES INSTEAD OF JUST ONE: we would not be dependent on exampleXXX selector naming to mark example methods as it is now also in Pharo 4 AND we could do the preview in the new GT tools!!! Also with <exampleInstance> or <exemplar> we would also make it more clear that it returns an instance for a preview! In non-technical terms this would be a WIN-WIN for Tudor and me ;)  

Assume having a MultistateButtonMorph with <example> pragma. You can inspect MultistateButtonMorph (class) and will get as preview morph instance of the button.

It is not that I do not understand this. I know that by providing instance examples this would also be a step forward on the GT/tools side. I would not like to see only ONE step backward and only ONE forward when we can do TWO MOVES forward. Is this so hard to understand? If Tudor agrees on either <examplar> <sample> or <exampleInstance> he will get a beer. Should I buy you a beer as well to convince you? ;) Thx T.

stepharo wrote:

I'm confused. Did you use the <example> pragmas before?

Yes, this was already integrated in Pharo 4 since several weeks. It allows marking an class side method without relying on the exampleXXX pattern. Maybe I should have made more noise about it. So you can have a class side example method to demonstrate or give something to others to learn: tryThisOut <example> ... without having to rely on the exampleXXX pattern. Nautilus honors this the same way as for exampleXXX methods with a play icon that one can click and that executes the example. No need to have or select "self tryThisOut" in a comment. And you can choose selector names you like and that are good for your users like "simpleExampleToTryOut" or "confusingExampleToDisplay". It would also allow us collect all example methods easily and display them in an example browser for newbees they can use to go through all example methods and learn from the code. Tudor in parallel worked on <gtExample> and unfortunately changed this to <example> afterwards as well (maybe upon your request). He has a new feature that when you open an inspector on a class you can see "example instances" of that class in a new tab. For this to work he needed also a pragma - by choosing the same name we got this conflict in the pragmas. But it is not about who was first - it is about correct naming. This new feature in GT requires a method to return "example instances" - thats why I suggested to use a better name like <exampleInstance> or just <exemplar>. With this we would be clear in naming, would not conflict and be sove both issues (the new preview and not relying on exampleXXX for example methods). I would neither like to loose the fix that I already provided and that was integrated nor the nice work of Tudor.

I'm ok with exemplar too.

Attached is a changeset "GTExemplars.1.cs" that: - changes the GT use of <example>, <example:> and <exampleFrom:> to <exemplar> and <exemplar:> and <exemplarFrom:> - it also uses correct method naming for the returned exemplars/sample instances of the class, for instance #gtExampleSimple -> simpleExemplar - it also changes GTExample -> GTExemplar, GTExampleExtractionStrategy -> GTExamplarExtractionStrategy, ... and also uses ...exemplar... instead of ...example... for the methods and temporaries in these classes. With this changeset the new feature does not conflict. The changeset is based on Pharo4.0 Latest update: #40582 as of today and when quickly integrated this should be easy to fileIn/integrate into the externally managed GT tools as well as the image. With this integrated into GT/Pharo 4 we would not conflict and make things clear: 1. we use the term "example" for regular Smalltalk code examples as most of us knows from the past either in an exampleXXX method or with the <example> pragma. 2. And we can use the concept and term "exemplar" to return instances/exemplars of a class and browse them with the new preview feature Tudor introduced. "Give me an exemplar of class Character, give me an exemplar of class String, ..." => I'll leave the decison to the community or finally the board to integrate this as I communicated my points and reasons now often enough including an attached ready to be integrated solution. I did my homework now and leave this to others to decide and either deny it or open a bug to integrate.

PS: From far it looks like a bikeshed discussion :)

May be. But I'm very serious about this as you see because getting names and concepts right is often the hardest part. And it would be hard to change after the release because people will use it already. Bye T.

Hi Torsten, We will rename <example> back to <gtExample> and keep the API as it is. That will leave Pharo 4 with one <example> method while the other 100 will use <gtExample>. This will be available with the next GT integration. The decision has nothing to do with arguments. This discussion managed to sadden me and I will not continue it anymore. The release is too important and we got distracted from the goal. I wish you all a peaceful night. Doru On Wed, Mar 25, 2015 at 10:54 PM, Torsten Bergmann <astares@gmx.de> wrote:

stepharo wrote:

...

I'm confused. Did you use the <example> pragmas before?

Yes, this was already integrated in Pharo 4 since several weeks. It allows marking an class side method without relying on the exampleXXX pattern. Maybe I should have made more noise about it.

So you can have a class side example method to demonstrate or give something to others to learn:

tryThisOut <example> ...

without having to rely on the exampleXXX pattern.

Nautilus honors this the same way as for exampleXXX methods with a play icon that one can click and that executes the example. No need to have or select "self tryThisOut" in a comment. And you can choose selector names you like and that are good for your users like "simpleExampleToTryOut" or "confusingExampleToDisplay".

It would also allow us collect all example methods easily and display them in an example browser for newbees they can use to go through all example methods and learn from the code.

Tudor in parallel worked on <gtExample> and unfortunately changed this to <example> afterwards as well (maybe upon your request). He has a new feature that when you open an inspector on a class you can see "example instances" of that class in a new tab.

For this to work he needed also a pragma - by choosing the same name we got this conflict in the pragmas.

But it is not about who was first - it is about correct naming. This new feature in GT requires a method to return "example instances" - thats why I suggested to use a better name like <exampleInstance> or just <exemplar>.

With this we would be clear in naming, would not conflict and be sove both issues (the new preview and not relying on exampleXXX for example methods).

I would neither like to loose the fix that I already provided and that was integrated nor the nice work of Tudor.

...

I'm ok with exemplar too.

Attached is a changeset "GTExemplars.1.cs" that:

- changes the GT use of <example>, <example:> and <exampleFrom:> to <exemplar> and <exemplar:> and <exemplarFrom:> - it also uses correct method naming for the returned exemplars/sample instances of the class, for instance #gtExampleSimple -> simpleExemplar - it also changes GTExample -> GTExemplar, GTExampleExtractionStrategy -> GTExamplarExtractionStrategy, ... and also uses ...exemplar... instead of ...example... for the methods and temporaries in these classes.

With this changeset the new feature does not conflict. The changeset is based on Pharo4.0 Latest update: #40582 as of today and when quickly integrated this should be easy to fileIn/integrate into the externally managed GT tools as well as the image.

With this integrated into GT/Pharo 4 we would not conflict and make things clear:

1. we use the term "example" for regular Smalltalk code examples as most of us knows from the past either in an exampleXXX method or with the <example> pragma.

2. And we can use the concept and term "exemplar" to return instances/exemplars of a class and browse them with the new preview feature Tudor introduced. "Give me an exemplar of class Character, give me an exemplar of class String, ..."

=> I'll leave the decison to the community or finally the board to integrate this as I communicated my points and reasons now often enough including an attached ready to be integrated solution.

I did my homework now and leave this to others to decide and either deny it or open a bug to integrate.

...

PS: From far it looks like a bikeshed discussion :)

May be. But I'm very serious about this as you see because getting names and concepts right is often the hardest part. And it would be hard to change after the release because people will use it already.

Bye T.

-- www.tudorgirba.com "Every thing has its own flow"

What happened to "The needs of the many outweigh the needs of the few" - LLAP ?

On 25 Mar 2015, at 23:28, Tudor Girba <tudor@tudorgirba.com> wrote:

Hi Torsten,

We will rename <example> back to <gtExample> and keep the API as it is. That will leave Pharo 4 with one <example> method while the other 100 will use <gtExample>. This will be available with the next GT integration.

The decision has nothing to do with arguments. This discussion managed to sadden me and I will not continue it anymore. The release is too important and we got distracted from the goal.

I wish you all a peaceful night.

Doru

On Wed, Mar 25, 2015 at 10:54 PM, Torsten Bergmann <astares@gmx.de> wrote: stepharo wrote:

...

I'm confused. Did you use the <example> pragmas before?

Yes, this was already integrated in Pharo 4 since several weeks. It allows marking an class side method without relying on the exampleXXX pattern. Maybe I should have made more noise about it.

So you can have a class side example method to demonstrate or give something to others to learn:

tryThisOut <example> ...

without having to rely on the exampleXXX pattern.

Nautilus honors this the same way as for exampleXXX methods with a play icon that one can click and that executes the example. No need to have or select "self tryThisOut" in a comment. And you can choose selector names you like and that are good for your users like "simpleExampleToTryOut" or "confusingExampleToDisplay".

It would also allow us collect all example methods easily and display them in an example browser for newbees they can use to go through all example methods and learn from the code.

Tudor in parallel worked on <gtExample> and unfortunately changed this to <example> afterwards as well (maybe upon your request). He has a new feature that when you open an inspector on a class you can see "example instances" of that class in a new tab.

For this to work he needed also a pragma - by choosing the same name we got this conflict in the pragmas.

But it is not about who was first - it is about correct naming. This new feature in GT requires a method to return "example instances" - thats why I suggested to use a better name like <exampleInstance> or just <exemplar>.

With this we would be clear in naming, would not conflict and be sove both issues (the new preview and not relying on exampleXXX for example methods).

I would neither like to loose the fix that I already provided and that was integrated nor the nice work of Tudor.

...

I'm ok with exemplar too.

Attached is a changeset "GTExemplars.1.cs" that:

- changes the GT use of <example>, <example:> and <exampleFrom:> to <exemplar> and <exemplar:> and <exemplarFrom:> - it also uses correct method naming for the returned exemplars/sample instances of the class, for instance #gtExampleSimple -> simpleExemplar - it also changes GTExample -> GTExemplar, GTExampleExtractionStrategy -> GTExamplarExtractionStrategy, ... and also uses ...exemplar... instead of ...example... for the methods and temporaries in these classes.

With this changeset the new feature does not conflict. The changeset is based on Pharo4.0 Latest update: #40582 as of today and when quickly integrated this should be easy to fileIn/integrate into the externally managed GT tools as well as the image.

With this integrated into GT/Pharo 4 we would not conflict and make things clear:

1. we use the term "example" for regular Smalltalk code examples as most of us knows from the past either in an exampleXXX method or with the <example> pragma.

2. And we can use the concept and term "exemplar" to return instances/exemplars of a class and browse them with the new preview feature Tudor introduced. "Give me an exemplar of class Character, give me an exemplar of class String, ..."

=> I'll leave the decison to the community or finally the board to integrate this as I communicated my points and reasons now often enough including an attached ready to be integrated solution.

I did my homework now and leave this to others to decide and either deny it or open a bug to integrate.

...

PS: From far it looks like a bikeshed discussion :)

May be. But I'm very serious about this as you see because getting names and concepts right is often the hardest part. And it would be hard to change after the release because people will use it already.

Bye T.

-- www.tudorgirba.com

"Every thing has its own flow"

Ok… my 2c: Basically there is a difference between an “example” and a prototype, which is what the gtExample intends to do. Exemplar is just another way to name a prototype. Sorry to make you sad and tired… but when you introduce such an important new tool as all the gtools are, you cannot expect people to accept all your choices “as is”… and debate is the only way to achieve some consensus. Esteban ps: we are just days from release and we are all stressed a lot… so lets take a breath and consider things with the appropriate distance. We are not talking about the cure for cancer here, just the right name for a pragma, in a method.

On 26 Mar 2015, at 10:02, Torsten Bergmann <astares@gmx.de> wrote:

Hi Tudor,

...

We will rename <example> back to <gtExample> and keep the API as it is. That will leave Pharo 4 with one <example> method while the other 100 will >use <gtExample>. This will be available with the next GT integration.

As I already wrote (and Guillermo equally pointed out): most of them are there because you created/introduced many extension methods with GT to provide these sample instances like in $a for Charater or 42 for Integer, ... Which is completely valid to demonstrate how usefull your new extension is. But it is because you investigated so far more to demonstrate this new mechanism.

And yes, currently we have just one <example> in the image (beside some other in external projects). But if we do not want to rely on the exampleXXX pattern anymore we will mark the typical example methods with <example> in the future and would have around 140 in the latest image:

|coll| coll := IdentitySet new. Object withAllSubclassesDo: [:aClass | aClass class selectorsDo: [:selector | (selector beginsWith: 'example') ifTrue: [ coll add: selector ] ]]. ^coll

If we dont mark them I agree that there are only a few counterwise.

But again: from my side it is not about the current numbers. It is about the future mechanism, clear and understandable concepts and naming.

The usualy exampleXXX demos for code fits well with <example> from the name and mentally. "Example" is a very generous term for something to look at and learn.

In Pharo one can now demonstrate in the new GT inspector lively ready made instances! You feature and the research bound to it is not only important but a real improvement. I like that and I'm sure this will push us forward a lot.

Still IMHO mentally using <example> for depicting "code to look at" does fit namewise and conceptualy very well with the known and usual example methods in the image or external packages. Some of them provide an instance, but many of them just show how to use code.

And yes: I would the new GT mechanism to use a term and pragma name that better depicts what should be provided from the one who uses it: typical example instances or exemplars of the class.

When one creates a class

Object subclass: #RevolutionarySystem instanceVariableNames: 'name' classVariableNames: '' category: 'The-World'

he can implement a class side method to use the new mechanism:

uniqueExemplar <exemplar>

^RevolutionarySystem called: 'Pharo'

And this class side method returns an exemplary instance. If such a method should also serves as an example method (in the tradition of a code example to look at) one can even mark it with both pragmas.

...

The decision has nothing to do with arguments.

Why do you negotiate instead of (at a minimum) ellaborate what you think of the made proposal to use "exemplar" for the new GT mechanism.

See the definition for <exemplar>:

http://dictionary.reference.com/browse/exemplar "a model or pattern to be copied or imitated" "a typical example or instance"

http://www.thefreedictionary.com/exemplar "One that is worthy of imitation; a perfect example or model" "One that is typical or representative"

http://www.merriam-webster.com/dictionary/exemplar "an admired person or thing that is considered an example that deserves to be copied" "a typical example"

http://www.ldoceonline.com/dictionary/exemplar "formal a good or typical example"

http://www.dict.cc/?s=exemplar "instance" "specimen" "sample"

All the 100 instances now returns by GT extension are such exemplars: they are typical instances like $a or 42 one can use as a model or pattern to be copied or imitated.

Would'nt that perfectly fit with what you intended with your new feature: the preview should help people to just inspect a class, look at the new "e.g." tab and learn from premade instances?

...

The release is too important and we got distracted from the goal.

No doubt that the release is important and fixing it NOW from the technical side is easy as I demonstrated with the changeset. I guess rolling back <gtExample> would take you more time than reviewing it.

Before doing any action on your side I would really like to know your opinion about <exemplar>. I'm fine when you can not accept it - but please tell me about the reasons.

Bye T.

Hi, I/we do not want to impose anything on anyone. <gtExample> was introduced a long time (more than 1 year) ago in GT/Moose. It is used both for documentation purposes and for generic stress tests for the Inspector and Spotter (and let's not even count that the concept offers an alternative to SUnit testing that we will pursue in the near future). It got integrated in Pharo and then renamed to <example> 6 months ago (in October) after a public discussion on this mailing list. It later got mixed with the example* selectors as part of #isExampleMethod and used in Nautilus with a looser interpretation to essentially trigger the example. This debate started 7 days before the release. The reason why the debate started is that exactly one method started to use it differently than all other <example> methods from the Pharo image. While this debate fired on, GT does not build and cannot be integrated, even though in parallel we work like mad to meet the deadline and fix all issues that are being reported. And the way the debate took place is also borderline for my taste, too. I do not appreciate being shout at. I am not mad, but please do not expect me to be happy either. I also find it discouraging that people talk about GT as if it would not be Pharo or as if we would want to force people to do things. We are indeed a standalone team with an own set of ideas, but we do not want to force our work on anyone. As the decision was to make GT a central part of Pharo, we kindly ask you to treat us as part of Pharo. We never shied away from debates and listening to people. In fact, we think we are going over the board with actively listening and reacting. We can still debate the <example>, but not now. We have a release to meet. We can talk about it afterwards. But, for this to happen, I also kindly ask you to remove the <example> check from #isExampleMethod. This would allow us to start from a clean slate in Pharo 5. Cheers, Doru On Thu, Mar 26, 2015 at 12:06 PM, Esteban Lorenzano <estebanlm@gmail.com> wrote:

Ok… my 2c:

Basically there is a difference between an “example” and a prototype, which is what the gtExample intends to do. Exemplar is just another way to name a prototype. Sorry to make you sad and tired… but when you introduce such an important new tool as all the gtools are, you cannot expect people to accept all your choices “as is”… and debate is the only way to achieve some consensus.

Esteban

ps: we are just days from release and we are all stressed a lot… so lets take a breath and consider things with the appropriate distance. We are not talking about the cure for cancer here, just the right name for a pragma, in a method.

...

On 26 Mar 2015, at 10:02, Torsten Bergmann <astares@gmx.de> wrote:

Hi Tudor,

...

We will rename <example> back to <gtExample> and keep the API as it is. That will leave Pharo 4 with one <example> method while the other 100 will use <gtExample>. This will be available with the next GT integration.

As I already wrote (and Guillermo equally pointed out): most of them are there because you created/introduced many extension methods with GT to provide these sample instances like in $a for Charater or 42 for Integer, ... Which is completely valid to demonstrate how usefull your new extension is. But it is because you investigated so far more to demonstrate this new mechanism.

And yes, currently we have just one <example> in the image (beside some other in external projects). But if we do not want to rely on the exampleXXX pattern anymore we will mark the typical example methods with <example> in the future and would have around 140 in the latest image:

|coll| coll := IdentitySet new. Object withAllSubclassesDo: [:aClass | aClass class selectorsDo: [:selector | (selector beginsWith: 'example') ifTrue: [ coll add: selector ] ]]. ^coll

If we dont mark them I agree that there are only a few counterwise.

But again: from my side it is not about the current numbers. It is about the future mechanism, clear and understandable concepts and naming.

The usualy exampleXXX demos for code fits well with <example> from the name and mentally. "Example" is a very generous term for something to look at and learn.

In Pharo one can now demonstrate in the new GT inspector lively ready made instances! You feature and the research bound to it is not only important but a real improvement. I like that and I'm sure this will push us forward a lot.

Still IMHO mentally using <example> for depicting "code to look at" does fit namewise and conceptualy very well with the known and usual example methods in the image or external packages. Some of them provide an instance, but many of them just show how to use code.

And yes: I would the new GT mechanism to use a term and pragma name that better depicts what should be provided from the one who uses it: typical example instances or exemplars of the class.

When one creates a class

Object subclass: #RevolutionarySystem instanceVariableNames: 'name' classVariableNames: '' category: 'The-World'

he can implement a class side method to use the new mechanism:

uniqueExemplar <exemplar>

^RevolutionarySystem called: 'Pharo'

And this class side method returns an exemplary instance. If such a method should also serves as an example method (in the tradition of a code example to look at) one can even mark it with both pragmas.

...

The decision has nothing to do with arguments.

Why do you negotiate instead of (at a minimum) ellaborate what you think of the made proposal to use "exemplar" for the new GT mechanism.

See the definition for <exemplar>:

http://dictionary.reference.com/browse/exemplar "a model or pattern to be copied or imitated" "a typical example or instance"

http://www.thefreedictionary.com/exemplar "One that is worthy of imitation; a perfect example or model" "One that is typical or representative"

http://www.merriam-webster.com/dictionary/exemplar "an admired person or thing that is considered an example that deserves to be copied" "a typical example"

http://www.ldoceonline.com/dictionary/exemplar "formal a good or typical example"

http://www.dict.cc/?s=exemplar "instance" "specimen" "sample"

All the 100 instances now returns by GT extension are such exemplars: they are typical instances like $a or 42 one can use as a model or pattern to be copied or imitated.

Would'nt that perfectly fit with what you intended with your new feature: the preview should help people to just inspect a class, look at the new "e.g." tab and learn from premade instances?

...

The release is too important and we got distracted from the goal.

No doubt that the release is important and fixing it NOW from the technical side is easy as I demonstrated with the changeset. I guess rolling back <gtExample> would take you more time than reviewing it.

Before doing any action on your side I would really like to know your opinion about <exemplar>. I'm fine when you can not accept it - but please tell me about the reasons.

Bye T.

-- www.tudorgirba.com "Every thing has its own flow"

Hi Tudor, Disclaimer: this mail is not intended to heat this up once again or insult you. It is meant to bring some more light into the darkness: we all can only decide on what we read and the actions that we see from others, sometimes a lot is not known from the other participants side. Exactly because of this let me tell you my side of the story: The discussion from October [1] between you and Stef happened in a thread "structuring widget examples" that I personally missed and did not follow. At around the same time I extended Nautilus so that (additionally to other clickable method icons one can also click on #exampleXXX and initialize method icons. We have around 140 of such exampleXXX methods in the image, also in many external packages (like Bloc). These exampleXXX methods are used to demonstrate Smalltalk/Pharo code and are a valuable source to learn from. When I announced this "click to run exampleXXX" feature on the list in October 2014 you welcomed and supported that idea [2]. I also heard the first time that we have an overlap in interest in making "examples" more visible in one way or the other. So we discussed about this solely in the context of example methods and I was as that time unaware of other GT related work in this regard. In this discussion you mentioned that being dependendent on the selector naming convention for the examples is not good and therefore you suggested that I extend my slice to use the <example> pragma for these clickable code examples. Lets repeat: what I defend here the whole time was your very own idea, not mine as one can read in the list archive [2]. I supported your opinion because it was and still is an improvement! The pragma <example> that you suggested to me for the traditional Smalltalk class side exampleXXX methods fitted perfectly also namewise and therefore got integrated as a valuable addition into the image. We shared the common view that using the <example> pragma is a cleaner way to mark "example methods". Anything was fine and I also happily used this pragma also in own external packages. I also wanted to go through all the example methods in the image to mark them with the <example> pragma and additionally provide an example browser for newbees based on the pragma as mentioned in the thread. But I was too busy to do it. So the simple reason for the low number of pragma usage in the standard image is that I had not yet time to do this. It was also not a pressuring task because #exampleXXX where clickable and the pragma infrastructure was in place to mark all other exampleXXX selectors or selectors like #niceExampleToTryOut. So it could be used at any point in time later. CI builds were green and the sun was shining for all of us... I was unaware (at that time) of one important thing and this discussion here and your mails now made it more clear: Stef asked you also back in October to use <example> instead of <gtExample> and you followed this - but on the other hand and also in October you suggested to me to use exactly the same pragma <example>. At that time nobody seem to have been aware of this upcoming name collision that was introduced with Stefs request to you for GT on one side and your suggestion to me for getting independent from exampleXXX on the other side. So in parallel you worked on a feature to "display sample instances" for a class in a new inspector tab ("e.g.") - for that the meaning behind the pragma marked methods was to return instances. You added more and more methods tagged with <example> on Character, String, ... to return samples like $a or 42. GT is one of the packages that is hosted "externally" and get resynchronized into Pharo from time to time using Configs. The image included the <example> pragma logic for the click action in Nautilus. And with each new integration of next GT versions into the standard Pharo image more and more <example> marked methods came in providing objects/instances. So it seems it was only a matter of time that this unfortunate "double usage" of the pragma showed their effects: Nicolai Hess wondered this week about a "useless play icon" in Nautilus and created issue #15225 four days ago [3] because when you execute a method that just returns an instance via the Nautilus icon nothing happens. To make it clear: it's not that someone like me - just for fun - wanted to debate about naming or reify examples discussion shortly before the release. We all just want to improve. The unfortunate timing of 7 days before the release came from the effects of colliding pragma usage/goals showing up now. You, Marcus and me commented in issue #15225. I commented this bug and explained about the common agreement of using <example> for exampleXXX and example methods to also allow different example selectors/method names. As an answer (and contrary to your own suggestion to me from October) you presented then a different definition of what an <example> means for you: Tudor Girba 24.03.2015 13:58 Uhr in issue #15225 "The semantics of <example> is to offer an initialized object that can be used for documentation or testing purposes." This sudden "redefinition" was very surprising to me and to be honest looked like a justification to meet the needs of the new inspector feature introduced to Pharo solely. And it is a redefinition as for sure it was not what was discussed/what was suggested by you to me in October 2014 for the usage of <example> Therefore I took this out of the bugtracker onto the dev-list: - because this showed up so late and shortly before the release (assuming that when we introduce the wrong this will be used and hard to change afterwards) - and to avoid that this stayed hidden in the bug tracker - we all have further misunderstandings on the pragma usage and the definition what methods to depict as example. In your first initial response on this thread here in the mailinglist [4] you claimed that it was me who would be "putting <example> and example* selectors in the same pot" now. But it was not me - it was you in October 2014 who defined it exactly that way and urged me to integrate this in my slice as we see in [2]. And similar to the bugtracker you wrote on the list that you "do not redefine anything" while in the same post presented the definition that an "<example> returns an initialized object" by your definition once again. It was that writing that once again made me think: "how can Tudor ignore our discussion, throw his own suggestion from October away and now decide for a new semantics on his own?". Additionally one of the arguments on your side were that there were already 96 method annotated that way. But I dont want to count who was more busy on either side in annotating methods. I wanted and still want a solution that fits both improvements including proper naming. And I was really perplex when you then commented in the evening in the issue #15225: "As there was no complain, we proceeded as agreed and this should be the expected status quo for this release." without all of us participating here having at least a certain degree of agreement. Leaving out the community and wondering that the discussion fires up again? Also you stated that "nobody" is using the <example>, completely ignoring that I already mentioned to you that I did because we agreed on that in October, it was available since then and I mostly work in Pharo4 already. Yes - not yet as part of the image but in a few external packages already. To me that really looked like while we were in complete agreement first now nothing what I say in this whole topic now counts for you ... Your side of the story may be different than mine - nonetheless I wanted to tell you my point of view in the hope you understand why I wrote what I wrote here. Please reread all what is said with that knowledge. My intention was and still is to preserve this initial definition of <example> as in the October discussion as it solves the problem to not rely on the method name for the example methods. And we should find a proper pragma name for the needs to tag instance returning methods for the new inspector feature or more research on that topic of using such instances. I made a proposal, others suggested proposals as well. But you did not write one single line if or why they are inacceptable for you, you only answered in general or with "then we go back to gtExample" (which would also steal your time similar to fixing it right now). I tried to support with a changeset so that it is less work on your side, also no feedback on this. I tried hard and I'm not mad either!

From all that my impression grew and grew that you want to now reserve the <example> solely for the new initialized object semantics or you will completely return back to <gtExample> if we do not follow you on this.

You said the whole discussion made you unhappy. Do you think it made me happy? Definitely not. I hope the above details explains it well enough the story from my side! You can accuse me for being too harsh with my mails - which was bad from my side but it was because I was hardly trying to defend your own suggestion from October! Also I do not know where you got the impression that GT is treated as an "Alien" or something not belonging to Pharo. Do you really believe I would invest many hours to try out, give feedback to shape a HelpTopic Spotter addition, use GT for improving Pillar [6] or even build a MongoBrowser [7] and describe this in a lengthy article [8] when I would see GT as something in the outer space of the Pharo universe? Since I started this thread and the discussion I like you to know: I APOLOGIZE when this was discussed to harsh, has stolen too much time or when you feel offended from things said during the discussion. Our community members only rarely meet in person to discuss things and email often is a useful but sometimes also horrible medium. I first was unsure if I should response to this thread again: raising the risk of adding more oil to the water of upsetting each other even more. But the Pharo Zen says: "Communication is key", "Learning from mistakes" and "One step at a time". This situation is still not ideal or solved for the release. I would like to see still two steps forward instead of rolling back. Several proposals were made: 1. use <example> as agreed in October for exampleXXX methods/example methods with different selectors and use <exemplar> for the instance returning methods that I proposed (including a changeset) Stef said it would be OK for him 2. use <exampleOfInstance> and <exampleOfInstance:> as Kilon suggested 3. use <exampleCode> for code examples and <exampleInstance> for the GT extension as Andreas/Christophe suggested 4. use <sample> For sure we can have others. If they are inacceptable for you then shortly elaborate on why or what could be seen as acceptable solution from your side. Pharo belongs to all of us. Thanks in advance if you do so! Bye T. [1] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2014-October/1013... [2] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2014-October/01... [3] https://pharo.fogbugz.com/f/cases/15225 [4] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583... [5] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583... [6] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/0171... [7] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/0176... [8] https://medium.com/concerning-pharo/building-a-mongo-browser-in-pharo-fe2104...     Gesendet: Donnerstag, 26. März 2015 um 14:30 Uhr Von: "Tudor Girba" <tudor@tudorgirba.com> An: "Esteban Lorenzano" <estebanlm@gmail.com> Cc: "Stéphane Ducasse" <stephane.ducasse@inria.fr>, "Pharo Development List" <pharo-dev@lists.pharo.org> Betreff: Re: [Pharo-dev] Existing <script> <example> pragmas and new GT needs Hi,   I/we do not want to impose anything on anyone.   <gtExample> was introduced a long time (more than 1 year) ago in GT/Moose. It is used both for documentation purposes and for generic stress tests for the Inspector and Spotter (and let's not even count that the concept offers an alternative to SUnit testing that we will pursue in the near future). It got integrated in Pharo and then renamed to <example> 6 months ago (in October) after a public discussion on this mailing list. It later got mixed with the example* selectors as part of #isExampleMethod and used in Nautilus with a looser interpretation to essentially trigger the example.   This debate started 7 days before the release. The reason why the debate started is that exactly one method started to use it differently than all other <example> methods from the Pharo image. While this debate fired on, GT does not build and cannot be integrated, even though in parallel we work like mad to meet the deadline and fix all issues that are being reported.   And the way the debate took place is also borderline for my taste, too. I do not appreciate being shout at. I am not mad, but please do not expect me to be happy either.   I also find it discouraging that people talk about GT as if it would not be Pharo or as if we would want to force people to do things. We are indeed a standalone team with an own set of ideas, but we do not want to force our work on anyone. As the decision was to make GT a central part of Pharo, we kindly ask you to treat us as part of Pharo.   We never shied away from debates and listening to people. In fact, we think we are going over the board with actively listening and reacting. We can still debate the <example>, but not now. We have a release to meet. We can talk about it afterwards. But, for this to happen, I also kindly ask you to remove the <example> check from #isExampleMethod. This would allow us to start from a clean slate in Pharo 5.   Cheers, Doru       On Thu, Mar 26, 2015 at 12:06 PM, Esteban Lorenzano <estebanlm@gmail.com> wrote:Ok… my 2c: Basically there is a difference between an “example” and a prototype, which is what the gtExample intends to do. Exemplar is just another way to name a prototype. Sorry to make you sad and tired… but when you introduce such an important new tool as all the gtools are, you cannot expect people to accept all your choices “as is”… and debate is the only way to achieve some consensus. Esteban ps: we are just days from release and we are all stressed a lot… so lets take a breath and consider things with the appropriate distance. We are not talking about the cure for cancer here, just the right name for a pragma, in a method.

On 26 Mar 2015, at 10:02, Torsten Bergmann <astares@gmx.de[astares@gmx.de]> wrote:

Hi Tudor,

...

We will rename <example> back to <gtExample> and keep the API as it is. That will leave Pharo 4 with one <example> method while the other 100 will >use <gtExample>. This will be available with the next GT integration.

As I already wrote (and Guillermo equally pointed out): most of them are there because you created/introduced many extension methods with GT to provide these sample instances like in $a for Charater or 42 for Integer, ... Which is completely valid to demonstrate how usefull your new extension is. But it is because you investigated so far more to demonstrate this new mechanism.

And yes, currently we have just one <example> in the image (beside some other in external projects). But if we do not want to rely on the exampleXXX pattern anymore we will mark the typical example methods with <example> in the future and would have around 140 in the latest image:

|coll| coll := IdentitySet new. Object withAllSubclassesDo: [:aClass |       aClass class selectorsDo: [:selector |            (selector  beginsWith: 'example') ifTrue: [ coll add: selector ] ]]. ^coll

If we dont mark them I agree that there are only a few counterwise.

But again: from my side it is not about the current numbers. It is about the future mechanism, clear and understandable concepts and naming.

The usualy exampleXXX demos for code fits well with <example> from the name and mentally. "Example" is a very generous term for something to look at and learn.

In Pharo one can now demonstrate in the new GT inspector lively ready made instances! You feature and the research bound to it is not only important but a real improvement. I like that and I'm sure this will push us forward a lot.

Still IMHO mentally using <example> for depicting "code to look at" does fit namewise and conceptualy very well with the known and usual example methods in the image or external packages. Some of them provide an instance, but many of them just show how to use code.

And yes: I would the new GT mechanism to use a term and pragma name that better depicts what should be provided from the one who uses it: typical example instances or exemplars of the class.

When one creates a class

    Object subclass: #RevolutionarySystem        instanceVariableNames: 'name'        classVariableNames: ''        category: 'The-World'

he can implement a class side method to use the new mechanism:

    uniqueExemplar        <exemplar>

       ^RevolutionarySystem called: 'Pharo'

And this class side method returns an exemplary instance. If such a method should also serves as an example method (in the tradition of a code example to look at) one can even mark it with both pragmas.

...

The decision has nothing to do with arguments.

Why do you negotiate instead of (at a minimum) ellaborate what you think of the made proposal to use "exemplar" for the new GT mechanism.

See the definition for <exemplar>:

http://dictionary.reference.com/browse/exemplar[http://dictionary.reference.com/browse/exemplar]    "a model or pattern to be copied or imitated"    "a typical example or instance"

http://www.thefreedictionary.com/exemplar[http://www.thefreedictionary.com/exemplar]    "One that is worthy of imitation; a perfect example or model"    "One that is typical or representative"

http://www.merriam-webster.com/dictionary/exemplar[http://www.merriam-webster.com/dictionary/exemplar]    "an admired person or thing that is considered an example that deserves to be copied"    "a typical example"

http://www.ldoceonline.com/dictionary/exemplar[http://www.ldoceonline.com/dictionary/exemplar]    "formal a good or typical example"

http://www.dict.cc/?s=exemplar[http://www.dict.cc/?s=exemplar]    "instance"    "specimen"    "sample"

All the 100 instances now returns by GT extension are such exemplars: they are typical instances like $a or 42 one can use as a model or pattern to be copied or imitated.

Would'nt that perfectly fit with what you intended with your new feature: the preview should help people to just inspect a class, look at the new "e.g." tab and learn from premade instances?

...

The release is too important and we got distracted from the goal.

No doubt that the release is important and fixing it NOW from the technical side is easy as I demonstrated with the changeset. I guess rolling back <gtExample> would take you more time than reviewing it.

Before doing any action on your side I would really like to know your opinion about <exemplar>. I'm fine when you can not accept it - but please tell me about the reasons.

Bye T.

    -- www.tudorgirba.com[http://www.tudorgirba.com]   "Every thing has its own flow"

On Sat, Mar 28, 2015 at 5:00 AM, Sean P. DeNigris <sean@clipperadams.com> wrote:

Torsten Bergmann wrote

...

1. use <example> as agreed in October for exampleXXX methods/example methods with different selectors and use <exemplar> for the instance returning methods that I proposed (including a changeset) Stef said it would be OK for him

2. use <exampleOfInstance> and <exampleOfInstance:> as Kilon suggested

3. use <exampleCode> for code examples and <exampleInstance> for the GT extension as Andreas/Christophe suggested

4. use <sample>

Isn't it amazing that we all care so much about Pharo and each other and still create a mess sometimes :) But then we always clean it up! I liked your quoting Pharo zen. I should probably do that more when I get annoyed.

I wasn't going to weigh in because it seemed like it would definitely be pushed to 5.0, but since the discussion is still ongoing. And that's good because: 1) as T. said, if we introduce something for a year it will be much harder to change once people are using it 2) and, as a pragma rename for example code, there seems to be limited risk/work involved (should be easily re-writable no?)

From a native English perspective, for GT I think only #exampleInstance (or almost-as-good #sampleInstance) both sound natural and clearly reveal the intention. For the other "play button variety", #example is fine, but #exampleCode or #sampleCode would be more explicit in light of the two distinct usages now. For simplicity, maybe they should mirror each other i.e. (exampleInstance & exampleCode) | (sampleInstance & sampleCode).

Anyway my 2c

With <example> in dispute and concern with locking in semantics for Pharo 4, it might be pragmatic for both sides to back away from <example> for the Pharo 4 release to mirrored pragmas <exampleInstance> & <exampleCode>. It will be easier to discuss semantics in Pharo 5 for a new <example> rather than modifying and existing one. It should be no trouble to carry forward <exampleInstance> & <exampleCode> for a while before they are "maybe" deprecated. To add a further 2c, I wonder if Pharo 5 might consider parameterising <example>: * <example:instance> or <example:inspect> or <example:returnsValue> * <example:code> or <example:doit> or <example:play> then you might even have <example:inspect,play> @Doru, Sorry I had used a few caps to emphasise some phrases. I didn't consider it shouting unless I typed caps for the whole paragraph. I'll amend how I do this. cheers -ben

Hi Torsten, Thanks for this mail. Indeed, mail is a poor medium and both the writer and the reader has to exercise more patience which does not always happen. There were two things that got to me: too long emails, and the overuse of capital letters. The latter one feels like shouting, and the long emails were just too time consuming in a rather stressful situation of meeting the deadline. And at the end, it led to longer responses that included points that were not addressed. Replying to the current mail takes more time than I have now. I will reply, but later. Cheers, Doru On Fri, Mar 27, 2015 at 7:07 PM, Torsten Bergmann <astares@gmx.de> wrote:

Hi Tudor,

Disclaimer: this mail is not intended to heat this up once again or insult you. It is meant to bring some more light into the darkness: we all can only decide on what we read and the actions that we see from others, sometimes a lot is not known from the other participants side.

Exactly because of this let me tell you my side of the story:

The discussion from October [1] between you and Stef happened in a thread "structuring widget examples" that I personally missed and did not follow.

At around the same time I extended Nautilus so that (additionally to other clickable method icons one can also click on #exampleXXX and initialize method icons. We have around 140 of such exampleXXX methods in the image, also in many external packages (like Bloc). These exampleXXX methods are used to demonstrate Smalltalk/Pharo code and are a valuable source to learn from.

When I announced this "click to run exampleXXX" feature on the list in October 2014 you welcomed and supported that idea [2]. I also heard the first time that we have an overlap in interest in making "examples" more visible in one way or the other. So we discussed about this solely in the context of example methods and I was as that time unaware of other GT related work in this regard. In this discussion you mentioned that being dependendent on the selector naming convention for the examples is not good and therefore you suggested that I extend my slice to use the <example> pragma for these clickable code examples.

Lets repeat: what I defend here the whole time was your very own idea, not mine as one can read in the list archive [2].

I supported your opinion because it was and still is an improvement! The pragma <example> that you suggested to me for the traditional Smalltalk class side exampleXXX methods fitted perfectly also namewise and therefore got integrated as a valuable addition into the image.

We shared the common view that using the <example> pragma is a cleaner way to mark "example methods". Anything was fine and I also happily used this pragma also in own external packages. I also wanted to go through all the example methods in the image to mark them with the <example> pragma and additionally provide an example browser for newbees based on the pragma as mentioned in the thread. But I was too busy to do it.

So the simple reason for the low number of pragma usage in the standard image is that I had not yet time to do this. It was also not a pressuring task because #exampleXXX where clickable and the pragma infrastructure was in place to mark all other exampleXXX selectors or selectors like #niceExampleToTryOut. So it could be used at any point in time later.

CI builds were green and the sun was shining for all of us...

I was unaware (at that time) of one important thing and this discussion here and your mails now made it more clear: Stef asked you also back in October to use <example> instead of <gtExample> and you followed this - but on the other hand and also in October you suggested to me to use exactly the same pragma <example>. At that time nobody seem to have been aware of this upcoming name collision that was introduced with Stefs request to you for GT on one side and your suggestion to me for getting independent from exampleXXX on the other side.

So in parallel you worked on a feature to "display sample instances" for a class in a new inspector tab ("e.g.") - for that the meaning behind the pragma marked methods was to return instances. You added more and more methods tagged with <example> on Character, String, ... to return samples like $a or 42.

GT is one of the packages that is hosted "externally" and get resynchronized into Pharo from time to time using Configs. The image included the <example> pragma logic for the click action in Nautilus. And with each new integration of next GT versions into the standard Pharo image more and more <example> marked methods came in providing objects/instances.

So it seems it was only a matter of time that this unfortunate "double usage" of the pragma showed their effects: Nicolai Hess wondered this week about a "useless play icon" in Nautilus and created issue #15225 four days ago [3] because when you execute a method that just returns an instance via the Nautilus icon nothing happens.

To make it clear: it's not that someone like me - just for fun - wanted to debate about naming or reify examples discussion shortly before the release. We all just want to improve. The unfortunate timing of 7 days before the release came from the effects of colliding pragma usage/goals showing up now.

You, Marcus and me commented in issue #15225. I commented this bug and explained about the common agreement of using <example> for exampleXXX and example methods to also allow different example selectors/method names.

As an answer (and contrary to your own suggestion to me from October) you presented then a different definition of what an <example> means for you:

Tudor Girba 24.03.2015 13:58 Uhr in issue #15225 "The semantics of <example> is to offer an initialized object that can be used for documentation or testing purposes."

This sudden "redefinition" was very surprising to me and to be honest looked like a justification to meet the needs of the new inspector feature introduced to Pharo solely. And it is a redefinition as for sure it was not what was discussed/what was suggested by you to me in October 2014 for the usage of <example>

Therefore I took this out of the bugtracker onto the dev-list: - because this showed up so late and shortly before the release (assuming that when we introduce the wrong this will be used and hard to change afterwards) - and to avoid that this stayed hidden in the bug tracker - we all have further misunderstandings on the pragma usage and the definition what methods to depict as example.

In your first initial response on this thread here in the mailinglist [4] you claimed that it was me who would be "putting <example> and example* selectors in the same pot" now. But it was not me - it was you in October 2014 who defined it exactly that way and urged me to integrate this in my slice as we see in [2].

And similar to the bugtracker you wrote on the list that you "do not redefine anything" while in the same post presented the definition that an "<example> returns an initialized object" by your definition once again.

It was that writing that once again made me think: "how can Tudor ignore our discussion, throw his own suggestion from October away and now decide for a new semantics on his own?".

Additionally one of the arguments on your side were that there were already 96 method annotated that way. But I dont want to count who was more busy on either side in annotating methods. I wanted and still want a solution that fits both improvements including proper naming.

And I was really perplex when you then commented in the evening in the issue #15225:

"As there was no complain, we proceeded as agreed and this should be the expected status quo for this release."

without all of us participating here having at least a certain degree of agreement. Leaving out the community and wondering that the discussion fires up again?

Also you stated that "nobody" is using the <example>, completely ignoring that I already mentioned to you that I did because we agreed on that in October, it was available since then and I mostly work in Pharo4 already. Yes - not yet as part of the image but in a few external packages already. To me that really looked like while we were in complete agreement first now nothing what I say in this whole topic now counts for you ...

Your side of the story may be different than mine - nonetheless I wanted to tell you my point of view in the hope you understand why I wrote what I wrote here.

Please reread all what is said with that knowledge. My intention was and still is to preserve this initial definition of <example> as in the October discussion as it solves the problem to not rely on the method name for the example methods. And we should find a proper pragma name for the needs to tag instance returning methods for the new inspector feature or more research on that topic of using such instances.

I made a proposal, others suggested proposals as well. But you did not write one single line if or why they are inacceptable for you, you only answered in general or with "then we go back to gtExample" (which would also steal your time similar to fixing it right now). I tried to support with a changeset so that it is less work on your side, also no feedback on this. I tried hard and I'm not mad either!

From all that my impression grew and grew that you want to now reserve the <example> solely for the new initialized object semantics or you will completely return back to <gtExample> if we do not follow you on this.

You said the whole discussion made you unhappy. Do you think it made me happy? Definitely not. I hope the above details explains it well enough the story from my side! You can accuse me for being too harsh with my mails - which was bad from my side but it was because I was hardly trying to defend your own suggestion from October!

Also I do not know where you got the impression that GT is treated as an "Alien" or something not belonging to Pharo. Do you really believe I would invest many hours to try out, give feedback to shape a HelpTopic Spotter addition, use GT for improving Pillar [6] or even build a MongoBrowser [7] and describe this in a lengthy article [8] when I would see GT as something in the outer space of the Pharo universe?

Since I started this thread and the discussion I like you to know: I APOLOGIZE when this was discussed to harsh, has stolen too much time or when you feel offended from things said during the discussion. Our community members only rarely meet in person to discuss things and email often is a useful but sometimes also horrible medium.

I first was unsure if I should response to this thread again: raising the risk of adding more oil to the water of upsetting each other even more. But the Pharo Zen says: "Communication is key", "Learning from mistakes" and "One step at a time".

This situation is still not ideal or solved for the release. I would like to see still two steps forward instead of rolling back. Several proposals were made:

1. use <example> as agreed in October for exampleXXX methods/example methods with different selectors and use <exemplar> for the instance returning methods that I proposed (including a changeset) Stef said it would be OK for him

2. use <exampleOfInstance> and <exampleOfInstance:> as Kilon suggested

3. use <exampleCode> for code examples and <exampleInstance> for the GT extension as Andreas/Christophe suggested

4. use <sample>

For sure we can have others. If they are inacceptable for you then shortly elaborate on why or what could be seen as acceptable solution from your side. Pharo belongs to all of us.

Thanks in advance if you do so!

Bye T.

[1] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2014-October/1013... [2] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2014-October/01... [3] https://pharo.fogbugz.com/f/cases/15225 [4] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583... [5] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583... [6] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/0171... [7] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/0176... [8] https://medium.com/concerning-pharo/building-a-mongo-browser-in-pharo-fe2104...

Gesendet: Donnerstag, 26. März 2015 um 14:30 Uhr Von: "Tudor Girba" <tudor@tudorgirba.com> An: "Esteban Lorenzano" <estebanlm@gmail.com> Cc: "Stéphane Ducasse" <stephane.ducasse@inria.fr>, "Pharo Development List" <pharo-dev@lists.pharo.org> Betreff: Re: [Pharo-dev] Existing <script> <example> pragmas and new GT needs

Hi,

I/we do not want to impose anything on anyone.

<gtExample> was introduced a long time (more than 1 year) ago in GT/Moose. It is used both for documentation purposes and for generic stress tests for the Inspector and Spotter (and let's not even count that the concept offers an alternative to SUnit testing that we will pursue in the near future). It got integrated in Pharo and then renamed to <example> 6 months ago (in October) after a public discussion on this mailing list. It later got mixed with the example* selectors as part of #isExampleMethod and used in Nautilus with a looser interpretation to essentially trigger the example.

This debate started 7 days before the release. The reason why the debate started is that exactly one method started to use it differently than all other <example> methods from the Pharo image. While this debate fired on, GT does not build and cannot be integrated, even though in parallel we work like mad to meet the deadline and fix all issues that are being reported.

And the way the debate took place is also borderline for my taste, too. I do not appreciate being shout at. I am not mad, but please do not expect me to be happy either.

I also find it discouraging that people talk about GT as if it would not be Pharo or as if we would want to force people to do things. We are indeed a standalone team with an own set of ideas, but we do not want to force our work on anyone. As the decision was to make GT a central part of Pharo, we kindly ask you to treat us as part of Pharo.

We never shied away from debates and listening to people. In fact, we think we are going over the board with actively listening and reacting. We can still debate the <example>, but not now. We have a release to meet. We can talk about it afterwards. But, for this to happen, I also kindly ask you to remove the <example> check from #isExampleMethod. This would allow us to start from a clean slate in Pharo 5.

Cheers, Doru

On Thu, Mar 26, 2015 at 12:06 PM, Esteban Lorenzano <estebanlm@gmail.com> wrote:Ok… my 2c:

Basically there is a difference between an “example” and a prototype, which is what the gtExample intends to do. Exemplar is just another way to name a prototype. Sorry to make you sad and tired… but when you introduce such an important new tool as all the gtools are, you cannot expect people to accept all your choices “as is”… and debate is the only way to achieve some consensus.

Esteban

ps: we are just days from release and we are all stressed a lot… so lets take a breath and consider things with the appropriate distance. We are not talking about the cure for cancer here, just the right name for a pragma, in a method.

...

On 26 Mar 2015, at 10:02, Torsten Bergmann <astares@gmx.de[ astares@gmx.de]> wrote:

Hi Tudor,

...

We will rename <example> back to <gtExample> and keep the API as it is. That will leave Pharo 4 with one <example> method while the other 100 will use <gtExample>. This will be available with the next GT integration.

As I already wrote (and Guillermo equally pointed out): most of them are there because you created/introduced many extension methods with GT to provide these sample instances like in $a for Charater or 42 for Integer, ... Which is completely valid to demonstrate how usefull your new extension is. But it is because you investigated so far more to demonstrate this new mechanism.

And yes, currently we have just one <example> in the image (beside some other in external projects). But if we do not want to rely on the exampleXXX pattern anymore we will mark the typical example methods with <example> in the future and would have around 140 in the latest image:

|coll| coll := IdentitySet new. Object withAllSubclassesDo: [:aClass | aClass class selectorsDo: [:selector | (selector beginsWith: 'example') ifTrue: [ coll add: selector ] ]]. ^coll

If we dont mark them I agree that there are only a few counterwise.

But again: from my side it is not about the current numbers. It is about the future mechanism, clear and understandable concepts and naming.

The usualy exampleXXX demos for code fits well with <example> from the name and mentally. "Example" is a very generous term for something to look at and learn.

In Pharo one can now demonstrate in the new GT inspector lively ready made instances! You feature and the research bound to it is not only important but a real improvement. I like that and I'm sure this will push us forward a lot.

Still IMHO mentally using <example> for depicting "code to look at" does fit namewise and conceptualy very well with the known and usual example methods in the image or external packages. Some of them provide an instance, but many of them just show how to use code.

And yes: I would the new GT mechanism to use a term and pragma name that better depicts what should be provided from the one who uses it: typical example instances or exemplars of the class.

When one creates a class

Object subclass: #RevolutionarySystem instanceVariableNames: 'name' classVariableNames: '' category: 'The-World'

he can implement a class side method to use the new mechanism:

uniqueExemplar <exemplar>

^RevolutionarySystem called: 'Pharo'

And this class side method returns an exemplary instance. If such a method should also serves as an example method (in the tradition of a code example to look at) one can even mark it with both pragmas.

...

The decision has nothing to do with arguments.

Why do you negotiate instead of (at a minimum) ellaborate what you think of the made proposal to use "exemplar" for the new GT mechanism.

See the definition for <exemplar>:

http://dictionary.reference.com/browse/exemplar[http://dictionary.reference.com/browse/exemplar]

...

"a model or pattern to be copied or imitated" "a typical example or instance"

http://www.thefreedictionary.com/exemplar[http://www.thefreedictionary.com/exemplar]

...

"One that is worthy of imitation; a perfect example or model" "One that is typical or representative"

http://www.merriam-webster.com/dictionary/exemplar[http://www.merriam-webster.com/dictionary/exemplar]

...

"an admired person or thing that is considered an example that deserves to be copied" "a typical example"

http://www.ldoceonline.com/dictionary/exemplar[http://www.ldoceonline.com/dictionary/exemplar]

...

"formal a good or typical example"

http://www.dict.cc/?s=exemplar[http://www.dict.cc/?s=exemplar] "instance" "specimen" "sample"

All the 100 instances now returns by GT extension are such exemplars: they are typical instances like $a or 42 one can use as a model or pattern to be copied or imitated.

Would'nt that perfectly fit with what you intended with your new feature: the preview should help people to just inspect a class, look at the new "e.g." tab and learn from premade instances?

...

The release is too important and we got distracted from the goal.

No doubt that the release is important and fixing it NOW from the technical side is easy as I demonstrated with the changeset. I guess rolling back <gtExample> would take you more time than reviewing it.

Before doing any action on your side I would really like to know your opinion about <exemplar>. I'm fine when you can not accept it - but please tell me about the reasons.

Bye T.

--

www.tudorgirba.com[http://www.tudorgirba.com]

"Every thing has its own flow"

-- www.tudorgirba.com "Every thing has its own flow"

On Wed, Apr 8, 2015 at 4:20 PM, Tudor Girba <tudor@tudorgirba.com> wrote:

Hi Torsten,

Your summary is almost correct and indeed it shows a misunderstanding. Here the corrections from my point of view: - <gtExample> together with concrete usages and the associated mechanism was developed 1 year ago and it got integrated together with the rest of the GT from the beginning. <gtExample> has always meant a method that returned an object of the same class (or possibly subclass). - Like you pointed out, we renamed it to <example> after a discussion on this mailing list. You did not see the discussion. Or maybe it was not well explained, like Nicolai pointed out, even though the messages did show both concrete examples and the interpretation in tools. - Then a couple of weeks later you introduced the handling of #example* selectors in Nautilus. - Then I urged you to use the existing <example> instead of #example*, and the message was intended to mean that the <example> would have the meaning of the existing <example> annotated methods and their existing interpretation in tools and tests. This was my expectation, but it was likely not well explained. - You replied with a suggestion of adding the <example> check in the isExampleMethod, and I did not reply. If I would have seen that mail I would have not agreed. - You went on to add the <example> check resulting in fact in redefining the meaning of the original <gtExample>. I missed this change, too.

So, I think this is the root of the misunderstanding.

Now, the main disagreement is related to names. We would like to enhance significantly more the infrastructure around the gtExample in GT (including documentation, prototyping and testing), and I will try to summarize our thoughts in a post these days so that you can see the direction. In the meantime, I propose to have this discussion when we have more to show for in order to provide a more concrete point of view. This should happen after Pharo 4.

And, to have a better chance of having a clean slate discussion later on in which to consider the value we associate to names, I would like to remove the <example> check from isExampleMethod and continue to preserve the treatment of #example* selectors in Nautilus. That will reset the state as it was before hte above mentioned misunderstanding, and would allow us to start from scratch. Would you agree?

Cheers, Doru

HI Doru, I see in 40594 you've backed out the change of <gtExample> to <example>. Thanks for starting the Pharo 5 discussion with a clean slate from your side. cheers -ben

I would not do that. I think that removing the example pragma check is sufficient for now. Could we do it? Cheers, Doru On Wed, Apr 8, 2015 at 5:16 PM, Nicolai Hess <nicolaihess@web.de> wrote:

2015-04-08 10:20 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

And, to have a better chance of having a clean slate discussion later on in which to consider the value we associate to names, I would like to remove the <example> check from isExampleMethod and continue to preserve the treatment of #example* selectors in Nautilus.

Wouldn't we need to change the check to:

isExampleMethod if selector starts with 'example' *AND HAS NOT* a <example> (or <gtExample>) pragma

because there are tons of #example* methods, some of them open an example and some of them with the pragma, create an instance for the inspector?

-- www.tudorgirba.com "Every thing has its own flow"

Hi, On Thu, Apr 9, 2015 at 11:31 AM, Nicolai Hess <nicolaihess@web.de> wrote:

2015-04-09 8:48 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

I would not do that. I think that removing the example pragma check is sufficient for now. Could we do it?

Sufficient for what?

You said to add the extra check saying " *AND HAS NOT* a <example> (or <gtExample>) pragma " and I said that it is sufficient to just remove the pragma check for the Pharo 4 release :).

I think there is no problem if we remove the pragma check. Because only very few (if any) example methods (those that really open an example) relies only on the pragma, without having a #exampleXXX name too.

Exactly.

I just think this would not change much. We need to clean up the mess with the #example* methods.

Thanks. Can you produce the issue and slice? @Torsten: are you fine with this? Doru

...

Cheers, Doru

On Wed, Apr 8, 2015 at 5:16 PM, Nicolai Hess <nicolaihess@web.de> wrote:

...

2015-04-08 10:20 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

And, to have a better chance of having a clean slate discussion later on in which to consider the value we associate to names, I would like to remove the <example> check from isExampleMethod and continue to preserve the treatment of #example* selectors in Nautilus.

Wouldn't we need to change the check to:

isExampleMethod if selector starts with 'example' *AND HAS NOT* a <example> (or <gtExample>) pragma

because there are tons of #example* methods, some of them open an example and some of them with the pragma, create an instance for the inspector?

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com "Every thing has its own flow"

Hi, On Thu, Apr 9, 2015 at 11:44 AM, Nicolai Hess <nicolaihess@web.de> wrote:

2015-04-09 11:36 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

Hi,

On Thu, Apr 9, 2015 at 11:31 AM, Nicolai Hess <nicolaihess@web.de> wrote:

...

2015-04-09 8:48 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

I would not do that. I think that removing the example pragma check is sufficient for now. Could we do it?

Sufficient for what?

You said to add the extra check saying " *AND HAS NOT* a <example> (or <gtExample>) pragma " and I said that it is sufficient to just remove the pragma check for the Pharo 4 release :).

No, I don't think this is enough. There are so many #exampleXXX method from GT in the Pharo4 image and most of them don't work with nautilus play-icon for #exampleXXX methods

They don't do anything harmful either. But, you can also add the check as you suggest.

...

...

I think there is no problem if we remove the pragma check. Because only very few (if any) example methods (those that really open an example) relies only on the pragma, without having a #exampleXXX name too.

Exactly.

...

I just think this would not change much. We need to clean up the mess with the #example* methods.

Thanks.

Can you produce the issue and slice?

For what, removing the example check or renaming all #example* methods that don't open an example?

For removing the example check. Cheers, Doru

...

@Torsten: are you fine with this?

Doru

...

...

Cheers, Doru

On Wed, Apr 8, 2015 at 5:16 PM, Nicolai Hess <nicolaihess@web.de> wrote:

...

2015-04-08 10:20 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

And, to have a better chance of having a clean slate discussion later on in which to consider the value we associate to names, I would like to remove the <example> check from isExampleMethod and continue to preserve the treatment of #example* selectors in Nautilus.

Wouldn't we need to change the check to:

isExampleMethod if selector starts with 'example' *AND HAS NOT* a <example> (or <gtExample>) pragma

because there are tons of #example* methods, some of them open an example and some of them with the pragma, create an instance for the inspector?

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com "Every thing has its own flow"

Hi, On Thu, Apr 9, 2015 at 12:31 PM, Nicolai Hess <nicolaihess@web.de> wrote:

2015-04-09 11:53 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

Hi,

On Thu, Apr 9, 2015 at 11:44 AM, Nicolai Hess <nicolaihess@web.de> wrote:

...

2015-04-09 11:36 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

Hi,

On Thu, Apr 9, 2015 at 11:31 AM, Nicolai Hess <nicolaihess@web.de> wrote:

...

2015-04-09 8:48 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

I would not do that. I think that removing the example pragma check is sufficient for now. Could we do it?

Sufficient for what?

You said to add the extra check saying " *AND HAS NOT* a <example> (or <gtExample>) pragma " and I said that it is sufficient to just remove the pragma check for the Pharo 4 release :).

No, I don't think this is enough. There are so many #exampleXXX method from GT in the Pharo4 image and most of them don't work with nautilus play-icon for #exampleXXX methods

They don't do anything harmful either.

No? We have now methods with the play icon that opens some window/widget/... (The old examples) And we have now many new example methods with this play icon that just do nothing (visible). I find this distracting.

...

But, you can also add the check as you suggest.

Well, I don't like this solution. We would define a method to be an "example method" if it is *not* tagged with <example> pragma. This is confusing too.

Yes, that is why I said that we should not add that check :)

Possible solutions: - remove the "run this example" play icon from nautilus, because with all the new exampleXXX methods from GT it is useless for ~half of all the methods. - rename the example methods from GT to something else, so it does not interfere with nautilus

Ok. We will rename the #example* methods from GT to gtExample* before the release.

- change the isExampleMethod check to *only* check for some <OnWhatEverExamplePragmaWeAgree> and tag all old (spec/widget/UI) example methods with this pragma.

I wish to have no pragma in isExampleMethod for Pharo 4. We can talk about it afterwards. But, we still need a pharo issue. Could you create one? :) Cheers, Doru

For Pharo 4.0 I think we have to live with this mess and clean it up for the next release.

...

...

...

...

I think there is no problem if we remove the pragma check. Because only very few (if any)

example methods (those that really open an example) relies only on the pragma, without having a #exampleXXX name too.

Exactly.

...

I just think this would not change much. We need to clean up the mess with the #example* methods.

Thanks.

Can you produce the issue and slice?

For what, removing the example check or renaming all #example* methods that don't open an example?

For removing the example check.

Cheers, Doru

...

...

@Torsten: are you fine with this?

Doru

...

...

Cheers, Doru

On Wed, Apr 8, 2015 at 5:16 PM, Nicolai Hess <nicolaihess@web.de> wrote:

...

2015-04-08 10:20 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

And, to have a better chance of having a clean slate discussion later on in which to consider the value we associate to names, I would like to remove the <example> check from isExampleMethod and continue to preserve the treatment of #example* selectors in Nautilus.

Wouldn't we need to change the check to:

isExampleMethod if selector starts with 'example' *AND HAS NOT* a <example> (or <gtExample>) pragma

because there are tons of #example* methods, some of them open an example and some of them with the pragma, create an instance for the inspector?

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com

"Every thing has its own flow"

-- www.tudorgirba.com "Every thing has its own flow"

Hi. I read this long long thread. And too me #example is good common name for any kind of examples. I really don't want to think what pragma I should use for concrete scenario. All existed methods are just examples. No care is they return instances or not. So I am not understand what the problem with example methods which not return instance of class? And what concrete tool you try to implement? If it is special "examples" tab when inpecting/browsing classes why it should be restricted to working only with instances of given class? Your tool can analize result of example method and provide different kind of interfaces. And with instance of selected class it will work as you already implemented. And with example from Athens it can provide tools to control tiger demo (for example) Best regards, Denis 2015-04-09 9:48 GMT+03:00 Tudor Girba <tudor@tudorgirba.com>:

I would not do that. I think that removing the example pragma check is sufficient for now. Could we do it?

Cheers, Doru

On Wed, Apr 8, 2015 at 5:16 PM, Nicolai Hess <nicolaihess@web.de> wrote:

...

2015-04-08 10:20 GMT+02:00 Tudor Girba <tudor@tudorgirba.com>:

...

And, to have a better chance of having a clean slate discussion later on in which to consider the value we associate to names, I would like to remove the <example> check from isExampleMethod and continue to preserve the treatment of #example* selectors in Nautilus.

Wouldn't we need to change the check to:

isExampleMethod if selector starts with 'example' *AND HAS NOT* a <example> (or <gtExample>) pragma

because there are tons of #example* methods, some of them open an example and some of them with the pragma, create an instance for the inspector?

-- www.tudorgirba.com

"Every thing has its own flow"

2015-04-09 13:12 GMT+03:00 Tudor Girba <tudor@tudorgirba.com>:

Hi,

Please, let's try to not restart the debate now. We can do it after the release :).

Ok. Nobody wrote suggestion to just fix behaviour of your tool when example not return instance of class. So it is my little idea

2015-04-09 13:16 GMT+03:00 Nicolai Hess <nicolaihess@web.de>:

There are methods named #exampleXXX that - "open" something (the UI-Widget examples for example open a widget/window/dialog ...) - create an instance for the object class this method is defined (see all methods tagged with pragma <gtExample>

...

And what concrete tool you try to implement?

The little "play-icon" in Nautilus currently depends on the method name, if it is named #exapleXXX, treat it as example method that *opens something* GTInspector provides a "instance example" (E.g.)-tab. You can see a list of example methods that *create instances* (and inspect them)

I'm not see problem here. Tab should be named "examples". And when user select example which open some morph it is normal expected behaviour. And when selected example return instance of selected class it can be handled as specific case. And when selected example open morph and returned it user will see it and explore it at same time which is good feature to me.

...

If it is special "examples" tab when inpecting/browsing classes why it should be restricted to working only with instances of given class?

If it *opens* a window/ a Morph or anything else, this is a side-effect the glamour team don't want, because they intend to use this example-instance-creation for other things as well (for example: automatic testing).

Agree, if you want to process group of examples you should distinguish examples which only provide instances without side effects

On Thu, Mar 26, 2015 at 9:19 PM, Ben Coman <btc@openinworld.com> wrote:

On Wed, Mar 25, 2015 at 9:33 PM, Tudor Girba <tudor@tudorgirba.com> wrote:

...

- Modeling Examples to Test and Understand Software, Markus Gaelli, PhD Thesis, 2006 http://scg.unibe.ch/archive/phd/gaelli-phd.pdf

...

- JExample: Exploiting Dependencies Between Tests to Improve Defect Localization, Kuhn etal, 2008 http://scg.unibe.ch/archive/papers/Kuhn08aJExample.pdf

(Phexample is also available on SmalltalkHub)

...

In spite of the first using "example" as a metaphor and the second using "example" in its name, these are references are about composable tests, not examples. While a test can serve as an example, a test is a different concept than an "Example". So yes, its a great idea to explicitly define dependencies between tests by them returning instances to be used by other tests, but there are plenty of examples that do not follow that pattern, nor should all examples be forced to follow that pattern, nor should they be force to be tagged something other than an <example>.

Language is a funny thing. Dictionaries tend to list all "possible" meanings and don't necessarily indicate which are the more common usage. The supporters of "exemplar" seems to have a German background, and maybe the German word "exemplar" is an exact match, but it seems the meaning has evolved since English imported it. As a native english speaker, to me "exemplar" has an immediate sense of being too exotic for the purpose, and also more a meaning of "the BEST example/instance of..." - which I think overstates the purpose here.

I have marked the more common meanings and underlined significant words in the the supplied dictionary meanings...

On Thu, Mar 26, 2015 at 5:02 PM, Torsten Bergmann <astares@gmx.de> wrote:

...

what you think of the made proposal to use "exemplar" for the new GT mechanism.

See the definition for <exemplar>:

http://www.thefreedictionary.com/exemplar more this --> "One that is _worthy_ of imitation; a _perfect_ example or model" less this --> "One that is typical or representative"

...

http://www.merriam-webster.com/dictionary/exemplar more this --> "an _admired_ person or thing that is considered an example that _deserves_ to be copied" less this --> "a typical example"

http://www.dict.cc/?s=exemplar "instance" "specimen" "sample"

Note that the german-english dictionary also proposes "sample", which to me seems the most suitable for the intent of returning an item for inspection...

http://www.merriam-webster.com/dictionary/sample "a representative part or a single item from a larger whole or group especially _when-presented-for-inspection_ or shown as evidence of quality : specimen"

http://www.thefreedictionary.com/sample "A specimen taken for analysis or testing" Sorry I also meant to add, that specimen could also work... http://www.thefreedictionary.com/specimen "An individual, item, or part representative of a class or whole." http://www.merriam-webster.com/dictionary/specimen "Something (such as an animal or plant) collected as an example of a particular kind of thing ; a small amount or piece of something that can be tested or examined" ...but that I liked <sample> since it rhymes with <example> (Together these would be ample for a needs - daboomboom!) cheers -ben

Hey guys since we talk about the <example> pragma, I wanted to thank the implementors of this very useful feature. I was testing Bloc and it comes with loads of examples using this pragma and has been extremely convenient. Definitely will be using it with my code too. I was not ware of <script> that sound very useful too. Keep up the awesome job.

torsten I'm confused. Did you use the <example> pragmas before? Because I was the one in favor to remove this ugly gt in front of gtExample Stef Le 25/3/15 17:32, Torsten Bergmann a écrit :

Hi Tudor,

...

However, I think there is significantly more value in examples that do return objects.

Yet again: no doubt that they may be of value. This is not the point. If they provide "more value" than methods that do not return an instance depends on what you want to achieve with them. But please accept the fact that they are NOT THE ONLY WAYof giving "examples" on system usage to others. There are in fact others as well. Regarding your script suggestion: Examples and script have in common is that they can be executed - but that does not automagically makes them the same. An example is CONCEPTUALLY not the same as a script. The purpose of creating a script is a different from the purpose of creating an example. A script is something I ran, an example is something that is explicitly provided for others to learn from it.

...

Until now, nobody is really using the <example> except the code that is packaged in GT

So you state that I'm nobody. Sad that my code does not count... :(

Is this really your argument that we now start counting and decide upon the number of methods that use this already? Do you really want the community to decide on that base in the future? Then we would had to write only ugly code because the ugly code outwighted the the number of clean code in the past when we forked from Squeak.

Again: this discussion is not about number of usage, it is about getting cleaner and about the correct naming.

The <example> tag as it was integrated from my side solves the problem of not relying on exampleXXX for tagging general code examples. You in parallel also used the same tag name for something that is more specific: an example method that returns an example instance/exemplar.

...

Nevertheless, please, let's focus on the release that comes in a few days. Especially because of the release in a few days I bring this topic up. When we keep it that way people will use it and we can hardly change it afterwards.Thats why I want a solution now and not defer this simple decision (it is nothing more) afterwards. we could remove the <example> pragma check from isExampleMethod

Why should we? You yourself wrote in the issue tracker that it is not good to only rely on selector names starting with exampleXXX.

...

The word example is based on previous research. Which say what? Academics is always right and in this context it now has to be like YOU stated? Please do not always get to far from the basic issue itself. We do not discuss how valuable this is - we know that already.

BTW: I have a degree in software technologies as well and support the idea of using congrete example objects. I agree with you in all the benefits, the underestimated power, etc. and would like to see Pharo move forward not only there. The most underestimated power is in its metaprogramming facilities.

The term "Example" is very general and in the Smalltalk contextalready and often usedto provide "example" methods. Some of them provide instances, others not. You talk only about the first subset: the examples who provide concrete instances. So we should name them accordingly: EXEMPLAR or EXAMPLEOBJECT in thecontext of OOP. I still stay with my proposal, we should stay consistent and name/mark things what they are: 1. general "examples" as <example> which solves the "not rely on method names" issue 2. and marking example method that are specifically returning an example instance with <exampleInstance> or <exemplar> or <sample> as Ben suggested

If it is a effort/time problem of changing the methods providing such example methods in the GT repo I offer to do this change.

As Pharo is not only YOURS and not only MINE I would like to see more opinions or proposals from others. ;)

Thanks T.

"Ben Coman" wrote

The word that I feel best applies to Doru's need is <sample>, to return a fully initialised sample instance that you can play with in the >Inspector.  When you double-click a method so tagged you can think of it as "give me a sample" of yourself.

What would you think of "exemplar" and "give me an examplar of yourself"? Thanks T.

On Thu, Mar 26, 2015 at 12:35 AM, Torsten Bergmann <astares@gmx.de> wrote:

"Ben Coman" wrote

...

The word that I feel best applies to Doru's need is <sample>, to return a fully initialised sample instance that you can play with in the Inspector. When you double-click a method so tagged you can think of it as "give me a sample" of yourself.

What would you think of "exemplar" and "give me an examplar of yourself"?

I missed responding directly to this. Sorry, that just sounds wrong. :) "Give me an example of yourself" is better, and "give me a sample of yourself" better again. cheers -ben