Documentation patches

Documentation patches

[Andreas Enge]

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

Attached are four more patches that go beyond typos and so on, so I would
like to hear your opinion. For the last one, I am not sure if the info is
correct, but since the importer treats JSON files, I thought that assuming
a dependency on Guile-JSON had a good chance of being correct.

Andreas


[-- Attachment #2: 0001-doc-Move-paragraphs-in-description-of-guix-archive.patch --]
[-- Type: text/plain, Size: 2904 bytes --]

From a58b5438300c0e5cd64aec4959fa34bcf5c0f205 Mon Sep 17 00:00:00 2001
From: Andreas Enge <andreas@enge.fr>
Date: Sat, 13 Feb 2016 20:04:10 +0100
Subject: [PATCH 1/4] doc: Move paragraphs in description of guix archive.

* doc/guix.texi ("invoking guix archive"): Move paragraph describing basic
  invocation from the end to the beginning of the section.
---
 doc/guix.texi | 46 ++++++++++++++++++++++++----------------------
 1 file changed, 24 insertions(+), 22 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index bac7389..0ff5cfc 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2004,8 +2004,30 @@ useful to Guix developers.
 The @command{guix archive} command allows users to @dfn{export} files
 from the store into a single archive, and to later @dfn{import} them.
 In particular, it allows store files to be transferred from one machine
-to the store on another machine.  For example, to transfer the @code{emacs}
-package to a machine connected over SSH, one would run:
+to the store on another machine.
+
+To export store files as an archive to standard output, run:
+
+@example
+guix archive --export @var{options} @var{specifications}...
+@end example
+
+@var{specifications} may be either store file names or package
+specifications, as for @command{guix package} (@pxref{Invoking guix
+package}).  For instance, the following command creates an archive
+containing the @code{gui} output of the @code{git} package and the main
+output of @code{emacs}:
+
+@example
+guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
+@end example
+
+If the specified packages are not built yet, @command{guix archive}
+automatically builds them.  The build process may be controlled with the
+common build options (@pxref{Common Build Options}).
+
+To transfer the @code{emacs} package to a machine connected over SSH,
+one would run:
 
 @example
 guix archive --export -r emacs | ssh the-machine guix archive --import
@@ -2127,26 +2149,6 @@ archive contents coming from possibly untrusted substitute servers.
 
 @end table
 
-To export store files as an archive to standard output, run:
-
-@example
-guix archive --export @var{options} @var{specifications}...
-@end example
-
-@var{specifications} may be either store file names or package
-specifications, as for @command{guix package} (@pxref{Invoking guix
-package}).  For instance, the following command creates an archive
-containing the @code{gui} output of the @code{git} package and the main
-output of @code{emacs}:
-
-@example
-guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
-@end example
-
-If the specified packages are not built yet, @command{guix archive}
-automatically builds them.  The build process may be controlled with the
-common build options (@pxref{Common Build Options}).
-
 @c *********************************************************************
 @include emacs.texi
 
-- 
2.6.3


[-- Attachment #3: 0002-doc-Use-modify-phases-syntax-in-example.patch --]
[-- Type: text/plain, Size: 865 bytes --]

From 4ff40a70eb7ed35f153e001f5935956286dfbdbf Mon Sep 17 00:00:00 2001
From: Andreas Enge <andreas@enge.fr>
Date: Sat, 13 Feb 2016 20:07:08 +0100
Subject: [PATCH 2/4] doc: Use modify-phases syntax in example.

* doc/guix.texi ("build systems"): Use modify-phases syntax instead of
  alist-delete in example.
---
 doc/guix.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 0ff5cfc..42b3fba 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2651,7 +2651,7 @@ The list of phases used for a particular package can be changed with the
 @code{#:phases} parameter.  For instance, passing:
 
 @example
-#:phases (alist-delete 'configure %standard-phases)
+#:phases (modify-phases %standard-phases (delete 'configure))
 @end example
 
 means that all the phases described above will be used, except the
-- 
2.6.3


[-- Attachment #4: 0003-doc-Drop-documentation-of-deprecated-procedures.patch --]
[-- Type: text/plain, Size: 3366 bytes --]

From b46aab8149d30708e58b10e2428eb4a41f63f61e Mon Sep 17 00:00:00 2001
From: Andreas Enge <andreas@enge.fr>
Date: Sat, 13 Feb 2016 20:08:26 +0100
Subject: [PATCH 3/4] doc: Drop documentation of deprecated procedures.

* doc/guix.texi ("build systems"): Drop documentation of
  BUILD-EXPRESSION->DERIVATION.
---
 doc/guix.texi | 53 -----------------------------------------------------
 1 file changed, 53 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 42b3fba..979288c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3022,59 +3022,6 @@ best course of action for that is to write the build code as a
 ``G-expression'', and to pass it to @code{gexp->derivation}.  For more
 information, @pxref{G-Expressions}.
 
-Once upon a time, @code{gexp->derivation} did not exist and constructing
-derivations with build code written in Scheme was achieved with
-@code{build-expression->derivation}, documented below.  This procedure
-is now deprecated in favor of the much nicer @code{gexp->derivation}.
-
-@deffn {Scheme Procedure} build-expression->derivation @var{store} @
-       @var{name} @var{exp} @
-       [#:system (%current-system)] [#:inputs '()] @
-       [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
-       [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
-       [#:references-graphs #f] [#:allowed-references #f] @
-       [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
-Return a derivation that executes Scheme expression @var{exp} as a
-builder for derivation @var{name}.  @var{inputs} must be a list of
-@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
-@code{"out"} is assumed.  @var{modules} is a list of names of Guile
-modules from the current search path to be copied in the store,
-compiled, and made available in the load path during the execution of
-@var{exp}---e.g., @code{((guix build utils) (guix build
-gnu-build-system))}.
-
-@var{exp} is evaluated in an environment where @code{%outputs} is bound
-to a list of output/path pairs, and where @code{%build-inputs} is bound
-to a list of string/output-path pairs made from @var{inputs}.
-Optionally, @var{env-vars} is a list of string pairs specifying the name
-and value of environment variables visible to the builder.  The builder
-terminates by passing the result of @var{exp} to @code{exit}; thus, when
-@var{exp} returns @code{#f}, the build is considered to have failed.
-
-@var{exp} is built using @var{guile-for-build} (a derivation).  When
-@var{guile-for-build} is omitted or is @code{#f}, the value of the
-@code{%guile-for-build} fluid is used instead.
-
-See the @code{derivation} procedure for the meaning of
-@var{references-graphs}, @var{allowed-references}, @var{local-build?},
-and @var{substitutable?}.
-@end deffn
-
-@noindent
-Here's an example of a single-output derivation that creates a directory
-containing one file:
-
-@lisp
-(let ((builder '(let ((out (assoc-ref %outputs "out")))
-                  (mkdir out)    ; create /gnu/store/@dots{}-goo
-                  (call-with-output-file (string-append out "/test")
-                    (lambda (p)
-                      (display '(hello guix) p))))))
-  (build-expression->derivation store "goo" builder))
-
-@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
-@end lisp
-
 
 @node The Store Monad
 @section The Store Monad
-- 
2.6.3


[-- Attachment #5: 0004-doc-Add-footnote-on-Guile-JSON.patch --]
[-- Type: text/plain, Size: 1016 bytes --]

From 1d83f47bce4106dd917384a56dc6d2c259678b87 Mon Sep 17 00:00:00 2001
From: Andreas Enge <andreas@enge.fr>
Date: Sat, 13 Feb 2016 20:11:14 +0100
Subject: [PATCH 4/4] doc: Add footnote on Guile-JSON.

* doc/guix.texi ("invoking guix import"): Add a footnote to the CPAN importer
  on the need for Guile-JSON.
---
 doc/guix.texi | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 979288c..c5a7de7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4321,7 +4321,9 @@ guix import gem rails
 
 @item cpan
 @cindex CPAN
-Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
+Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}@footnote{This
+functionality requires Guile-JSON to be installed.
+@xref{Requirements}.}.
 Information is taken from the JSON-formatted metadata provided through
 @uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
 relevant information, such as module dependencies.  License information
-- 
2.6.3