Re: inside the Guile REPL

[Mark H Weaver <mhw@netris.org>]

Pjotr Prins <pjotr.public12@thebird.nl> writes:

> I have started to document how to use Guix from the Guile REPL.
> Tips/hints wanted from experienced hackers! This is not only to keep
> my memory fresh, it may be useful for others.
>
>   https://github.com/pjotrp/guix-notes/blob/master/HACKING.org#debugging-the-package

I have a few comments and corrections to offer:

* Several of the code examples have extra close parens at the end which
  are highlighted in red when viewing in a web browser.

* In the Scheme world, we prefer to use the word "procedure" instead of
  "function", to reflect the fact that it is not merely a mapping from
  inputs to outputs but can perform side effects as well.

* In "Hash colon (#:) notation", you write "The #: signifies a symbol or
  literal keyword syntax [...]".  Keywords are distinct from symbols, so
  you shouldn't say it's a symbol.

* In "Percentage (%) notation", it would be good to mention that it is
  merely a convention, like '_' in C.  Scheme treats '%' exactly the
  same as any other letter.

* In "Key-values":
   * 'build-system' is not a method, but rather a record constructor.
   * 'name', 'description', and 'lower' are not functions but rather
     field names.

* In "Defining a function", it might be worth mentioning that 'define'
  can be used to bind identifiers to any value, not just procedures.
  Most prominently, we use it to define packages, build systems, etc.

* In "Defining a variable":
   * 'let' and 'let*' are not functions, but rather special forms.
   * Regarding the difference between 'let' and 'let*', what you wrote
     is true, but the more important difference between let and let* is
     that let* allows the initializers of later variables to refer to
     the earlier variables, whereas the initializers of let only see
     variables outside of the let.  For example:

      (let ((a 1) (b 2))
        (let ((b a) (a b))
          (list a b)))

     returns (2 1), but if the inner let is replaced with let*, then it
     will return (1 1).

* In "Inside functions", you write "Backquote is like quote, but only
  selected subexpressions are evaluated".  This would seem to suggest
  that 'quote' evaluates all subexpressions.  Removing the word "only"
  might help.  Also, the actual name for this construct is 'quasiquote',
  and it might be good to use that name since it is what can be found in
  the Guile manual and on the web.

  Also, You assume the reader knows the shorthand forms of how 'quote'
  and 'quasiquote' are normally written.  The comma is also a shorthand
  for 'unquote', and it would be good to mention that, since it's a good
  name for it and may aid understanding.  It would also be good if the
  first example showed the outer quasiquote, since unquote is not valid
  outside of quasiquote.  ",@" is shorthand for unquote-splicing.

* In "More about Guile/scheme", I don't think it's accurate to say that
  Guile is a "minimalistic" implementation.  It's moderately large for a
  Scheme implementation.

* In "Renaming and moving files", it would be good to show the newer
  'modify-phases' syntax instead.

* In "Starting the daemon", it might be worth mentioning that it should
  be run as root, but that the actual build processes are run as
  unprivileged build users.

* In "From the command line", you gave a suggested command:

    ./pre-inst-env guix --load-path ./gnu

  I'm not sure what you're trying to do there.  When I run that command,
  it says "unrecognized option '--load-path'".  Maybe you meant
  something like this:

    ./pre-inst-env guix package --load-path=./gnu [...]

  but that's not right either, because the <DIR> passed to --load-path
  should be such that module (gnu packages foo) is located in
  <DIR>/gnu/packages/foo.scm.  Anyway, it's not needed because
  ./pre-inst-env automatically adds the right paths to access the
  packages within ./gnu/packages/*.scm.

That's all for now, I'll try to review the rest later.

Anyway, this is a great start.  Thanks for working on it!

      Mark