From 39bee8a2937ea28e74b5c807962fb8bc87fe6887 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Wed, 17 Jun 2015 21:58:04 +0200
Subject: Add 'guix edit'.

* guix/scripts/edit.scm: New file.
* Makefile.am (MODULES): Add it.
* doc.am (SUBCOMMANDS): Add 'edit'.
* doc/guix.texi (Defining Packages): Add xref to "Invoking guix edit".
  (Invoking guix edit): New node.
* po/guix/POTFILES.in: Add it.
---
 doc/guix.texi | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/guix.texi b/doc/guix.texi
index 1c7f4e1232..a93003d625 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -124,6 +124,7 @@ Defining Packages
 Utilities
 
 * Invoking guix build::         Building packages from the command line.
+* Invoking guix edit::
 * Invoking guix download::      Downloading a file and printing its hash.
 * Invoking guix hash::          Computing the cryptographic hash of a file.
 * Invoking guix import::        Importing package definitions.
@@ -1931,7 +1932,10 @@ unavailable to the build process, possibly leading to a build failure.
 
 Once a package definition is in place, the
 package may actually be built using the @code{guix build} command-line
-tool (@pxref{Invoking guix build}).  @xref{Packaging Guidelines}, for
+tool (@pxref{Invoking guix build}).  You can easily jump back to the
+package definition using the @command{guix edit} command
+(@pxref{Invoking guix edit}).
+@xref{Packaging Guidelines}, for
 more information on how to test package definitions, and
 @ref{Invoking guix lint}, for information on how to check a definition
 for style conformance.
@@ -3261,6 +3265,7 @@ programming interface of Guix in a convenient way.
 
 @menu
 * Invoking guix build::         Building packages from the command line.
+* Invoking guix edit::          Editing package definitions.
 * Invoking guix download::      Downloading a file and printing its hash.
 * Invoking guix hash::          Computing the cryptographic hash of a file.
 * Invoking guix import::        Importing package definitions.
@@ -3548,6 +3553,28 @@ the parsed command-line options.
 @end defvr
 
 
+@node Invoking guix edit
+@section Invoking @command{guix edit}
+
+@cindex package definition, editing
+So many packages, so many source files!  The @command{guix edit} command
+facilitates the life of packagers by pointing their editor at the source
+file containing the definition of the specified packages.  For instance:
+
+@example
+guix edit gcc-4.8 vim
+@end example
+
+@noindent
+launches the program specified in the @code{EDITOR} environment variable
+to edit the recipe of GCC@tie{}4.8.4 and that of Vim.
+
+If you are using Emacs, note that the Emacs user interface provides
+similar functionality in the ``package info'' buffers created by
+@kbd{M-x guix-search-by-name} and similar commands (@pxref{Emacs
+Commands}).
+
+
 @node Invoking guix download
 @section Invoking @command{guix download}
 
-- 
cgit v1.2.3