guile scheme tutorial

guile scheme tutorial

[amirouche]

Hello!


If you are getting started guix and want a glimpse of guile,
I made a small tutorial that might get you started:

    https://github.com/a-guile-mind/book/#a-guile-mind-book

Feel free to share your own resources to learn Guile Scheme.

Happy hacking!



Amirouche ~ amz3

Re: guile scheme tutorial

[Guy fleury]

Hello amirouche,

thank you for sharing!
Le 3 mai 2019 15:40, <amirouche@hyper.dev> a écrit :

> Hello!
>
>
> If you are getting started guix and want a glimpse of guile,
> I made a small tutorial that might get you started:
>
>    https://github.com/a-guile-mind/book/#a-guile-mind-book
>
> Feel free to share your own resources to learn Guile Scheme.
>
> Happy hacking!
>
>
>
> Amirouche ~ amz3
>
>

Re: guile scheme tutorial

[Laura Lazzati]

Thanks :)

Re: guile scheme tutorial

[amirouche]

On 2019-05-03 14:45, amirouche@hyper.dev wrote:
> Hello!
> 
> 
> If you are getting started guix and want a glimpse of guile,
> I made a small tutorial that might get you started:
> 
>    https://github.com/a-guile-mind/book/#a-guile-mind-book

I was just made aware that the calculations results are not good
in the tutorial. I can not fix it right now. I will do it tomorrow.

You need to install guile-readline to have "normal" REPL:

   guix install guile-readline

Also, rekado made a package called guile-studio:

   This is Emacs with a few settings that make working
   with Guile easier for people new to Emacs.  Features
   include: CUA mode, Geiser, tool bar icons to evaluate
   Guile buffers, support for Guile's very own picture
   language, code completion, a simple mode line, etc.

And as noted above guile-picture-language.

In my usual workflow I don't rely only on emacs. I use somewhat
magit but for instance I don't use emacs-guix. ymmv. Anyway,
the goal of the tutorial is to get you started with scheme syntax.

The big omissions of the tutorial:

- macros, you can use macros without knowing how to write one.
   define-record-type is a macro. The package definition is a macro.
   Just remember that the evaluation of expressions in a macro is macro
   specific. Refer to an example or the documentation to learn how
   to use it.

