diff mbox series

[bug#39533] doc: Clarify documentation of guix environment --expose vs.

Message ID 87k14v34hr.fsf@cassou.me
State Accepted
Headers show
Series [bug#39533] doc: Clarify documentation of guix environment --expose vs. | expand

Checks

Context Check Description
cbaines/comparison success View comparision
cbaines/git branch success View Git branch
cbaines/applying patch fail View Laminar job

Commit Message

Damien Cassou Feb. 9, 2020, 8:11 p.m. UTC 
The documentation for --expose and --share parameters are so similar
that the reader has to read both descriptions in parallel to find the
difference.

* doc/guix.texi (Invoking guix environment): Merge the two descriptions
into one, making it much easier to see the difference.

Comments

Maja Kądziołka Feb. 14, 2020, 10 p.m. UTC | #1 
On Sun, Feb 09, 2020 at 09:11:44PM +0100, Damien Cassou wrote:
> The documentation for --expose and --share parameters are so similar
> that the reader has to read both descriptions in parallel to find the
> difference.
> 
> * doc/guix.texi (Invoking guix environment): Merge the two descriptions
> into one, making it much easier to see the difference.

Thanks for the patch! I agree that the options are so similar that they
are best described together. I've edited the commit message slightly and
pushed your patch as 459e0967705945bf6b5861598202aefef27451cd.
diff mbox series

Patch

From a790162f26a2349039955c70f264822dc00986b3 Mon Sep 17 00:00:00 2001
From: Damien Cassou <damien@cassou.me>
Date: Sun, 9 Feb 2020 21:07:04 +0100
Subject: [PATCH] doc: Clarify documentation of guix environment --expose vs.
 --share

The documentation for --expose and --share parameters are so similar that the
reader has to read both descriptions in parallel to find the difference.

* doc/guix.texi (Invoking guix environment): Merge the two descriptions into
one, making it much easier to see the difference.
---
 doc/guix.texi | 19 ++++---------------
 1 file changed, 4 insertions(+), 15 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 56cc333fe4..baa128f6f0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4958,8 +4958,10 @@  shared and will change to the user's home directory within the container
 instead.  See also @code{--user}.
 
 @item --expose=@var{source}[=@var{target}]
-For containers, expose the file system @var{source} from the host system
-as the read-only file system @var{target} within the container.  If
+@item --share=@var{source}[=@var{target}]
+For containers, @code{--expose} (resp. @code{--share}) exposes the file
+system @var{source} from the host system as the read-only
+(resp. writable) file system @var{target} within the container.  If
 @var{target} is not specified, @var{source} is used as the target mount
 point in the container.
 
@@ -4971,19 +4973,6 @@  directory:
 guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
 @end example
 
-@item --share=@var{source}[=@var{target}]
-For containers, share the file system @var{source} from the host system
-as the writable file system @var{target} within the container.  If
-@var{target} is not specified, @var{source} is used as the target mount
-point in the container.
-
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible for both reading and writing via the
-@file{/exchange} directory:
-
-@example
-guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
-@end example
 @end table
 
 @command{guix environment}
-- 
2.24.1