Hi Vincent,

Vincent Legoll <vincent.legoll@gmail.com> skribis:

> I put this in a separate email, as it's becoming long...
>
> The packaging doc:
>
> https://www.gnu.org/software/guix/manual/guix.html#Defining-Packages
> is good, but still not enough for beginners.
>
> Essentially it's missing what is hidden behind "Without being a Scheme ..."
>
> It wouldn't hurt to have the scheme non-obvious parts explained:
>
> - the comma operator
> - the backquote operator
> - the quote operator
> - the arobase operator (is it for list unpacking ?)
> - the percent operator
> - the #: operator
> - the different module import things (#:use-module vs (use-modules) vs ...)
>
> (Forgive my probably-not-appropriate terms.)
>
> No need to explain function calls, string quoting and simple stuff, though.
>
> I tried to find a good tutorial explaining all of those, but couldn't. I found
> snippets that helped me understand some of those, but they were scattered,
> and it's still blurry.
>
> Specific explanations will be more useful that a general scheme tutorial, the
> hello.scm is good as an example :
>
> (inputs `(("gawk" ,gawk)))
>
> here we use the backquote because ...
> the comma is there for ...
>
> (arguments `(#:configure-flags '("--enable-silent-rules")))
>
> here the #: means ...
> we use the simple quote because ...

I would propose the patch below as a start.  While it does not give
detailed explanations, it provides terminology and pointers, in
particular to this section of the Guile manual:

  https://www.gnu.org/software/guile/manual/html_node/Expression-Syntax.html

Unfortunately, this section of Guile’s manual is a reference and it
lacks examples and a good overview.  I think we should fix it on Guile’s
side instead of palliating this deficiency in Guix’s manual.

If nobody beats me at it, I can try and improve this is in Guile’s
manual afterwards.

What do you think?

Thanks,
Ludo’.