- quasiquote, quote, unquote, unquote-splicing which is used a lot
   in guix package definitions. Their understanding and use are
   straight forward. They allow to describe a construction using
   the literal syntax e.g.:

     (list (cons 'a 42) ('b 101))

   Can be written:

     '((a . 42) (b 101))

   Which happens to be what the REPL give in the output plus the quote.

   Then if you have a variable around you can insert it inside a
   quasiquote with unquote e.g.:

      (define magic 42)
      `((a . ,magic) (b 101))

   quasiquote and unquote is used in most association lists. Like in 
package
   definition inputs, propagated inputs and the last one I don't 
remember.


One last advice, when you import a module in the REPL, it must be easier
to prefix the import (that will import everything public in that module)
so that you can TAB-complete the prefix to learn the content fo the 
module:


   (use-modules ((guix packages) #:prefix foo:))

Then when you type foo: in the REPL (or geiser) you get only what is in 
the
module prefixed with foo:

This is usually done in guile project, inside modules to avoid variable 
clash
but it is also helpful in the REPL to discover the content of a module.

The best way to learn code is to read good code like guix.

> Feel free to share your own resources to learn Guile Scheme.
> 
> Happy hacking!

Re: guile scheme tutorial

[rendaw]

On 5/3/19 9:45 PM, amirouche@hyper.dev wrote:
> Hello!
>
>
> If you are getting started guix and want a glimpse of guile,
> I made a small tutorial that might get you started:
>
>    https://github.com/a-guile-mind/book/#a-guile-mind-book
>
> Feel free to share your own resources to learn Guile Scheme.
>
> Happy hacking!
>
>
>
> Amirouche ~ amz3
>

Oh, this is great!  I've actually been putting together a small Guix
guide here:
https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md

It has a small Guile primer, but it doesn't go into depth or have any
hands on examples like yours.  My goal was to cover just enough so that
people could understand Guix configs (or at least 90% of them), so no
recursion, etc.  I'm glad you got into records, I just kind of handwaved
that away ("they're functions", not 100% sure this is correct either).

Re: guile scheme tutorial

[rendaw]

On 5/3/19 9:45 PM, amirouche@hyper.dev wrote:
> Hello!
>
>
> If you are getting started guix and want a glimpse of guile,
> I made a small tutorial that might get you started:
>
>    https://github.com/a-guile-mind/book/#a-guile-mind-book
>
> Feel free to share your own resources to learn Guile Scheme.
>
> Happy hacking!
>
>
>
> Amirouche ~ amz3
>
(Whoops, replied with the wrong account.)

Oh, this is great!  I've actually been putting together a small Guix
guide here:
https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md

It has a small Guile primer, but it doesn't go into depth or have any
hands on examples like yours.  My goal was to cover just enough so that
people could understand Guix configs (or at least 90% of them), so no
recursion, etc.  I'm glad you got into records, I just kind of handwaved
that away ("they're functions", not 100% sure this is correct either).

Re: guile scheme tutorial

[Ludovic Courtès]

Hi rendaw,

rendaw <7e9wc56emjakcm@s.rendaw.me> skribis:

> Oh, this is great!  I've actually been putting together a small Guix
> guide here:
> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md

Nice!

I skimmed at
<https://gitlab.com/rendaw/blog/blob/master/a_brief_guix_review.md> and
I wonder if you could point out areas where documentation is severely
lacking?  We’d all very much welcome improvements to the manual so your
insight as a newcomer is valuable.

(Besides I wouldn’t consider mailing lists as a “user hostile” tool, but
that’s not another story…)

Thanks,
Ludo’.

Re: guile scheme tutorial

[amirouche]

On 2019-05-04 08:08, rendaw wrote:
> On 5/3/19 9:45 PM, amirouche@hyper.dev wrote:
>> Hello!
>> 
>> 
> (Whoops, replied with the wrong account.)
> 
> Oh, this is great!  I've actually been putting together a small Guix
> guide here:
> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md
> 
> It has a small Guile primer, but it doesn't go into depth or have any
> hands on examples like yours.  My goal was to cover just enough so that
> people could understand Guix configs (or at least 90% of them), so no
> recursion, etc.  I'm glad you got into records, I just kind of 
> handwaved
> that away ("they're functions", not 100% sure this is correct either).

That is good. The beginning looks like guix is not worthwhile and then
you continue in the second page with an introduction to guile and guix.
I find it nice actually.

I spotted a minor error:

   (system* (string-append #$openssl "/bin/openssl")
            "genrsa" "-out" private-key "2048"))

   
https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md#running-executables

Indeed you can run programs like that but in guix it is preferred to run
with invoke, see the source :)

Thanks for sharing!

Re: guile scheme tutorial

[Laura Lazzati]

Hi!

Thanks all of you for the tutorials :)

We can compliment them with the videos :) - my bad, sorry, I would
have liked to have them already finished :(

Regards :)

Laura

Re: guile scheme tutorial

[rendaw]

On 5/4/19 8:02 PM, amirouche@hyper.dev wrote:
> On 2019-05-04 08:08, rendaw wrote:
>> On 5/3/19 9:45 PM, amirouche@hyper.dev wrote:
>>> Hello!
>>>
>>>
>> (Whoops, replied with the wrong account.)
>>
>> Oh, this is great!  I've actually been putting together a small Guix
>> guide here:
>> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md
>>
>>
>> It has a small Guile primer, but it doesn't go into depth or have any
>> hands on examples like yours.  My goal was to cover just enough so that
>> people could understand Guix configs (or at least 90% of them), so no
>> recursion, etc.  I'm glad you got into records, I just kind of handwaved
>> that away ("they're functions", not 100% sure this is correct either).
>
> That is good. The beginning looks like guix is not worthwhile and then
> you continue in the second page with an introduction to guile and guix.
> I find it nice actually.
>
> I spotted a minor error:
>
>   (system* (string-append #$openssl "/bin/openssl")
>            "genrsa" "-out" private-key "2048"))
>
>  
> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md#running-executables
>
> Indeed you can run programs like that but in guix it is preferred to run
> with invoke, see the source :)
>
> Thanks for sharing!

Oh awesome, thanks!  I saw the recommendation to use invoke (in the
package guide?) but actually I'd like to know what the difference
between invoke and system* are... the code above was something I grabbed
from the Guix source somewhere (cups.scm?)

I just checked now (defined in guix/build/utils.scm) and it looks like
invoke raises an exception if the command has a non-zero exit, but
otherwise they're the same.

One more note for the guide I guess :D

Re: guile scheme tutorial

[rendaw]

On 5/4/19 5:57 PM, Ludovic Courtès wrote:
> Hi rendaw,
>
> rendaw <7e9wc56emjakcm@s.rendaw.me> skribis:
>
>> Oh, this is great!  I've actually been putting together a small Guix
>> guide here:
>> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md
> Nice!
>
> I skimmed at
> <https://gitlab.com/rendaw/blog/blob/master/a_brief_guix_review.md> and
> I wonder if you could point out areas where documentation is severely
> lacking?  We’d all very much welcome improvements to the manual so your
> insight as a newcomer is valuable.
>
> (Besides I wouldn’t consider mailing lists as a “user hostile” tool, but
> that’s not another story…)
>
> Thanks,
> Ludo’.

Thanks for looking at that!  I appreciate you asking and I'd like to
provide a careful answer.


The documentation currently excels at:

1. Installation (straightforward, theory light steps for getting started)

2. Listing commands and arguments

3. Specific use cases - setting up an application, bootstrapping the
installer, creating graphs


The areas that were important for me but weren't well documented were:

1. Concepts

* What is functional package management?  What is garbage collection? 
How do these work?

What is a package?  How does Guix determine what makes a package
unique?  What's a derivation, and what's the relationship between
derivations and packages?  The best I could find is that a derivation
communicates an action to the store, but that uses vocabulary in ways
that 99% of readers won't be familiar with ("communicate", "action",
isn't the "store" a directory?) and is so abstract that it won't help
people make choices dependent on that.  What's a tangible example of a
derivation?  Where and why would someone use a derivation directly?

The only gc documentation says that anything reachable from a root won't
be deleted, but doesn't explain what a root is, how they're created, how
they're identified, how they're removed, etc.

What's a profile?  The documentation says where they're stored, but not
how they interact with garbage collection.  What's the relationship
between a profile and a system config scm file?

What is a system generation?  How does this relate to the above?  How
does it work, maybe with a tangible example.

* What happens when running guix system?

How is the config file used?  The documentation says that the config scm
has should contain the operating system definition, but that's wrong -
it should return the operating system definition.  The config itself is
essentially a function, and I've seen confusion due to that not being
clearly explained in other threads ("Installing a package using guile
script").

What does guix system do with the definition once it's returned?  How
does install happen on a live system?  What stages are there in the install?

How does this process change for the different install targets? (vm,
disk-image, docker image, etc)

* G-expressions

The analogy to quotes is useful, but how do these actually work? 
They're relocatable - how does one store them to disk?  Read them from
disk an execute them?  Or execute them from memory?  Quotes can be
converted back from data using `eval` - what's the g-expression
equivalent?  Where can they be used (maybe this is more a reference
thing - which functions take g-expression arguments)?

What is lowering, what can be lowered, and what's the relation between
lowering and g-expressions?

How do you run a program in a g-expression?  This seems like one of the
most fundamental things one would do in a g-expression (especially when
interfacing with a world of non-guile software) but AFAICT it's only
addressed indirectly in a blog post.  The blog post says use invoke, and
that invoke should be used instead of system*.  Why?  What does it do
differently?  If invoke is better, why does Guix source use system*?

* Package creation

Again, the documentation says "use these build systems" but not why, or
what they do.  How does a build system transform a bunch of files into
something in /gnu/store?  What are the expectations of a package (where
do binaries go, shared libraries, etc).  Kernel modules?  Plugins for
other software?  Things with a global registry file/directory?

How do dependencies between packages work?  How are packages exposed to
users?  How are packages exposed to services?  How are packages exposed
to other packages?  And I don't mean how as in "what's the canonical way
to access package X" but "all these packages are in different
directories - how does the build process know that this package needs to
access this directory instead of this other directory?"

IMO it would be better to start with the trivial build system, say "we
have these files, here's how we turn it into a package" then show how
the build systems make it much simpler but that they're just an
extension of first principles.

* Services

I've been discussing this in another thread, but it's the same thing -
what a service is is unclear because it hinges on the use of the word
"extend" which isn't defined.

2. Reference

* Specifications

The arguments to functions are defined but what the function/macro
returns is often missing or incompletely defined.  `service` returns a
record of type `<service>` with fields `type` and `value`.  Without
knowing this stuff it's impossible to effectively "program" around it -
ex: filtering services, doing match, introspecting packages, etc. 
`scheme-file` returns an object - what sort of object, how can it be
used, etc.

For arguments with enumerative or switch parameters, how the function
behaves with different values is only partially defined.  Ex:
needed-for-boot? only describes what happens when #t, not when #f.  Same
with #volatile-root? in initrd.

Function specifications should have a much more rigorous format.  Links
to related definitions would be awesome too.

* Current status

There's a lot of "this doesn't work yet" type comments in the code, but
isn't mentioned in the documentation.  Ex: disk-image with uefi
bootloaders.  Users will read about features in the documentation,
assume it works (it's documented and there's no caveats), and then dump
N hours into trying to figure out what they did wrong.

* Comprehensiveness

Many auxiliary methods are not defined.  For example,
`use-package-modules` and `use-service-modules`.  These appear
frequently in the documentation, but it's unclear why you'd use those
instead of `use-modules` and the syntax is subtly different.  `mkdir-p`,
`chmod`, `make-forkexec-constructor` (it's hard to create shepherd
services without this), `call-with-output-file`, ...


I listed a lot of specific points because I think it's the best way to
communicate how I got blocked, but I don't think these should be
explicitly answered in the documentation.  If the documentation starts
with theory/concepts, such as explaining that "invoke runs a program
with system* but raises an exception if the return code is nonzero",
then the explanation of why it should be preferred to system*, how it's
different to system*, and what situations each should be used in is
stuff the reader can easily reach on their own.

Re: guile scheme tutorial

[amirouche]

On 2019-05-07 04:15, rendaw wrote:
> On 5/4/19 8:02 PM, amirouche@hyper.dev wrote:
>> On 2019-05-04 08:08, rendaw wrote:
>>> On 5/3/19 9:45 PM, amirouche@hyper.dev wrote:
>>>> Hello!
>>>> 
>>>> 
>>> (Whoops, replied with the wrong account.)
>>> 
>>> Oh, this is great!  I've actually been putting together a small Guix
>>> guide here:
>>> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md
>>> 
>>> 
>>> It has a small Guile primer, but it doesn't go into depth or have any
>>> hands on examples like yours.  My goal was to cover just enough so 
>>> that
>>> people could understand Guix configs (or at least 90% of them), so no
>>> recursion, etc.  I'm glad you got into records, I just kind of 
>>> handwaved
>>> that away ("they're functions", not 100% sure this is correct 
>>> either).
>> 
>> That is good. The beginning looks like guix is not worthwhile and then
>> you continue in the second page with an introduction to guile and 
>> guix.
>> I find it nice actually.
>> 
>> I spotted a minor error:
>> 
>>   (system* (string-append #$openssl "/bin/openssl")
>>            "genrsa" "-out" private-key "2048"))
>> 
>>  
>> https://gitlab.com/rendaw/blog/blob/master/how_to_guix_for_those_who_dont.md#running-executables
>> 
>> Indeed you can run programs like that but in guix it is preferred to 
>> run
>> with invoke, see the source :)
>> 
>> Thanks for sharing!
> 
> Oh awesome, thanks!  I saw the recommendation to use invoke (in the
> package guide?) but actually I'd like to know what the difference
> between invoke and system* are... the code above was something I 
> grabbed
> from the Guix source somewhere (cups.scm?)
> 
> I just checked now (defined in guix/build/utils.scm) and it looks like
> invoke raises an exception if the command has a non-zero exit, but
> otherwise they're the same.

Also it returns #t which is expected in every phase procedure.

Re: guile scheme tutorial

[Ludovic Courtès]

Hello!

rendaw <7e9wc56emjakcm@s.rendaw.me> skribis:

> The areas that were important for me but weren't well documented were:

Thanks for explaining!  That’s a lot of things to digest.  :-)

I’m not entirely sure I agree with or understand everything you mention,
I’ll comment on some of these below.  However, I think you should really
propose incremental improvements to the manual in these areas; it’ll be
easier to discuss specific sections or paragraphs.

> 1. Concepts
>
> * What is functional package management?  What is garbage collection? 
> How do these work?

“(guix) Managing Software the Guix Way” has a paragraph about functional
package management, but that’s (purposefully) the only place where FPM
is discussed.

> What is a package?  How does Guix determine what makes a package
> unique?  What's a derivation, and what's the relationship between
> derivations and packages?  The best I could find is that a derivation
> communicates an action to the store, but that uses vocabulary in ways
> that 99% of readers won't be familiar with ("communicate", "action",
> isn't the "store" a directory?) and is so abstract that it won't help
> people make choices dependent on that.  What's a tangible example of a
> derivation?  Where and why would someone use a derivation directly?

“(guix) Defining Packages” explains:

     Behind the scenes, a derivation corresponding to the ‘<package>’
  object is first computed by the ‘package-derivation’ procedure.  That
  derivation is stored in a ‘.drv’ file under ‘/gnu/store’.  The build
  actions it prescribes may then be realized by using the
  ‘build-derivations’ procedure (*note The Store::).

… with cross-references.

> The only gc documentation says that anything reachable from a root won't
> be deleted, but doesn't explain what a root is, how they're created, how
> they're identified, how they're removed, etc.

“(guix) Invoking guix gc” has a paragraph that I think explains what a
GC root is:

     The garbage collector has a set of known “roots”: any file under
  ‘/gnu/store’ reachable from a root is considered “live” and cannot be
  deleted; any other file is considered “dead” and may be deleted.  The
  set of garbage collector roots (“GC roots” for short) includes default
  user profiles; by default, the symlinks under ‘/var/guix/gcroots’
  represent these GC roots.  New GC roots can be added with ‘guix build
  --root’, for example (*note Invoking guix build::).  The ‘guix gc
  --list-roots’ command lists them.

> * What happens when running guix system?

How does “(guix) Using the Configuration System” fall short here?

> What does guix system do with the definition once it's returned?  How
> does install happen on a live system?  What stages are there in the install?
>
> How does this process change for the different install targets? (vm,
> disk-image, docker image, etc)

Likewise, how does “(guix) Invoking guix system” fail to explain this?

> * G-expressions
>
> The analogy to quotes is useful, but how do these actually work? 
> They're relocatable - how does one store them to disk?  Read them from
> disk an execute them?  Or execute them from memory?  Quotes can be
> converted back from data using `eval` - what's the g-expression
> equivalent?  Where can they be used (maybe this is more a reference
> thing - which functions take g-expression arguments)?

I think that “(guix) G-Expressions” answers some of these questions, but
perhaps you could propose a patch to clarify that.

Keep in mind that this section is not about the design and
implementation of G-Expressions—there’s a paper on that topic.  Instead,
the intent is to explain why they exist in the first place, and how they
can be used.

> * Package creation
>
> Again, the documentation says "use these build systems" but not why, or
> what they do.

“(guix) Build Systems” has:

  Each package definition specifies a “build system” and arguments for
  that build system (*note Defining Packages::).  This ‘build-system’
  field represents the build procedure of the package, as well as implicit
  dependencies of that build procedure.

I think that’s an good intro for “what they do”, no?

> IMO it would be better to start with the trivial build system, say "we
> have these files, here's how we turn it into a package" then show how
> the build systems make it much simpler but that they're just an
> extension of first principles.

I’m not sure.  I think as a packager you’re first and foremost
interested in ‘gnu-build-system’, ‘cmake-build-system’, and so on,
because those are the first you’ll use to get things done.
‘trivial-build-system’ is usually advanced usage.

> * Services
>
> I've been discussing this in another thread, but it's the same thing -
> what a service is is unclear because it hinges on the use of the word
> "extend" which isn't defined.

I think it does explain extensions in quite some detail, but Chris
concurs with you that it’s unclear, so I guess there’s room for
improvement.  :-)

In short, I’m sure there’s room for improvement in the manual.  I’m just
not sure what you are criticizing or suggesting.  That’s why I’d
encourage you to pick one specific example and post a patch for
discussion.  That would allow us to have a clearer understanding of how
we could improve things.

Thanks,
Ludo’.

Re: guile scheme tutorial

[Pierre Neidhardt]

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

For what it's worth, most of rendaw's comments resonate to me, from back
when I first got started with Guix.

But now, with hindsight, it's not obvious to me anymore what can be
fixed in the manual.

I believe the reason for this is simply that Guix and all its
concepts are a lot to take for newcomers, it's simply too hard to digest
even after multiple readings.  It takes time and practice.

A well written manual might not be the only answer we are looking for.  How
do we teach complex concepts in schools?  With examples and exercises.
Maybe we should do that.  Blog articles could be a good fit.

My two cents :)

-- 
Pierre Neidhardt
https://ambrevar.xyz/

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

Re: guile scheme tutorial

[swedebugia]

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

On 2019-05-08 15:15, Pierre Neidhardt wrote:
> For what it's worth, most of rendaw's comments resonate to me, from back
> when I first got started with Guix.
> 
> But now, with hindsight, it's not obvious to me anymore what can be
> fixed in the manual.
> 
> I believe the reason for this is simply that Guix and all its
> concepts are a lot to take for newcomers, it's simply too hard to digest
> even after multiple readings.  It takes time and practice.
> 
> A well written manual might not be the only answer we are looking for.  How
> do we teach complex concepts in schools?  With examples and exercises.
> Maybe we should do that.  Blog articles could be a good fit.

+1

-- 
Cheers Swedebugia


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Guix cookbook (was: guile scheme tutorial)

[Ricardo Wurmus]

Pierre Neidhardt <mail@ambrevar.xyz> writes:

> A well written manual might not be the only answer we are looking for.  How
> do we teach complex concepts in schools?  With examples and exercises.
> Maybe we should do that.  Blog articles could be a good fit.

I’m not a fan of blog posts for teaching, because they quickly lose
relevance.  An example: recently someone on IRC said they were following
your packaging tutorial and something wasn’t working; someone else then
said that the blog post was outdated.  I don’t recall the details, but I
find this worrying, because people might spend time learning something
from blog posts only to have to unlearn things again.

Blog posts are great for outreach and to spawn contemporary discussions.
But I think that ultimately we should enhance the manual.  We are not
limited to having just one document that needs to meet all
requirements.  We can have more than one thing.

Previously, we floated the idea of having a Guix cookbook with short
tutorials showing how to achieve well-defined tasks such as writing a
package (i.e. an updated and distilled version of your blog post
perhaps), setting up a bluetooth-enabled MPD-powered media workstation,
configuring a complex web application with database, web server, etc.

I’d really like to see such a cookbook become part of Guix.  It would
always be up-to-date and it can provide much needed examples that might
otherwise clutter up the manual.

What do you think?  Shall we start with converting your packaging
tutorial?

--
Ricardo

Re: Guix cookbook (was: guile scheme tutorial)

[Pierre Neidhardt]

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

I agree with all your points!

Regarding the bootstrapping process: we could already split the
packaging tutorial into 2 "recipes":
- A guile primer
- The actual packaging tutorial

Of course we would interlink them.

Once done, we should not forget to update the blog post to let the
readers know to refer to the corresponding cookbook instead.

Out of curiosity, can you remember which part of the tutorial is out of
date?  I cannot think of anything.

-- 
Pierre Neidhardt
https://ambrevar.xyz/

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

Re: Guix cookbook (was: guile scheme tutorial)

[Ricardo Wurmus]

Pierre Neidhardt <mail@ambrevar.xyz> writes:

> I agree with all your points!
>
> Regarding the bootstrapping process: we could already split the
> packaging tutorial into 2 "recipes":
> - A guile primer
> - The actual packaging tutorial
>
> Of course we would interlink them.
>
> Once done, we should not forget to update the blog post to let the
> readers know to refer to the corresponding cookbook instead.

Sounds good.  I’d like to keep the cookbook chapters rather short and
focused, so splitting things up into independent chapters is fine.

> Out of curiosity, can you remember which part of the tutorial is out of
> date?  I cannot think of anything.

I think it was a misunderstanding:

    http://bayfront.guix.info:3333/2019-05-08.log#042356

The tutorial says:

    Follow the instruction from the "Contributing" chapter in the manual
    to set up the repository environment.

I think they did not follow those instructions.  Sorry for the false
alarm!

--
Ricardo

Re: guile scheme tutorial

[rendaw]

On 5/9/19 1:35 AM, swedebugia wrote:
> On 2019-05-08 15:15, Pierre Neidhardt wrote:
>> For what it's worth, most of rendaw's comments resonate to me, from back
>> when I first got started with Guix.
>>
>> But now, with hindsight, it's not obvious to me anymore what can be
>> fixed in the manual.
>>
>> I believe the reason for this is simply that Guix and all its
>> concepts are a lot to take for newcomers, it's simply too hard to digest
>> even after multiple readings.  It takes time and practice.
>>
>> A well written manual might not be the only answer we are looking for.  How
>> do we teach complex concepts in schools?  With examples and exercises.
>> Maybe we should do that.  Blog articles could be a good fit.
> +1
>
I'm definitely behind the examples thing.  My guide has some (ex:
disabling root login) but it's not the first place you'd go looking for
that.  I'm not sure I like blogs though - IMO those are good for topical
writing, like release announcements, admin changes, postmortems, etc,
but I'd never go there if I had a specific technical question and by
nature they're not organized for such use.

What about a wiki like what Arch does?  I know nothing about wiki
administration, but the Arch wiki is full of basic (non-concept
information - how to install and configure package x or y) and specific
examples with snippets (how to enable a microphone in alsa).

Also if we're talking about 3rd party blogs TBH I think they're fairly
hard to find.  Having an official curated list of 3rd party
documentation would be great, but nothing beats official documentation
for discoverability.

Re: guile scheme tutorial

[Pierre Neidhardt]

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

Hi,

You might have missed the discussion where Ricardo explained he didn't
like blog posts either.  Now Ricardo and I are leaning towards a
"cookbook" integrated into the manual.

Regarding the Wiki: I think this was discussed some years ago and if I
remember correctly the consensus was that Wikis are too unmanageable.
More importantly, they don't track specific Guix versions, so they
quickly run out of sync with the development of Guix.  Manuals don't
have this drawback.

Cheers!

-- 
Pierre Neidhardt
https://ambrevar.xyz/

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

Re: Guix cookbook

[swedebugia]

On 2019-05-09 23:38, Ricardo Wurmus wrote:
> 
> Pierre Neidhardt <mail@ambrevar.xyz> writes:
> 
>> I agree with all your points!
>>
>> Regarding the bootstrapping process: we could already split the
>> packaging tutorial into 2 "recipes":
>> - A guile primer
>> - The actual packaging tutorial
>>
>> Of course we would interlink them.
>>
>> Once done, we should not forget to update the blog post to let the
>> readers know to refer to the corresponding cookbook instead.
> 
> Sounds good.  I’d like to keep the cookbook chapters rather short and
> focused, so splitting things up into independent chapters is fine.

+1 This sounds great. I will happily contribute to this.

-- 
Cheers Swedebugia

Re: guile scheme tutorial

[Laura Lazzati]

Hi!

May I help by fixing some typos :) ?

Regards :)
Laura