docs: unshare: split --map-users/--map-groups into readable paragraphs

No text changes, only line breaks to improve readability.

Addresses: https://github.com/util-linux/util-linux/issues/3838
Signed-off-by: Karel Zak <kzak@redhat.com>

diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc
index d40bfee3c5657b60d8bddc32b0930da31ca2d3b3..114027c501c99075a8d1643bf4dceb5cde0bb780 100644 (file)
--- a/sys-utils/unshare.1.adoc
+++ b/sys-utils/unshare.1.adoc
@@ -110,7 +110,11 @@ Just before running the program, mount the binfmt_misc filesystem at _mountpoint
 Run the program only after the current effective user ID has been mapped to _uid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*.
 
 *--map-users* __inneruid__**:**__outeruid__**:**__count__|**auto**|**subids**|**all**::
-Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged. The mapping specified by *--map-user* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-user*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outeruid_ or _inneruid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest user ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-user* rather than including it. As a result, a user ID you expected this block to map (for example the first ID of an *id -u*-based range) may instead resolve to the ID set by *--map-user*, and the topmost _outeruid_ of the block may go unmapped. Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*.
+Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged.
++
+The mapping specified by *--map-user* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-user*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outeruid_ or _inneruid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest user ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-user* rather than including it. As a result, a user ID you expected this block to map (for example the first ID of an *id -u*-based range) may instead resolve to the ID set by *--map-user*, and the topmost _outeruid_ of the block may go unmapped.
++
+Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*.
 +
 Before util-linux version 2.39, this option expected a comma-separated argument of the form _outeruid_**,**_inneruid_**,**_count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/uid_map_ and the _X-mount.idmap_ mount option.
 
@@ -118,7 +122,11 @@ Before util-linux version 2.39, this option expected a comma-separated argument
 Run the program only after the current effective group ID has been mapped to _gid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--setgroups=deny* and *--user*.
 
 *--map-groups* __innergid__**:**__outergid__**:**__count__|**auto**|**subids**|**all**::
-Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged. The mapping specified by *--map-group* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-group*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outergid_ or _innergid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest group ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-group* rather than including it. As a result, a group ID you expected this block to map (for example the first ID of an *id -g*-based range) may instead resolve to the ID set by *--map-group*, and the topmost _outergid_ of the block may go unmapped. Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*.
+Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged.
++
+The mapping specified by *--map-group* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-group*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outergid_ or _innergid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest group ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-group* rather than including it. As a result, a group ID you expected this block to map (for example the first ID of an *id -g*-based range) may instead resolve to the ID set by *--map-group*, and the topmost _outergid_ of the block may go unmapped.
++
+Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*.
 +
 Before util-linux version 2.39, this option expected a comma-separated argument of the form _outergid_**,**_innergid_**,**_count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/gid_map_ and the _X-mount.idmap_ mount option.