From 306bd7b8b952b1e721fd36a9d69b3373862e8087 Mon Sep 17 00:00:00 2001
From: Karl Hallsby <karl@hallsby.com>
Date: Sun, 8 Jan 2023 13:37:55 -0600
Subject: 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(+)

(limited to 'doc')

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
-- 
cgit v1.2.3