branch master updated: doc: Document how to use specific package outputs in code.

[guix-commits]

This is an automated email from the git hooks/post-receive script.

apteryx pushed a commit to branch master
in repository guix.

The following commit(s) were added to refs/heads/master by this push:
     new 306bd7b8b9 doc: Document how to use specific package outputs in code.
306bd7b8b9 is described below

commit 306bd7b8b952b1e721fd36a9d69b3373862e8087
Author: Karl Hallsby <karl@hallsby.com>
AuthorDate: Sun Jan 8 13:37:55 2023 -0600

    doc: Document how to use specific package outputs in code.
    
    * doc/guix.texi (Packages with Multiple Outputs): Provide an example of
    selecting a package's output in Scheme.
    
    Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
    Modified-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
---
 doc/guix.texi | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 330d83d9ab..5a2dc2a3a3 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -113,6 +113,7 @@ Copyright @copyright{} 2022⁠–⁠2023 Bruno Victal@*
 Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@*
 Copyright @copyright{} 2023 Giacomo Leidi@*
 Copyright @copyright{} 2022 Antero Mejr@*
+Copyright @copyright{} 2023 Karl Hallsby
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -4317,6 +4318,25 @@ 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 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:
+
+@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