Re: Newbie packagers

[ludo@gnu.org (Ludovic Courtès)]

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

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’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1882 bytes --]

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}).