Ideas for making Guile easier to approach

[Christine Lemmer-Webber]

I've been appreciating the feedback in this thread about Guile; I'm
starting a new topic name because I think we've deviated from talking
about Guile Hall and more about Guile.

Some stuff below.

Chris Vine <vine35792468@gmail.com> writes:

> On Tue, 08 Feb 2022 19:19:06 +0700
> Blake Shaw <blake@nonconstructivism.com> wrote:
>
>> Vijay Marupudi <vijaymarupudi@gatech.edu> writes:
>> > I don't think it's fair to say that using packages in Guile just as
>> > easy/hard as other languages. Python / Javascript make this incredibly
>> > easy, and their ecosystem is evidence for that success. Their package
>> > managers have flaws, but they have benefits too, and those benefits
>> > would be great for Guile.
>> 
>> I would just like to tag onto this convo that I agree that its not fair
>> to say that Guile is easy and will quickly bless those who endeavor to
>> learn it with superpowers. My experience w/Racket was very smooth and I 
>> got working in it very quickly. I was a contracted to work on a project in
>> Python a few months ago and without ever studying it I was able to 
>> start doing production work in it (ridiculous how intuitive it is,
>> really). Before I started learning Guile I read Edwin Brady's book on
>> Idris and found Idris much easier to get from start to end of small
>> projects I was working on (because there is a well written book on it).
>> 
>> While Guile has become my favorite programming language, it took me
>> several months to learn how to navigate & figure out how to navigate the
>> SRFIs, how to plan a program so that I can know what to expect along the
>> way (what features I'll need to implement myself, etc) before I was able
>> to get productive in it beyond the realm of Guix. And I think most would
>> agree that Scheme is a less advanced language than Idris (I did some
>> category theory in school so I have some intuition for the ideas, but
>> still). And to be honest, I still hit plenty of road blocks.
>> 
>> There were definitely some times where I was digging around trying to
>> figure out how to do things and came across messages in the archives
>> saying "its so easy you just do [vague hand wavy explanation]". And I
>> found that quite frustrating, like there is an insularity meant to weed
>> out the bad apples. And when this topic popped up on the guix list a few
>> weeks ago some others expressed similar concerns, folks who are doing
>> very impressive work. A programming language should never make
>> programmers feel dumb -- it should make us feel empowered!
>
> Everything is capable of improvement but the guile manual is a manual
> and not I think primarily intended as a language tutorial (although
> Chapter 3 of the manual does have a very cursory introduction to the
> scheme language).  If you are looking for a tutorial, I suggest reading
> https://www.scheme.com/tspl4/ .  It covers the R6RS flavour, but at the
> tutorial level I don't think the various current standard flavours
> (R5RS, R6RS and R7RS) matter too much.
>
> I would be reluctant to see the manual turned into a tutorial if that
> were to mean abridging any of its current completeness.

The manual does contain a very brief tutorial, but it's brief...  the
Guix cookbook also contains something short.  Both seem a bit lacking to
me but they could be starting points.

Regarding the manual as a manual, I actually personally like the Guile
manual a lot.  I think it's very well written.  But it's a reference
guide.

But I do remember finding it overwhelming and confusing initially.  I
think a few things could improve the situation, some manual related,
some other things:


Guile Reference vs Guile Guide
==============================

Personally I think the *best* experience I have ever had in reading
manuals is in Racket.

Racket has a nice way of handling things:

 - There's a set of initial "short tutorials" that are really to get you
   up and running and feel like you "did something cool" fast.  This is
   great, and it would be nice to have some of these, maybe with
   screencast examples.

 - Racket also separates the "Guide" from the "Reference".  Well that's
   sensible!  Guile actually has a very good "reference manual", maybe
   what it needs is a *companion* in terms of the "Guile Guide".

(Note that despite my high praise for Racket's manuals, that's not a
universal impression; I have a friend who has told me several times that
Racket's manuals were hard for her because they seem too aimed at PLT
type folks.  I still think highly of them but want to note that.)


Module names
============

ice-9 -> guile
--------------

I think that ice-9 is a weird namespace for "guile's standard library"
but it's what we have for historical reasons.  Still I would have
preferred that namespace simply be "guile", so we have (guile match) and
(guile format) instead of (ice-9 ...).  It would be clearer what ice-9
*is* to have it be called "guile" instead.  But maybe it's too late for
that.  How much work would it be to do an alias like this?


Named SRFIs
-----------

If it's possible to do such aliases, I'd also say that making sense of
what SRFI module is what is a real mess for me.  (srfi srfi-9) doesn't
tell me what that SRFI *is*.  However, if we supported "named" versions
of SRFIs, that would help me.  Which of these would be easier to read?

Heck, maybe I should make a SRFI for common human readable SRFI names.
#mildlyspicytake #maybenotabadidea


An example, a comparison
------------------------

Taken all together, imagine if instead of:

  (define-module (my-module)
    #:use-module (ice-9 match)
    #:use-module (ice-9 format)
    #:use-module (srfi srfi-1)
    #:use-module (srfi srfi-9)
    #:use-module (srfi srfi-37)
    #:use-module (srfi srfi-41)
    #:use-module (srfi srfi-64))         

We had:

  (define-module (my-module)
    #:use-module (guile match)
    #:use-module (guile format)
    #:use-module (srfi list-utils)
    #:use-module (srfi records)
    #:use-module (srfi args-fold)
    #:use-module (srfi streams)
    #:use-module (srfi tests))

Much easier to follow, no?


Guile Studio and the picture language!
======================================

I've finally, finally tried out Ricardo Wurmus' Guile Studio, which is
actually quite impressive.  It sets up Emacs to be like DrRacket, easy
to pick up and hack for a complete newcomer.  Very nice!  If we do have
screencasty type things it might be nice to use Guile Studio as the
environment we start showing people in.


Wisp
====

I'd like to actually see Guile integrate Wisp as a core language and
think about what it would be like to support it as a recommended
alternate way of writing programs.  I think with the new block-level
highlighting that Arne has written, Wisp could be near ready for prime
time.  This could mean:

 - Getting wisp actually in Guile's official languages
 - Figuring out how to get geiser to be nicely integrated
 - Figuring out how to make importing Wisp modules be as easy as
   importing parenthetical-lisp ones


Anyway, those are my thoughts.  This email was longer than I meant or
expected.  Maybe it's useful.  Thoughts?

 - Christine