On Tue, Jun 23, 2015 at 12:59 AM, Ben Coman <b...@openinworld.com> wrote: > On Mon, Jun 22, 2015 at 11:17 PM, Torsten Bergmann <asta...@gmx.de> 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
btw, I bumped into an interesting resource (which incidentally supports my case but is probably generally useful)... http://sentence.yourdictionary.com/exemplar
