<example> pragmas and example* methods use-cases

> Hi Peter,
>
> there was no agreement - so we rolled back for Pharo 4 to discuss/decide for Pharo 5.
>
> I communicated already how I would solve it to get IMHO a consistent and
> easy understandable solution:
>
> 1. executable example
> =====================
>   We talk about executable code here: an "example" in the traditional Smalltalk sense
>   means ONLY a runnable piece of code to demonstrate something. Since a long time and not only in Pharo this
>   is typically done in methods with prefix "example". 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.
>
>   These methods with the "example" in the name are currently honored by Nautilus with the
>   clickable icon. See SystemProgressMorph>>exampleChangeLabel or others.
>
>   => To not be limited to the prefix in the method name I proposed to be able
>      to additionally use the <example> pragma to mark example methods.
>      This way you can choose the method name freely to give an example to others
>      on how to use them.
>
> 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"
>
> So I proposed and still propose
>  - "exampleXXX"  prefixed methods and <example> pragma for traditional examples as used in other Smalltalks and Pharo before
>  - "exemplarXXX" prefixed methods and <exemplar> pragma (mark code that return an instance always) for the future inspection
>    of exemplars in the tools

> On Mon, Jun 22, 2015 at 11:17 PM, Torsten Bergmann <[hidden email]> wrote:
>> Hi Peter,
>>
>> there was no agreement - so we rolled back for Pharo 4 to discuss/decide for Pharo 5.
>>
>> I communicated already how I would solve it to get IMHO a consistent and
>> easy understandable solution:
>>
>> 1. executable example
>> =====================
>>   We talk about executable code here: an "example" in the traditional Smalltalk sense
>>   means ONLY a runnable piece of code to demonstrate something. Since a long time and not only in Pharo this
>>   is typically done in methods with prefix "example". 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.
>>
>>   These methods with the "example" in the name are currently honored by Nautilus with the
>>   clickable icon. See SystemProgressMorph>>exampleChangeLabel or others.
>>
>>   => To not be limited to the prefix in the method name I proposed to be able
>>      to additionally use the <example> pragma to mark example methods.
>>      This way you can choose the method name freely to give an example to others
>>      on how to use them.
>>
>> 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"
>>
>> So I proposed and still propose
>>  - "exampleXXX"  prefixed methods and <example> pragma for traditional examples as used in other Smalltalks and Pharo before
>>  - "exemplarXXX" prefixed methods and <exemplar> pragma (mark code that return an instance always) for the future inspection
>>    of exemplars in the tools
>
> Sorry. I'm going to have to play the native english speaker card here.
> I could live with it, but "examplar" just doesn't sound right for this.
>
> * Dictionary meanings are useful, but meaning can be skewed without
> contemporary context.
> * Dictionaries cover a lot of corner cases, some inherited from a
> hundred years ago, and language evolves.  They may remain technically
> correct and understandable, but not sound "right".
> * I've probably only seen the word used couple of times in my life,
> never in this context.
> * I notice its also a German word.  I expect its hard to disassociate
> from its common German usage.   Sorry, after English stole it from
> German, it probably corrupted it.
> * Check its synonyms: "epitome, perfect example, shining example,
> model, paragon, ideal...". This is its contemporary meaning and I
> guess the returned sample won't be expected to be the "best most
> perfect sample".  It will just be "some sample" or a "basic sample"
> for you to inspect.
> * "Sample" is 2 characters shorter than "Exemplar" to fit in label of
> the GT tab.  I presume its useful to match the tab label with the
> pragma.
>
> cheers -ben