Ideas for a Guile tutorial to go with the new site

Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

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.

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.

 - 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?

Re: Ideas for a Guile tutorial to go with the new site

[Taylan Ulrich Bayırlı/Kammer]

Christopher Allan Webber <cwebber@dustycloud.org> 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.
>
> I think we can keep with the kids playing with robot toys idea and
> stretch that a bit.  Here's a brief outline:
>
>  [... snip ...]
>
> 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'm not sure if I'd have time to contribute to it, but I'm all for the
idea. :-)

Taylan

Re: Ideas for a Guile tutorial to go with the new site

[Luis Felipe López Acevedo]

On 2015-10-18 10:41, Christopher Allan Webber wrote:
> 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.
> 
> 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.
> 
>  - 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?

Absolutely. This is in line with my thoughts about the intro tutorial.

The "Getting up and running" section looks like a good part to start 
materializing the tutorial.

-- 
Luis Felipe López Acevedo
http://sirgazil.bitbucket.org/

Re: Ideas for a Guile tutorial to go with the new site

[Amirouche Boubekki]

Le 2015-10-18 20:44, Luis Felipe López Acevedo a écrit :
> On 2015-10-18 10:41, Christopher Allan Webber wrote:
>> 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.
>> 
>> 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.
>> 
>>  - 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?
> 
> Absolutely. This is in line with my thoughts about the intro tutorial.

To the contrary I think it's not a good idea to start upfront the 
tutorial with which editor should be used is a good way to loose half of 
the readers, because they will feel more uncomfortable and not up to the 
task. To be useful emacs requires one 'Getting Started' tutorial in 
itself. Or anykind of setup for that matter. The tutorial should go as 
quickly as possible to the matter and start with coding.

I started a tutorial at http://hypermove.net/. I don't introduce 
readline until the user knows what the REPL is. Part 1 is all done in 
REPL. I subtly introduce emacs as a good choice for an editor in part 2 
which is done in an editor. But doesn't enforce it.

I don't think my tutorial is perfect, far away that idea is. I'll 
rewrite the tutorial to avoid any allusion to the Earth Software System 
and instead use The Little Lost Robot as storyline.

> The "Getting up and running" section looks like a good part to start 
> materializing the tutorial.

I sent a previous mail to the ML describing my work. Again feel free to 
comment.

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

Amirouche Boubekki writes:

> To the contrary I think it's not a good idea to start upfront the 
> tutorial with which editor should be used is a good way to loose half of 
> the readers, because they will feel more uncomfortable and not up to the 
> task. To be useful emacs requires one 'Getting Started' tutorial in 
> itself. Or anykind of setup for that matter. The tutorial should go as 
> quickly as possible to the matter and start with coding.
>
> I started a tutorial at http://hypermove.net/. I don't introduce 
> readline until the user knows what the REPL is. Part 1 is all done in 
> REPL. I subtly introduce emacs as a good choice for an editor in part 2 
> which is done in an editor. But doesn't enforce it.

Okay, sorry if I wasn't being clear... my goal in that section would be
to encourage everyone who *isn't already an emacs user* to pick up a
simple editor and know how to use that with Guile, but them give them a
brief tip that they want to look into Emacs + Geiser once they've dived
in a bit more deeply.

I don't think this section needs to be too long.  I agree it should not
be overwhelming.

>> The "Getting up and running" section looks like a good part to start 
>> materializing the tutorial.
>
> I sent a previous mail to the ML describing my work. Again feel free to 
> comment.

We discussed this on IRC, but I think your tutorial and the one I
proposed above target different audiences, which is great!  Having
multiple tutorials is very helpful.

Re: Ideas for a Guile tutorial to go with the new site

[BCG]

On 10/19/2015 12:29 PM, Christopher Allan Webber wrote:
> Amirouche Boubekki writes:
>
>> To the contrary I think it's not a good idea to start upfront the
>> tutorial with which editor should be used is a good way to loose half of
>> the readers, because they will feel more uncomfortable and not up to the
>> task. To be useful emacs requires one 'Getting Started' tutorial in
>> itself. Or anykind of setup for that matter. The tutorial should go as
>> quickly as possible to the matter and start with coding.
>>
>> I started a tutorial at http://hypermove.net/. I don't introduce
>> readline until the user knows what the REPL is. Part 1 is all done in
>> REPL. I subtly introduce emacs as a good choice for an editor in part 2
>> which is done in an editor. But doesn't enforce it.
> Okay, sorry if I wasn't being clear... my goal in that section would be
> to encourage everyone who *isn't already an emacs user* to pick up a
> simple editor and know how to use that with Guile, but them give them a
> brief tip that they want to look into Emacs + Geiser once they've dived
> in a bit more deeply.
>
> I don't think this section needs to be too long.  I agree it should not
> be overwhelming.
>
Personally I would appreciate a not-so-brief tip.  Most resources on the 
web about coding in scheme seem to claim that emacs is the best 
environment for it, but rarely go into the reasoning about why or 
provide a focused way to get started with it.  I'd be happy to try out 
those tools, but it hardly is worth it to me to slog through the emacs 
tutorial just to see if I like whatever advantages it may have for 
coding Scheme.

