doc: extend Collections desc in module man

Author: xdelaruelle

.aspell.en.pws

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 862
+personal_ws-1.1 en 870
 ABBRVLIST
 ActiveTcl
 Adrien
@@ -225,6 +225,7 @@ al
 alfoo
 aliasname
 aliastoname
+anotherproc
 appA
 appB
 appC
@@ -252,6 +253,7 @@ bashcompletiondir
 bashrc
 baz
 bd
+beforeEval
 bindir
 binpath
 bioappA
@@ -299,6 +301,7 @@ cmdModuleSwitch
 cmdModuleTest
 cmdModuleUnload
 cmds
+cmdstring
 codespell
 collectModuleTag
 commandexp
@@ -570,9 +573,12 @@ msg
 mtreview
 multilib
 mvapich
+mycmd
 myhost
 mysoftware
 mytag
+mytarget
+myvar
 myversion
 nF
 nL
@@ -606,8 +612,10 @@ openmpi
 optionname
 os
 osVersion
+othercmd
 othertag
 othervalue
+othervar
 oxymoronic
 packagename
 parsable

NEWS.rst

@@ -163,7 +163,10 @@ Modules 5.2.0 (not yet released)
   :file:`siteconfig.tcl` file to define specific variables in modulerc
   interpreter context. :sitevar:`modulerc_extra_vars` is a list of variable
   name and value pairs. (fix issue #286)
-* Add :ref:`Site-specific configuration` section in :ref:`module(1)` man page.
+* Doc: Add :ref:`Site-specific configuration` section in :ref:`module(1)` man
+  page.
+* Doc: extend :ref:`Collections` section with examples in :ref:`module(1)` man
+  page.
 
 .. _Nagelfar: http://nagelfar.sourceforge.net/
 .. _ShellCheck: https://www.shellcheck.net/

doc/source/module.rst

@@ -2572,31 +2572,246 @@ Collections
 Collections describe a sequence of :subcmd:`module use<use>` then
 :subcmd:`module load<load>` commands that are interpreted by
 :file:`modulecmd.tcl` to set the user environment as described by this
-sequence. When a collection is activated, with the :subcmd:`restore`
-sub-command, module paths and loaded modules are unused or unloaded if they
-are not part or if they are not ordered the same way as in the collection.
+sequence.
 
 Collections are generated by the :subcmd:`save` sub-command that dumps the
 current user environment state in terms of module paths and loaded modules. By
 default collections are saved under the :file:`$HOME/.module` directory.
 
-Collections may be valid for a given target if they are suffixed. In this
-case these collections can only be restored if their suffix correspond to
-the current value of the :envvar:`MODULES_COLLECTION_TARGET` environment
-variable (see the dedicated section of this topic below).
+.. parsed-literal::
+
+    :ps:`$` module list
+    Currently Loaded Modulefiles:
+     1) foo/1.2   2) bar/2.0   3) qux/3.5
+    :ps:`$` module save foo
+    :ps:`$` cat $HOME/.module/foo
+    module use --append /path/to/modulefiles
+    module load foo
+    module load bar/2.0
+    module load qux/3.5
+
+The content of a collection can also be displayed with the :subcmd:`saveshow`
+sub-command. Note that in the above example, bare module name is recorded for
+``foo`` modulefile as loaded version is the implicit default. Loaded version
+recording can be enforced by enabling :mconfig:`collection_pin_version`
+configuration option.
+
+.. parsed-literal::
+
+    :ps:`$` module config collection_pin_version 1
+    :ps:`$` module save foo
+    :ps:`$` module saveshow foo
+    -------------------------------------------------------------------
+    :sgrhi:`/home/user/.module/foo`:
+
+    :sgrcm:`module` use --append /path/to/modulefiles
+    :sgrcm:`module` load foo/1.2
+    :sgrcm:`module` load bar/2.0
+    :sgrcm:`module` load qux/3.5
+
+    -------------------------------------------------------------------
+
+When a collection is activated, with the :subcmd:`restore`
+sub-command, module paths and loaded modules are unused or unloaded if they
+are not part or if they are not ordered the same way as in the collection.
+
+.. parsed-literal::
+
+    :ps:`$` module list
+    Currently Loaded Modulefiles:
+     1) foo/1.2   2) bar/2.1   3) qux/3.5
+    :ps:`$` module restore foo
+    Unloading :sgrhi:`qux/3.5`
+    Unloading :sgrhi:`bar/2.1`
+    Loading :sgrhi:`bar/2.0`
+    Loading :sgrhi:`qux/3.5`
+    :ps:`$` module list
+    Currently Loaded Modulefiles:
+     1) foo/1.2   2) bar/2.0   3) qux/3.5
+
+In the above example, second and third module loaded are changed. First loaded
+module is not changed or reloaded as it is the same module between current
+environment and collection. As second loaded module was different, this module
+and all those loaded afterward are unloaded to then load the sequence
+described by collection. As a result, third loaded module is reloaded, even if
+is was the same module between current environment and collection.
+
+Existing collections can be listed with :subcmd:`savelist` sub-command. They
+can be deleted with :subcmd:`saverm` sub-command.
+
+.. parsed-literal::
+
+    :ps:`$` module savelist
+    Named collection list:
+     1) default   2) foo
+    :ps:`$` module saverm default
+    :ps:`$` module savelist
+    Named collection list:
+     1) foo
+
+When no argument is provided to :subcmd:`save`, :subcmd:`restore`,
+:subcmd:`saveshow` or :subcmd:`saverm` sub-commands, the ``default``
+collection is assumed.
+
+Collection can also be specified as a full pathname:
+
+.. parsed-literal::
+
+    :ps:`$` module save /path/to/collections/bar
+    :ps:`$` module saveshow /path/to/collections/bar
+    -------------------------------------------------------------------
+    :sgrhi:`/path/to/collections/bar`:
+
+    :sgrcm:`module` use --append /path/to/modulefiles
+    :sgrcm:`module` load foo/1.2
+    :sgrcm:`module` load bar/2.0
+    :sgrcm:`module` load qux/3.5
+
+    -------------------------------------------------------------------
+
+Initial environment
+"""""""""""""""""""
+
+Initial environment state, which corresponds to modulepaths enabled and
+modules loaded during :ref:`Modules initialization<Package Initialization>`,
+is referred as the ``__init__`` collection. This collection is virtual as
+its content is stored in the :envvar:`__MODULES_LMINIT` and not in a file. It
+can be displayed with :subcmd:`saveshow` and restored with :subcmd:`restore`
+sub-command.
+
+.. parsed-literal::
+
+    :ps:`$` module saveshow __init__
+    -------------------------------------------------------------------
+    :sgrhi:`initial environment`:
+
+    :sgrcm:`module` use --append /path/to/modulefiles
+    :sgrcm:`module` load foo/1.2
+
+    -------------------------------------------------------------------
 
