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. 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? :) Now, let's discuss why having an example concept defined as an "initialized object" is actually valuable. In order to run examples, you need the well initialized object. So, you can have: GLMBrick class>>exampleZindex <example: 'Example of z-index support in Brick'> ^ GLMBrick new ... and then GLMBrick class>>exampleZindexOpen " self exampleZindexOpen " self exampleZindex openInBrickWindowLabeled: 'Z-Index example' But, the interesting thing is that you can also use the example object for other purposes. For example, you can embed the object in a browser, or you can run automatic smoke tests. Specifically, given that GT proposes the idea of moldable tools that others can easily extend, it is also a challenge to test these extensions. Having examples for each of the extended classes makes this endeavor easily possible. And then we can also start considering the work on seeing tests as a whole as nothing but examples with assertions that depend on each other, but let's talk about that at another time. There is great value that comes from the simple and clearly defined concept of <example>. Btw, I think we should avoid talking about "for GT's purpose" because it sounds as if GT would be an alien that should be put in quarantine :) 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"