After so many years of vi muscle memory I just can't find justification 
to slow down my productivity and learn emacs... but I wouldn't mind 
doing it just for Guile coding where I'm not really productive yet 
anyways - especially if there was getting started guide focused on that 
with pointers to other resources for a deeper dive if I like it.

Even if I didn't end up switching to emacs for everything, I may find 
that I want to use it just for Scheme... just like I fire up Eclipse 
when I want to work on Java, but I don't bother using Eclipse for 
anything else

It doesn't seem like a suggestion for a development environment should 
distract too much from a tutorial, but maybe that is too much to expect 
when your audience includes hackers. ;)

Just my opinion, which is worth what you paid for it.

-- Ben

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

BCG writes:

> On 10/19/2015 12:29 PM, Christopher Allan Webber wrote:
>> Amirouche Boubekki writes:
>>
>>> To the contrary I think it's not a good idea to start upfront the
>>> tutorial with which editor should be used is a good way to loose half of
>>> the readers, because they will feel more uncomfortable and not up to the
>>> task. To be useful emacs requires one 'Getting Started' tutorial in
>>> itself. Or anykind of setup for that matter. The tutorial should go as
>>> quickly as possible to the matter and start with coding.
>>>
>>> I started a tutorial at http://hypermove.net/. I don't introduce
>>> readline until the user knows what the REPL is. Part 1 is all done in
>>> REPL. I subtly introduce emacs as a good choice for an editor in part 2
>>> which is done in an editor. But doesn't enforce it.
>> Okay, sorry if I wasn't being clear... my goal in that section would be
>> to encourage everyone who *isn't already an emacs user* to pick up a
>> simple editor and know how to use that with Guile, but them give them a
>> brief tip that they want to look into Emacs + Geiser once they've dived
>> in a bit more deeply.
>>
>> I don't think this section needs to be too long.  I agree it should not
>> be overwhelming.
>>
> Personally I would appreciate a not-so-brief tip.  Most resources on the 
> web about coding in scheme seem to claim that emacs is the best 
> environment for it, but rarely go into the reasoning about why or 
> provide a focused way to get started with it.  I'd be happy to try out 
> those tools, but it hardly is worth it to me to slog through the emacs 
> tutorial just to see if I like whatever advantages it may have for 
> coding Scheme.
>
> After so many years of vi muscle memory I just can't find justification 
> to slow down my productivity and learn emacs... but I wouldn't mind 
> doing it just for Guile coding where I'm not really productive yet 
> anyways - especially if there was getting started guide focused on that 
> with pointers to other resources for a deeper dive if I like it.
>
> Even if I didn't end up switching to emacs for everything, I may find 
> that I want to use it just for Scheme... just like I fire up Eclipse 
> when I want to work on Java, but I don't bother using Eclipse for 
> anything else
>
> It doesn't seem like a suggestion for a development environment should 
> distract too much from a tutorial, but maybe that is too much to expect 
> when your audience includes hackers. ;)
>
> Just my opinion, which is worth what you paid for it.
>
> -- Ben

Thanks for the input!  Maybe we can go both ways... keep it brief in the
tutorial, but have a link to "for more on why this is, see this link"
which goes to the manual, or some blogpost, or other resource?

Re: Ideas for a Guile tutorial to go with the new site

[Luis Felipe López Acevedo]

On 2015-10-20 17:45, BCG wrote:
> On 10/19/2015 12:29 PM, Christopher Allan Webber wrote:
>> Amirouche Boubekki writes:
>> 
>>> To the contrary I think it's not a good idea to start upfront the
>>> tutorial with which editor should be used is a good way to loose half 
>>> of
>>> the readers, because they will feel more uncomfortable and not up to 
>>> the
>>> task. To be useful emacs requires one 'Getting Started' tutorial in
>>> itself. Or anykind of setup for that matter. The tutorial should go 
>>> as
>>> quickly as possible to the matter and start with coding.
>>> 
>>> I started a tutorial at http://hypermove.net/. I don't introduce
>>> readline until the user knows what the REPL is. Part 1 is all done in
>>> REPL. I subtly introduce emacs as a good choice for an editor in part 
>>> 2
>>> which is done in an editor. But doesn't enforce it.
>> Okay, sorry if I wasn't being clear... my goal in that section would 
>> be
>> to encourage everyone who *isn't already an emacs user* to pick up a
>> simple editor and know how to use that with Guile, but them give them 
>> a
>> brief tip that they want to look into Emacs + Geiser once they've 
>> dived
>> in a bit more deeply.
>> 
>> I don't think this section needs to be too long.  I agree it should 
>> not
>> be overwhelming.
>> 
> Personally I would appreciate a not-so-brief tip.  Most resources on
> the web about coding in scheme seem to claim that emacs is the best
> environment for it, but rarely go into the reasoning about why or
> provide a focused way to get started with it.  I'd be happy to try out
> those tools, but it hardly is worth it to me to slog through the emacs
> tutorial just to see if I like whatever advantages it may have for
> coding Scheme.

