Hi Vincent,
Vincent Legoll <vincent.leg...@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’.
diff --git a/doc/guix.texi b/doc/guix.texi
index e7b233d..8d332f6 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2452,12 +2452,35 @@ The @code{arguments} field specifies options for the build system
@var{gnu-build-system} as a request run @file{configure} with the
@code{--enable-silent-rules} flag.
+@cindex quote
+@cindex quoting
+@cindex backquote (quasiquote)
+What about these backquote (@code{`}) and quote (@code{'}) characters?
+They are Scheme syntax to introduce a literal data structure; @code{'}
+is synonymous with @code{quote}, and @code{`} is synonymous with
+@code{quasiquote}. @xref{Expression Syntax, quoting,, guile, GNU Guile
+Reference Manual}, for details. Here the value of the @code{arguments}
+field is a list of arguments passed to the build system.
+
+The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
+(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
+@code{#:configure-flags} is a keyword used to pass a keyword argument
+to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
+Reference Manual}).
+
@item
The @code{inputs} field specifies inputs to the build process---i.e.,
build-time or run-time dependencies of the package. Here, we define an
input called @code{"gawk"} whose value is that of the @var{gawk}
variable; @var{gawk} is itself bound to a @code{<package>} object.
+@cindex comma (unquote)
+Again, @code{`} (@code{quasiquote}) allows us to introduce a literal
+list in the @code{inputs} field, while @code{,} (a comma, synonymous
+with @code{unquote}) allows us to insert a value in the list
+(@pxref{Expression Syntax, unquote,, guile, GNU Guile Reference
+Manual}).
+
Note that GCC, Coreutils, Bash, and other essential tools do not need to
be specified as inputs here. Instead, @var{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}).
