Comments on the Gem Cutter docs
<div><span style="font-family: Helvetica; font-size: 12px" class="Apple-style-span">Thought I'd make some notes on this as I read through it. Overall, it'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 'anythings')"</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't "[Num]". (same applies to type-class reference on p25 - maybe the intro to the doc should just list some 'prerequisites'?)</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'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 'snapped' 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'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?</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't been explicitly explained, so mentioning their appearance in the browser might be confusing if people aren'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'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'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'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'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>