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.

��

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.

��

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

example

and move this discussion after the release?

��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" :)

�� 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"