diff --git a/doc/emacs.texi b/doc/emacs.texi index 180037a88f..5fa15d7783 100644 --- a/doc/emacs.texi +++ b/doc/emacs.texi @@ -1,29 +1,21 @@ @node Emacs Interface -@section Emacs Interface +@chapter Emacs Interface @cindex Emacs -GNU Guix comes with a visual user interface for GNU@tie{}Emacs, known -as ``guix.el''. It can be used for routine package management tasks, -pretty much like the @command{guix package} command (@pxref{Invoking -guix package}). Specifically, ``guix.el'' makes it easy to: - -@itemize -@item browse and display packages and generations; -@item search, install, upgrade and remove packages; -@item display packages from previous generations; -@item do some other useful things. -@end itemize +GNU Guix comes with several useful modules (known as ``guix.el'') for +GNU@tie{}Emacs which are intended to make an Emacs user interaction with +Guix convenient and fun. @menu * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. -* Usage: Emacs Usage. Using the interface. -* Configuration: Emacs Configuration. Configuring the interface. +* Package Management: Emacs Package Management. Managing packages and generations. * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. * Completions: Emacs Completions. Completing @command{guix} shell command. @end menu + @node Emacs Initial Setup -@subsection Initial Setup +@section Initial Setup On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el'' is ready to use, provided Guix is installed system-wide, which is the @@ -105,22 +97,32 @@ emacs, The GNU Emacs Manual}). You can activate Emacs packages installed in your profile whenever you want using @kbd{M-x@tie{}guix-emacs-load-autoloads}. -@node Emacs Usage -@subsection Usage + +@node Emacs Package Management +@section Package Management Once ``guix.el'' has been successfully configured, you should be able to -use commands for displaying packages and generations. This information -can be displayed in a ``list'' or ``info'' buffer. +use a visual interface for routine package management tasks, pretty much +like the @command{guix package} command (@pxref{Invoking guix package}). +Specifically, it makes it easy to: + +@itemize +@item browse and display packages and generations; +@item search, install, upgrade and remove packages; +@item display packages from previous generations; +@item do some other useful things. +@end itemize @menu * Commands: Emacs Commands. @kbd{M-x guix-@dots{}} * General information: Emacs General info. Common for both interfaces. * ``List'' buffer: Emacs List buffer. List-like interface. * ``Info'' buffer: Emacs Info buffer. Help-like interface. +* Configuration: Emacs Configuration. Configuring the interface. @end menu @node Emacs Commands -@subsubsection Commands +@subsection Commands All commands for displaying packages and generations use the current profile, which can be changed with @@ -191,7 +193,7 @@ Once @command{guix pull} has succeeded, the Guix REPL is restared. This allows you to keep using the Emacs interface with the updated Guix. @node Emacs General info -@subsubsection General information +@subsection General information The following keys are available for both ``list'' and ``info'' types of buffers: @@ -235,7 +237,7 @@ was restarted, you may want to revert ``list'' buffer (by pressing @kbd{g}). @node Emacs List buffer -@subsubsection ``List'' buffer +@subsection ``List'' buffer An interface of a ``list'' buffer is similar to the interface provided by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}). @@ -310,7 +312,7 @@ with another marked generation. @end table @node Emacs Info buffer -@subsubsection ``Info'' buffer +@subsection ``Info'' buffer The interface of an ``info'' buffer is similar to the interface of @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}). @@ -485,11 +487,11 @@ Various settings for ``info'' buffers. @node Emacs Prettify -@subsection Guix Prettify Mode +@section Guix Prettify Mode -Along with ``guix.el'', GNU@tie{}Guix comes with ``guix-prettify.el''. -It provides a minor mode for abbreviating store file names by replacing -hash sequences of symbols with ``@dots{}'': +GNU@tie{}Guix also comes with ``guix-prettify.el''. It provides a minor +mode for abbreviating store file names by replacing hash sequences of +symbols with ``@dots{}'': @example /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 @@ -526,7 +528,7 @@ mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example: @node Emacs Completions -@subsection Shell Completions +@section Shell Completions Another feature that becomes available after configuring Emacs interface (@pxref{Emacs Initial Setup}) is completing of @command{guix} diff --git a/doc/guix.texi b/doc/guix.texi index 5a9ebc93f8..cb5bbab2a0 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -70,6 +70,7 @@ package management tool written for the GNU system. * Introduction:: What is Guix about? * Installation:: Installing Guix. * Package Management:: Package installation, upgrade, etc. +* Emacs Interface:: Using Guix from Emacs. * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. * GNU Distribution:: Software for your friendly GNU system. @@ -101,13 +102,19 @@ Package Management * Features:: How Guix will make your life brighter. * Invoking guix package:: Package installation, removal, etc. -* Emacs Interface:: Package management from Emacs. * Substitutes:: Downloading pre-built binaries. * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. * Invoking guix archive:: Exporting and importing store files. +Emacs Interface + +* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. +* Package Management: Emacs Package Management. Managing packages and generations. +* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. +* Completions: Emacs Completions. Completing @command{guix} shell command. + Programming Interface * Defining Packages:: Defining new packages. @@ -964,14 +971,13 @@ features. This chapter describes the main features of Guix, as well as the package management tools it provides. Two user interfaces are provided for -routine package management tasks: a command-line interface -(@pxref{Invoking guix package, @code{guix package}}), and a visual user -interface in Emacs (@pxref{Emacs Interface}). +routine package management tasks: A command-line interface described below +(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user +interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}). @menu * Features:: How Guix will make your life brighter. * Invoking guix package:: Package installation, removal, etc. -* Emacs Interface:: Package management from Emacs. * Substitutes:: Downloading pre-built binaries. * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. @@ -1455,8 +1461,6 @@ Finally, since @command{guix package} may actually start build processes, it supports all the common build options that @command{guix build} supports (@pxref{Invoking guix build, common build options}). -@include emacs.texi - @node Substitutes @section Substitutes @@ -1898,6 +1902,8 @@ automatically builds them. The build process may be controlled with the same options that can be passed to the @command{guix build} command (@pxref{Invoking guix build, common build options}). +@c ********************************************************************* +@include emacs.texi @c ********************************************************************* @node Programming Interface