GNU bug report logs - #30410
[PATCH 2/2] doc: Document the --manifest option for guix pack.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 30410 in the body.
You can then email your comments to 30410 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Konrad Hinsen <konrad.hinsen <at> fastmail.net>
To: guix-patches <at> gnu.org
Subject: [PATCH 2/2] doc: Document the --manifest option for guix pack.
Date: Sat, 10 Feb 2018 12:35:41 +0100

* doc/guix.texi (Invoking guix pack): Document --manifest.
---
 doc/guix.texi | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 13187f2e8..f64f95929 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2841,6 +2841,19 @@ This has the same purpose as the same-named option in @command{guix
 build} (@pxref{Additional Build Options, @code{--expression} in
 @command{guix build}}).
 
+@item --manifest=@var{file}
+@itemx -m @var{file}
+Use the packages contained in the manifest object
+returned by the Scheme code in @var{file}.
+
+This has a similar purpose as the same-named option in @command{guix
+package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
+same manifest files. It allows you to define a collection of packages
+once and use it both for creating profiles and for creating archives
+for use on machines that do not have Guix installed. Note that you can
+specify @emph{either} a manifest file @emph{or} a list of packages,
+but not both.
+
 @item --system=@var{system}
 @itemx -s @var{system}
 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-- 
2.14.3 (Apple Git-98)

Message #8 received at 30410 <at> debbugs.gnu.org (full text, mbox):

From: myglc2 <at> gmail.com
To: Konrad Hinsen <konrad.hinsen <at> fastmail.net>
Cc: 30410 <at> debbugs.gnu.org
Subject: Re: [bug#30410] [PATCH 2/2] doc: Document the --manifest option for
 guix pack.
Date: Mon, 12 Feb 2018 14:15:14 -0500

Hi Konrad,

Very cool patch!

On 02/10/2018 at 12:35 Konrad Hinsen writes:

> +for use on machines that do not have Guix installed. Note that you can
> +specify @emph{either} a manifest file @emph{or} a list of packages,
> +but not both.

FWIW, here are a few thoughts ...

It would be helpful to add an example or two of "list of packages".

The term manifest has a few meanings in guix. There are the "input
manifests" forms accepted by '--manifest=' and the "output manifests"
produced by 'guix package' (e.g.,$HOME/.guix-profile/manifest). Only
input manifests are documented now. But ISTM there may eventually be a
tool to produce an input manifest from a user's profile that has grown
organically through install/remove operations. If/when that happens,
"output manifests" might also be mentioned in the doc.

Currently the doc doesn't show an actual manifest. Rather it shows 2
"input manifest" forms that are acceptable to '--manifest=' ...

          (use-package-modules guile emacs)
          (packages->manifest
           (list emacs
                 guile-2.0
                 ;; Use a specific package output.
                 (list guile-2.0 "debug")))

... and ...

(specifications->manifest
           '("emacs" "guile <at> 2.2" "guile <at> 2.2:debug"))

These can be a source of confusion, typos, and error (or at least they
were to me). So I wonder: Does adding a 3rd "list of packages" form make
the option murkier? Would a separate option be simpler to document/use?

HTH - George

Message #11 received at 30410 <at> debbugs.gnu.org (full text, mbox):

From: Konrad Hinsen <konrad.hinsen <at> fastmail.net>
To: myglc2 <at> gmail.com
Cc: 30410 <at> debbugs.gnu.org
Subject: Re: [bug#30410] [PATCH 2/2] doc: Document the --manifest option for
 guix pack.
Date: Tue, 13 Feb 2018 09:23:12 +0100

Hi George,

> FWIW, here are a few thoughts ...
>
> It would be helpful to add an example or two of "list of packages".

That basically means that my doc isn't clear enough :-(

There is no special "list of packages". What I refer to is a command
line with multiple package arguments, either package names or -e <Expr>
arguments.

The point is that "-m manifest.scm" and package-name or -e arguments
are mutually exclusive.

The problem I had with formulating this is that package-name arguments
are never explicitly mentioned in the documentation, only options are
documented. The only way to know that you can just list package names on
the command line is looking at the examples.

Any idea of how to do this better?

Konrad.

Message #14 received at 30410 <at> debbugs.gnu.org (full text, mbox):

From: myglc2 <at> gmail.com
To: Konrad Hinsen <konrad.hinsen <at> fastmail.net>
Cc: 30410 <at> debbugs.gnu.org
Subject: Re: [bug#30410] [PATCH 2/2] doc: Document the --manifest option for
 guix pack.
Date: Tue, 13 Feb 2018 23:04:30 -0500

On 02/13/2018 at 09:23 Konrad Hinsen writes:
Hi  Konrad,

> Hi George,
>
>> FWIW, here are a few thoughts ...
>>
>> It would be helpful to add an example or two of "list of packages".
>
> That basically means that my doc isn't clear enough :-(
>
> There is no special "list of packages". What I refer to is a command
> line with multiple package arguments, either package names or -e <Expr>
> arguments.
>
> The point is that "-m manifest.scm" and package-name or -e arguments
> are mutually exclusive.
>
> The problem I had with formulating this is that package-name arguments
> are never explicitly mentioned in the documentation, only options are
> documented. The only way to know that you can just list package names on
> the command line is looking at the examples.

Yeah, in the doc "list of packages" might mean a scheme list or "naming
one or more packages on the command line" or a “manifest” object (which
is roughly a list of packages) ;-) But maybe that's not your problem.

> Any idea of how to do this better?

I thought you were saying that --manifest would accept a manifest form
or a list of packages. But now I think I get it.

How about saying packages may be specified by the -m option or the -e
option or an explicit list of packages on the command line.

- or -

packages may be specified by only one of the following methods: the -m
option, the -e option, or an explicit list on the command line.

HTH - George

Message #19 received at 30410-done <at> debbugs.gnu.org (full text, mbox):

From: ludo <at> gnu.org (Ludovic Courtès)
To: Konrad Hinsen <konrad.hinsen <at> fastmail.net>
Cc: 30410-done <at> debbugs.gnu.org
Subject: Re: [bug#30410] [PATCH 2/2] doc: Document the --manifest option for
 guix pack.
Date: Thu, 15 Feb 2018 15:24:00 +0100

Konrad Hinsen <konrad.hinsen <at> fastmail.net> skribis:

> * doc/guix.texi (Invoking guix pack): Document --manifest.

I’ve squashed this one with the patch that adds the code, so the commit
is self-contained.

> +@item --manifest=@var{file}
> +@itemx -m @var{file}
> +Use the packages contained in the manifest object
> +returned by the Scheme code in @var{file}.
> +
> +This has a similar purpose as the same-named option in @command{guix
> +package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
> +same manifest files. It allows you to define a collection of packages
> +once and use it both for creating profiles and for creating archives
> +for use on machines that do not have Guix installed. Note that you can
> +specify @emph{either} a manifest file @emph{or} a list of packages,
> +but not both.

On second thought, I wonder if we should allow both -m and a list of
packages.  After all, ‘guix package’ supports it, and it doesn’t cost us
anything.  WDYT?

Thanks!

Ludo’.

Message #22 received at 30410 <at> debbugs.gnu.org (full text, mbox):

From: Konrad Hinsen <konrad.hinsen <at> fastmail.net>
To: 30410 <at> debbugs.gnu.org
Subject: Re: bug#30410: closed (Re: [bug#30410] [PATCH 2/2] doc: Document the
 --manifest option for guix pack.)
Date: Thu, 15 Feb 2018 20:14:48 +0100

help-debbugs <at> gnu.org (GNU bug Tracking System) writes:

> On second thought, I wonder if we should allow both -m and a list of
> packages.  After all, ‘guix package’ supports it, and it doesn’t cost us
> anything.  WDYT?

Personally I don't have a use case for that, which is why I didn't
bother. But it may indeed be simpler to implement this than to explain
that it's not.

Konrad.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.