04/06: doc: Make '--manifest' more visible.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 99bd74d549bc893e79a541b4e71ceac3909b7cff
Author: Ludovic Courtès <address@hidden>
Date:   Fri May 22 11:08:28 2015 +0200

    doc: Make '--manifest' more visible.
    
    * doc/guix.texi (Invoking guix package): Mention the declarative approach 
and
      --manifest in the intro.  And an anchor for --manifest.  Explain why/how 
it
      can be used.  Tweak wording.
---
 doc/guix.texi |   32 ++++++++++++++++++++++++--------
 1 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index fd0d29c..4b7f06f 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -941,7 +941,7 @@ guix package @var{options}
 
 Primarily, @var{options} specifies the operations to be performed during
 the transaction.  Upon completion, a new profile is created, but
-previous generations of the profile remain available, should the user
+previous @dfn{generations} of the profile remain available, should the user
 want to roll back.
 
 For example, to remove @code{lua} and install @code{guile} and
@@ -951,6 +951,11 @@ For example, to remove @code{lua} and install @code{guile} 
and
 guix package -r lua -i guile guile-cairo
 @end example
 
address@hidden package} also supports a @dfn{declarative approach}
+whereby the user specifies the exact set of packages to be available and
+passes it @i{via} the @option{--manifest} option
+(@pxref{profile-manifest, @option{--manifest}}).
+
 For each user, a symlink to the user's default profile is automatically
 created in @file{$HOME/.guix-profile}.  This symlink always points to the
 current generation of the user's default profile.  Thus, users can add
@@ -1062,21 +1067,32 @@ substring ``emacs'':
 $ guix package --upgrade . --do-not-upgrade emacs
 @end example
 
address@hidden address@hidden
address@hidden @address@hidden
 @itemx -m @var{file}
-Create a new @dfn{generation} of the profile from the manifest object
address@hidden profile declaration
address@hidden profile manifest
+Create a new generation of the profile from the manifest object
 returned by the Scheme code in @var{file}.
 
-A manifest file may look like this:
+This allows you to @emph{declare} the profile's contents rather than
+constructing it through a sequence of @code{--install} and similar
+commands.  The advantage is that @var{file} can be put under version
+control, copied to different machines to reproduce the same profile, and
+so on.
+
address@hidden FIXME: Add reference to (guix profile) documentation when 
available.
address@hidden must return a @dfn{manifest} object, which is roughly a list
+of packages:
 
address@hidden packages->manifest
 @example
-(use-package-modules guile emacs gcc)
+(use-package-modules guile emacs)
 
 (packages->manifest
- (list guile-2.0
-       emacs
+ (list emacs
+       guile-2.0
        ;; Use a specific package output.
-       (list gcc "debug")))
+       (list guile-2.0 "debug")))
 @end example
 
 @item --roll-back