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

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

[Konrad Hinsen]

* 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)

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

[myglc2]

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@2.2" "guile@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

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

[Konrad Hinsen]

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.

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

[myglc2]

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

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

[Ludovic Courtès]

Konrad Hinsen <konrad.hinsen@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’.

[bug#30410] closed (Re: [bug#30410] [PATCH 2/2] doc: Document the --manifest option for guix pack.)

[Konrad Hinsen]

help-debbugs@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.