From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andreas Enge Subject: Documentation patches Date: Sat, 13 Feb 2016 20:19:28 +0100 Message-ID: <20160213191928.GA9991@debian> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="bg08WKrSYDhXBjb5" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:48245) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aUfjE-0000Ug-SO for guix-devel@gnu.org; Sat, 13 Feb 2016 14:19:38 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aUfjB-0002KK-K3 for guix-devel@gnu.org; Sat, 13 Feb 2016 14:19:36 -0500 Received: from mailrelay7.public.one.com ([91.198.169.215]:13788) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aUfjB-0002KF-6y for guix-devel@gnu.org; Sat, 13 Feb 2016 14:19:33 -0500 Content-Disposition: inline List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: guix-devel@gnu.org --bg08WKrSYDhXBjb5 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 --bg08WKrSYDhXBjb5 Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="0001-doc-Move-paragraphs-in-description-of-guix-archive.patch" >From a58b5438300c0e5cd64aec4959fa34bcf5c0f205 Mon Sep 17 00:00:00 2001 From: Andreas Enge 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 --bg08WKrSYDhXBjb5 Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="0002-doc-Use-modify-phases-syntax-in-example.patch" >From 4ff40a70eb7ed35f153e001f5935956286dfbdbf Mon Sep 17 00:00:00 2001 From: Andreas Enge 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 --bg08WKrSYDhXBjb5 Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="0003-doc-Drop-documentation-of-deprecated-procedures.patch" >From b46aab8149d30708e58b10e2428eb4a41f63f61e Mon Sep 17 00:00:00 2001 From: Andreas Enge 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{} # @dots{}> -@end lisp - @node The Store Monad @section The Store Monad -- 2.6.3 --bg08WKrSYDhXBjb5 Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="0004-doc-Add-footnote-on-Guile-JSON.patch" >From 1d83f47bce4106dd917384a56dc6d2c259678b87 Mon Sep 17 00:00:00 2001 From: Andreas Enge 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 --bg08WKrSYDhXBjb5--