Just for your information Bloc already has 150 methods using the <example> pragma. Most likely there are other libraries out there using it as well. I also suspect since this is new and not documented <example> will be heavily used in the future because having example code is too useful to pass. I am off to port my methods to it :)

On Thu, Mar 26, 2015 at 12:28 AM, 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.








--

"Every thing has its own flow"