Comments on the Gem Cutter docs

Question

<div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">Thought I&#39;d make some notes on this as I read through it. Overall, it&#39;s a very nice intro to the tool and what it can do.</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p8 - "The type Num </span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">a => [a] (a list of 'anythings', where 'anything' is a number value) is clearly a more </span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">specific version of [a] (the general list of &#39;anythings&#39;)"</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">Probably needs a sentence or so to very briefly introduce the concept of type classes ... Java developers are going to be surprised that the input type isn&#39;t "[Num]". (same applies to type-class reference on p25 - maybe the intro to the doc should just list some &#39;prerequisites&#39;?)</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p7/8 - I think after introducing polymorphism, a brief comment explaining that this implies that the colours of the ins and outs won&#39;t necessarily match might be handy.</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">[As a side point, it might increase usability of the gem cutter if the inputs / outputs were larger? or maybe the mouse &#39;snapped&#39; to them when dragging?]</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p12 - At this point I&#39;m still not sure whether Gem Cutter is effectively just providing a graphical way of writing CAL code, or whether it&#39;s doing something else. I managed to locate the "./bin/cal/release/CAL/GemCutterSaveModule.cal" file which seems to be reflecting what I&#39;m doing in the cutter - it might be useful to explicitly point people to this so that they can see what is going on if they&#39;re interested?</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p13 - By this point, Data Constructors haven&#39;t been explicitly explained, so mentioning their appearance in the browser might be confusing if people aren&#39;t familiar with Haskell?</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p48 - The discussion of the ordering of arguments and partial evaluation assumes an understanding of currying which hasn&#39;t been explained yet in the document.</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p49 - I couldn&#39;t get a local variable to show up in the code editor as described by the document. I used the following:</span></div><div style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px"><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">let a = (2*x);</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">in</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">greaterThan a 17</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p55 - ok, this is where the typeclass explanation is. Might be worth a forward ref earlier in the doc.</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">"A list of characters (a string) will be [Char]," .... my understanding is that Strings aren&#39;t lists of Chars in CAL - so maybe this could be confusing.</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">The description of type classes here could probably use being tidied up a bit - I think it would likely be confusing to someone completely unfamiliar with them. Might be useful to stress the similarities (& of course differences) with Java interfaces.</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p58 - "The language is a functional language. This means that every entity in the language is a function." ... is this possibly misleading - given the existence of base types etc?</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">typo: "This is feature of lambda calculus" -> "This is a feature..."  .... in fact, given that this isn&#39;t explicitly referenced in the doc, might be worth removing it.</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p60 - "length :: [a] -> Double"  should be "length :: [a] -> Int"</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">typo: fundamentalstandard   ... missing space</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">p61 - "A type reduces the set of possible values for a variable from an infinite set, to a smaller set." - possibly not the best explanation.</span></div><div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span"><br /></span></div><div><br /></div><div><br /></div>

Answer 1

Thanks very much for the comments. Â
The Gem Cutter Manual is the least 'evolved' of docs we have put out (written in 2001 and only given some TLC last week!). To be honest, we almost didn't put it out, but as I think you've confirmed, it is worth it because we need an intro to the tool. Your notes are very welcome, and will help us tighten up the text, especially in some of its 'fuzzier' aspects ;-)
Aside from your points about the document flow turns of phrase, I can comment on the following points:
>[As a side point, it might increase usability of the gem cutter if the inputs / outputs were larger? or maybe the mouse 'snapped' to them when dragging?]
Yes, the snapping idea would be a good feature. I think it was discussed once(!) Connecting in the regular way does require one's fine motor skills to be in reasonable shape.Â
>At this point I'm still not sure whether Gem Cutter is effectively just providing a graphical way of writing CAL code, or whether it's doing something else. I managed to locate the "./bin/cal/release/CAL/GemCutterSaveModule.cal" file which seems to be reflecting what I'm doing in the cutter - it might be useful to explicitly point people to this so that they can see what is going on if they're interested?
The Gem Cutter does indeed 'just write CAL code' (in fact just functions). In its current form, it's utility lies as a kind of interactive laboratory for when people are experimenting with functional logic. Typically it therefore has the most usefulness in the following situations:
- When learning about functional programming
- When setting out to design some new functional module from scratch (where you want a more RAD approach, quickly prototyping some ideas, testing them, lots of iterative refinement etc).Â
- When playing with composition - perhaps testing the public interfaces of some modules to check that desired logic can be built from the 'building blocks' they expose (particularly useful with the sort of high-level 'functional models' we build to express high-level data behaviours).
Around here, I tend to see it up on people's screens when they are at the beginning of some larger task. Once some key ideas have been established, then people tend to take what the Gem Cutter has produced in the way of code, and move over to a regular syntax workflow (in Eclipse). Â
The biggest strength of the Gem Cutter is its interactivity IMO. Using the tool often provides considerable insights as you see types change on connectors or run small portions of code (you can run any 'collector'). This is certainly valuable at particular points, but when you are done 'programming through a keyhole', then you just resort to your favourite text editor. To me, this can be a big 'something else'. Â
BTW, another way to see the code that gets produced from the Gem Cutter is to connect logic to the Target Gem (result) and then use the "Edit->Copy Special->Target Gem Source" menu option. This will put CAL code into your paste buffer. Â
>I couldn't get a local variable to show up in the code editor as described by the document. I used the following: let a = (2*x);ingreaterThan a 17
Er...yes, I think that functionality is defunct (probably changed sometime in 2004!), sorry about the misleading information. The Code Gem Editor these days does not show local variables on the LHS, just arguments and functions. Instead, local variables are highlighted in the code and a tooltip will indicate what they
represent. Â