Re: Ideas for a Guile tutorial to go with the new site
Mike Gerwitz writes: > On Wed, Dec 16, 2015 at 08:33:30 -0600, Christopher Allan Webber wrote: >> What you'll notice is that each new sentence starts on its own line. >> Sentences which have characters which continue beyond line 79 "wrap", >> but are indented to be clear that they align with a previous sentence. > > I'm actually quite fond of this; good idea. This will clean up my diffs > substantially (I refill every time I modify a paragraph). > > Thanks for sharing that. Glad someone else will find it helpful :)
Re: Ideas for a Guile tutorial to go with the new site
On Wed, Dec 16, 2015 at 08:33:30 -0600, Christopher Allan Webber wrote: > What you'll notice is that each new sentence starts on its own line. > Sentences which have characters which continue beyond line 79 "wrap", > but are indented to be clear that they align with a previous sentence. I'm actually quite fond of this; good idea. This will clean up my diffs substantially (I refill every time I modify a paragraph). Thanks for sharing that. -- Mike Gerwitz Free Software Hacker | GNU Maintainer http://mikegerwitz.com FSF Member #5804 | GPG Key ID: 0x8EE30EAB signature.asc Description: PGP signature
Re: Ideas for a Guile tutorial to go with the new site
Alex Sassmannshausen writes: > That's looking pretty good. Personally I'm not sure about the > positioning of the bit about text editors — it feels like it is a little > tangential to getting Guile up and running. It feels like perhaps it > should be mentioned later (e.g. when you actually mention storing stuff > in a .scm file? > > (also, it kind of acts as a mental barrier to just firing up Guile and > having a go — which is, I think, the playful feeling you want to instil > in your readership?) I think you're right probably. I tried to make it an "optional" section. On the other hand, realizing why Guile is really nice to work in requires having a pretty decent setup, so it might be worth the time investment to mention it there. I'm not sure yet... I think maybe once more content has come after it, we can re-evaluate and refactor. Would that make sense? For now, I've broken up the editor and readline part into its own clearly marked as "optional" section. > I definitely still think this is a really cool way to go. I'd probably > think that you'll want to walk a fine line between playfulness and over > the top childishness — and that line will be different for different > people I guess! 8-| Yeah it will. I'll be tuning towards my own personal preferences, and hopefully that aligns with enough people. > But I think it's a cool initiative, that would have really helped me if > it had been available on the Guile website when I first started learning > Guile. Yay! > As an aside, what's the best way to pass you "editorial" feedback (typos > and such) — as git patches or as inline corrections? Either works; but git patches are nice. I tried to set up the format of documentation so that patching it should be easy while keeping the source readable. To demonstrate, here's an example: (p [You also might build up some fun toys while running through this tutorial. You might want to play with them and re-use them without having to type them in all over again. This is where your text editor comes into play! Try opening a new file, we'll call it "sandbox.scm". When you build something in this tutorial you'd like to use over and over again without retyping it between REPL sessions, you can put it here. Let's try putting something there now:]) What you'll notice is that each new sentence starts on its own line. Sentences which have characters which continue beyond line 79 "wrap", but are indented to be clear that they align with a previous sentence. This is an unusual convention, but I think a sane one: my usual temptation is to use emacs' fill-paragraph technique to keep things looking nice in plaintext, but that can entirely rearrange paragraphs, and in my experience makes merging changes hard. I heard the recommendation a while ago that keeping a sentence on its own line is a better way to go for version-controlled documentation, but usually that ends up flying off beyond column 80, and I hate that. So the above approach merges the two. That seems like useful information to document, so I'll do that now. :) Patches welcome. Please include an update to the copyright line including your name if you do so, and acknowledge that you're okay with it being dual licensed under the LGPL and GFDL!
Re: Ideas for a Guile tutorial to go with the new site
Hi Chris, Christopher Allan Webber writes: > Christopher Allan Webber writes: > >> Hello! >> >> So I've been thinking a bit about what a friendly "intro" tutorial would >> look like that could fit with the direction the site is heading. I came >> up with some ideas I wanted to capture before I totally lost them. > > Well I started implementing this. > > Here's the code: > https://notabug.org/cwebber/guile-tutorial > > It's using the excellent Skribilo. (I had *no idea* just how excellent until > I started this... amazing stuff!) Indeed, that looks pretty neat! > So: > >> I think we can keep with the kids playing with robot toys idea and >> stretch that a bit. Here's a brief outline: >> >> - Intro >> - Getting up and running >>(picture of one of those robots with a wind-up-toy-key on its back?) >>+ How to start guile from the command line, add readline support >>+ Editor setup, simple >> >> Details how to write some scheme with any editor, maybe makes a >> free software editor recommendation of something simple that's not >> too hard to get going with Scheme. Would GEdit work? >> >> Shows how to write a file and then import it at the REPL, >> then reload it as you add things. >> >> Teaches the basic idea of writing code in a file + playing at the REPL. >> >>+ Editor setup, advanced: Emacs + Geiser >> >> Explains that this is the advanced, but recommended version. >> It takes some time to get started with if you are not already an >> emacs user, but you may want to come back to it later. Explains >> how to set things up. > > I've gotten this far. The rest of the stuff below still needs to be > done. That's looking pretty good. Personally I'm not sure about the positioning of the bit about text editors — it feels like it is a little tangential to getting Guile up and running. It feels like perhaps it should be mentioned later (e.g. when you actually mention storing stuff in a .scm file? (also, it kind of acts as a mental barrier to just firing up Guile and having a go — which is, I think, the playful feeling you want to instil in your readership?) > I'm still interested in mixing this with sirgazil/Lusis's drawings if he > is. I think that would be great! > I haven't gotten into the fun part of the tutorial yet, but I'm kind of > optimistic. The remaining parts are below. What do people think, is > this worth spending the time on? And might we want to put it on the > Guile website officially at some point...? > >> - First steps >> >>Much like The Little Schemer uses food as variable names, I think >>it's a good idea to stick with abstract fun concepts. Here, I think >>it would be great to continue along with the "Guile is a playground, >>come play!" idea by using toys as variable names, and defining >>procedures that evoke nostalgia for older programmers and sound >>playful for younger ones. >> >>Some ideas: >> + could use building lists as putting toys in and out of a toy >>chest >> >>(define toy-chest '(robot teddy-bear doll-with-comb toy-soldier)) >> >> + could have a simple-bake-oven set of procedures that takes >>arguments like flavor and dessert-type: >> >> #> (define (simple-bake-oven flavor dessert-type) >> (format #f "Yum! You made a tasty ~a flavored ~a!" >> flavor dessert-type)) >> #> (simple-bake-oven "banana" "cake") >> $20 = "Yum! You made a tasty banana flavored cake!" >> >>and then we can increase the advanced features a bit: >> >> #> (define* (fancy-bake-oven flavor dessert-type >> #:optional topping) >> (if topping >> (format #f "Yum! You made a tasty ~a flavored ~a covered >> in ~a!" >> flavor dessert-type topping) >> (format #f "Yum! You made a tasty ~a flavored ~a!" >> flavor dessert-type))) >> #> (fancy-bake-oven "mint" "ice cream" "chocolate fudge") >> $21 = "Yum! You made a tasty mint flavored ice cream covered in >> chocolate fudge!" >> >>Yes... the fancy bake oven version is so fancy it can even bake >>ice cream! ;) >> >> + Introduce modules as extensions for our robots. >> >> I'm sure there are other things! But I think a tutorial in this style >> might be fun, and would fit the site well. And the desire for a good >> tutorial has been expressed many times. >> >> What do others think? I definitely still think this is a really cool way to go. I'd probably think that you'll want to walk a fine line between playfulness and over the top childishness — and that line will be different for different people I guess! 8-| But I think it's a cool initiative, that would have really helped me if it had been available on the Guile website when I first started learning Guile.