-Stash collections are created and restored respectively with :subcmd:`stash`
-and :subcmd:`stashpop` sub-commands. When created, current environment state
-is dumped in a collection then environment is :subcmd:`reset` to the defined
-initial state. When restored, environment is updated to match stash collection
-definition, then stash collection file is deleted. Stash collections have same
-format and are saved in the same location than other collections. Collection
-target also applies to stash collection.
+If the ``default`` collection does not exist, :subcmd:`saveshow` and
+:subcmd:`restore` sub-commands assume ``__init__`` collection when no argument
+provided to them.
+
+.. parsed-literal::
+
+    :ps:`$` module list
+    Currently Loaded Modulefiles:
+     1) foo/1.2   2) bar/2.1   3) qux/3.5
+    :ps:`$` module savelist
+    Named collection list:
+     1) foo
+    :ps:`$` module restore
+    Unloading :sgrhi:`qux/3.5`
+    Unloading :sgrhi:`bar/2.1`
+
+Initial environment state can also be restored with the :subcmd:`reset`
+sub-command. This sub-command behavior can be changed with
+:mconfig:`reset_target_state` configuration option to choose to just purge
+loaded modules or to restore a specific collection.
+
+Collection targets
+""""""""""""""""""
+
+A collection target can be defined for current environment session with the
+:mconfig:`collection_target` configuration option. When set, available
+collections are reduced to those suffixed with target name. Which means
+:subcmd:`restore`, :subcmd:`saveshow`, :subcmd:`savelist` and :subcmd:`saverm`
+only find collections matching currently set target.
+
+.. parsed-literal::
+
+    :ps:`$` module savelist
+    Named collection list:
+     1) foo
+    :ps:`$` module config collection_target mytarget
+    :ps:`$` module savelist
+    No named collection (for target "mytarget").
+    :ps:`$` module restore foo
+    :sgrer:`ERROR`: Collection foo (for target "mytarget") cannot be found
+
+When saving a new collection, generated file is suffixed with currently set
+target name.
+
+.. parsed-literal::
+
+    :ps:`$` module save bar
+    :ps:`$` module savelist
+    Named collection list (for target "mytarget"):
+     1) bar
+    :ps:`$` ls $HOME/.module
+    bar.mytarget  foo
+
+Collection targets help to distinguish contexts and make collection reachable
+only from the context they have been made for. For instance the same user
+account may be used to access different OSes or machine architectures. With a
+target set, users are ensured to only access collections built for the context
+they are currently connected to. See also :envvar:`MODULES_COLLECTION_TARGET`
+section.
+
+Stash collections
+"""""""""""""""""
+
+Current user environment can be stashed with :subcmd:`stash` sub-command. When
+this sub-command is called, current module environment is saved in a stash
+collection then `initial environment`_ is restored.
+
+.. parsed-literal::
+
+    :ps:`$` module list
+    Currently Loaded Modulefiles:
+     1) foo/1.2   2) qux/4.2
+    :ps:`$` module stash
+    Unloading :sgrhi:`qux/4.2`
+
+Specific sub-commands are available to handle stash collections:
+:subcmd:`stashpop`, :subcmd:`stashlist`, :subcmd:`stashshow`,
+:subcmd:`stashrm` and :subcmd:`stashclear`. A stash collection is restored
+with :subcmd:`stashpop` which also deletes the collection once restored.
+
+.. parsed-literal::
+
+    :ps:`$` module stashlist
+    Stash collection list (for target "mytarget"):
+     0) stash-1667669750191
+    :ps:`$` module stashpop
+    Loading :sgrhi:`qux/4.2`
+    :ps:`$` module stashlist
+    No stash collection (for target "mytarget").
+
+Stash collections have same format and are saved in the same location than
+other collections. Collection target also applies to stash collection.
+Creation timestamp is saved in stash collection name.
+
+Stash collection can be designated by their full collection name (i.e.,
+*stash-<creation_timestamp>*) or a stash index. Most recent stash
+collection has index *0*, *1* is the one before it. When no argument is
+provided on stash sub-commands, the latest stash collection is assumed (that
+is stash index *0*).
+
+.. parsed-literal::
+
+    :ps:`$` module stashlist
+    Stash collection list (for target "mytarget"):
+     0) stash-1667669750783   1) stash-1667669750253
+    :ps:`$` module stashshow 1
+    -------------------------------------------------------------------
+    :sgrhi:`/home/user/.module/stash-1667669750253.mytarget:`
+
+    :sgrcm:`module` use --append /path/to/modulefiles
+    :sgrcm:`module` load foo/1.2
+    :sgrcm:`module` load bar/2.0
+
+    -------------------------------------------------------------------
 
 .. only:: html
 
    .. versionadded:: 4.0
 
+   .. versionchanged:: 5.2
+      Initial environment state introduced
+
    .. versionchanged:: 5.2
       Stash collection introduced