[bug#60661] [DOCUMENTATION] doc: Example of selecting package output with lisp

[bug#60661] [DOCUMENTATION] doc: Example of selecting package output with lisp

[Karl Hallsby]

* doc/guix.texi (Packages with Multiple Outputs): Give example of how to
select a package's output is a Lisp-y fashion, without using a special
procedure like specification->package.
---
 doc/guix.texi | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 293c3016aa..025a73f616 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4315,6 +4315,23 @@ The command to install its documentation is:
 guix install glib:doc
 @end example
 
+While the colon syntax works for command-line specification of package
+outputs, it will not work when specifying the package by Guix name.
+For example, say you want to add only @code{glib}'s documentation to
+your @code{operating-system}'s globally installed packages
+(@pxref{operating-system Reference}).
+
+@lisp
+(use-modules (gnu packages glib))
+;; glib-with-documentation is the Guile symbol for the glib package
+(operating-system
+ ...
+ (packages
+  (append
+   (list (list glib-with-documentation "doc"))
+         %base-packages)))
+@end lisp
+
 Some packages install programs with different ``dependency footprints''.
 For instance, the WordNet package installs both command-line tools and
 graphical user interfaces (GUIs).  The former depend solely on the C

base-commit: 812ecf7ee673a3d619d1d3664350508c67e9d92c
-- 
2.38.1

bug#60661: [DOCUMENTATION] doc: Example of selecting package output with lisp

[Maxim Cournoyer]

Hello Karl,

Karl Hallsby <karl@hallsby.com> writes:

> * doc/guix.texi (Packages with Multiple Outputs): Give example of how to
> select a package's output is a Lisp-y fashion, without using a special
> procedure like specification->package.
> ---
>  doc/guix.texi | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 293c3016aa..025a73f616 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -4315,6 +4315,23 @@ The command to install its documentation is:
>  guix install glib:doc
>  @end example
>  
> +While the colon syntax works for command-line specification of package
> +outputs, it will not work when specifying the package by Guix name.
> +For example, say you want to add only @code{glib}'s documentation to
> +your @code{operating-system}'s globally installed packages
> +(@pxref{operating-system Reference}).
> +
> +@lisp
> +(use-modules (gnu packages glib))
> +;; glib-with-documentation is the Guile symbol for the glib package
> +(operating-system
> + ...
> + (packages
> +  (append
> +   (list (list glib-with-documentation "doc"))
> +         %base-packages)))
> +@end lisp
> +
>  Some packages install programs with different ``dependency footprints''.
>  For instance, the WordNet package installs both command-line tools and
>  graphical user interfaces (GUIs).  The former depend solely on the C
>
> base-commit: 812ecf7ee673a3d619d1d3664350508c67e9d92c

Thanks for the contribution!  I've taken the liberty to reword it
slightly, to voice it using the third person instead of "you", like
this:

--8<---------------cut here---------------start------------->8---
modified   doc/guix.texi
@@ -4318,10 +4318,12 @@ guix install glib:doc
 @end example
 
 While the colon syntax works for command-line specification of package
-outputs, it will not work when specifying the package by Guix name.
-For example, say you want to add only @code{glib}'s documentation to
-your @code{operating-system}'s globally installed packages
-(@pxref{operating-system Reference}).
+outputs, it will not work when using a package @emph{variable} in Scheme
+code.  For example, to add the documentation of @code{glib} to the
+globally installed packages of an @code{operating-system} (see
+@ref{operating-system Reference}), a list of two items, the first one
+being the package @emph{variable} and the second one the name of the
+output to select (a string), must be used instead:
--8<---------------cut here---------------end--------------->8---

I also added your name to the list of contributors to 'guix.texi'.  I
hope you like it.

The change has now been installed.

-- 
Thanks,
Maxim