doc: add manual page for "envml" command

Fixes #190

Signed-off-by: Xavier Delaruelle <[email protected]>

Author: xdelaruelle

.hunspell.en.dic

@@ -1238,3 +1238,5 @@ RenvModule
 tablelist
 haveDynamicMPATH
 settarg
+ACTIONs
+arg2

INSTALL-win.rst

@@ -104,6 +104,6 @@ a modulepath and contains few modulefile examples::
         ------- C:/Program Files/Environment Modules/modulefiles --------
         module-git  module-info  null
 
-Documentation of the :ref:`module(1)` and :ref:`ml(1)` commands and
-:ref:`modulefile(5)` syntax can be found in the ``doc`` directory in
-installation directory.
+Documentation of the :ref:`module(1)`, :ref:`ml(1)` and :ref:`envml(1)`
+commands and :ref:`modulefile(5)` syntax can be found in the ``doc`` directory
+in installation directory.

Makefile

@@ -815,8 +815,8 @@ dist-tar: ChangeLog.gz share/rpm/environment-modules.spec pkgdoc
 		lib/configure lib/config.h.in $(DIST_AUTORECONF_EXTRA) ChangeLog.gz \
 		doc/build/MIGRATING.txt doc/build/changes.txt doc/build/INSTALL.txt \
 		doc/build/INSTALL-win.txt doc/build/NEWS.txt doc/build/CONTRIBUTING.txt \
-		doc/build/module.1.in doc/build/ml.1 doc/build/modulefile.5 \
-		share/rpm/environment-modules.spec
+		doc/build/module.1.in doc/build/ml.1 doc/build/envml.1 \
+		doc/build/modulefile.5 share/rpm/environment-modules.spec
 
 dist-gzip: dist-tar
 	$(ECHO_GEN2) $(DIST_PREFIX).tar.gz
@@ -847,6 +847,8 @@ dist-win: modulecmd.tcl ChangeLog.gz README pkgdoc
 	$(INSTALL_DATA) doc/build/NEWS.txt $(DIST_WIN_PREFIX)/doc/
 	$(INSTALL_DATA) doc/build/CONTRIBUTING.txt $(DIST_WIN_PREFIX)/doc/
 	$(INSTALL_DATA) doc/build/module.txt $(DIST_WIN_PREFIX)/doc/
+	$(INSTALL_DATA) doc/build/ml.txt $(DIST_WIN_PREFIX)/doc/
+	$(INSTALL_DATA) doc/build/envml.txt $(DIST_WIN_PREFIX)/doc/
 	$(INSTALL_DATA) doc/build/modulefile.txt $(DIST_WIN_PREFIX)/doc/
 	$(MAKE) --no-print-directory -C init dist-win DIST_WIN_PREFIX=../$(DIST_WIN_PREFIX)
 	$(INSTALL_PROGRAM) script/INSTALL.bat $(DIST_WIN_PREFIX)/

NEWS.rst

