I'll revisit my previous suggestion. In real life... * a "sample" is a real object you can hold. You ask a supplier to "send you a sample" of their product so you can inspect it before you buy lots. In an industrial factory, you "take a sample" to take an item from the process stream to the lab to analyse. Both of these are real objects you can hold. In addition, Digital Signal Processing does sampling, it doesn't do exampling. * an "example" is one step removed from real life objects. The maths teacher works through an example. Someone's behaviour can set a good example. A programming script can provide an example of how to do something. People say "for example, how about my hypothetical** situation". None of these refer to a real object. Now you can use "example" to refer to real objects, but usually second hand when you are describing a general characteristic. It doesn't have the same concrete semantic of a real object as "sample". There were other suggestions that were reasonable. It might be better to have one pragma that is parameterized by what sort of example it is. cheers -ben ** Consider for a moment, what would the world be like without hypothetical situations? On Mon, Jun 22, 2015 at 6:49 PM, Nicolai Hess <nicolaihess@web.de> wrote:

2015-06-22 12:03 GMT+02:00 Peter Uhnák <i.uhnak@gmail.com>:

...

Hi,

there was a long discussion about the meaning of example* methods and <example> pragmas, however I do not know what was the final resolution.

Basically I am interested in two use-cases

1. executable example (the one where Nautilus shows nice play icon) This is as I understand only through example* naming (on class-side).

Yes, but I would like to use a pragma again and don't rely naming convention, we just wasn't able to agree on one.

...

2. returning examples (example that returns some value that I can reuse) Is this what <example> pragma is for? How would I go about naming it considering that having play icon there would be counter-productive (user would be clicking on it and nothing would happen).

Inspector and spotter use gtExample* names in addition to an <gtExample> pragma. <gtExample> -> for finding those methods gtExample*name -> for not getting the play icon.

This is less than perfect.

...

Thanks, Peter

Hi, We are working on a more elaborate model for examples, but we need a bit more time to get to a rounder solution. Cheers, Doru On Mon, Jun 22, 2015 at 12:49 PM, Nicolai Hess <nicolaihess@web.de> wrote:

2015-06-22 12:03 GMT+02:00 Peter Uhnák <i.uhnak@gmail.com>:

...

Hi,

there was a long discussion about the meaning of example* methods and <example> pragmas, however I do not know what was the final resolution.

Basically I am interested in two use-cases

1. executable example (the one where Nautilus shows nice play icon) This is as I understand only through example* naming (on class-side).

Yes, but I would like to use a pragma again and don't rely naming convention, we just wasn't able to agree on one.

...

2. returning examples (example that returns some value that I can reuse) Is this what <example> pragma is for? How would I go about naming it considering that having play icon there would be counter-productive (user would be clicking on it and nothing would happen).

Inspector and spotter use gtExample* names in addition to an <gtExample> pragma. <gtExample> -> for finding those methods gtExample*name -> for not getting the play icon.

This is less than perfect.

...

Thanks, Peter

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

On Tue, Jun 23, 2015 at 6:13 AM, Peter Uhnák <i.uhnak@gmail.com> wrote:

Thank you all for your answers (For whatever reason all replies by Torsten to this thread ended up as separate threads.. maybe mail client issues?)

It seems that <sample> is then the go-to naming for now. I also like that the word starts differently so it's easy to differentiate them at a glance.

We should also see what Doru comes up with.

On Mon, Jun 22, 2015 at 5:17 PM, Torsten Bergmann <astares@gmx.de> wrote:

...

It is important to note that these methods COULD BUT MUST NOT RETURN an instance. Usually such a method is only there to demonstrate code.

I'm not sure I understand the purpose of this restriction. For example BorderedMorph>>exampleGradient could on top of opening a morph also return the instance. If you are running it from Nautilus it makes no difference, but when you run it manually you could also inspect the instance, so you could further manipulate with it... in a sense two-in-one. :) Otherwise you would have to get it via inspecting morph halos.

Or in another sense you could either inspect <sample> and then manually run it, or execute <example> that would on top of that also return inspectable value of the <sample>.

...

2. returning examples ===================== While some example methods just demo code and code usage (like "Job example" or "BorderedMorph exampleGradient") a subset of them directly return an instance of the method defining class (like LabelMorph>>example).

