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

[Christopher Allan Webber <cwebber@dustycloud.org>]

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!