@@ -154,6 +154,7 @@ Modules 5.6.0 (not yet released)
 * Add :mfcmd:`haveDynamicMPATH` modulefile command
 * Fix ``use.own`` example modulefile to report when creating local modulefiles
   directory. (fix issue #576)
+* Doc: add manual page for :ref:`envml(1)` command. (fix issue #190)
 
 .. _Security policy: https://github.com/envmodules/modules/blob/main/SECURITY.md
 .. _Modules chat room: https://matrix.to/#/#modules:matrix.org

README.md

@@ -110,7 +110,7 @@ type:
 
 The following man pages are provided:
 
-    module(1), ml(1), modulefile(5)
+    module(1), ml(1), envml(1), modulefile(5)
 
 
 Test suite

configure

@@ -998,7 +998,8 @@ if [ -e "${builddocdir}/changes.txt" ] && [ -e "${builddocdir}/MIGRATING.txt" ]
    && [ -e "${builddocdir}/INSTALL.txt" ] && [ -e "${builddocdir}/INSTALL-win.txt" ] \
    && [ -e "${builddocdir}/NEWS.txt" ] && [ -e "${builddocdir}/CONTRIBUTING.txt" ] \
    && [ -e "${builddocdir}/module.1.in" ] && [ -e "${builddocdir}/ml.1" ] \
-   && [ -e "${builddocdir}/modulefile.5" ] && [ "$oldbuilddoc" != 'y' ]; then
+   && [ -e "${builddocdir}/envml.1" ] && [ -e "${builddocdir}/modulefile.5" ] \
+   && [ "$oldbuilddoc" != 'y' ]; then
    builddoc=p
 # test sphinx availability otherwise
 else

doc/Makefile

@@ -37,7 +37,8 @@ ALL_RST := $(wildcard $(SOURCE_DIR)/*.rst $(SOURCE_DIR)/cookbook/*.rst\
 	$(SOURCE_DIR)/design/*.rst)
 ALL_TXT := $(patsubst $(SOURCE_DIR)/%,$(BUILD_DIR)/%,$(patsubst %.rst,%.txt,$(ALL_RST)))
 ALL_HTML := $(patsubst $(SOURCE_DIR)/%,$(BUILD_DIR)/%,$(patsubst %.rst,%.html,$(ALL_RST)))
-ALL_MAN := $(BUILD_DIR)/module.1 $(BUILD_DIR)/ml.1 $(BUILD_DIR)/modulefile.5
+ALL_MAN := $(BUILD_DIR)/module.1 $(BUILD_DIR)/ml.1 $(BUILD_DIR)/envml.1\
+	$(BUILD_DIR)/modulefile.5
 
 all: man txt
 
@@ -100,7 +101,8 @@ $(BUILD_DIR)/%.txt: $(SOURCE_DIR)/%.rst $(SOURCE_DIR)/version.py
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/*.txt
 	$(SPHINXBUILD) $(SPHINXOPTS) -b text "$(SOURCE_DIR)" "$(BUILD_DIR)"
 
-$(BUILD_DIR)/module.1.in $(BUILD_DIR)/modulefile.5 $(BUILD_DIR)/ml.1: $(ALL_RST) $(SOURCE_DIR)/version.py
+$(BUILD_DIR)/module.1.in $(BUILD_DIR)/modulefile.5 $(BUILD_DIR)/ml.1 $(BUILD_DIR)/envml.1: $(ALL_RST) $(SOURCE_DIR)/version.py
+	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/envml.1
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/ml.1
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/module.1.in
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/modulefile.5
@@ -124,6 +126,7 @@ ifeq ($(docinstall),y)
 endif
 	$(INSTALL_DATA) $(BUILD_DIR)/module.1 '$(DESTDIR)$(mandir)/man1/'
 	$(INSTALL_DATA) $(BUILD_DIR)/ml.1 '$(DESTDIR)$(mandir)/man1/'
+	$(INSTALL_DATA) $(BUILD_DIR)/envml.1 '$(DESTDIR)$(mandir)/man1/'
 	$(INSTALL_DATA) $(BUILD_DIR)/modulefile.5 '$(DESTDIR)$(mandir)/man5/'
 
 uninstall:
@@ -138,6 +141,7 @@ ifeq ($(docinstall),y)
 endif
 	rm -f '$(DESTDIR)$(mandir)/man1/module.1'
 	rm -f '$(DESTDIR)$(mandir)/man1/ml.1'
+	rm -f '$(DESTDIR)$(mandir)/man1/envml.1'
 	rm -f '$(DESTDIR)$(mandir)/man5/modulefile.5'
 	rmdir '$(DESTDIR)$(mandir)/man1' '$(DESTDIR)$(mandir)/man5'
 	rmdir '$(DESTDIR)$(mandir)'

doc/source/conf.py

@@ -305,7 +305,8 @@ def get_version_release_from_git():
 man_pages = [
     ('module', 'module', u'command interface to the Modules package', [], 1),
     ('ml', 'ml', u'handy command interface to the Modules package', [], 1),
-    ('modulefile', 'modulefile', u'files containing Tcl code for the Modules package', [], 5)
+    ('modulefile', 'modulefile', u'files containing Tcl code for the Modules package', [], 5),
+    ('envml', 'envml', u'run a command in an environment setting up by Modules', [], 1)
 ]
 
 

doc/source/envml.rst

@@ -0,0 +1,104 @@
+.. _envml(1):
+
+envml
+=====
+
+SYNOPSIS
+--------
+
+**envml** [*MODULE_ACTION*]... [--] *COMMAND* [*ARG*]...
+
+DESCRIPTION
+-----------
+
+The :command:`envml` command is a helper script that configures the shell
+environment using specified Environment Modules actions before executing a
+given command.
+
+This is useful for running a command in a modified environment without
+permanently altering the current shell session.
+
+The script first interprets arguments as module actions, then switches to
+command execution after either encountering ``--`` or determining that the
+remaining arguments form the actual command to run.
+
+MODULE_ACTION FORMAT
+--------------------
+
+Each module action argument can be one of the following forms:
+
+- ``purge``
+  Unload all currently loaded modulefiles.
+
+- ``restore[=coll]``
+  Restore the module environment from the named collection ``coll``. If no
+  name is given, restores the default collection.
+
+- ``unload=mod1[&mod2...]``
+  Unload one or more specified modulefiles.
+
+- ``switch=mod1&mod2``
+  Unload ``mod1`` and load ``mod2``.
+
+- ``[load=]mod1[&mod2...]``
+  Load one or more specified modulefiles. ``load=`` can be omitted.
+
+Multiple MODULE_ACTIONs can be passed in a single argument using the colon
+(``:``) separator. The ampersand (``&``) is used to specify multiple modules
+in a single action.
+
+COMMAND EXECUTION
+-----------------
+
+Everything following the ``--`` separator is treated as the command to execute
+in the modified environment.
+
+If no ``--`` separator is provided, :command:`envml` assumes the first
+argument is a MODULE_ACTION and the remaining arguments form the command to
+execute.
+
+OPTIONS
+-------
+
+.. option:: --help, -h
+
+ Display usage information and exit.
+
+EXAMPLES
+--------
+
+Run ``command arg1 arg2`` in the environment restored from the default module
+collection:
+
+.. code-block:: sh
+
+    envml restore command arg1 arg2
+
+Purge all modules, then load ``mod1`` and ``mod2``, and run the command:
+
+.. code-block:: sh
+
+    envml purge:mod1:mod2 command arg1 arg2
+
+Use the ``--`` separator to avoid ambiguity:
+
+.. code-block:: sh
+
+    envml restore load=mod1&mod2 -- command arg1 arg2
+
+EXIT STATUS
+-----------
+
+The :command:`envml` command returns the exit status of the executed command
+or ``1`` if module action fails.
+
+DIAGNOSTICS
+-----------
+
+If the :command:`module` command is not available in the shell (i.e., not a
+shell function), :command:`envml` will print an error and exit.
+
+SEE ALSO
+--------
+
+:ref:`module(1)`, :ref:`ml(1)`, :ref:`modulefile(5)`

doc/source/index.rst

@@ -111,6 +111,7 @@ automatically configured to the correct architecture.
    ml
    module
    modulefile
+   envml
 
 .. toctree::
    :hidden:
@@ -135,8 +136,9 @@ introduced by each version is available in the :ref:`MIGRATING` guide.
 :ref:`changes` document gives an in-depth view of the modified behaviors and
 new features between major versions.
 
-Reference manual page for the :ref:`module(1)` and :ref:`ml(1)` commands and
-for :ref:`modulefile(5)` script provide details on all supported options.
+Reference manual page for the :ref:`module(1)`, :ref:`ml(1)` and
+:ref:`envml(1)` commands and for :ref:`modulefile(5)` script provide details
+on all supported options.
 
 A :ref:`cookbook` of recipes describes how to use the various features of
 Modules and how to extend the :command:`module` command to achieve specific