[bug#66585] [PATCH] doc: Expound on the build-side versus host-side modules topic.

[Maxim Cournoyer]

Discussed in <https://issues.guix.gnu.org/65924#98-lineno27>.

* doc/contributing.texi (Modules): Add new context indices, and provide a
real-life counter-example, and its ramifications.

Reported-by: Ludovic Courtès <ludo@gnu.org>
Change-Id: I06975fb24f0d67c833884313a727dc550f61d8a0
---
 doc/contributing.texi | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 864190b119..be159e237e 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1279,14 +1279,19 @@ Programming Paradigm
 
 @node Modules
 @subsection Modules
-
+@cindex build-side modules
+@cindex host-side modules
 Guile modules that are meant to be used on the builder side must live in
 the @code{(guix build @dots{})} name space.  They must not refer to
 other Guix or GNU modules.  However, it is OK for a ``host-side'' module
-to use a build-side module.
+to use a build-side module.  As an example, the @code{(guix
+search-paths)} module should not be imported and used by a package since
+it isn't meant to be used as a ``build-side'' module.  It would also
+couple the module with the package's dependency graph, which is
+undesirable.
 
 Modules that deal with the broader GNU system should be in the
-@code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
+@code{(gnu @dots{})} name space rather than @code{(guix @dots{})}
 
 @node Data Types and Pattern Matching
 @subsection Data Types and Pattern Matching

base-commit: ff11cbc2e9589bcb98eb9cad1704b4b991d6f20e
-- 
2.41.0