The idea of the GT Tools is to call these methods and display the return value as inspectable "instances" in the tools, so for instance if you inspect class VirtualMachine or Character you get a tab entitled "E.g." where you can click on these sample instances.

GT and (because GT )now latest Pharo currently still uses "gtExample" method prefix or <gtExample> pragma to mark such methods and there is also to wish to remove the "gt" prefix. But with this we would have a clash with the other "exampleXXX" usage.

=> I would propose to mark the code examples that return an instance with an <exemplar> method.

According to Google definition of <exemplar> noun - "a person or thing serving as a typical example or excellent model."

...

Urban dictionary defines <exemplar> as "a typical or standard model or specimen"

As a side note... I think it's best to use urban dictionary for slang, and not Pharo dev. :) Looking up the name of it there shows at least a bit of self-reflection. :)

Good idea, but even this can be misleading and the usual wiki concerns with apply. While (b) seems reasonable, (a) and (c) are very suspect. Note the author "placefake." http://www.urbandictionary.com/define.php?term=exemplar (a) the mythical task occupying any computer technician, preferably employed by a university or other educational institute, for their summer months of 'down time.' (b) a typical or standard model or specimen: (i.e. and example. just said with a really dorky 15th century word.) (c) any action performed by don swanner. by placefakeJune 04, 2010 cheers -ben

2015-06-29 20:10 GMT+02:00 Sean P. DeNigris <sean@clipperadams.com>:

Peter Uhnák wrote

...

It seems that <sample> is then the go-to naming for now

I agree with Ben that from a native English perspective, exemplar doesn't quite sound right.

Sample and Example are the two words that most clearly capture the intent. The problem with using #sample to return instances and #example to illustrate usage is that it's a bit too subtle. Even though technically one could argue the logic of that distinction, in reality English speakers use them interchangeably and it will be confusing. A core principle of Smalltalk is to type a bit more to make things clearer (e.g. avoid single-character/abbreviated variable names). I strongly feel we should be more specific and uniform by either using (<exampleInstance> & <exampleCode>) or (<sampleInstance> & <sampleCode>).

<sample> for example instances <demo> for examples opening a window or any other interaction ?

----- Cheers, Sean -- View this message in context: http://forum.world.st/example-pragmas-and-example-methods-use-cases-tp483342... Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.

On 29-06-15 20:10, Sean P. DeNigris wrote:

I strongly feel we should be more specific and uniform by either using (<exampleInstance> & <exampleCode>) or (<sampleInstance> & <sampleCode>).

+1 Be specific. Stephan

On Tue, Jun 30, 2015 at 2:10 AM, Sean P. DeNigris <sean@clipperadams.com> wrote:

Peter Uhnák wrote

...

It seems that <sample> is then the go-to naming for now

I agree with Ben that from a native English perspective, exemplar doesn't quite sound right.

Sample and Example are the two words that most clearly capture the intent. The problem with using #sample to return instances and #example to illustrate usage is that it's a bit too subtle. Even though technically one could argue the logic of that distinction, in reality English speakers use them interchangeably and it will be confusing.

Thats a fair argument.

A core principle of Smalltalk is to type a bit more to make things clearer (e.g. avoid single-character/abbreviated variable names). I strongly feel we should be more specific and uniform by either using (<exampleInstance> & <exampleCode>) or (<sampleInstance> & <sampleCode>).

I find myself liking the last two, I think since the concatenated words rolls off the tongue nicer with one less syllable, but I think any of those are fine. Actually, rather than pairing based on the first part, maybe using <exampleCode> together with <sampleInstance> will distinguish the most between the two cases. cheers -ben

2015-06-30 11:21 GMT-03:00 Sean P. DeNigris <sean@clipperadams.com>:

Ben Coman wrote

...

I find myself liking the last two... Actually... maybe using <exampleCode> together with <sampleInstance> will distinguish the most between the two cases

I agree that any of those would be fine. I kind of like your last suggestion, in fact.

"Code" could mean anything. I would use: <exampleSmalltalkCode> <examplePharoCode> etc Hernán

----- Cheers, Sean -- View this message in context: http://forum.world.st/example-pragmas-and-example-methods-use-cases-tp483342... Sent from the Pharo Smalltalk Users mailing list archive at Nabble.com.