I think a video tutorial to get the user started with Guile + Emacs 
would be great for that. First video in a "Learn GNU Guile" series 
hosted in a MediaGoblin instance :)



-- 
Luis Felipe López Acevedo
http://sirgazil.bitbucket.org/

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

Luis Felipe López Acevedo writes:

> On 2015-10-20 17:45, BCG wrote:
>> On 10/19/2015 12:29 PM, Christopher Allan Webber wrote:
>>> Amirouche Boubekki writes:
>>> 
>>>> To the contrary I think it's not a good idea to start upfront the
>>>> tutorial with which editor should be used is a good way to loose half 
>>>> of
>>>> the readers, because they will feel more uncomfortable and not up to 
>>>> the
>>>> task. To be useful emacs requires one 'Getting Started' tutorial in
>>>> itself. Or anykind of setup for that matter. The tutorial should go 
>>>> as
>>>> quickly as possible to the matter and start with coding.
>>>> 
>>>> I started a tutorial at http://hypermove.net/. I don't introduce
>>>> readline until the user knows what the REPL is. Part 1 is all done in
>>>> REPL. I subtly introduce emacs as a good choice for an editor in part 
>>>> 2
>>>> which is done in an editor. But doesn't enforce it.
>>> Okay, sorry if I wasn't being clear... my goal in that section would 
>>> be
>>> to encourage everyone who *isn't already an emacs user* to pick up a
>>> simple editor and know how to use that with Guile, but them give them 
>>> a
>>> brief tip that they want to look into Emacs + Geiser once they've 
>>> dived
>>> in a bit more deeply.
>>> 
>>> I don't think this section needs to be too long.  I agree it should 
>>> not
>>> be overwhelming.
>>> 
>> Personally I would appreciate a not-so-brief tip.  Most resources on
>> the web about coding in scheme seem to claim that emacs is the best
>> environment for it, but rarely go into the reasoning about why or
>> provide a focused way to get started with it.  I'd be happy to try out
>> those tools, but it hardly is worth it to me to slog through the emacs
>> tutorial just to see if I like whatever advantages it may have for
>> coding Scheme.
>
> I think a video tutorial to get the user started with Guile + Emacs 
> would be great for that. First video in a "Learn GNU Guile" series 
> hosted in a MediaGoblin instance :)

That would be great, yes!

Re: Ideas for a Guile tutorial to go with the new site

[Ludovic Courtès]

Howdy!

I like all the ideas, being a fan of the simplicity and welcoming
aspects of the “Little” books.

So, who’s in?  :-)

Thanks,
Ludo’.

Re: Ideas for a Guile tutorial to go with the new site

[Mathieu Lirzin]

Hi Christopher,

Christopher Allan Webber <cwebber@dustycloud.org> writes:

>  - 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?

As much as I appreciate my Emacs environment, I think GEdit + basic REPL
in a terminal is the right choice for presenting Guile.  I think it
would be better not explaining how to setup Geiser+Emacs in this
tutorial and just mentioning it by giving a link to separate resource
(which don't exist yet...) for those who are already familiar with
Emacs.

> 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.

This is definitely a great initiative!

Thanks,

--
Mathieu Lirzin

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

Mathieu Lirzin writes:

> Hi Christopher,
>
> Christopher Allan Webber <cwebber@dustycloud.org> writes:
>
>>  - 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?
>
> As much as I appreciate my Emacs environment, I think GEdit + basic REPL
> in a terminal is the right choice for presenting Guile.  I think it
> would be better not explaining how to setup Geiser+Emacs in this
> tutorial and just mentioning it by giving a link to separate resource
> (which don't exist yet...) for those who are already familiar with
> Emacs.

That's roughly what I was going for!  I figured there would be a very
minimal introduction on how to set up a hacking environment with *any*
editor, then those who are ready to set up geiser + emacs can figure out
how to do it, after being pointed in this direction anyway.

>> 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.
>
> This is definitely a great initiative!
>
> Thanks,

Great, thank you!

(I hope I or someone else have time to do it soon...!)
 - Chris

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

Ludovic Courtès writes:

> Howdy!
>
> I like all the ideas, being a fan of the simplicity and welcoming
> aspects of the “Little” books.
>
> So, who’s in?  :-)
>
> Thanks,
> Ludo’.

I'm glad you like it.  I would *like* to be able to do this, but I
officially don't have the time right at the moment.  Unofficially, I
might do it anyway when procrastinating on something "more important" ;)

But that's definitely a "no promises" statement.  If someone else took
the initiative I'd be happy to jump in and help with that!

 - Chris

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

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!)

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.

I'm still interested in mixing this with sirgazil/Lusis's drawings if he
is.

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?

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

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

Oh right, and a preview:
  http://dustycloud.org/misc/guile-tutorial.html

Re: Ideas for a Guile tutorial to go with the new site

[Alex Sassmannshausen]

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.

As an aside, what's the best way to pass you "editorial" feedback (typos
and such) — as git patches or as inline corrections?

HTH,

Alex

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

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

[Mike Gerwitz]

[-- Attachment #1: Type: text/plain, Size: 582 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

Re: Ideas for a Guile tutorial to go with the new site

[Christopher Allan Webber]

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 :)