Existing <script> <example> pragmas and new GT needs

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 <[hidden email]> 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 <[hidden email]> 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.
>
>
>

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 <[hidden email]> 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 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/101377.html
[2] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2014-October/014267.html
[3] https://pharo.fogbugz.com/f/cases/15225
[4] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583.html
[5] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583.html
[6] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/017186.html
[7] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/017613.html
[8] https://medium.com/concerning-pharo/building-a-mongo-browser-in-pharo-fe2104052843



 
 

Gesendet: Donnerstag, 26. März 2015 um 14:30 Uhr
Von: "Tudor Girba" <[hidden email]>
An: "Esteban Lorenzano" <[hidden email]>
Cc: "Stéphane Ducasse" <[hidden email]>, "Pharo Development List" <[hidden email]>
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 <[hidden email]> 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 <[hidden email][[hidden email]]> 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>:
>

> <a href="http://dictionary.reference.com/browse/exemplar[http://dictionary.reference.com/browse/exemplar]" target="_blank">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"
>
> <a href="http://www.thefreedictionary.com/exemplar[http://www.thefreedictionary.com/exemplar]" target="_blank">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"
>
> <a href="http://www.merriam-webster.com/dictionary/exemplar[http://www.merriam-webster.com/dictionary/exemplar]" target="_blank">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"
>
> <a href="http://www.ldoceonline.com/dictionary/exemplar[http://www.ldoceonline.com/dictionary/exemplar]" target="_blank">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"

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/101377.html
[2] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2014-October/014267.html
[3] https://pharo.fogbugz.com/f/cases/15225
[4] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583.html
[5] http://lists.pharo.org/pipermail/pharo-dev_lists.pharo.org/2015-March/107583.html
[6] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/017186.html
[7] http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/2015-March/017613.html
[8] https://medium.com/concerning-pharo/building-a-mongo-browser-in-pharo-fe2104052843



 
 

Gesendet: Donnerstag, 26. März 2015 um 14:30 Uhr
Von: "Tudor Girba" <[hidden email]>
An: "Esteban Lorenzano" <[hidden email]>
Cc: "Stéphane Ducasse" <[hidden email]>, "Pharo Development List" <[hidden email]>
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 <[hidden email]> 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 <[hidden email][[hidden email]]> 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>:
>

> <a href="http://dictionary.reference.com/browse/exemplar[http://dictionary.reference.com/browse/exemplar]" target="_blank">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"
>
> <a href="http://www.thefreedictionary.com/exemplar[http://www.thefreedictionary.com/exemplar]" target="_blank">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"
>
> <a href="http://www.merriam-webster.com/dictionary/exemplar[http://www.merriam-webster.com/dictionary/exemplar]" target="_blank">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"
>
> <a href="http://www.ldoceonline.com/dictionary/exemplar[http://www.ldoceonline.com/dictionary/exemplar]" target="_blank">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"