From 15cdc75d7b8f52f499c389efe7417ce239f73a4c Mon Sep 17 00:00:00 2001
From: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Date: Sun, 25 Apr 2021 21:58:22 +0200
Subject: [PATCH] doc: desc. edit/MODULES_EDITOR in NEWS/MIGRATING

---
 MIGRATING.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 NEWS.rst      | 21 +++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/MIGRATING.rst b/MIGRATING.rst
index 5b6a4097e..1cbc2196c 100644
--- a/MIGRATING.rst
+++ b/MIGRATING.rst
@@ -8,6 +8,54 @@ Modules. It provides an overview of the new features and changed behaviors
 that will be encountered when upgrading.
 
 
+From v4.7 to v4.8
+=================
+
+This new version is backward-compatible with v4.7 and primarily fixes bugs and
+adds new features. Version 4.8 introduces new functionalities that are
+described in this section. See the :ref:`4.8 release notes<4.8 release notes>`
+for a complete list of the changes between Modules v4.7 and v4.8.
+
+Editing modulefiles
+-------------------
+
+:subcmd:`edit` sub-command is introduced to give the ability to open
+modulefiles in a text editor. Modulefiles can be specified like with any other
+sub-command: using regular, symbolic or aliased names or using advanced
+version specifiers.
+
+.. parsed-literal::
+
+    :ps:`$` ml edit foo
+
+:subcmd:`edit` sub-command resolves the path toward the designated modulefile
+then call configured text editor to open this modulefile with it. Below, the
+modulefile is opened with the ``vi`` command:
+
+.. parsed-literal::
+
+    #%Module
+    module-whatis [module-info name]
+    setenv PATH /path/to/foo-1.0/bin
+    ~                                                           
+    ~                                                           
+    ~                                                           
+    "/path/to/modulefiles/foo/1.0" 3L, 42B 1,1           All
+
+The :mconfig:`editor` configuration option controls the editor command to use.
+This option can be configured at installation time with the
+:instopt:`--with-editor` installation option. If not set, :mconfig:`editor`
+configuration option is set by default to ``vi``.
+
+:mconfig:`editor` configuration option can be changed with the
+:subcmd:`config` sub-command. Which sets the :envvar:`MODULES_EDITOR`
+environment variable.
+
+The :envvar:`VISUAL` or the :envvar:`EDITOR` environment variables override
+the default value of :mconfig:`editor` configuration option but are overridden
+by the :envvar:`MODULES_EDITOR` environment variable.
+
+
 From v4.6 to v4.7
 =================
 
diff --git a/NEWS.rst b/NEWS.rst
index 0d3d281c9..ac6db91e2 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -6,6 +6,27 @@ Release notes
 This file describes changes in recent versions of Modules. It primarily
 documents those changes that are of interest to users and admins.
 
+.. _4.8 release notes:
+
+Modules 4.8.0 (not yet released)
+--------------------------------
+
+* Introduce the :subcmd:`edit` sub-command that opens modulefile passed as
+  argument in a text editor. Modulefile can be specified like with any other
+  sub-command, leveraging defined symbolic versions, aliases or using advanced
+  version specifiers.
+* Add the :mconfig:`editor` configuration option to select the text editor to
+  use with :subcmd:`edit` sub-command. When this option is set through the
+  :subcmd:`config` sub-command, the :envvar:`MODULES_EDITOR` environment
+  variable is set. The :instopt:`--with-editor` installation option controls
+  the default value of :mconfig:`editor` configuration option. If not set at
+  installation time, ``vi`` is set as default editor.
+* Default value of :mconfig:`editor` configuration option is overridden by the
+  :envvar:`VISUAL` or the :envvar:`EDITOR` environment variables, which are
+  both in turn overridden by the :envvar:`MODULES_EDITOR` environment
+  variable.
+
+
 .. _4.7 release notes:
 
 Modules 4.7.1 (2021-04-06)